hermetica-yield-rotator

Hermetica イールドローテーター

Hermetica の USDh ステーキング APY と Bitflow HODLMM dlmm_1 の APR を監視し、Stacks メインネット上で利回りの高いプロトコルへ資金をローテーションする、プロトコル横断型のイールドローテーターです。

機能

Hermetica のメインネットコントラクト 5 つ（staking-v1、staking-state-v1、staking-silo-v1-1、usdh-token-v1、susdh-token-v1）に問い合わせ、現在の交換レート、ステーキング状態、クールダウン期間、ユーザーのポジションを取得します。Bitflow App と Quotes API から、Bitflow HODLMM dlmm_1 の APR とアクティブなビンを取得します。ローカルの状態ファイルで USDh/sUSDh の交換レートを追跡し、時間経過に伴う比率の変化から APY を推定します。

評価モード（デフォルト）では、HOLD／STAKE／ROTATE_TO_HODLMM／ROTATE_TO_STAKING のいずれかを推奨します。書き込みモード（--confirm 指定時）では、推奨アクションを実行する MCP ツールコマンドを出力します。

ローテーションのロジック： 利回りの差が 2% のしきい値を超えるとローテーションします。HODLMM が優先される場合は、Hermetica のアンステークを開始し（7 日間のクールダウン）、その後 USDh を USDCx にスワップして（dlmm_1 が受け付けるのは USDh ではなく USDCx です）、HODLMM に預け入れます。ステーキングが優先される場合は、HODLMM のビンを削除し、Hermetica でステーキングします。未使用の USDh は USDCx にスワップしてから、その時点で最も利回りの高いプロトコルにすぐに預け入れます。

30 分間のローテーションクールダウンにより、頻繁な切り替えを防ぎます。書き込みアクションにはすべて --confirm が必要です。

エージェントに必要な理由

USDh のステーキング利回りと HODLMM の LP 手数料は、それぞれ独立して変動します。積極的にローテーションしなければ、市場環境が変化したときにエージェントは利回りを逃してしまいます。このスキルはそのギャップを埋めます。単一の --action=rotate --confirm で、ライブデータに基づいて資金を最適なプロトコルに再配分します。

安全性に関する注意事項

• 自動運用の上限は 500 USDh — コードにハードコードされています。 --amount を明示しない場合、ステーク／アンステーク／ローテーション操作の上限は、ウォレット残高にかかわらず 500 USDh です。より大きなポジションを操作するには --amount を指定してください。
• コードにより Doctor-first の事前チェックが強制されます： 書き込みアクションの実行前に、Hermetica のコントラクトとステーキング状態にアクセスできることを検証します。参照先がダウンしている場合は PREFLIGHT_FAILED で中止します。
• 書き込みアクションにはすべて明示的な --confirm フラグが必要です。誤って実行されることはありません
• 2% の最小差分しきい値により、ノイズによる不要なローテーションを防ぎます
• ローテーション間の 30 分間のクールダウンをローカルの状態ファイルで追跡します
• ステーク／アンステーク開始の前に残高を確認し、不足している場合は拒否します
• APY データを取得できない場合（交換レートの履歴が 1 時間未満）、ローテーションをブロックします
• 実行前にローテーションのクールダウンを確認します
• initiate-unstake は 7 日間のクールダウンを常に報告するため、エージェントは 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 とアクティブなビンを取得し、ローテーションの処理の一部として bitflow_swap（USDh → USDCx）、bitflow_hodlmm_add_liquidity、bitflow_hodlmm_remove_liquidity の MCP コマンドを出力します。dlmm_1 が受け付けるのは USDh ではなく USDCx のため、スワップ処理が必要です。

データソース

ソース	データ	エンドポイント
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