fetchTotalSbtcStakedForBond

Calls the pox-5 get-total-sbtc-staked-for-bond read-only and returns the total sats recorded for a protocol bond.

---

Usage

import { fetchTotalSbtcStakedForBond } from '@stacks/bitcoin-staking';

const totalSats = await fetchTotalSbtcStakedForBond({ bondIndex: 1, network: 'mainnet' }); // sats, as a bigint

Notes

• Reads the protocol-bonds-total-staked map through get-total-sbtc-staked-for-bond. Returns 0n when there is no entry.
• The total counts sats from Bitcoin L1 lockups and from sBTC alike: register-for-bond adds the registration's sats whichever path the staker used (L673-L676).
• register-for-bond sets the value to the bond's first-cycle share total plus the new registration's sats (L704-L706, L793-L795). announce-l1-early-exit (L1238-L1240) and unstake-sbtc (L1312-L1315) subtract the sats they release.
• For the bond's share total in a specific reward cycle, the figure pox-5 uses when it computes rewards, call fetchTotalSharesStakedForCycle with bondIndex.
• Throws an Error if the node returns a non-2xx status (the message starts with Error calling read-only function.) or answers okay: false (the message is the node's cause).

Reference Link

---

Signature

function fetchTotalSbtcStakedForBond(
  opts: { bondIndex: number } & NetworkClientParam
): Promise<bigint>;

opts is a NetworkClientParam plus bondIndex.

---

Returns

Promise<bigint>

Total sats recorded for the bond.

---

Parameters

opts.bondIndex (required)

• Type: number

Index of the protocol bond.

opts.network (optional)

• Type: StacksNetworkName | StacksNetwork

The network to query: a name such as 'mainnet' or 'testnet', or a StacksNetwork object. Defaults to 'mainnet'.

opts.client (optional)

• Type: { baseUrl?: string; fetch?: FetchFn }

Overrides the API base URL or the fetch function, for example to query your own node. Fields you set replace the network's defaults.