buildSetBondAdmin

Builds an unsigned contract call to pox-5 set-bond-admin, which hands the bond-admin role to a new principal. The bond-admin is the only principal that can set up protocol bonds with buildSetupBond.

---

Usage

import { buildSetBondAdmin, fetchEligibleSetBondAdmin } from '@stacks/bitcoin-staking';
import {
  TransactionSigner,
  broadcastTransaction,
  fetchNonce,
  privateKeyToAddress,
  privateKeyToPublic,
  publicKeyToHex,
} from '@stacks/transactions';

const privateKey = process.env.BOND_ADMIN_KEY!; // key of the current bond-admin
const address = privateKeyToAddress(privateKey, 'mainnet');

const check = await fetchEligibleSetBondAdmin({ caller: address, network: 'mainnet' });
if (!check.ok) throw new Error(`set-bond-admin would fail: ${check.reasons}`);

const tx = await buildSetBondAdmin({
  newAdmin: 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
  publicKey: publicKeyToHex(privateKeyToPublic(privateKey)),
  fee: 10_000n, // micro-STX
  nonce: await fetchNonce({ address, network: 'mainnet' }),
  network: 'mainnet',
});

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

Notes

• Only the current bond-admin can call it. pox-5 compares contract-caller with the bond-admin data-var and fails with ERR_UNAUTHORIZED (u1) otherwise (pox-5.clar L451-L467). Read the current holder with fetchBondAdmin.

• The new admin holds the role as soon as the transaction succeeds and does not have to accept it. If newAdmin is wrong, only that principal can rotate the role again.

• No asset moves, so the call needs no post conditions.

• A txid from broadcastTransaction confirms submission only. The call can still fail on-chain: read the mined transaction's result and pass an (err uN) to parsePox5Error.

Reference Link

---

Signature

function buildSetBondAdmin(args: BuildSetBondAdminArgs & TxParams): Promise<StacksTransactionWire>;

args combines BuildSetBondAdminArgs with TxParams.

---

Returns

Promise<StacksTransactionWire>

Resolves to an unsigned StacksTransactionWire that calls pox-5 set-bond-admin. Sign it with TransactionSigner, then send it with broadcastTransaction.

---

Parameters

args.newAdmin (required)

• Type: string

Stacks principal to install as the new bond-admin, standard or contract. To hand the role to a multisig, pass the multisig's address.

args.fee (required)

• Type: IntegerType

Transaction fee in micro-STX.

args.nonce (required)

• Type: IntegerType

Nonce of the origin account. Read it with fetchNonce.

args.network (required)

• Type: StacksNetworkName | StacksNetwork

A name such as 'mainnet' or 'testnet', or a StacksNetwork 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 to attach. The builder adds none.

args.postConditionMode (optional)

• Type: PostConditionModeName

'allow', 'deny' or 'originator'. Defaults to 'deny'.