Eligibility Preflights

Every state-changing PoX-5 entrypoint guards itself with a chain of asserts, and a failed assert costs the sender a transaction fee for nothing. @stacks/bitcoin-staking ships a fetchEligible* preflight for each entrypoint that rebuilds those asserts client-side from read-only fetches — no transaction, no fee, no signature. Run the preflight, and if it passes, build and broadcast; if it fails, you get the exact error codes the contract would return.

All examples use @stacks/bitcoin-staking for the PoX-5 surface.

The EligibilityResult contract

Every preflight resolves to the same shape:

type EligibilityResult =
  | { ok: true }
  | { ok: false; reasons: [Pox5ErrorCode, ...Pox5ErrorCode[]] };

On ok: false, reasons lists every gate that would fail — not just the first — as the contract's own error codes (Pox5ErrorCode), in the order the contract evaluates them. reasons[0] is the error the transaction would actually abort with; the rest tell you what would fail next once you've fixed it. The POX5_ERROR_NAMES and POX5_ERROR_DESCRIPTIONS maps translate each code to its Clarity constant name (e.g. ERR_NOT_ALLOWLISTED) and a human-readable description.

Two caveats apply across the whole family:

• Point-in-time. Timing gates (prepare phase, bond setup windows, bond start heights) are evaluated against the current burn height. A result that is true now can flip by the time your transaction is mined — treat a passing preflight near a cycle boundary with suspicion.
• Some gates can't be reproduced off-chain. The signer-manager's validate-stake! trait call, parts of the L1 SPV proof, and contract-caller construction concerns are only enforced on-chain (details per function below). A passing preflight is a strong signal, not a guarantee.

Preflights that need chain metadata accept an optional poxInfo (from fetchPoxInfo), so callers that already hold it avoid the extra round-trip.

Worked example: register-for-bond

fetchEligibleRegisterForBond takes the same identifying inputs you'd pass to buildRegisterForBond and checks the allowlist, timing, STX minimum and balance, signer registration and key grant, overlapping positions, and rollover window:

import { POX5_ERROR_NAMES, fetchEligibleRegisterForBond } from '@stacks/bitcoin-staking';

const network = 'mainnet';

const eligible = await fetchEligibleRegisterForBond({
  bondIndex: 4,
  staker: user.stxAddress, // the future tx-sender
  amountUstx: 150_000_000_000n,
  satsTotal: 100_000_000n, // sBTC amount, or summed L1 lockup outputs
  signerManager: 'SP000…USER.signer-manager',
  network,
});

if (!eligible.ok) {
  // reasons[0] is what the tx would actually abort with
  const named = eligible.reasons.map(code => `${POX5_ERROR_NAMES[code]} (u${code})`);
  throw new Error(`register-for-bond would fail: ${named.join(', ')}`);
}

// Safe to buildRegisterForBond(...) with the same inputs and broadcast.

When registering with an L1 lockup (kind: 'btc'), also pass the lockup outputs — this enables the unlock-height (u52), duplicate-outpoint (u46), and block-header (u40) SPV checks. Pass the summed output sats as satsTotal regardless. The merkle proof (u41), output script (u42), amount (u45), and tx-parse (u39) legs of the proof are verified only on-chain.

In simpler flows a one-line guard before the builder call is enough:

const eligible = await fetchEligibleUnstake({ staker: user.stxAddress, oldSignerManager, network });
if (!eligible.ok) throw new Error('unstake would fail: u' + eligible.reasons.join(', u'));

The full family

Each preflight gates exactly one entrypoint:

What preflights can't see

A few gates live outside what read-only fetches can reproduce; a passing preflight does not clear them:

• validate-stake! — register-for-bond, update-bond-registration, stake, and stake-update all call into the signer-manager contract, which may reject the transaction on its own logic (allowlisting, capacity, fees). See Signers for how managers own approval.
• Caller-construction gates — announce-l1-early-exit requires contract-caller == tx-sender == staker (send it directly from the staker, never through an intermediary contract), and grant-signer-key requires contract-caller == signerManager (the signer-manager contract submits it itself). These fail at the contract regardless of what the preflight says about state.
• Token transfers — unstake-sbtc and claim-rewards move sBTC the contract already custodies, so the transfer itself isn't checked.
• L1 SPV proof legs — for register-for-bond with outputs, the merkle proof, output script, amount, and tx-parse checks run only on-chain.

A few behavioral notes worth knowing:

• fetchEligibleStakeUpdate reports a lock period ≤ 0 as INVALID_NUM_CYCLES, though on-chain a negative result is a uint underflow (runtime abort) rather than that error code.
• fetchEligibleGrantSignerKey collapses the contract's ERR_INVALID_SIGNATURE_RECOVER (u13) (malformed signature) and ERR_INVALID_SIGNATURE_PUBKEY (u14) (recovers to a different key) into the latter.
• fetchEligibleClaimRewards takes a reward cycle, not a distribution-cycle index — passing the wrong cycle yields 0 earned and a NO_CLAIMABLE_REWARDS result rather than an error.