> For the complete documentation index, see [llms.txt](https://docs.stacks.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacks.co/reference/stacks.js/stacks-bitcoin-staking/build/buildstake.md). # buildStake Builds an unsigned contract call to pox-5 `stake`, which locks the sender's STX in the STX-only staking tranche under a signer-manager. The lock starts at the next reward cycle and lasts `numCycles` reward cycles. *** ### Usage ```ts import { buildStake, fetchEligibleStake, fetchPoxInfo } from '@stacks/bitcoin-staking'; import { Pc, TransactionSigner, broadcastTransaction, fetchNonce, privateKeyToAddress, privateKeyToPublic, publicKeyToHex, } from '@stacks/transactions'; const network = 'mainnet'; const privateKey = process.env.STAKER_KEY!; const staker = privateKeyToAddress(privateKey, network); const signerManager = 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.my-signer-manager'; const amountUstx = 1_000_000_000n; // 1,000 STX in micro-STX const numCycles = 6; const poxInfo = await fetchPoxInfo({ network }); const startBurnHt = poxInfo.currentBurnchainBlockHeight; const check = await fetchEligibleStake({ staker, signerManager, amountUstx, numCycles, startBurnHt, poxInfo, network, }); if (!check.ok) throw new Error(`stake would fail: ${check.reasons}`); const tx = await buildStake({ signerManager, amountUstx, numCycles, startBurnHt, publicKey: publicKeyToHex(privateKeyToPublic(privateKey)), fee: 10_000n, // micro-STX nonce: await fetchNonce({ address: staker, network }), network, postConditions: [Pc.principal(staker).willSendEq(amountUstx).ustxToLock()], }); new TransactionSigner(tx).signOrigin(privateKey); const result = await broadcastTransaction({ transaction: tx, network }); ``` #### Notes * Send it during the reward phase of any cycle, which excludes its last `prepareCycleLength` Bitcoin blocks (100 on mainnet), the prepare phase. In the prepare phase it fails with `ERR_STAKE_IN_PREPARE_PHASE (u47)` ([pox-5.clar L976-L1086](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L976-L1086)). * `startBurnHt` must be a Bitcoin block height in the current reward cycle: pox-5 requires the cycle after it to be the next reward cycle and fails with `ERR_INVALID_START_BURN_HEIGHT (u24)` otherwise. A transaction that confirms in a later cycle than `startBurnHt` fails the same way. * `numCycles` must be 1 to 96 (`ERR_INVALID_NUM_CYCLES (u20)`, [L3315-L3320](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3315-L3320)). * The signer-manager must be registered (`ERR_SIGNER_NOT_FOUND (u23)`) with an active signer key grant (`ERR_SIGNER_KEY_GRANT_NOT_FOUND (u17)`). Its `validate-stake!` can reject the stake with its own error code. * An active STX-only stake fails with `ERR_ALREADY_STAKED (u19)`: change it with [buildStakeUpdate](/reference/stacks.js/stacks-bitcoin-staking/build/buildstakeupdate.md). A bond membership whose 12-cycle term has not ended by the next reward cycle fails with the same code. Rolling over from an ending bond is allowed only from half a reward cycle before that bond ends (`ERR_ROLLOVER_TOO_EARLY (u48)`). * The sender's total STX balance, locked plus unlocked, must cover `amountUstx` (`ERR_INSUFFICIENT_STX (u8)`). * [fetchEligibleStake](/reference/stacks.js/stacks-bitcoin-staking/eligibility/fetcheligiblestake.md) dry-runs every check except the signer-manager's `validate-stake!`. * pox-5 never calls `stx-transfer?`: the node applies the lock. Attach a staking post condition for `amountUstx` with `ustxToLock()`, as in the Usage example. Without it, the default `deny` mode aborts the transaction with `abort_by_post_condition`. * A rollover from an sBTC-backed bond refunds all sBTC that pox-5 custodies for that bond, from pox-5's principal (`poxInfo.contractId`) to the sender ([L1051-L1054](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1051-L1054)). Read the amount with [fetchStakerCustodiedSbtc](/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchstakercustodiedsbtc.md) and, in `deny` mode, add `Pc.principal(poxInfo.contractId).willSendEq(custodied).ft(poxInfo.sbtcContract, 'sbtc-token')` for it. * A txid from [broadcastTransaction](/reference/stacks.js/stacks-transactions/network/broadcasttransaction.md) confirms submission only. The call can still fail on-chain: read the mined transaction's result and pass an `(err uN)` to [parsePox5Error](/reference/stacks.js/stacks-bitcoin-staking/errors/parsepox5error.md). [**Reference Link**](https://github.com/stx-labs/stacks.js/blob/6101c99efe5a9616ce7e16cef68e28fd10676e7e/packages/bitcoin-staking/src/build.ts#L433-L479) *** ### Signature ```ts function buildStake( args: { signerManager: string; amountUstx: IntegerType; numCycles: number; startBurnHt: number; signerCalldata?: Uint8Array | string; } & TxParams ): Promise; ``` The transaction fields come from [TxParams](/reference/stacks.js/stacks-bitcoin-staking/types/txparams.md). *** ### Returns `Promise` Resolves to an unsigned [StacksTransactionWire](/reference/stacks.js/stacks-transactions/signing/stackstransactionwire.md) that calls pox-5 `stake`. Sign it with [TransactionSigner](/reference/stacks.js/stacks-transactions/signing/transactionsigner.md), then send it with [broadcastTransaction](/reference/stacks.js/stacks-transactions/network/broadcasttransaction.md). *** ### Parameters #### args.signerManager (required) * **Type**: `string` Contract principal of the signer-manager, which implements `signer-manager-trait`. #### args.amountUstx (required) * **Type**: `IntegerType` STX to lock, in micro-STX. #### args.numCycles (required) * **Type**: `number` Reward cycles to lock for, 1 to 96. #### args.startBurnHt (required) * **Type**: `number` A Bitcoin block height in the current reward cycle. pox-5 uses it as a replay guard. `poxInfo.currentBurnchainBlockHeight` from [fetchPoxInfo](/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchpoxinfo.md) works. #### args.signerCalldata (optional) * **Type**: `Uint8Array | string` Up to 500 bytes, as bytes or hex, that pox-5 forwards unread to the signer-manager's `validate-stake!`. Omitted, the contract receives `none`. [buildSignerCalldata](/reference/stacks.js/stacks-bitcoin-staking/signer/buildsignercalldata.md) encodes an L1 BTC payout election for signer-managers that read that format. #### args.fee (required) * **Type**: `IntegerType` Transaction fee in micro-STX. #### args.nonce (required) * **Type**: `IntegerType` Nonce of the origin account. Read it with [fetchNonce](/reference/stacks.js/stacks-transactions/network/fetchnonce.md). #### args.network (required) * **Type**: `StacksNetworkName | StacksNetwork` A name such as `'mainnet'` or `'testnet'`, or a [StacksNetwork](/reference/stacks.js/stacks-network/network/stacksnetwork.md) object. Sets the contract address (the network's boot address, `SP000000000000000000002Q6VF78` on mainnet) and the transaction version and chain ID. #### args.publicKey (required for a single-sig origin) * **Type**: `string` Hex public key of the account that signs the transaction. #### args.publicKeys and args.numSignatures (required for a multisig origin) * **Type**: `PublicKey[]` and `number` Pass these instead of `publicKey` to build for an M-of-N multisig origin. This package defaults `useNonSequentialMultiSig` to `true`; pass `false` for the sequential hash mode. Pass `address` to check the key order against the multisig address. #### args.postConditions (optional) * **Type**: `PostCondition[]` [Post conditions](/reference/stacks.js/stacks-transactions/types/postcondition.md) to attach. The builder adds none. #### args.postConditionMode (optional) * **Type**: `PostConditionModeName` `'allow'`, `'deny'` or `'originator'`. Defaults to `'deny'`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.stacks.co/reference/stacks.js/stacks-bitcoin-staking/build/buildstake.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.