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. 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

Contents

allow-contract-caller

delegate-stack-stx

delegate-stx

disallow-contract-caller

reject-pox

revoke-delegate-stx

stack-aggregation-commit

stack-stx

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

Contents

get-total-ustx-stacked

is-pox-active

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.