@secondlayer/stacks 4.1.0 → 4.3.0

package/dist/src/pox5/index.d.ts

@@ -350,167 +350,6 @@ declare const C_SCRIPT_NUM_MAX = 549755813888n;
 * commit a height Bitcoin would reinterpret.
 */
 declare const BITCOIN_LOCKTIME_THRESHOLD = 500000000n;
-/**
-* Pure cycle/height math, mirroring the pox-5 helper read-onlys byte-for-byte
-* (`burn-height-to-reward-cycle`, `reward-cycle-to-burn-height`,
-* `bond-period-to-reward-cycle`, `burn-height-to-distribution-index`).
-*
-* All functions anchor on chain-reported parameters — pass values from
-* `/v2/pox` (`first_burnchain_block_height`, `reward_cycle_length`,
-* `prepare_cycle_length`) and `getPox5Activation` (`firstRewardCycleId` =
-* the contract's `first-bond-period-cycle`). Nothing is hardcoded, so the
-* math is correct on mainnet, testnet, and devnet alike.
-*/
-type PoxCycleParams = {
-	/** `/v2/pox` `first_burnchain_block_height`. */
-	firstBurnchainBlockHeight: number
-	/** `/v2/pox` `reward_cycle_length` (mainnet 2100). */
-	rewardCycleLength: number
-};
-type BondCycleParams = PoxCycleParams & {
-	/** pox-5's first bond-period cycle (`getPox5Activation().firstRewardCycleId`). */
-	firstBondPeriodCycle: number
-};
-/** Reward cycle containing `burnHeight`. Mirrors `burn-height-to-reward-cycle`. */
-declare function burnHeightToRewardCycle(burnHeight: number, params: PoxCycleParams): number;
-/** Burn height at the start of `cycle`. Mirrors `reward-cycle-to-burn-height`. */
-declare function rewardCycleToBurnHeight(cycle: number, params: PoxCycleParams): number;
-/** Reward cycle at which bond period `bondIndex` starts. Mirrors `bond-period-to-reward-cycle`. */
-declare function bondPeriodToRewardCycle(bondIndex: number, params: BondCycleParams): number;
-/** Burn height at which bond period `bondIndex` starts. Mirrors `bond-period-to-burn-height`. */
-declare function bondPeriodToBurnHeight(bondIndex: number, params: BondCycleParams): number;
-/** First reward cycle in which bond `bondIndex`'s STX unlock (start + 12 cycles). */
-declare function bondUnlockCycle(bondIndex: number, params: BondCycleParams): number;
-/**
-* Distribution-cycle index at `burnHeight` — distribution cycles are half a
-* reward cycle long. Mirrors `burn-height-to-distribution-index`.
-*/
-declare function burnHeightToDistributionIndex(burnHeight: number, params: PoxCycleParams): number;
-/**
-* Whether `burnHeight` falls in a cycle's prepare phase (the final
-* `prepareCycleLength` blocks). pox-5 rejects `unstake-sbtc` and
-* `announce-l1-early-exit` during a prepare phase.
-*/
-declare function isInPreparePhase(burnHeight: number, params: PoxCycleParams & {
-	prepareCycleLength: number
-}): boolean;
-type BondPhase = "too-early" | "open" | "locked" | "unlocked";
-/**
-* Coarse lifecycle phase of bond `bondIndex` at `burnHeight`: `too-early`
-* (before the bond's start is registerable), `open`/`locked` while active,
-* `unlocked` after 12 cycles.
-*/
-declare function bondPhaseAtHeight(bondIndex: number, burnHeight: number, params: BondCycleParams): BondPhase;
-type BitcoinNetwork = "mainnet" | "testnet" | "regtest";
-/**
-* Byte-for-byte TypeScript mirrors of pox-5's Bitcoin-script helpers
-* (`serialize-c-script-num`, `push-c-script-num`, `push-script-bytes`,
-* `construct-lockup-script`, `construct-lockup-output-script`), pinned
-* against the final contract in stacks-core 4.0.1. The contract validates a
-* staker's L1 lockup output against exactly these bytes, so any divergence
-* means a rejected registration — the read-onlys on-chain double as a
-* cross-check oracle for these functions.
-*/
-/**
-* Minimal little-endian ScriptNum encoding of a non-negative integer
-* (`0` → empty; a `0x00` sign byte is appended when the top byte's high bit
-* is set). Mirrors `serialize-c-script-num`, including its 2^39 ceiling.
-*/
-declare function serializeCScriptNum(n: number | bigint): Uint8Array;
-/**
-* Push arbitrary bytes onto a Bitcoin script: direct length byte under 76,
-* `OP_PUSHDATA1` under 256, `OP_PUSHDATA2` otherwise. Mirrors
-* `push-script-bytes`.
-*/
-declare function pushScriptBytes(bytes: Uint8Array): Uint8Array;
-/**
-* Push a numeric script value: `OP_0` for zero, the single-byte ops
-* `OP_1`..`OP_16` for 1–16, else a minimal ScriptNum push. Mirrors
-* `push-c-script-num`.
-*/
-declare function pushCScriptNum(n: number | bigint): Uint8Array;
-/** `to-consensus-buff?` of a principal — the staker identity the script commits to. */
-declare function stakerConsensusBuff(stxAddress: string): Uint8Array;
-/**
-* The 32-byte witness item the early-exit branch must reveal:
-* `sha256(to-consensus-buff? staker)`. The script stores `sha256` of THIS,
-* so revealing it proves which staker the exit is for.
-*/
-declare function stakerPreimage(stxAddress: string): Uint8Array;
-type BuildLockupScriptOptions = {
-	/** Staker principal (standard or contract address). */
-	stxAddress: string
-	/** Burn height at which the CLTV branch becomes spendable. */
-	unlockBurnHeight: number | bigint
-	/** Staker-signature subscript, run last in BOTH branches. */
-	stakerUnlockBytes: Uint8Array | string
-	/** Per-bond early-unlock subscript (from `protocol-bonds.early-unlock-bytes`). */
-	earlyUnlockBytes: Uint8Array | string
-};
-/**
-* The L1 lockup witness script. Mirrors `construct-lockup-script`:
-*
-* ```
-* OP_IF
-*   <unlockBurnHeight> OP_CHECKLOCKTIMEVERIFY
-* OP_ELSE
-*   OP_SIZE <32> OP_EQUALVERIFY OP_SHA256
-*   <sha256(sha256(consensus-buff(staker)))> OP_EQUALVERIFY
-*   <earlyUnlockBytes>
-* OP_ENDIF
-* OP_VERIFY
-* <stakerUnlockBytes>
-* ```
-*/
-declare function buildLockupScript(opts: BuildLockupScriptOptions): Uint8Array;
-/**
-* P2WSH `scriptPubKey` for a lockup script: `0x0020 || sha256(script)`.
-* Mirrors `construct-lockup-output-script`.
-*/
-declare function buildLockupOutputScript(opts: BuildLockupScriptOptions): Uint8Array;
-/** The bech32 P2WSH address a staker sends their L1 BTC lockup to. */
-declare function buildLockupAddress(opts: BuildLockupScriptOptions, network?: BitcoinNetwork): string;
-/**
-* The default staker subscript: `<pubkey> OP_CHECKSIG` — spendable by one
-* key. Any script tail is valid as far as the contract is concerned; this is
-* the common case.
-*/
-declare function buildDefaultStakerUnlockBytes(publicKey: Uint8Array | string): Uint8Array;
-/**
-* PoX-5 signer-key grants: SIP-018 structured-data signatures authorizing a
-* signer-manager contract to use a signer key. Mirrors
-* `pox-5.get-signer-grant-message-hash` — domain `pox-5-signer/1.0.0`,
-* message `{ topic: "grant-authorization", signer-manager, auth-id }`.
-*/
-type SignerGrantOptions = {
-	/** The signer-manager contract principal being authorized. */
-	signerManager: string
-	/** Replay-protection id, chosen by the signer. */
-	authId: bigint | number
-	/** Stacks chain id (`mainnet.id` / `testnet.id`). */
-	chainId: number
-};
-/**
-* The 32-byte hash a signer signs to grant their key — byte-identical to the
-* contract's `get-signer-grant-message-hash` read-only (which doubles as an
-* on-chain cross-check).
-*/
-declare function computeSignerGrantHash(opts: SignerGrantOptions): Uint8Array;
-/**
-* Sign a signer-key grant. Returns the 65-byte recoverable signature in RSV
-* order (recovery byte last), hex — the layout `grant-signer-key`'s
-* `signer-sig (buff 65)` expects.
-*/
-declare function signSignerGrant(account: LocalAccount, opts: SignerGrantOptions): Promise<string>;
-/**
-* Verify a signer-key grant signature locally: recover the pubkey from the
-* RSV signature over the grant hash and compare. Returns `false` for
-* malformed input rather than throwing.
-*/
-declare function verifySignerGrant(opts: SignerGrantOptions & {
-	publicKey: Uint8Array | string
-	signature: Uint8Array | string
-}): boolean;
 type IntegerType = number | string | bigint | Uint8Array;
 /**
 * Named fee tiers. `'low' | 'mid' | 'high'` map to the node's three fee
@@ -713,6 +552,462 @@ type RevokeSignerGrantParams = TxOptions & {
 	signerManager: string
 	signerKey: Uint8Array | string
 };
+type SetBondAdminParams = TxOptions & {
+	newAdmin: string
+};
+type SetPauseAdminParams = TxOptions & {
+	newAdmin: string
+};
+type PauseRewardsParams = TxOptions;
+type EligibilityResult = {
+	ok: true
+} | {
+	ok: false
+	reasons: [Pox5ErrorCode, ...Pox5ErrorCode[]]
+};
+type EligibleStakeParams = {
+	staker: string
+	signerManager: string
+	amountUstx: IntegerType
+	numCycles: IntegerType
+	startBurnHeight: IntegerType
+};
+type EligibleRegisterForBondParams = {
+	staker: string
+	bondIndex: IntegerType
+	signerManager: string
+	amountUstx: IntegerType
+	btcLockup: BtcLockup
+};
+type EligibleUnstakeParams = {
+	staker: string
+	oldSignerManager: string
+};
+type EligibleUnstakeSbtcParams = {
+	staker: string
+	signerManager: string
+	amountSats: IntegerType
+};
+type EligibleClaimRewardsParams = {
+	signer: string
+	rewardCycle: IntegerType
+	bondIndex?: IntegerType
+	bondPeriods?: IntegerType[]
+};
+type EligibleGrantSignerKeyParams = {
+	signerKey: Uint8Array | string
+	signerManager: string
+	authId: IntegerType
+};
+type EligibleAdminParams = {
+	caller: string
+};
+declare function eligibleStake2(client: Client, params: EligibleStakeParams): Promise<EligibilityResult>;
+declare function eligibleRegisterForBond2(client: Client, params: EligibleRegisterForBondParams): Promise<EligibilityResult>;
+declare function eligibleUnstake2(client: Client, params: EligibleUnstakeParams): Promise<EligibilityResult>;
+declare function eligibleUnstakeSbtc2(client: Client, params: EligibleUnstakeSbtcParams): Promise<EligibilityResult>;
+declare function eligibleClaimRewards2(client: Client, params: EligibleClaimRewardsParams): Promise<EligibilityResult>;
+declare function eligibleGrantSignerKey2(client: Client, params: EligibleGrantSignerKeyParams): Promise<EligibilityResult>;
+declare function eligibleSetBondAdmin2(client: Client, params: EligibleAdminParams): Promise<EligibilityResult>;
+declare function eligiblePauseRewards2(client: Client, params: EligibleAdminParams): Promise<EligibilityResult>;
+/**
+* Pure cycle/height math, mirroring the pox-5 helper read-onlys byte-for-byte
+* (`burn-height-to-reward-cycle`, `reward-cycle-to-burn-height`,
+* `bond-period-to-reward-cycle`, `burn-height-to-distribution-index`).
+*
+* All functions anchor on chain-reported parameters — pass values from
+* `/v2/pox` (`first_burnchain_block_height`, `reward_cycle_length`,
+* `prepare_cycle_length`) and `getPox5Activation` (`firstRewardCycleId` =
+* the contract's `first-bond-period-cycle`). Nothing is hardcoded, so the
+* math is correct on mainnet, testnet, and devnet alike.
+*/
+type PoxCycleParams = {
+	/** `/v2/pox` `first_burnchain_block_height`. */
+	firstBurnchainBlockHeight: number
+	/** `/v2/pox` `reward_cycle_length` (mainnet 2100). */
+	rewardCycleLength: number
+};
+type BondCycleParams = PoxCycleParams & {
+	/** pox-5's first bond-period cycle (`getPox5Activation().firstRewardCycleId`). */
+	firstBondPeriodCycle: number
+};
+/** Reward cycle containing `burnHeight`. Mirrors `burn-height-to-reward-cycle`. */
+declare function burnHeightToRewardCycle(burnHeight: number, params: PoxCycleParams): number;
+/** Burn height at the start of `cycle`. Mirrors `reward-cycle-to-burn-height`. */
+declare function rewardCycleToBurnHeight(cycle: number, params: PoxCycleParams): number;
+/** Reward cycle at which bond period `bondIndex` starts. Mirrors `bond-period-to-reward-cycle`. */
+declare function bondPeriodToRewardCycle(bondIndex: number, params: BondCycleParams): number;
+/** Burn height at which bond period `bondIndex` starts. Mirrors `bond-period-to-burn-height`. */
+declare function bondPeriodToBurnHeight(bondIndex: number, params: BondCycleParams): number;
+/** First reward cycle in which bond `bondIndex`'s STX unlock (start + 12 cycles). */
+declare function bondUnlockCycle(bondIndex: number, params: BondCycleParams): number;
+/**
+* Minimum L1 CLTV height for bond `bondIndex` — half a cycle before the
+* bond period ends. Mirrors `get-bond-l1-unlock-height`. Distinct from
+* {@link bondUnlockCycle} (the STX unlock cycle).
+*/
+declare function computeBondUnlockHeight(bondIndex: number, params: BondCycleParams): number;
+/**
+* Distribution-cycle index at `burnHeight` — distribution cycles are half a
+* reward cycle long. Mirrors `burn-height-to-distribution-index`.
+*/
+declare function burnHeightToDistributionIndex(burnHeight: number, params: PoxCycleParams): number;
+/** Burn height at the start of `distIndex`. Mirrors `distribution-cycle-to-burn-height`. */
+declare function distributionCycleToBurnHeight(distIndex: number, params: PoxCycleParams): number;
+/**
+* Distribution cycle containing `burnHeight`. Named after the contract's
+* `current-distribution-cycle` but takes height as an argument — no clock.
+*/
+declare function currentDistributionCycle(burnHeight: number, params: PoxCycleParams): number;
+/**
+* Whether `burnHeight` falls in a cycle's prepare phase (the final
+* `prepareCycleLength` blocks). pox-5 rejects `unstake-sbtc` and
+* `announce-l1-early-exit` during a prepare phase.
+*/
+declare function isInPreparePhase(burnHeight: number, params: PoxCycleParams & {
+	prepareCycleLength: number
+}): boolean;
+type BondPhase = "too-early" | "open" | "locked" | "unlocked";
+/**
+* Coarse lifecycle phase of bond `bondIndex` at `burnHeight`: `too-early`
+* (before the bond's start is registerable), `open`/`locked` while active,
+* `unlocked` after 12 cycles.
+*/
+declare function bondPhaseAtHeight(bondIndex: number, burnHeight: number, params: BondCycleParams): BondPhase;
+/**
+* Prepare-aware bond lifecycle. `open` is the registerable window — it
+* ends when the start cycle's prepare phase begins (`register-for-bond`
+* then fails with `ERR_STAKE_IN_PREPARE_PHASE`). Coarse cycle buckets
+* (whole pre-start cycle as `open`) stay on {@link BondPhase}.
+*
+* `eligible`/`missed`/`finished` are omitted: they are not contract
+* states (registration is height-gated, not a per-staker enum).
+*/
+type BondStatusName = "too-early" | "open" | "locked" | "unlocked";
+declare function bondStatusAtHeight(bondIndex: number, burnHeight: number, params: BondCycleParams & {
+	prepareCycleLength: number
+}): BondStatusName;
+type BitcoinNetwork = "mainnet" | "testnet" | "regtest";
+/**
+* Byte-for-byte TypeScript mirrors of pox-5's Bitcoin-script helpers
+* (`serialize-c-script-num`, `push-c-script-num`, `push-script-bytes`,
+* `construct-lockup-script`, `construct-lockup-output-script`), pinned
+* against the final contract in stacks-core 4.0.1. The contract validates a
+* staker's L1 lockup output against exactly these bytes, so any divergence
+* means a rejected registration — the read-onlys on-chain double as a
+* cross-check oracle for these functions.
+*/
+/**
+* Minimal little-endian ScriptNum encoding of a non-negative integer
+* (`0` → empty; a `0x00` sign byte is appended when the top byte's high bit
+* is set). Mirrors `serialize-c-script-num`, including its 2^39 ceiling.
+*/
+declare function serializeCScriptNum(n: number | bigint): Uint8Array;
+/**
+* Push arbitrary bytes onto a Bitcoin script: direct length byte under 76,
+* `OP_PUSHDATA1` under 256, `OP_PUSHDATA2` otherwise. Mirrors
+* `push-script-bytes`.
+*/
+declare function pushScriptBytes(bytes: Uint8Array): Uint8Array;
+/**
+* Push a numeric script value: `OP_0` for zero, the single-byte ops
+* `OP_1`..`OP_16` for 1–16, else a minimal ScriptNum push. Mirrors
+* `push-c-script-num`.
+*/
+declare function pushCScriptNum(n: number | bigint): Uint8Array;
+/** `to-consensus-buff?` of a principal — the staker identity the script commits to. */
+declare function stakerConsensusBuff(stxAddress: string): Uint8Array;
+/**
+* The 32-byte witness item the early-exit branch must reveal:
+* `sha256(to-consensus-buff? staker)`. The script stores `sha256` of THIS,
+* so revealing it proves which staker the exit is for.
+*/
+declare function stakerPreimage(stxAddress: string): Uint8Array;
+type BuildLockupScriptOptions = {
+	/** Staker principal (standard or contract address). */
+	stxAddress: string
+	/** Burn height at which the CLTV branch becomes spendable. */
+	unlockBurnHeight: number | bigint
+	/** Staker-signature subscript, run last in BOTH branches. */
+	stakerUnlockBytes: Uint8Array | string
+	/** Per-bond early-unlock subscript (from `protocol-bonds.early-unlock-bytes`). */
+	earlyUnlockBytes: Uint8Array | string
+};
+/**
+* The L1 lockup witness script. Mirrors `construct-lockup-script`:
+*
+* ```
+* OP_IF
+*   <unlockBurnHeight> OP_CHECKLOCKTIMEVERIFY
+* OP_ELSE
+*   OP_SIZE <32> OP_EQUALVERIFY OP_SHA256
+*   <sha256(sha256(consensus-buff(staker)))> OP_EQUALVERIFY
+*   <earlyUnlockBytes>
+* OP_ENDIF
+* OP_VERIFY
+* <stakerUnlockBytes>
+* ```
+*/
+declare function buildLockupScript(opts: BuildLockupScriptOptions): Uint8Array;
+/**
+* P2WSH `scriptPubKey` for a lockup script: `0x0020 || sha256(script)`.
+* Mirrors `construct-lockup-output-script`.
+*/
+declare function buildLockupOutputScript(opts: BuildLockupScriptOptions): Uint8Array;
+/** The bech32 P2WSH address a staker sends their L1 BTC lockup to. */
+declare function buildLockupAddress(opts: BuildLockupScriptOptions, network?: BitcoinNetwork): string;
+/**
+* The default staker subscript: `<pubkey> OP_CHECKSIG` — spendable by one
+* key. Any script tail is valid as far as the contract is concerned; this is
+* the common case.
+*/
+declare function buildDefaultStakerUnlockBytes(publicKey: Uint8Array | string): Uint8Array;
+type RegisterMetadata = {
+	lockAddress: string
+	lockScript: Uint8Array
+	outputScript: Uint8Array
+	unlockBytes: Uint8Array
+	unlockHeight: number
+};
+/**
+* One-call L1 register metadata: unlock height, staker subscript, lock
+* script, P2WSH output, and address. Staker funds `lockAddress` then
+* passes `lockScript` into the proof mapper.
+*/
+declare function buildRegisterMetadata(opts: {
+	bondIndex: number
+	stxAddress: string
+	bitcoinPublicKey: Uint8Array | string
+	earlyUnlockBytes: Uint8Array | string
+	network?: BitcoinNetwork
+	cycle: BondCycleParams
+}): RegisterMetadata;
+/**
+* PoX-5 signer-key grants: SIP-018 structured-data signatures authorizing a
+* signer-manager contract to use a signer key. Mirrors
+* `pox-5.get-signer-grant-message-hash` — domain `pox-5-signer/1.0.0`,
+* message `{ topic: "grant-authorization", signer-manager, auth-id }`.
+*/
+type SignerGrantOptions = {
+	/** The signer-manager contract principal being authorized. */
+	signerManager: string
+	/** Replay-protection id, chosen by the signer. */
+	authId: bigint | number
+	/** Stacks chain id (`mainnet.id` / `testnet.id`). */
+	chainId: number
+};
+/**
+* The 32-byte hash a signer signs to grant their key — byte-identical to the
+* contract's `get-signer-grant-message-hash` read-only (which doubles as an
+* on-chain cross-check).
+*/
+declare function computeSignerGrantHash(opts: SignerGrantOptions): Uint8Array;
+/**
+* Sign a signer-key grant. Returns the 65-byte recoverable signature in RSV
+* order (recovery byte last), hex — the layout `grant-signer-key`'s
+* `signer-sig (buff 65)` expects.
+*/
+declare function signSignerGrant(account: LocalAccount, opts: SignerGrantOptions): Promise<string>;
+/**
+* Verify a signer-key grant signature locally: recover the pubkey from the
+* RSV signature over the grant hash and compare. Returns `false` for
+* malformed input rather than throwing.
+*/
+declare function verifySignerGrant(opts: SignerGrantOptions & {
+	publicKey: Uint8Array | string
+	signature: Uint8Array | string
+}): boolean;
+/**
+* A Bitcoin merkle inclusion proof, shaped for the SIP-044 `verify-merkle-proof`
+* built-in: `(leaf-hash, root-hash, tx-index, tx-count, sibling-hashes)`.
+*
+* - `siblings` are the sibling node hashes from the leaf up to (excluding) the
+*   root, in *internal* byte order — never reversed.
+* - `txCount` (not tree-depth) pins the canonical tree shape; the built-in
+*   rejects any proof whose length differs from `ceil(log2(tx-count))`.
+*/
+interface MerkleProof {
+	siblings: Uint8Array[];
+	txIndex: number;
+	txCount: number;
+}
+/**
+* A self-contained Bitcoin SPV proof: everything the SIP-044 built-ins need to
+* prove a tx (and one of its outputs) is committed in a confirmed block. Hashes
+* are internal byte order throughout.
+*/
+interface SpvProof {
+	rawTx: Uint8Array;
+	/** The tx's txid, internal order — the merkle leaf. */
+	txidInternal: Uint8Array;
+	/** Output index of interest, if the proof targets a specific output. */
+	vout?: number;
+	merkle: MerkleProof;
+	/** The 80-byte block header that commits the tx. */
+	header: Uint8Array;
+	/** Bitcoin block height. */
+	height: number;
+}
+/** The block context a `ProofSource` resolves for a confirmed tx. */
+interface BlockForTx {
+	/** 80-byte block header. */
+	header: Uint8Array;
+	height: number;
+	/** All of the block's txids, internal order, in block order. */
+	txidsInternal: Uint8Array[];
+	/** Index of the target tx within the block. */
+	txIndex: number;
+}
+/**
+* Where proof inputs come from. The default is the integrator's own Bitcoin node
+* (`bitcoinRpcSource`) — trustless; a hosted Esplora-compatible endpoint
+* (`esploraSource`) is the fallback. `buildTxProof` independently re-checks
+* whatever a source returns, so a wrong or hostile source fails loudly rather
+* than producing a bad proof.
+*/
+interface ProofSource {
+	/** Raw (serialized) tx bytes for a txid (display-order hex). */
+	getRawTx(txid: string): Promise<Uint8Array>;
+	/** The confirming block's header, height, and txid set for a txid. */
+	getBlockForTx(txid: string): Promise<BlockForTx>;
+}
+/**
+* Map a generic SIP-044 `SpvProof` onto pox-5's `L1LockupOutput`.
+* Witness is stripped, the lockup vout is resolved against the P2WSH
+* of `lockScript`, and more than {@link MAX_LEAF_HASHES} siblings throws.
+*/
+declare function spvProofToL1LockupOutput(opts: {
+	proof: SpvProof
+	/** Witness script; hashed to match the P2WSH lockup output. */
+	lockScript: Uint8Array
+	unlockBurnHeight: IntegerType
+	/** Default: `proof.vout`, else the unique matching output. */
+	vout?: number
+}): L1LockupOutput;
+/**
+* Fetch a SIP-044 proof from `source` and map it onto pox-5's lockup shape.
+* `source` is required — no hosted Esplora default.
+*/
+declare function buildPox5LockProof(opts: {
+	source: ProofSource
+	txid: string
+	lockScript: Uint8Array
+	unlockBurnHeight: IntegerType
+	vout?: number
+}): Promise<L1LockupOutput>;
+import * as btc from "@scure/btc-signer";
+/**
+* Spend a pox-5 P2WSH lockup back out.
+*
+* Two paths through the lockup script (mirror of `construct-lockup-script`):
+* - `'locktime'` — CLTV exit (`OP_IF`), single-sig, spendable once the burn
+*   height is past the lock's unlock height.
+* - `'early-exit'` — cosigned exit (`OP_ELSE`), 2-of-2 staker + bond cosigner.
+*   Valid only after `announce-l1-early-exit` on Stacks; this helper spends the
+*   UTXO and does not announce.
+*/
+type ReclaimPath = "locktime" | "early-exit";
+/** Confirmed lockup UTXO (esplora / mempool.space shape). */
+type ReclaimUtxo = {
+	txid: string
+	vout: number
+	value: IntegerType
+	/** Cross-check only; re-derived from `lockScript` when omitted. */
+	scriptPubKey?: Uint8Array
+};
+/** Inputs to {@link buildReclaim}. */
+type BuildReclaimOpts = {
+	path: ReclaimPath
+	utxo: ReclaimUtxo
+	network: BitcoinNetwork
+	/**
+	* Sweep output: `value - feeSats` pays `address`. Mutate the returned tx's
+	* outputs before signing if needed (`SIGHASH_ALL` commits to them).
+	*/
+	output: {
+		address: string
+		feeSats: IntegerType
+	}
+	/**
+	* The lockup `witnessScript` — pass the bytes you funded (typically
+	* `buildLockupScript(...)` / `RegisterMetadata.lockScript`). The CLTV
+	* unlock height is decoded from it.
+	*/
+	lockScript: Uint8Array | string
+};
+/**
+* Build the unsigned reclaim transaction (a `@scure/btc-signer` `Transaction`).
+*
+* One P2WSH input with `witnessUtxo` + `witnessScript` so the tx is a complete
+* PSBT (`toPSBT` / `fromPSBT` round-trip). HSM path: `buildReclaim` →
+* `tx.signIdx` or {@link computeReclaimSighash} + detached `partialSig` →
+* {@link finalizeReclaim}.
+*
+* - `path: "early-exit"` → `sequence = 0xffffffff`, `lockTime = 0`
+* - `path: "locktime"` → `sequence = 0xfffffffe`, `lockTime = unlockHeight`
+*/
+declare function buildReclaim(opts: BuildReclaimOpts): btc.Transaction;
+/**
+* Input-0 BIP-143 sighash for a reclaim tx.
+*
+* In-process keys should prefer `tx.signIdx(privateKey, 0)`. This helper is
+* for HSMs / MPC that sign a bare digest, and for passing the early-exit
+* sighash between parties. Recompute after any output/fee change.
+*
+* Reads `witnessScript` + amount off the tx (set by {@link buildReclaim});
+* pass `opts` to re-supply them for a tx parsed from raw hex.
+*/
+declare function computeReclaimSighash(tx: btc.Transaction, opts?: {
+	witnessScript?: Uint8Array | string
+	amountSats?: IntegerType
+}): Uint8Array;
+/**
+* Sign a reclaim sighash with a software key: DER + trailing `SIGHASH_ALL`.
+* `lowR` defaults to `false` to match btc-signer's `signIdx`. Kept as the
+* software stand-in for a detached signer (HSM tests).
+*/
+declare function signReclaim(sighash: Uint8Array, privateKey: Uint8Array | string, opts?: {
+	lowR?: boolean
+}): Uint8Array;
+/** Arguments to {@link finalizeReclaim}, discriminated on the spend path. */
+type FinalizeReclaimOpts = {
+	path: "early-exit"
+	tx: btc.Transaction
+	/** Staker principal — rebuilds the 32-byte preimage the `OP_ELSE` branch reveals. */
+	stxAddress: string
+} | {
+	path: "locktime"
+	tx: btc.Transaction
+};
+/**
+* Assemble the custom IF/ELSE witness from signatures already on the tx.
+*
+* btc-signer's own finalizer cannot build this script, so we splice
+* `finalScriptWitness` directly. Does not broadcast.
+*
+* - locktime: `[stakerSig, 0x01, witnessScript]`
+* - early-exit: `[stakerSig, cosignerSig, preimage, <empty>, witnessScript]`
+*/
+declare function finalizeReclaim(opts: FinalizeReclaimOpts): {
+	txHex: string
+	txid: string
+};
+type ReclaimOpts = BuildReclaimOpts & {
+	/** 32-byte BTC private key (raw bytes or hex). Not a Stacks account key. */
+	stakerPrivateKey: Uint8Array | string
+	/** Required for `path: "early-exit"`. */
+	cosignerPrivateKey?: Uint8Array | string
+	/** Required for `path: "early-exit"` — feeds {@link stakerPreimage}. */
+	stxAddress?: string
+};
+/**
+* One-shot reclaim for in-process BTC keys: build + signIdx + finalize.
+* Does not broadcast; the caller relays `txHex`.
+*/
+declare function reclaim(opts: ReclaimOpts): {
+	txHex: string
+	txid: string
+};
 /**
 * A staker's whole PoX-5 position in ONE batched request: staker info, bond
 * membership, custodied sBTC, and the current cycle — the state a dashboard
@@ -744,6 +1039,27 @@ type Pox5Actions = {
 		verifySignerKeyGrant: (signerManager: string, signerKey: Uint8Array | string) => Promise<boolean>
 		getCurrentRewardCycle: () => Promise<bigint>
 		getFirstRewardCycle: () => Promise<bigint>
+		getEarned: (params: {
+			signer: string
+			rewardCycle: IntegerType
+			bondIndex?: IntegerType
+		}) => Promise<bigint>
+		getEarnedStakerRewards: (params: {
+			signer: string
+			rewardCycle: IntegerType
+			bondIndex?: IntegerType
+			staker: string
+		}) => Promise<bigint>
+		getLastRewardComputeHeight: () => Promise<bigint>
+		getTotalSharesStakedForCycle: (rewardCycle: IntegerType, bondIndex?: IntegerType) => Promise<bigint>
+		eligibleStake: (params: EligibleStakeParams) => Promise<EligibilityResult>
+		eligibleRegisterForBond: (params: EligibleRegisterForBondParams) => Promise<EligibilityResult>
+		eligibleUnstake: (params: EligibleUnstakeParams) => Promise<EligibilityResult>
+		eligibleUnstakeSbtc: (params: EligibleUnstakeSbtcParams) => Promise<EligibilityResult>
+		eligibleClaimRewards: (params: EligibleClaimRewardsParams) => Promise<EligibilityResult>
+		eligibleGrantSignerKey: (params: EligibleGrantSignerKeyParams) => Promise<EligibilityResult>
+		eligibleSetBondAdmin: (params: EligibleAdminParams) => Promise<EligibilityResult>
+		eligiblePauseRewards: (params: EligibleAdminParams) => Promise<EligibilityResult>
 		setupBond: (params: SetupBondParams) => Promise<string>
 		registerForBond: (params: RegisterForBondParams) => Promise<string>
 		updateBondRegistration: (params: UpdateBondRegistrationParams) => Promise<string>
@@ -757,6 +1073,16 @@ type Pox5Actions = {
 		claimStakerRewardsForSigner: (params: ClaimStakerRewardsForSignerParams) => Promise<string>
 		grantSignerKey: (params: GrantSignerKeyParams) => Promise<string>
 		revokeSignerGrant: (params: RevokeSignerGrantParams) => Promise<string>
+		setBondAdmin: (params: SetBondAdminParams) => Promise<string>
+		setPauseAdmin: (params: SetPauseAdminParams) => Promise<string>
+		pauseRewards: (params?: PauseRewardsParams) => Promise<string>
+		buildLockProof: (opts: {
+			source: ProofSource
+			txid: string
+			lockScript: Uint8Array
+			unlockBurnHeight: IntegerType
+			vout?: number
+		}) => Promise<L1LockupOutput>
 	}
 };
 /**
@@ -778,6 +1104,31 @@ type Pox5Actions = {
 * }
 */
 declare function pox5(): (client: Client) => Pox5Actions;
+/**
+* SIP-005 PoX `pox-addr` tuple, decoded from a Bitcoin address. `version` is
+* the PoX byte (`POX_ADDRESS_VERSION`), not a Bitcoin network version
+* (`p2sh` is 0x01 here, 0x05 on mainnet Bitcoin). `hashbytes` is the 20- or
+* 32-byte payload — unpadded, matching `check-pox-addr-hashbytes`.
+*/
+type BtcAddressRepr = {
+	version: number
+	hashbytes: Uint8Array
+};
+/**
+* Parse a Bitcoin address string into a PoX address tuple.
+* Supports P2PKH, P2SH, P2WPKH, P2WSH, P2TR (mainnet, testnet, regtest).
+*/
+declare function parseBtcAddress(address: string): BtcAddressRepr;
+declare function stringifyBtcAddress(repr: BtcAddressRepr, network: BitcoinNetwork): string;
+declare const BtcAddress: {};
+declare function buildSignerCalldata(opts: {
+	poxAddress: string | BtcAddressRepr
+	maxFeeSats: IntegerType
+}): Uint8Array;
+declare function parseSignerCalldata(calldata: Uint8Array | string): {
+	poxAddress: BtcAddressRepr
+	maxFeeSats: bigint
+};
 declare const POX5_ABI: {
 	readonly functions: readonly [{
 		readonly name: "current-pox-reward-cycle"
@@ -950,6 +1301,59 @@ declare const POX5_ABI: {
 				readonly error: "uint128"
 			}
 		}
+	}, {
+		readonly name: "get-earned"
+		readonly access: "read-only"
+		readonly args: readonly [{
+			readonly name: "signer"
+			readonly type: "principal"
+		}, {
+			readonly name: "reward-cycle"
+			readonly type: "uint128"
+		}, {
+			readonly name: "bond-index"
+			readonly type: {
+				readonly optional: "uint128"
+			}
+		}]
+		readonly outputs: "uint128"
+	}, {
+		readonly name: "get-earned-staker-rewards"
+		readonly access: "read-only"
+		readonly args: readonly [{
+			readonly name: "signer"
+			readonly type: "principal"
+		}, {
+			readonly name: "reward-cycle"
+			readonly type: "uint128"
+		}, {
+			readonly name: "bond-index"
+			readonly type: {
+				readonly optional: "uint128"
+			}
+		}, {
+			readonly name: "staker"
+			readonly type: "principal"
+		}]
+		readonly outputs: "uint128"
+	}, {
+		readonly name: "get-last-reward-compute-height"
+		readonly access: "read-only"
+		readonly args: readonly []
+		readonly outputs: "uint128"
+	}, {
+		readonly name: "get-total-shares-staked-for-cycle"
+		readonly access: "read-only"
+		readonly args: readonly [{
+			readonly name: "reward-cycle"
+			readonly type: "uint128"
+		}, {
+			readonly name: "bond-index"
+			readonly type: {
+				readonly optional: "uint128"
+			}
+		}]
+		readonly outputs: "uint128"
 	}, {
 		readonly name: "announce-l1-early-exit"
 		readonly access: "public"
@@ -1674,6 +2078,58 @@ declare const POX5_ABI: {
 				readonly error: "uint128"
 			}
 		}
+	}, {
+		readonly name: "set-bond-admin"
+		readonly access: "public"
+		readonly args: readonly [{
+			readonly name: "new-admin"
+			readonly type: "principal"
+		}]
+		readonly outputs: {
+			readonly response: {
+				readonly ok: {
+					readonly tuple: readonly [{
+						readonly name: "new-admin"
+						readonly type: "principal"
+					}, {
+						readonly name: "old-admin"
+						readonly type: "principal"
+					}]
+				}
+				readonly error: "uint128"
+			}
+		}
+	}, {
+		readonly name: "set-pause-admin"
+		readonly access: "public"
+		readonly args: readonly [{
+			readonly name: "new-admin"
+			readonly type: "principal"
+		}]
+		readonly outputs: {
+			readonly response: {
+				readonly ok: {
+					readonly tuple: readonly [{
+						readonly name: "new-admin"
+						readonly type: "principal"
+					}, {
+						readonly name: "old-admin"
+						readonly type: "principal"
+					}]
+				}
+				readonly error: "uint128"
+			}
+		}
+	}, {
+		readonly name: "pause-rewards"
+		readonly access: "public"
+		readonly args: readonly []
+		readonly outputs: {
+			readonly response: {
+				readonly ok: "bool"
+				readonly error: "uint128"
+			}
+		}
 	}]
 };
-export { verifySignerGrant, stakerPreimage, stakerConsensusBuff, signSignerGrant, serializeCScriptNum, rewardCycleToBurnHeight, pushScriptBytes, pushCScriptNum, pox5ContractId, pox5, parsePox5Error, isPox5Active, isInPreparePhase, getPoxInfo2 as getPoxInfo, getPox5Activation, describePox5Error, computeSignerGrantHash, burnHeightToRewardCycle, burnHeightToDistributionIndex, buildLockupScript, buildLockupOutputScript, buildLockupAddress, buildDefaultStakerUnlockBytes, bondUnlockCycle, bondPhaseAtHeight, bondPeriodToRewardCycle, bondPeriodToBurnHeight, assertPox5Active, UpdateBondRegistrationParams, UnstakeSbtcParams, UnstakeParams, StakerState, StakeUpdateParams, StakeParams, SignerGrantOptions, SetupBondParams, RevokeSignerGrantParams, RegisterForBondParams, PoxCycleParams, Pox5Info, Pox5EventTopic, Pox5ErrorCode, Pox5Activation, Pox5Actions, POX5_SIGNER_DOMAIN, POX5_EVENT_TOPICS, POX5_ERROR_NAMES, POX5_CONTRACT_NAME, POX5_CONTRACT_ID_MAINNET, POX5_ACTIVATION_BURN_HEIGHT_MAINNET, POX5_ABI, MAX_NUM_CYCLES, L1LockupOutput, GrantSignerKeyParams, ClaimStakerRewardsForSignerParams, ClaimRewardsParams, CalculateRewardsParams, C_SCRIPT_NUM_MAX, BuildLockupScriptOptions, BtcLockup, BondPhase, BondCycleParams, BOND_LENGTH_CYCLES, BOND_GAP_CYCLES, BITCOIN_LOCKTIME_THRESHOLD, AnnounceL1EarlyExitParams };
+export { verifySignerGrant, stringifyBtcAddress, stakerPreimage, stakerConsensusBuff, spvProofToL1LockupOutput, signSignerGrant, signReclaim, serializeCScriptNum, rewardCycleToBurnHeight, reclaim, pushScriptBytes, pushCScriptNum, pox5ContractId, pox5, parseSignerCalldata, parsePox5Error, parseBtcAddress, isPox5Active, isInPreparePhase, getPoxInfo2 as getPoxInfo, getPox5Activation, finalizeReclaim, eligibleUnstakeSbtc2 as eligibleUnstakeSbtc, eligibleUnstake2 as eligibleUnstake, eligibleStake2 as eligibleStake, eligibleSetBondAdmin2 as eligibleSetBondAdmin, eligibleRegisterForBond2 as eligibleRegisterForBond, eligiblePauseRewards2 as eligiblePauseRewards, eligibleGrantSignerKey2 as eligibleGrantSignerKey, eligibleClaimRewards2 as eligibleClaimRewards, distributionCycleToBurnHeight, describePox5Error, currentDistributionCycle, computeSignerGrantHash, computeReclaimSighash, computeBondUnlockHeight, burnHeightToRewardCycle, burnHeightToDistributionIndex, buildSignerCalldata, buildRegisterMetadata, buildReclaim, buildPox5LockProof, buildLockupScript, buildLockupOutputScript, buildLockupAddress, buildDefaultStakerUnlockBytes, bondUnlockCycle, bondStatusAtHeight, bondPhaseAtHeight, bondPeriodToRewardCycle, bondPeriodToBurnHeight, assertPox5Active, UpdateBondRegistrationParams, UnstakeSbtcParams, UnstakeParams, StakerState, StakeUpdateParams, StakeParams, SignerGrantOptions, SetupBondParams, SetPauseAdminParams, SetBondAdminParams, RevokeSignerGrantParams, RegisterMetadata, RegisterForBondParams, ReclaimUtxo, ReclaimPath, ReclaimOpts, PoxCycleParams, Pox5Info, Pox5EventTopic, Pox5ErrorCode, Pox5Activation, Pox5Actions, PauseRewardsParams, POX5_SIGNER_DOMAIN, POX5_EVENT_TOPICS, POX5_ERROR_NAMES, POX5_CONTRACT_NAME, POX5_CONTRACT_ID_MAINNET, POX5_ACTIVATION_BURN_HEIGHT_MAINNET, POX5_ABI, MAX_NUM_CYCLES, L1LockupOutput, GrantSignerKeyParams, FinalizeReclaimOpts, EligibleUnstakeSbtcParams, EligibleUnstakeParams, EligibleStakeParams, EligibleRegisterForBondParams, EligibleGrantSignerKeyParams, EligibleClaimRewardsParams, EligibleAdminParams, EligibilityResult, ClaimStakerRewardsForSignerParams, ClaimRewardsParams, CalculateRewardsParams, C_SCRIPT_NUM_MAX, BuildReclaimOpts, BuildLockupScriptOptions, BtcLockup, BtcAddressRepr, BtcAddress, BondStatusName, BondPhase, BondCycleParams, BOND_LENGTH_CYCLES, BOND_GAP_CYCLES, BITCOIN_LOCKTIME_THRESHOLD, AnnounceL1EarlyExitParams };