feat(sdk-coin-stx): add pox-5 staking contract support

[claude]

Requested by Noel Hawat · Slack thread

Description

Before: the SDK rejects any staking contract except pox-4 — the STX contract call builder throws on any other contract name, so pox-5 transactions can neither be built nor parsed/signed.

After: the SDK builds, signs, and deserializes calls to the new pox-5 contract's stake, stake-update, and unstake functions (mainnet SP000000000000000000002Q6VF78.pox-5, testnet ST000000000000000000002AMW42H.pox-5). pox-4 remains accepted during the transition window so in-flight pox-4 transactions (including half-signed/OVC flows, which re-run the same validation on deserialize) keep working until the fork activates.

How: the single hardcoded CONTRACT_NAME_STAKING = 'pox-4' equality check in ContractBuilder.contractName() is replaced by a VALID_STAKING_CONTRACT_NAMES = ['pox-4', 'pox-5'] allowlist (same pattern as the existing VALID_CONTRACT_FUNCTION_NAMES), and the pox-5 staking entrypoints stake, stake-update, unstake are added to the function-name allowlist. The existing JSON→ClarityValue conversion already expresses the new pox-5 argument shapes — the <signer-manager-trait> argument serializes as a contract principal CV ({ type: 'principal', val: 'ADDR.contract-name' }) and the (optional (buff 500)) signer-calldata as optional/buffer — so no builder changes were needed there; new tests prove a full stake call round-trips build → serialize → deserialize with identical args. StakeOptions.contractName in sdk-core is widened to include 'pox-5'.

Notes for reviewers:

• pox-5 function signatures are taken from the SIP-045 reference implementation (pox-wf-integration branch of stacks-network/stacks-core). This is pre-audit but near-final; re-verify against the shipped boot contract before the fork activates.
• The bond-related pox-5 functions (register-for-bond, update-bond-registration, unstake-sbtc, announce-l1-early-exit) are intentionally excluded — out of scope for STX-only staking.
• pox-4 removal should follow in a breaking release after the Epoch 4.0 fork, mirroring the pox-3→pox-4 migration lifecycle.
• Downstream consumers (wallet-platform, staking-service) need a published @bitgo/sdk-coin-stx / @bitgo/sdk-core version bump to pick this up; wallet-platform additionally has its own CONTRACT_NAMES = ['pox-4'] allowlist that must be extended separately.

Issue Number

CSHLD-000 (no dedicated ticket; junk-drawer reference per repo convention)

Type of change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• yarn unit-test in modules/sdk-coin-stx: 188 passing (includes 7 new pox-5 build/sign/round-trip tests, a new parseCv contract-principal test, and updated pox-2/pox-3/pox-6 negative tests). Serialized hex fixtures were generated by building the transactions with the SDK.
• yarn unit-test in modules/sdk-core: 525 passing, 1 pending.
• eslint and prettier --check clean on all changed files.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My code compiles correctly for both Node and Browser environments
• I have commented my code, particularly in hard-to-understand areas
• My commits follow Conventional Commits and I have properly described any BREAKING CHANGES
• The ticket or github issue was included in the commit message as a reference
• I have made corresponding changes to the documentation and on any new/updated functions and/or methods - jsdoc
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

🤖 Generated with Claude Code

https://claude.ai/code/session_016pcJwLhB4eR5uwREh9bL9e

---

Generated by Claude Code