hermetica-yield-rotator

Hermetica 收益轮换器

跨协议收益轮换器，用于监控 Hermetica USDh 质押 APY 与 Bitflow HODLMM dlmm_1 APR，并在 Stacks 主网上将资金轮换至收益更高的协议。

功能

查询五个 Hermetica 主网合约（staking-v1、staking-state-v1、staking-silo-v1-1、usdh-token-v1、susdh-token-v1），获取实时兑换率、质押状态、冷却期和用户持仓。通过 Bitflow App 和 Quotes API 获取 Bitflow HODLMM dlmm_1 APR 和活跃 bin。将 USDh/sUSDh 兑换率记录在本地状态文件中，根据比率随时间的变化估算 APY。

在评估模式（默认）下，提供 HOLD / STAKE / ROTATE_TO_HODLMM / ROTATE_TO_STAKING 建议。在写入模式（使用 --confirm）下，输出用于执行建议操作的 MCP 工具命令。

**轮换逻辑：**收益差超过 2% 阈值时进行轮换。HODLMM 收益更高时 → 发起 Hermetica 取消质押（7 天冷却期），然后将 USDh 兑换为 USDCx（dlmm_1 接受 USDCx，而非 USDh）并存入 HODLMM。质押收益更高时 → 移除 HODLMM bins，并在 Hermetica 质押。闲置 USDh → 兑换为 USDCx，然后立即存入收益最高的协议。

30 分钟轮换冷却期可防止频繁切换。所有写入操作都需要 --confirm。

Agent 为何需要它

USDh 质押收益和 HODLMM LP 手续费的变化互不相关。如果不主动轮换，市场情况变化时，Agent 就会错失收益。此技能可弥补这一缺口：只需执行一次 --action=rotate --confirm，即可根据实时数据将资金重新分配至最优协议。

安全注意事项

• **自主支出上限为 500 USDh，已在代码中硬编码。**未明确指定 --amount 时，无论钱包余额多少，质押／取消质押／轮换操作的上限均为 500 USDh。传入 --amount 可操作更大的持仓。
• **代码强制执行 Doctor 优先的预检：**写入操作会在执行前验证 Hermetica 合约和质押状态是否可访问。如果数据源不可用，则会以 PREFLIGHT_FAILED 中止。
• 所有写入操作都需要显式传入 --confirm 标志，避免意外执行
• 2% 的最低收益差阈值可避免因噪声而进行不必要的轮换
• 轮换之间设有 30 分钟冷却期，并记录在本地状态文件中
• 质押／发起取消质押前会检查余额，余额不足时拒绝操作
• APY 数据不可用（兑换率历史记录不足 1 小时）时会阻止轮换
• 执行前会检查轮换冷却期
• initiate-unstake 始终会报告 7 天冷却期，以便 Agent 规划 complete-unstake

输出约定

所有输出均为写入 stdout 的严格 JSON：

{
  "status": "success | error",
  "action": "HOLD | STAKE | ROTATE_TO_HODLMM | ROTATE_TO_STAKING | INITIATE_UNSTAKE | COMPLETE_UNSTAKE | CHECK | Blocked: <reason>",
  "data": {
    "mcp_commands": "[McpCommand[] | null] — present on write actions",
    "staking_enabled": "boolean",
    "exchange_rate": "number",
    "accumulated_yield_pct": "number",
    "estimated_apy_pct": "number | null",
    "cooldown_days": "number",
    "hodlmm_apr_pct": "number | null",
    "hodlmm_active_bin": "number | null",
    "yield_comparison": "string | null",
    "user_usdh": "number | null",
    "user_susdh": "number | null",
    "rotation_cooldown_ok": "boolean",
    "rotate_threshold_pct": "number"
  },
  "error": "null | { code, message, next }"
}

前置条件

此技能的所有链上交互都需要 AIBTC MCP 服务：

npx @aibtc/mcp-server@latest --install

命令

doctor

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts doctor

install-packs

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts install-packs --pack all

run — assess（只读，无需 --confirm）

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run --wallet SP1234...

run — stake

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=stake --amount=500 --confirm

run — initiate-unstake

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=initiate-unstake --amount=500 --confirm

run — complete-unstake

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=complete-unstake --confirm

run — rotate（自动轮换至收益最高的协议）

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=rotate --confirm

实时终端输出

doctor

{
  "status": "ok",
  "checks": [
    { "name": "Hermetica staking-v1",                      "ok": true, "detail": "exchange rate: 1.00000000 USDh/sUSDh" },
    { "name": "Hermetica staking-state-v1",                "ok": true, "detail": "staking enabled: true, cooldown: 7.0 days" },
    { "name": "Hermetica token contracts (USDh + sUSDh)",  "ok": true, "detail": "USDh supply: $9,049,413.13, sUSDh: 1,836,203.38" },
    { "name": "Bitflow HODLMM App API (dlmm_1)",           "ok": true, "detail": "APR: 17.72%, TVL: $77,143" },
    { "name": "Bitflow HODLMM Bins API (dlmm_1)",          "ok": true, "detail": "active bin: 504" }
  ],
  "message": "All data sources reachable. Ready to run."
}

install-packs

{
  "status": "ok",
  "message": "No packs required. hermetica-yield-rotator uses Hermetica contracts and Hiro/Bitflow public APIs only.",
  "data": { "requires": [] }
}

run --wallet（评估 — 无持仓）

{
  "status": "success",
  "action": "CHECK — staking enabled, protocol healthy. Provide --wallet to check position.",
  "data": {
    "staking_enabled": true,
    "exchange_rate": 1,
    "accumulated_yield_pct": 0,
    "estimated_apy_pct": null,
    "cooldown_days": 7,
    "usdh_total_supply": 9049413.13,
    "susdh_total_supply": 1836203.38,
    "hodlmm_apr_pct": 17.72,
    "hodlmm_tvl_usd": 77142.99,
    "hodlmm_active_bin": 504,
    "yield_comparison": "HODLMM dlmm_1 APR: 17.72% | USDh staking APY: tracking started — check again in ≥1h",
    "user_usdh": 0,
    "user_susdh": 0,
    "user_susdh_value_usdh": 0,
    "hodlmm_position_bins": null,
    "rotation_cooldown_ok": true,
    "rotate_threshold_pct": 2,
    "refusal_reasons": null,
    "silo_epoch_ts": 1774660532
  },
  "error": null
}

run --action=stake --amount=500 --confirm（余额检查 — 无 USDh）

{
  "status": "error",
  "action": "Blocked: Amount 500.00 USDh exceeds wallet balance 0.00",
  "data": null,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Amount 500.00 USDh exceeds wallet balance 0.00",
    "next": "Reduce --amount or acquire more USDh."
  }
}

run --action=rotate（缺少 --confirm 检查）

{
  "status": "error",
  "action": "Blocked: --confirm required for action 'rotate'",
  "data": null,
  "error": {
    "code": "CONFIRM_REQUIRED",
    "message": "--confirm required for action 'rotate'",
    "next": "Re-run with --confirm to execute."
  }
}

run --action=rotate --confirm（尚无 APY 数据检查）

{
  "status": "error",
  "action": "Blocked: Cannot rotate without both USDh APY and HODLMM APR data. APY requires ≥1h of exchange rate observations.",
  "data": null,
  "error": {
    "code": "INSUFFICIENT_YIELD_DATA",
    "message": "Cannot rotate without both USDh APY and HODLMM APR data. APY requires ≥1h of exchange rate observations.",
    "next": "Run in assess mode for ≥1h, then retry --action=rotate."
  }
}

是否集成 HODLMM？

• 是 — 符合 +$1,000 sBTC 奖励池的资格

在执行层集成 HODLMM：每次运行都会获取实时 dlmm_1 APR 和活跃 bin，并在轮换流程中输出 bitflow_swap（USDh → USDCx）、bitflow_hodlmm_add_liquidity 和 bitflow_hodlmm_remove_liquidity MCP 命令。由于 dlmm_1 接受 USDCx，而非 USDh，因此必须执行兑换步骤。

数据来源

来源	数据	端点
Hermetica staking-v1	汇率	SPN5AK…HSG.staking-v1::get-usdh-per-susdh
Hermetica staking-state-v1	质押是否启用、冷却时间	::get-staking-enabled、::get-cooldown-window
Hermetica staking-silo-v1-1	周期时间戳	::get-current-ts
Hermetica usdh-token-v1 / susdh-token-v1	代币供应量	::get-total-supply
Hiro Address API	用户 FT 余额	api.mainnet.hiro.so/extended/v1/address/{addr}/balances
Bitflow HODLMM App API	dlmm_1 APR、TVL、用户仓位区间	bff.bitflowapis.finance/api/app/v1/pools、/users/{addr}/positions/{pool}/bins
Bitflow HODLMM Quotes API	活跃区间 ID	bff.bitflowapis.finance/api/quotes/v1/bins/{pool}

来源

AIBTC x Bitflow Skills Pay the Bills 竞赛的获胜作品。
原作者：@cliqueengagements
竞赛 PR：https://github.com/BitflowFinance/bff-skills/pull/56