# stacking | Stacks.js 1.4.1 Library Reference
Documentation for Stacks.js 1.4.1 Library Reference

# @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',
    // }

## Index

### Classes

- InvalidAddressError
- StackingClient

### Interfaces

- BalanceInfo
- BlockTimeInfo
- CanLockStxOptions
- CoreInfo
- DelegateStackStxOptions
- DelegateStxOptions
- LockStxOptions
- PoxInfo
- StackAggregationCommitOptions
- StackingEligibility

### Type aliases

- PoxAddressArgs
- StackerInfo

### Variables

- BitcoinNetworkVersion

### Functions

- btcAddressVersionToHashMode
- decodeBtcAddress
- extractPoxAddressFromClarityValue
- getAddressHashMode
- getBTCAddress
- getErrorString
- hashModeToBtcAddressVersion
- poxAddressToBtcAddress

## Type aliases

### PoxAddressArgs

PoxAddressArgs: [version: Buffer, hashBytes: Buffer, network: "mainnet" | "testnet"] | [poxAddrClarityValue: ClarityValue , network: "mainnet" | "testnet"]

- Defined in packages/stacking/src/utils.ts:117

### StackerInfo

StackerInfo: { stacked: false } | { details: { amount_microstx: string; first_reward_cycle: number; lock_period: number; pox_address: { hashbytes: Buffer; version: Buffer }; unlock_height: number }; stacked: true }

- Defined in packages/stacking/src/index.ts:44

## Variables

### Const BitcoinNetworkVersion

BitcoinNetworkVersion: { mainnet: { P2PKH: 0; P2SH: 5 }; testnet: { P2PKH: 111; P2SH: 196 } } = ...

- Defined in packages/stacking/src/utils.ts:28

#### Type declaration

- ##### mainnet: { P2PKH: 0; P2SH: 5 }

  - ##### P2PKH: 0

  - ##### P2SH: 5

- ##### testnet: { P2PKH: 111; P2SH: 196 }

  - ##### P2PKH: 111

  - ##### P2SH: 196

## Functions

### btcAddressVersionToHashMode

- btcAddressVersionToHashMode(btcAddressVersion: number): AddressHashMode

- - Defined in packages/stacking/src/utils.ts:39

  #### Parameters

  - ##### btcAddressVersion: number

  #### Returns AddressHashMode

### decodeBtcAddress

- decodeBtcAddress(btcAddress: string): { data: Buffer; hashMode: AddressHashMode }

- - Defined in packages/stacking/src/utils.ts:80

  #### Parameters

  - ##### btcAddress: string

  #### Returns { data: Buffer; hashMode: AddressHashMode }

  - ##### data: Buffer

  - ##### hashMode: AddressHashMode

### extractPoxAddressFromClarityValue

- extractPoxAddressFromClarityValue(poxAddrClarityValue: ClarityValue ): { hashBytes: Buffer; version: Buffer }

- - Defined in packages/stacking/src/utils.ts:94

  #### Parameters

  - ##### poxAddrClarityValue: ClarityValue

  #### Returns { hashBytes: Buffer; version: Buffer }

  - ##### hashBytes: Buffer

  - ##### version: Buffer

### getAddressHashMode

- getAddressHashMode(btcAddress: string): AddressHashMode

- - Defined in packages/stacking/src/utils.ts:71

  #### Parameters

  - ##### btcAddress: string

  #### Returns AddressHashMode

### getBTCAddress

- getBTCAddress(version: Buffer, checksum: Buffer): string

- - Defined in packages/stacking/src/utils.ts:142

  #### Parameters

  - ##### version: Buffer

  - ##### checksum: Buffer

  #### Returns string

### getErrorString

- getErrorString(error: StackingErrors): string

- - Defined in packages/stacking/src/utils.ts:147

  #### Parameters

  - ##### error: StackingErrors

  #### Returns string

### hashModeToBtcAddressVersion

- hashModeToBtcAddressVersion(hashMode: AddressHashMode, network: "mainnet" | "testnet"): number

- - Defined in packages/stacking/src/utils.ts:54

  #### Parameters

  - ##### hashMode: AddressHashMode

  - ##### network: "mainnet" | "testnet"

  #### Returns number

### poxAddressToBtcAddress

- poxAddressToBtcAddress(...args: PoxAddressArgs ): string

- - Defined in packages/stacking/src/utils.ts:121

  #### Parameters

  - ##### Rest ...args: PoxAddressArgs

  #### Returns string

Generated using TypeDoc