buildRegisterMetadata

Derives the lockup address, witness script, output script, staker subscript and unlock height for a paired-BTC register-for-bond in one call. Combines computeBondUnlockHeight, buildUnlockScript and buildLockScript. Pure computation: no network call.

---

Usage

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

const bondIndex = 2;
const poxInfo = await fetchPoxInfo({ network: 'mainnet' });
const bond = await fetchBond({ bondIndex, network: 'mainnet' });
if (!bond) throw new Error(`bond ${bondIndex} is not set up`);

const meta = buildRegisterMetadata({
  bondIndex,
  poxInfo,
  bitcoinPublicKey: '02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc',
  stxAddress: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
  earlyUnlockBytes: bond.earlyUnlockBytes,
  network: 'mainnet',
});

meta.lockAddress; // send the sats to lock here
meta.unlockHeight; // 994700 for mainnet bond 2

Notes

• The unlock height is the bond's minimum, from computeBondUnlockHeight. To commit to a later height, build the pieces with buildUnlockScript, buildLockScript and buildLockAddress.

• Throws in the same cases as computeBondUnlockHeight, buildUnlockScript and buildLockScript.

• After the funding transaction confirms, pass meta.lockScript and meta.unlockHeight to buildLockProof or buildLockProofFromBlock, then pass the proof and meta.unlockBytes to buildRegisterForBond as lockup: { kind: 'btc', outputs: [proof], unlockBytes: meta.unlockBytes }.

• Store meta.lockScript. buildReclaim needs it to spend the lockup.

• The address encoding follows network: bc on 'mainnet', tb on 'testnet', bcrt on 'devnet' and 'mocknet'.

Reference Link

---

Signature

function buildRegisterMetadata(opts: {
  bondIndex: number;
  poxInfo: PoxInfo;
  bitcoinPublicKey: Uint8Array | string;
  stxAddress: string;
  earlyUnlockBytes: Uint8Array | string;
  network: StacksNetworkName | StacksNetwork;
  validateEarlyUnlockBytes?: boolean;
}): RegisterMetadata;

---

Returns

RegisterMetadata

A RegisterMetadata.

---

Parameters

opts.bondIndex (required)

• Type: number

The bond period index to register for.

opts.poxInfo (required)

• Type: PoxInfo

The result of fetchPoxInfo, used to compute the unlock height.

opts.bitcoinPublicKey (required)

• Type: Uint8Array | string

The staker's 33-byte compressed public key, as bytes or hex. It signs the reclaim of the lockup.

opts.stxAddress (required)

• Type: string

The staker's Stacks principal, standard or contract. It must be the address that sends register-for-bond.

opts.earlyUnlockBytes (required)

• Type: Uint8Array | string

The bond's early-unlock subscript, as bytes or hex. Read it from fetchBond.

opts.network (required)

• Type: StacksNetworkName | StacksNetwork

The network whose Bitcoin address encoding to use: a name such as 'mainnet' or 'testnet', or a StacksNetwork object.

opts.validateEarlyUnlockBytes (optional)

• Type: boolean

Set to false to skip the shape check on earlyUnlockBytes. The structural check still runs. Defaults to true.