sbtc-yield-maximizer

sBTC 收益最大化器

功能

比较 Zest sBTC 的实时收益率与 Bitflow sBTC HODLMM 当前机会，并将闲置 sBTC 转入收益最高且安全的路径。如果 Zest 是胜出路径，此版本会执行真实的 Zest sBTC 供应交易；如果 HODLMM 是胜出的安全可执行路径，则通过 CLI 编排 hodlmm-move-liquidity 执行 HODLMM 操作。

Agent 为什么需要它

Agent 不应基于静态假设部署 sBTC。资金转移前，它们需要一个真正的决策层，用于检查当前收益率、定价过时风险、HODLMM 流动性质量和钱包储备。此技能可将该决策转化为可重复且带有防护措施的写入流程。

安全说明

• 会写入链上数据。若 Zest 是胜出路径，run 会签署并广播真实的 Zest sBTC 供应交易；若 HODLMM 胜出，则会执行真实的 HODLMM 再平衡。
• 仅限主网。路由数据和写入执行均面向主网协议。
• 需要钱包密码。执行时，此技能会使用 AIBTC_WALLET_PASSWORD 解锁本地 AIBTC 钱包。
• 强制保留储备。写入路径执行后，钱包至少保留 --reserve-sats。
• 强制执行部署上限。路由金额受 --max-deploy-sats 限制。
• 强制保留 Gas 储备。钱包必须至少保留 --min-gas-reserve-ustx。
• 强制执行后置条件。Zest 服务层写入路径使用 PostConditionMode.Deny。
• 强制执行 HODLMM 过时价格门槛。读取时间超过 --max-data-age-seconds 的 HODLMM 数据，或价格偏差超过 --max-price-divergence-pct 的池会被排除。
• 强制执行 HODLMM 流动性门槛。TVL 或 24 小时交易量低于配置下限的池会被排除。
• 强制执行 APY 优势门槛。只有胜出平台至少领先 --min-apy-diff-bps 时，才会切换路由。
• 强制执行元冷却时间。必须经过 --cooldown-hours 指定的时间后，才能重复执行路由。
• 强制执行内存池深度防护。待处理的发送方交易深度超过 --mempool-depth-limit 时，将阻止执行。
• HODLMM 执行通过 CLI 委托给 hodlmm-move-liquidity，将钱包密码保存在环境变量作用域中，而非子进程 CLI 参数中，并遵守上游针对每个池的冷却时间和状态。
• 需要明确确认。除非提供 --confirm=MAXIMIZE，否则 run 不会执行。
• 尝试执行写入路径后，会重新锁定钱包。

命令

doctor

检查钱包解析情况、STX 和 sBTC 余额、Zest 金库读取结果、Bitflow 池读取结果、内存池深度，以及当前配置能否安全执行胜出路由。

bun run sbtc-yield-maximizer/sbtc-yield-maximizer.ts doctor

install-packs

列出此技能使用的必需运行时包。

bun run sbtc-yield-maximizer/sbtc-yield-maximizer.ts install-packs

status

显示实时余额、候选路由、路由评分、Zest 利率读取结果、排名第一的 HODLMM 候选项，以及当前胜出路由。

bun run sbtc-yield-maximizer/sbtc-yield-maximizer.ts status

run

解锁钱包、重新检查路由决策，并执行胜出的安全路由：

• Zest 胜出时，供应 sBTC 至 Zest
• HODLMM 胜出且当前仓位超出范围时，通过 hodlmm-move-liquidity 执行 HODLMM 再平衡

AIBTC_WALLET_PASSWORD='your-password' bun run sbtc-yield-maximizer/sbtc-yield-maximizer.ts run --confirm=MAXIMIZE

调优后的运行示例：

AIBTC_WALLET_PASSWORD='your-password' HODLMM_MOVE_LIQUIDITY_CMD='bun run /path/to/hodlmm-move-liquidity.ts' bun run sbtc-yield-maximizer/sbtc-yield-maximizer.ts run --wallet-id=b4d575f8-0865-4d6f-b1d6-5627b645a03c --max-deploy-sats=10000 --reserve-sats=100 --min-gas-reserve-ustx=100000 --min-hodlmm-volume-usd=1000 --min-hodlmm-tvl-usd=1000 --max-price-divergence-pct=0.5 --min-apy-diff-bps=50 --max-data-age-seconds=30 --mempool-depth-limit=0 --confirm=MAXIMIZE

输出约定

所有输出均以 JSON 格式写入 stdout。

成功：

{
  "status": "success",
  "action": "Executed the highest safe yield route",
  "data": {
    "operation": "maximize-yield",
    "txid": "0x...",
    "explorerUrl": "https://explorer.hiro.so/txid/0x...?chain=mainnet"
  },
  "error": null
}

已阻止：

{
  "status": "blocked",
  "action": "Hold idle sBTC until a safe executable route is available",
  "data": {},
  "error": {
    "code": "PREFLIGHT_BLOCKED",
    "message": "No executable route passed the configured safety gates",
    "next": "Re-run later or adjust thresholds with explicit operator approval"
  }
}

错误：

{ "error": "descriptive message" }

已知限制

• 此版本通过 CLI 而非源代码导入，与 hodlmm-move-liquidity 组合使用。该上游基础工具仍是 HODLMM 写入路径的唯一可信来源。
• HODLMM 预检路径使用 hodlmm-move-liquidity scan，这是一个不会广播交易的命令。只有在委托执行的 run --confirm 路径中才会实际执行 HODLMM 操作。
• Zest sBTC 收益率根据链上实时 Zest 金库读取结果计算，并解读为基点式供应信号。经核实，实时 v0-vault-sbtc 源代码定义了 BPS u10000，并以基点为单位进行利率计算。
• HODLMM 机会根据 Bitflow 应用和报价 API 的实时数据计算，考量 APR、费用运行率、交易量、TVL、价格过期检查，以及钱包是否已有可重新平衡的区间外 LP 仓位。
• 需要持有足够的 sBTC 以超过储备要求，并持有足够的 STX 以保留 Gas 储备。
• 钱包范围内的状态现在存储在 ~/.aibtc/ 下。升级后会从空状态开始，而不会迁移之前共享的 ~/.sbtc-yield-maximizer-state.json 冷却文件。