stacking

Stacking 技能

在 PoX-5 上质押 STX（自奖励周期 141 起在主网启用）。PoX-5 并不是 pox-4 的改名版本：

• 每笔质押都指定一个 签名者管理器，即实现了 pox-5 的 signer-manager-trait 的合约。不存在资金池委托（delegate-stx），质押本身也不包含奖励地址；管理器决定谁可以加入，并从可选的 签名者 calldata 中读取任何奖励支付偏好。
• 奖励以 sBTC 支付给签名者管理器。管理器从 pox-5 提取其份额（claim-rewards），再向质押者支付（claim-staker-rewards）后，质押者才能获得奖励。各管理器实现第二步的方式不同，有些会通过链下方式支付。
• 在 准备阶段（每个周期的最后 100 个区块），stake、stake-update 和 unstake 操作会被拒绝。
• 锁定不等于转账：交易会携带 pox-5 自身的后置条件（质押锁定金额，或“执行 PoX”），并采用 Deny 模式。

每次写入操作都会先确认 pox-5 仍是网络的活动 PoX 合约，否则会在签名前拒绝操作。

• get-pox-info、get-stacking-status、list-signers、get-rewards —— 只读，无需钱包（状态和奖励默认使用活动钱包的地址）。
• stack-stx、extend-stacking、unstake-stx、claim-rewards —— 写入操作，需要已解锁的钱包。

用法

bun run stacking/stacking.ts <subcommand> [options]

子命令

get-pox-info

当前 PoX-5 状态。

bun run stacking/stacking.ts get-pox-info

输出：

{
  "network": "mainnet",
  "contract": "SP000000000000000000002Q6VF78.pox-5",
  "burnHeight": 967284,
  "rewardCycle": 143,
  "nextCycleStartHeight": 968450,
  "preparePhaseStartHeight": 968350,
  "inPreparePhase": false,
  "firstBurnHeight": 666050,
  "rewardCycleLength": 2100,
  "prepareCycleLength": 100,
  "signerSetMinUstx": "50000000000",
  "totalLiquidSupplyUstx": "1867006091924579"
}

signerSetMinUstx 是 签名者 加入签名者集合所需委托的最低金额，并非每位质押者的最低金额。

get-stacking-status

bun run stacking/stacking.ts get-stacking-status [--address <addr>]

输出：

{
  "address": "SP1PSZZYFH9H5M81KGBV2XTFQBR3HQ17HJW7Y4ZK2",
  "network": "mainnet",
  "staking": true,
  "stake": {
    "signerManager": "SP8HK160YD5GHXP69VGA0TC7AQJ1X4CDW3XVERSE.xverse-signer-manager-2",
    "amountUstx": "500000000",
    "amount": "500.000000 STX",
    "firstRewardCycle": 144,
    "numCycles": 96,
    "unlockCycle": 240,
    "unlockBurnHeight": 1170050
  },
  "bond": null,
  "balance": {
    "totalUstx": "560494462",
    "lockedUstx": "500000000",
    "unlockedUstx": "60494462",
    "burnchainUnlockHeight": 1170050
  },
  "pox": { "contract": "SP000000000000000000002Q6VF78.pox-5", "burnHeight": 967284, "rewardCycle": 143, "nextCycleStartHeight": 968450, "preparePhaseStartHeight": 968350, "inPreparePhase": false }
}

当地址处于 pox-5 协议债券中时，会设置 bond（包含 bondIndex、amountUstx、amountSats、isL1Lock、signerManager）。

list-signers

列出某个奖励周期签名者集合中的签名者管理器（默认：下一个周期，新质押会加入该周期），并按委托的 STX 数量排序。

bun run stacking/stacking.ts list-signers [--reward-cycle <cycle>] [--with-payout-info]

选项：

• --reward-cycle（可选）——要列出的周期
• --with-payout-info（可选）——同时读取各管理器的质押者领取方式：staker-arg / caller（可链上领取）或 none（链下支付）。每位签名者会额外发起一次请求。

输出（已截断）：

{
  "network": "mainnet",
  "rewardCycle": 144,
  "count": 26,
  "signers": [
    { "signerManager": "SP1N8F8BBBC60XF6HJBNJHKPRGJ7WZBRGNDJX4YDR.signer-manager", "delegatedUstx": "85815090000000", "delegated": "85815090.000000 STX" }
  ],
  "note": "Managers can restrict who may stake ..."
}

只有达到或超过签名者集合最低金额的签名者才会显示。也可以使用合约 ID 对其他已注册的管理器进行质押。

stack-stx

通过签名者管理器锁定 STX。锁定从下一个奖励周期开始。

bun run stacking/stacking.ts stack-stx \
  --signer-manager <contractId> \
  --amount <microStx> \
  --num-cycles <1-96> \
  [--btc-reward-address <address> [--max-withdrawal-fee-sats <sats>] | --signer-calldata-hex <hex>]

选项：

• --signer-manager（必需）——签名者管理器合约 ID（参见 list-signers）
• --amount（必需）——要锁定的微 STX 数量（1 STX = 1,000,000 微 STX）
• --num-cycles（必需）——锁定的奖励周期数，1–96（一个周期约为 2 周）
• --btc-reward-address（可选）——用于奖励的 Bitcoin 地址，以 { pox-addr, max-fee } calldata 编码；参考管理器（例如 Xverse、Fast Pool）会采用这种格式，通过 sBTC 提现支付奖励。有些管理器要求提供此项，有些则会忽略。
• --max-withdrawal-fee-sats（可选）——使用 --btc-reward-address 时，每次支付的 sBTC 提现手续费上限（默认值：3000）
• --signer-calldata-hex（可选）——适用于采用自定义格式的管理器的原始 calldata（≤500 字节）；不可与 --btc-reward-address 一起使用

以下情况会在签名前拒绝操作：处于准备阶段（或距离准备阶段开始不足 3 个 burn 区块）、已在质押（请使用 extend-stacking）、管理器不是已注册的 pox-5 签名者，或金额超过地址的 STX 余额。

输出：

{
  "success": true,
  "txid": "0x...",
  "explorerUrl": "https://explorer.hiro.so/txid/0x...?chain=mainnet",
  "staker": "SP...",
  "signerManager": "SP8HK160YD5GHXP69VGA0TC7AQJ1X4CDW3XVERSE.xverse-signer-manager-2",
  "amountUstx": "2780000000",
  "amount": "2780.000000 STX",
  "firstRewardCycle": 144,
  "numCycles": 96,
  "unlockCycle": 240,
  "unlockBurnHeight": 1170050,
  "rewardPayout": "sBTC (if the manager supports it)",
  "network": "mainnet"
}

extend-stacking

更新现有的质押（stake-update）：延长质押、增加 STX、更换签名者管理器或更改奖励 calldata，也可以组合执行。

bun run stacking/stacking.ts extend-stacking \
  [--cycles-to-extend <cycles>] [--amount-increase <microStx>] [--signer-manager <contractId>] \
  (--btc-reward-address <address> [--max-withdrawal-fee-sats <sats>] | --signer-calldata-hex <hex> | --sbtc-payout)

每次更新都必须选择奖励方式。 pox-5 每次都会将 stake-update 的 calldata 传给管理器的 validate-stake!，而参考管理器（Xverse、Fast Pool）会将没有 calldata 视为“删除已存储的 BTC 奖励地址”；其他管理器则会拒绝。若要保留 BTC 奖励地址，请再次传入相同的 --btc-reward-address。--sbtc-payout 会按预期不发送 calldata。

未选择奖励方式、当前未处于质押状态、处于准备阶段、没有任何变更、增加金额超过未锁定余额、新管理器未注册，或锁定期限会超过下一个周期之后的 96 个周期时，操作会被拒绝。

输出：txid、explorerUrl、previous（更新前的质押）、signerManager、newAmountUstx、newAmount、unlockCycle、unlockBurnHeight。

unstake-stx

提前停止质押（unstake）。STX 会继续锁定至当前周期结束，并在下一个周期开始时解锁。

bun run stacking/stacking.ts unstake-stx

当前未处于质押状态、处于准备阶段，或质押已在下一个周期解锁时，操作会被拒绝。

输出：txid、explorerUrl、previous、unlockCycle、unlockBurnHeight。

get-rewards

查询某个周期中可从签名者管理器领取的 sBTC。pox-5 的 get-earned-staker-rewards 只有在管理器提取该周期的奖励后才会更新，因此此命令会计算提取后质押者可领取的金额（使用 pox-5 自身的 compute-earned-rewards，根据该周期的全局每代币奖励计算）。

bun run stacking/stacking.ts get-rewards --reward-cycle <cycle> [--address <addr>] [--signer-manager <contractId>]

输出：

{
  "address": "SP...",
  "network": "mainnet",
  "rewardCycle": 143,
  "signerManager": "SP8HK160YD5GHXP69VGA0TC7AQJ1X4CDW3XVERSE.xverse-signer-manager-2",
  "unclaimedSatsBeforeFees": "0",
  "managerUnpulledSats": "0",
  "stakerClaim": "staker-arg",
  "next": "Nothing to claim for this cycle."
}

claim-rewards

通过签名者管理器领取某个周期的 sBTC 奖励。如果管理器尚未从 pox-5 提取该周期的奖励，此命令会先发送管理器无需许可的 claim-rewards 交易（由此钱包支付第二笔交易），然后再发送质押者的领取交易。

bun run stacking/stacking.ts claim-rewards --reward-cycle <cycle> [--signer-manager <contractId>]

如果管理器没有链上质押者领取记录，或没有可领取金额（按 get-rewards 中的方式计算，因此管理器尚未提取的奖励仍计入），操作会被拒绝。发送两笔交易时，会使用连续的显式 nonce。sBTC 后置条件使用 /v2/pox 中 pox-5 报告的代币（pox_5_sbtc_contract），该代币与测试网默认的 sBTC 不同。后置条件仅允许 sBTC 从 pox-5（提取）和管理器（发放奖励）转出；不得有任何资金离开调用者。

输出：txid、explorerUrl、unclaimedSatsBeforeFees、managerPull（{ txid, explorerUrl } 或 null），以及发送了两笔交易时的 note。

注意事项

• 移植自 aibtc MCP 服务的 pox-5 质押工具（aibtcdev/aibtc-mcp-server#682）；交易参数和后置条件与主网的 stake、stake-update 和 unstake 交易一致。
• 管理器可以限制可质押者（允许列表、最低金额、必需的 calldata）。如果管理器拒绝质押，交易会在链上中止，但仍会产生手续费，因此请先查看管理器的条款。
• 钱包操作需要解锁钱包（bun run wallet/wallet.ts unlock）。
• Pillar 的 direct-stack-stx --pool fast-pool 和 direct-revoke-fast-pool 通过 Pillar 钱包合约调用 pox-4，在 pox-4 未激活时会被拒绝；PoX-5 质押请使用此技能。