buildSetPauseAdmin

Builds an unsigned contract call to pox-5 set-pause-admin, which hands the pause-admin role to a new principal. The pause-admin is the only principal that can stop signer reward claims with buildPauseRewards.

---

Usage

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

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

if ((await fetchPauseAdmin({ network: 'mainnet' })) !== address) {
  throw new Error('this key is not the current pause-admin');
}

const tx = await buildSetPauseAdmin({
  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 pause-admin can call it. pox-5 compares contract-caller with the pause-admin data-var and fails with ERR_UNAUTHORIZED (u1) otherwise (pox-5.clar L470-L484). Read the current holder with fetchPauseAdmin.

• 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 buildSetPauseAdmin(args: BuildSetPauseAdminArgs & TxParams): Promise<StacksTransactionWire>;

args combines BuildSetPauseAdminArgs with TxParams.

---

Returns

Promise<StacksTransactionWire>

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

---

Parameters

args.newAdmin (required)

• Type: string

Stacks principal to install as the new pause-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'.