buildAnnounceL1EarlyExit

Builds an unsigned contract call to pox-5 announce-l1-early-exit, which tells pox-5 that a staker has left their L1 BTC lockup early. pox-5 stops counting the staker's BTC for the rest of the bond; their STX stays locked.

---

Usage

import {
  buildAnnounceL1EarlyExit,
  fetchBondMembership,
  fetchEligibleAnnounceL1EarlyExit,
} from '@stacks/bitcoin-staking';
import {
  Pc,
  TransactionSigner,
  broadcastTransaction,
  fetchNonce,
  privateKeyToAddress,
  privateKeyToPublic,
  publicKeyToHex,
} from '@stacks/transactions';

const network = 'mainnet';
const privateKey = process.env.STAKER_KEY!;
const staker = privateKeyToAddress(privateKey, network);

const membership = await fetchBondMembership({ address: staker, network });
if (!membership?.isL1Lock) throw new Error('no active L1 bond membership');
const oldSignerManager = membership.signer;

const check = await fetchEligibleAnnounceL1EarlyExit({ staker, oldSignerManager, network });
if (!check.ok) throw new Error(`announce-l1-early-exit would fail: ${check.reasons}`);

const tx = await buildAnnounceL1EarlyExit({
  staker,
  oldSignerManager,
  publicKey: publicKeyToHex(privateKeyToPublic(privateKey)),
  fee: 10_000n, // micro-STX
  nonce: await fetchNonce({ address: staker, network }),
  network,
  postConditions: [Pc.principal(staker).willPerformPox()],
});

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

Notes

• The staker must send it. pox-5 requires contract-caller, tx-sender and staker to be the same principal, so a call forwarded through another contract also fails with ERR_UNAUTHORIZED (u1) (pox-5.clar L1175-L1257).
• Only for a membership backed by an L1 lockup (isL1Lock): an sBTC-backed membership fails with ERR_CANNOT_ANNOUNCE_L1_EARLY_UNLOCK (u35) and withdraws with buildUnstakeSbtc instead.
• Also fails with ERR_NOT_BOND_PARTICIPANT (u34) when the staker has no bond membership or its bond has ended, ERR_STAKE_IN_PREPARE_PHASE (u47) in the last prepareCycleLength Bitcoin blocks of a reward cycle (100 on mainnet), and ERR_INVALID_OLD_SIGNER_MANAGER (u36) when oldSignerManager is not the bound signer-manager.
• A second announcement for the same bond fails with ERR_L1_EARLY_EXIT_ALREADY_ANNOUNCED (u50). Check with fetchHasAnnouncedL1EarlyExit.
• fetchEligibleAnnounceL1EarlyExit dry-runs every check except the caller check.
• On success, pox-5 settles the staker's rewards, then sets their bond shares to zero from the current reward cycle, or the bond's first reward cycle if it has not started, through the end of the bond, reduces the bond totals by the same sats, and sets the membership's amount-sats to 0. The locked STX is untouched and unlocks on the bond's normal schedule.
• announce-l1-early-exit is a position-altering PoX action for the sender (pox_5.rs). In the default deny mode, and in originator mode, the node aborts the transaction unless it carries a PoX post condition for the sender, such as Pc.principal(staker).willPerformPox() (node check). No Stacks asset moves, so no other post condition is needed.
• 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 buildAnnounceL1EarlyExit(
  args: {
    staker: string;
    oldSignerManager: string;
  } & TxParams
): Promise<StacksTransactionWire>;

The transaction fields come from TxParams.

---

Returns

Promise<StacksTransactionWire>

Resolves to an unsigned StacksTransactionWire that calls pox-5 announce-l1-early-exit. Sign it with TransactionSigner, then send it with broadcastTransaction.

---

Parameters

args.staker (required)

• Type: string

Stacks address of the staker. It must be the address that signs the transaction.

args.oldSignerManager (required)

• Type: string

Contract principal of the signer-manager the membership is bound to. fetchBondMembership returns it as signer.

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