Stacking Contract

See a detailed list of all functions and error codes of the Stacking contract.

Introduction

Stacking is implemented as a smart contract using Clarity. On the testnet, you can always find the Stacking contract by this contract identifier: ST000000000000000000002AMW42H.pox.

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:

  1. The pox-addr is the same.
  2. 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

Previous
Stacks CLI
Next
Stacks Blockchain API