@stacks/stacking

Library for PoX Stacking.

Installation

npm install @stacks/stacking bn.js

Initialization

Initialize a StackingClient to interact with the Stacking contract.

Note: the StackingClient sets its transactions AnchorMode to Any.

import { getNonce } from '@stacks/transactions';
import { StacksTestnet, StacksMainnet } from '@stacks/network';
import { StackingClient } from '@stacks/stacking';
import BN from 'bn.js';

const network = new StacksTestnet();
// for mainnet: const network = new StacksMainnet();
const client = new StackingClient(address, network);

// the stacks STX address
const address = 'ST3XKKN4RPV69NN1PHFDNX3TYKXT7XPC4N8KC1ARH';
// a BTC address for reward payouts
const poxAddress = 'mvuYDknzDtPgGqm2GnbAbmGMLwiyW3AwFP';
// number cycles to stack
const cycles = 3;
// how much to stack, in microSTX
const amountMicroStx = new BN(100000000000);
// private key for transaction signing
const privateKey = 'd48f215481c16cbe6426f8e557df9b78895661971d71735126545abddcd5377001';
// block height at which to stack
const burnBlockHeight = 2000;

Check stacking eligibility

const stackingEligibility = await client.canStack({ poxAddress, cycles });

// {
//   eligible: false,
//   reason: 'ERR_STACKING_INVALID_LOCK_PERIOD',
// }

Stack STX

const stackingResults = await client.stack({
  amountMicroStx,
  poxAddress,
  cycles,
  privateKey,
  burnBlockHeight,
});

// {
//   txid: '0xf6e9dbf6a26c1b73a14738606cb2232375d1b440246e6bbc14a45b3a66618481',
// }

Will Stacking be executed in the next cycle?

const stackingEnabledNextCycle = await client.isStackingEnabledNextCycle();

// true / false

How long (in seconds) is a Stacking cycle?

const cycleDuration = await client.getCycleDuration();

// 120

How much time is left (in seconds) until the next cycle begins?

const secondsUntilNextCycle = await client.getSecondsUntilNextCycle();

// 600000

Get PoX info

const poxInfo = await client.getPoxInfo();

// {
//   contract_id: 'ST000000000000000000002AMW42H.pox',
//   first_burnchain_block_height: 0,
//   min_amount_ustx: 83335083333333,
//   prepare_cycle_length: 30,
//   rejection_fraction: 3333333333333333,
//   reward_cycle_id: 17,
//   reward_cycle_length: 120,
//   rejection_votes_left_required: 0,
//   total_liquid_supply_ustx: 40000840000000000
// }

Get Stacks node info

const coreInfo = await client.getCoreInfo();

// {
//   peer_version: 385875968,
//   pox_consensus: 'bb88a6e6e65fa7c974d3f6e91a941d05cc3dff8e',
//   burn_block_height: 2133,
//   stable_pox_consensus: '2284451c3e623237def1f8caed1c11fa46b6f0cc',
//   stable_burn_block_height: 2132,
//   server_version: 'blockstack-core 0.0.1 => 23.0.0.0 (HEAD:a4deb7a+, release build, linux [x86_64])',
//   network_id: 2147483648,
//   parent_network_id: 3669344250,
//   stacks_tip_height: 1797,
//   stacks_tip: '016df36c6a154cb6114c469a28cc0ce8b415a7af0527f13f15e66e27aa480f94',
//   stacks_tip_consensus_hash: 'bb88a6e6e65fa7c974d3f6e91a941d05cc3dff8e',
//   unanchored_tip: '6b93d2c62fc07cf44302d4928211944d2debf476e5c71fb725fb298a037323cc',
//   exit_at_block_height: null
// }

Get account balance

const responseBalanceInfo = await client.getAccountBalance();

// 800000000000

Does account have sufficient STX to meet minimum threshold?

const hasMinStxAmount = await client.hasMinimumStx();

// true / false

Get account stacking status

const stackingStatus = await client.getStatus();

// {
//   stacked: true,
//   details: {
//     amount_microstx: '80000000000000',
//     first_reward_cycle: 18,
//     lock_period: 10,
//     unlock_height: 3020,
//     pox_address: {
//       version: '00',
//       hashbytes: '05cf52a44bf3e6829b4f8c221cc675355bf83b7d'
//     }
//   }
// }

Delegation

There are four methods available for delegation, two for the delegators and two for the delegatee.

Delegatee

If you are the account owner ("stacker"), you can delegate or revoke delegation rights.

Delegate STX

// STX address of the delegator
const delegateTo = 'ST2MCYPWTFMD2MGR5YY695EJG0G1R4J2BTJPRGM7H';
// burn height at which the delegation relationship should be revoked (optional)
const untilBurnBlockHeight = 5000;

const delegetateResponse = await client.delegateStx({
  amountMicroStx,
  delegateTo,
  untilBurnBlockHeight, // optional
  privateKey,
});

// {
//   txid: '0xf6e9dbf6a26c1b73a14738606cb2232375d1b440246e6bbc14a45b3a66618481',
// }

Revoke delegation

// note that the parameter here is not JSON
const revokeResponse = await client.revokeDelegateStx(privateKey);

// {
//   txid: '0xf6e9dbf6a26c1b73a14738606cb2232375d1b440246e6bbc14a45b3a66618481',
// }

Delegator

If you are the delegator, you can stack ("lock up") tokens for your users and commit to stacking participation for upcoming reward cycles.

Stack delegated STX

// delegators would initiate a different client
const delegatorAddress = 'ST22X605P0QX2BJC3NXEENXDPFCNJPHE02DTX5V74';
// delegator private key for transaction signing
const delegatorPrivateKey = 'd48f215481c16cbe6426f8e557df9b78895661971d71735126545abddcd5377001';
// the BTC address for reward payouts
const delegatorBtcAddress = 'msiYwJCvXEzjgq6hDwD9ueBka6MTfN962Z';

// if you call this method multiple times in the same block, you need to increase the nonce manually
let nonce = getNonce(delegatorAddress, network);
nonce = nonce.add(new BN(1));

const delegatorClient = new StackingClient(delegatorAddress, network);

const delegetateStackResponses = await delegatorClient.delegateStackStx({
  stacker: address,
  amountMicroStx,
  poxAddress: delegatorBtcAddress,
  burnBlockHeight,
  cycles,
  privateKey: delegatorPrivateKey,
  nonce, // optional
});

//   {
//     txid: '0xf6e9dbf6a26c1b73a14738606cb2232375d1b440246e6bbc14a45b3a66618481',
//   }

Commit to stacking

// reward cycle id to commit to
const rewardCycle = 12;

const delegetateCommitResponse = await delegatorClient.stackAggregationCommit({
  poxAddress: delegatorBtcAddress,
  rewardCycle,
  privateKey: privateKeyDelegate,
});

// {
//   txid: '0xf6e9dbf6a26c1b73a14738606cb2232375d1b440246e6bbc14a45b3a66618481',
// }