> 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/buildcalculaterewards.md).

# buildCalculateRewards

Builds an unsigned contract call to pox-5 `calculate-rewards`, which splits the sBTC rewards pox-5 received since the last calculation between the protocol bond tranche, the reserve fund tranche and the STX-only staking tranche. Anyone can send it.

***

### Usage

```ts
import {
  buildCalculateRewards,
  fetchBond,
  fetchEligibleCalculateRewards,
} from '@stacks/bitcoin-staking';
import {
  TransactionSigner,
  broadcastTransaction,
  fetchNonce,
  privateKeyToAddress,
  privateKeyToPublic,
  publicKeyToHex,
} from '@stacks/transactions';

const network = 'mainnet';
const privateKey = process.env.SENDER_KEY!;
const address = privateKeyToAddress(privateKey, network);

// Every bond active at the calculation height, highest stxValueRatio first,
// lower bond index first on a tie.
const candidates = [0, 1, 2]; // bond indices that may still be active
const bonds = await Promise.all(
  candidates.map(async bondIndex => ({ bondIndex, bond: await fetchBond({ bondIndex, network }) }))
);
const bondIndices = bonds
  .filter(b => b.bond !== undefined)
  .sort((a, b) =>
    a.bond!.stxValueRatio === b.bond!.stxValueRatio
      ? a.bondIndex - b.bondIndex
      : Number(b.bond!.stxValueRatio - a.bond!.stxValueRatio)
  )
  .map(b => b.bondIndex);

const check = await fetchEligibleCalculateRewards({ bondIndices, network });
if (!check.ok) throw new Error(`calculate-rewards would fail: ${check.reasons}`);

const tx = await buildCalculateRewards({
  bondIndices,
  publicKey: publicKeyToHex(privateKeyToPublic(privateKey)),
  fee: 10_000n, // micro-STX
  nonce: await fetchNonce({ address, network }),
  network,
});

new TransactionSigner(tx).signOrigin(privateKey);
const result = await broadcastTransaction({ transaction: tx, network });
```

#### Notes

* Succeeds at most once per distribution cycle, half a reward cycle (1,050 Bitcoin blocks on mainnet). pox-5 settles up to the calculation height, the block before the current distribution cycle began, and fails with `ERR_DISTRIBUTION_ALREADY_COMPUTED (u30)` if that height is already settled ([pox-5.clar L2158-L2240](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2158-L2240)).
* `bondIndices` must include every bond active at the calculation height (`ERR_ACTIVE_BOND_NOT_INCLUDED (u33)`, [L2616-L2676](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2616-L2676)). Each listed bond must exist (`ERR_BOND_NOT_FOUND (u7)`) and be active (`ERR_BOND_NOT_ACTIVE (u31)`). A bond is active after its start height, up to and including the height 12 reward cycles later ([L3027-L3041](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3027-L3041)).
* Order `bondIndices` by descending `stxValueRatio`, and by ascending bond index on a tie (`ERR_INVALID_BOND_PERIOD_ORDERING (u29)`, [L2284-L2299](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2284-L2299)). pox-5 accepts at most 6 entries; the builder does not check the count.
* This package has no helper that lists the active bonds. Read candidates with [fetchBond](/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchbond.md), and dry-run the list with [fetchEligibleCalculateRewards](/reference/stacks.js/stacks-bitcoin-staking/eligibility/fetcheligiblecalculaterewards.md).
* In list order, each bond receives up to its target for the period, `totalSats * targetRateBps / 10000 / 50`, out of the new rewards ([L2264-L2272](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2264-L2272)). 15% of what remains (`RESERVE_RATIO`, 1,500 basis points) goes to the reserve, and the rest to STX-only stakers of the reward cycle that contains the calculation height. With no STX staked in that cycle, their share also goes to the reserve. See [Rewards and tranches](https://docs.stacks.co/learn/bitcoin-staking/rewards-and-tranches).
* The call updates pox-5's bookkeeping and moves no asset, so it needs no post conditions.
* 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#L583-L622)

***

### Signature

```ts
function buildCalculateRewards(
  args: {
    bondIndices: number[];
  } & TxParams
): Promise<StacksTransactionWire>;
```

The transaction fields come from [TxParams](/reference/stacks.js/stacks-bitcoin-staking/types/txparams.md).

***

### Returns

`Promise<StacksTransactionWire>`

Resolves to an unsigned [StacksTransactionWire](/reference/stacks.js/stacks-transactions/signing/stackstransactionwire.md) that calls pox-5 `calculate-rewards`. 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.bondIndices (required)

* **Type**: `number[]`

Every bond active at the calculation height, at most 6, sorted by descending `stxValueRatio` and ascending bond index on a tie.

#### 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/buildcalculaterewards.md?ask=<question>&goal=<user_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.