fetchBondL1UnlockHeight

Calls the pox-5 get-bond-l1-unlock-height read-only and returns the minimum Bitcoin block height that a protocol bond's L1 lockup script may use as its CLTV unlock height.

---

Usage

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

const unlockHeight = await fetchBondL1UnlockHeight({ bondIndex: 1, network: 'mainnet' }); // bigint

Notes

• get-bond-l1-unlock-height computes the burn height at which the bond's 12 reward cycles end, minus half a reward cycle length (1,050 Bitcoin blocks on mainnet). It reads no map, so it returns a height for a bond index that has not been set up.

• register-for-bond fails with ERR_INVALID_UNLOCK_HEIGHT (u52) for an L1 lockup output whose unlock height is below this value, or at or above 500,000,000 (L2074-L2079).

• computeBondUnlockHeight computes the same height locally from a PoxInfo, with no request, and returns a number.

• 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 fetchBondL1UnlockHeight(
  opts: { bondIndex: number } & NetworkClientParam
): Promise<bigint>;

opts is a NetworkClientParam plus bondIndex.

---

Returns

Promise<bigint>

The minimum L1 unlock height for the bond, as a Bitcoin block height.

---

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.