feat(sdk-coin-stx): add PoX-5 bond builders

[Doddanna17]

Summary

• Add PoX-5 contract constants and function validation.
• Add typed STX builders for bond registration, validator updates, early exit, STX-only staking, reward calculation, and claims.
• Add BTC/sBTC lockup Clarity value construction with SPV proof fields.
• Add factory parsing, sdk-core staking option support, and round-trip tests.

Verification

• Prettier: passed.
• ESLint: passed for changed files.
• Diff check: passed.
• Package tests/build are currently blocked before test collection by existing sdk-core io-ts and @bitgo/public-types/MPC dependency errors.

Ticket: SI-1486

[linear-code]

SI-1486

[github-actions]

⚠️ Unit tests are failing on Node 26.x (Current release line, non-blocking). This is not an LTS version yet, so it does not block merge, but it signals an incompatibility to fix before Node 26.x becomes LTS.

View run

[kisslove-dewangan]

codeowners files lgtm

[Doddanna17]

Hi @BitGo/hsm, @BitGo/ecosystem, @BitGo/wallet-core Team,

Please review and approve this PR.

Thanks!

[Doddanna17]

Reviewer Context: STX BTC Staking / PoX-5

This PR adds the BitGoJS transaction-construction layer for BTC-backed STX PoX-5 paired-bond staking. It is not the end-to-end staking-service orchestration or Wallet Platform implementation.

Protocol scope

PoX-5 paired-bond staking locks two assets:

1. BTC on Bitcoin in a canonical P2WSH/CLTV lockup.
2. STX on Stacks through register-for-bond.

The BTC lock is confirmed first. The Stacks registration then proves the BTC lock with SPV data and locks the STX amount.

register-for-bond argument model

Pox5Builder.registerForBond() constructs:

uint bondIndex
contract-principal signerManager
uint amountUstx
(response {
  outputs: (list 10 {
    height: uint,
    tx: (buff 100000),
    output-index: uint,
    header: (buff 80),
    leaf-hashes: (list 14 (buff 32)),
    tx-count: uint,
    tx-index: uint,
    amount: uint,
    unlock-burn-height: uint
  }),
  staker-unlock-bytes: (buff ...)
})
(optional (buff 500)) signerCalldata

The builder accepts both BTC and sBTC lockup forms. BTC lockups enforce 1-10 outputs and no more than 14 Merkle siblings per output. signerCalldata is the serialized { pox-addr, max-fee } tuple used to elect the L1 BTC reward path. Omitting it intentionally produces the protocol default sBTC path.

Other builders

The PR also provides typed construction for:

• update-bond-registration, including re-supplied signer calldata.
• announce-l1-early-exit.
• PoX-5 STX-only stake, stake-update, and unstake.
• calculate-rewards.
• claim-rewards.
• claim-staker-rewards-for-signer.

Early exit, validator switching, and reward claims are future lifecycle coverage and are not Phase 1 release gates. Phase 1 acceptance is the successful register-for-bond path.

Ownership boundaries

• Wallet Platform creates the paired wallet, BTC lock descriptor, BTC funding transaction, and the Stacks transaction request.
• Staking-service validates bond/allowlist/timing, waits for BTC confirmation, assembles or supplies SPV proof, builds the registration intent, and monitors/reconciles transaction requests.
• BitGoJS builds the serialized Stacks contract-call transaction used by Wallet Platform.
• HSM signs the serialized transaction with SIP-018 and preserves SIP-044 post-conditions.
• Indexer records registration, membership, bond lifecycle, and BTC outpoint correlation.

Validation and compatibility

• PoX-5 contract address is network-configured; it is not treated as PoX-4.
• Contract/function validation is explicit.
• Contract-call parsing supports nested Clarity values used by PoX-5, including response/list/tuple/optional values.
• Existing PoX-4 and generic transaction behavior remains unchanged.
• L1-locked BTC positions do not use unstake-sbtc.

Verification

• PoX-5 builder unit coverage includes registration, lockup response construction, signer calldata, update, and claim argument shapes.
• CI currently reports all required checks passing, including Node 22 and Node 24 unit tests, formatting, lint, dependency, Docker, and package verification checks. Node 26 is non-blocking.

Related implementation context: SI-1486, SI-1436, SI-1437, SI-1442, SI-1443, SI-1445, and the PoX-5 paired-bond TDD in coins-sandbox.

[Doddanna17]

Hi @BitGo/hsm, @BitGo/ecosystem, @BitGo/wallet-core Team,
Please review and approve this PR.
Thanks!