Stacking Contract
Introduction
Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API v2/pox
endpoint.
Below is a list of public and read-only functions as well as error codes that can be returned by those methods.
Public functions
allow-contract-caller
Signature: (allow-contract-caller caller until-burn-ht)
Input: principal, (optional uint)
Output: (response bool int)
Give a contract-caller authorization to call stacking methods. Normally, stacking methods may
only be invoked by direct transactions (i.e., the tx-sender
issues a direct contract-call
to the stacking methods).
By issuing an allowance, the tx-sender may call through the allowed contract.
delegate-stack-stx
Signature: (delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)
Input: principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint
Output: (response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)
As a delegate, stack the given principal's STX using partial-stacked-by-cycle
.
Once the delegate has stacked > minimum, the delegate should call stack-aggregation-commit
.
delegate-stx
Signature: (delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)
Input: uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))
Output: (response bool int)
Delegate to delegate-to
the ability to stack from a given address.
This method does not lock the funds, rather, it allows the delegate to issue the stacking lock.
The caller specifies:
- amount-ustx: the total amount of ustx the delegate may be allowed to lock
- until-burn-ht: an optional burn height at which this delegation expiration
- pox-addr: an optional address to which any rewards must be sent
disallow-contract-caller
Signature: (disallow-contract-caller caller)
Input: principal
Output: (response bool int)
Revokes authorization from a contract to invoke stacking methods through contract-calls
reject-pox
Signature: (reject-pox)
Input:
Output: (response bool int)
Reject Stacking for this reward cycle.
tx-sender
votes all its uSTX for rejection.
Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote.
revoke-delegate-stx
Signature: (revoke-delegate-stx)
Input:
Output: (response bool int)
Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists).
stack-aggregation-commit
Signature: (stack-aggregation-commit pox-addr reward-cycle)
Input: (tuple (hashbytes (buff 20)) (version (buff 1))), uint
Output: (response bool int)
Commit partially stacked STX.
This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, so long as:
- The pox-addr is the same.
- This "commit" transaction is called before the PoX anchor block. This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, but does not require it be all locked up within a single transaction
stack-stx
Signature: (stack-stx amount-ustx pox-addr start-burn-ht lock-period)
Input: uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint
Output: (response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)
Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). The STX will be locked for the given number of reward cycles (lock-period). This is the self-service interface. tx-sender will be the Stacker.
- The given stacker cannot currently be stacking.
- You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this
method still requires stacking over the absolute minimum amount, which can be obtained by calling
get-stacking-minimum
.
The tokens will unlock and be returned to the Stacker (tx-sender) automatically.
Read-only functions
can-stack-stx
Signature: (can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)
Input: (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint
Output: (response bool int)
Evaluate if a participant can stack an amount of STX for a given period.
get-pox-info
Signature: (get-pox-info)
Input:
Output: (response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)
Returns information about PoX status.
get-pox-rejection
Signature: (get-pox-rejection stacker reward-cycle)
Input: principal, uint
Output: (optional (tuple (amount uint)))
Returns the amount of uSTX that a given principal used to reject a PoX cycle.
get-stacker-info
Signature: (get-stacker-info stacker)
Input: principal
Output: (optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))
Returns the current stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none.
get-stacking-minimum
Signature: (get-stacking-minimum)
Input:
Output: uint
Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this
get-total-ustx-stacked
Signature: (get-total-ustx-stacked reward-cycle)
Input: uint
Output: uint
Returns the amount of currently participating uSTX in the given cycle.
is-pox-active
Signature: (is-pox-active reward-cycle)
Input: uint
Output: bool
Returns whether or not PoX has been rejected at a given PoX cycle.
Error codes
ERR_DELEGATION_EXPIRES_DURING_LOCK
Type: int
Value: 21
ERR_DELEGATION_POX_ADDR_REQUIRED
Type: int
Value: 23
ERR_DELEGATION_TOO_MUCH_LOCKED
Type: int
Value: 22
ERR_INVALID_START_BURN_HEIGHT
Type: int
Value: 24
ERR_NOT_ALLOWED
Type: int
Value: 19
ERR_STACKING_ALREADY_DELEGATED
Type: int
Value: 20
ERR_STACKING_ALREADY_REJECTED
Type: int
Value: 17
ERR_STACKING_ALREADY_STACKED
Type: int
Value: 3
ERR_STACKING_EXPIRED
Type: int
Value: 5
ERR_STACKING_INSUFFICIENT_FUNDS
Type: int
Value: 1
ERR_STACKING_INVALID_AMOUNT
Type: int
Value: 18
ERR_STACKING_INVALID_LOCK_PERIOD
Type: int
Value: 2
ERR_STACKING_INVALID_POX_ADDRESS
Type: int
Value: 13
ERR_STACKING_NO_SUCH_PRINCIPAL
Type: int
Value: 4
ERR_STACKING_PERMISSION_DENIED
Type: int
Value: 9
ERR_STACKING_POX_ADDRESS_IN_USE
Type: int
Value: 12
ERR_STACKING_STX_LOCKED
Type: int
Value: 6
ERR_STACKING_THRESHOLD_NOT_MET
Type: int
Value: 11
ERR_STACKING_UNREACHABLE
Type: int
Value: 255