buildPauseRewards

Builds an unsigned contract call to pox-5 pause-rewards, which permanently stops signers from claiming rewards.

---

Usage

import { buildPauseRewards, fetchRewardsPaused } 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 fetchRewardsPaused({ network: 'mainnet' }))) {
  const tx = await buildPauseRewards({
    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 L486-L497). Read the current holder with fetchPauseAdmin.

• Nothing in pox-5 sets rewards-paused back to false. The contract's comment states that rewards keep accumulating in the contract and that recovery requires a hard fork.

• After the pause, every claim-rewards call fails with ERR_REWARDS_PAUSED (u53) (L2404). claim-rewards is the only function that reads the flag, so calculate-rewards and claim-staker-rewards-for-signer keep running. Read the flag with fetchRewardsPaused.

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

args is a TxParams.

---

Returns

Promise<StacksTransactionWire>

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

---

Parameters

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'.