fetchBond

Reads a protocol bond's configuration from the pox-5 protocol-bonds map, or returns undefined if setup-bond has not been called for that index.

---

Usage

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

const bond = await fetchBond({ bondIndex: 1, network: 'mainnet' });

if (bond) {
  bond.targetRateBps; // target rate in basis points
  bond.earlyUnlockBytes; // hex, pass to buildLockScript or fetchConstructLockupScript
}

Notes

• Reads the protocol-bonds map through the node's /v2/map_entry endpoint. fetchProtocolBond returns the same data through the get-protocol-bond read-only.

• The result has no start height or first reward cycle. Both follow from bondIndex and the PoX parameters: compute them with bondPeriodToBurnHeight and bondPeriodToRewardCycle.

• earlyUnlockBytes is the bond's early-unlock subscript as a hex string without a 0x prefix. It is one of the inputs to the L1 lockup script: see buildLockScript.

• A non-2xx response, or a response without data, throws an Error whose message starts with Error fetching map entry for map "protocol-bonds".

Reference Link

---

Signature

function fetchBond(
  opts: { bondIndex: number } & NetworkClientParam
): Promise<Bond | undefined>;

opts is a NetworkClientParam plus bondIndex.

---

Returns

Promise<Bond | undefined>

Resolves to a Bond, or undefined when the map has no entry for bondIndex.

---

Parameters

opts.bondIndex (required)

• Type: number

Index of the protocol bond, the map key.

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.