zest-yield-manager

Zest Yield Manager

機能

Zest Protocol（Stacks L2）での sBTC 貸付ポジションを管理します。未使用の sBTC を供給して借り手から利回りを獲得し、ポジションの健全性を監視し、wSTX インセンティブ報酬を請求し、必要に応じて引き出します。すべての操作は、Pyth オラクルの価格フィードを使用する、監査済みの Zest のプール借入コントラクトを通じて実行されます。

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

sBTC を保有するエージェントは、未使用の資本が機会費用によって目減りします。このスキルは供給／引き出し／請求のサイクルを自動化し、手動操作なしでエージェントが利回りを獲得できるようにします。手動で呼び出す際につまずきやすい Pyth オラクル手数料、ポストコンディション、借入ヘルパーのバージョン管理にも対応します。

オンチェーンでの実証

実際の sBTC を使用して Stacks メインネットでテスト済みです（エージェントアドレス SP4DXVEC16FS6QR7RBKGWZYJKTXPC81W49W0ATJE）：

操作	Txid	ブロック	結果
1000 sats を供給	8f9eed21...	7,352,592	(ok true)
1000 sats を引き出し	a61c7b59...	7,352,600	(ok true)

一連の往復処理を検証済みです。メインネットで供給と引き出しの両方が成功します。

安全に関する注意事項

• チェーンに書き込みます。 供給と引き出しでは Stacks トランザクションを送信します（ガス代は約 50k uSTX、Pyth 手数料は約 2 uSTX）。
• 資金を移動します。 sBTC は供給時にウォレットから出て、引き出し時に戻ります。資金はカストディアルアドレスではなく、Zest の監査済み貸付プールに預けられます。
• メインネットのみです。 Zest Protocol は Stacks メインネットにデプロイされています。
• 供給のみです。 v1 は借入に対応していません。借入は利用できません。--allow-borrow フラグはありません。将来のバージョンでは、明示的なオプトインと清算防止策を備えた借入サポートが追加される可能性があります。
• 支出上限が適用されます。 呼び出しごとのデフォルトの最大供給額は 500,000 sats（DEFAULT_MAX_SUPPLY_SATS）です。--max-supply-sats で上書きできます。上限を超える金額では blocked ステータスが返され、スキルは処理を続行しません。
• 事前チェックを実行します。 書き込み操作の前に、スキルは次の項目を検証します：（1）STX ガス残高が 100,000 uSTX 以上、（2）sBTC 残高が要求額以上、（3）金額が支出上限内。いずれかのチェックに失敗すると、スキルは具体的なエラーコードと推奨される対処法を含む blocked を返します。
• トランザクションのシミュレーションはありません。 ブロードキャストは事前チェックと Zest のコントラクトレベルの検証に依存します。トランザクションシミュレーション（stxer によるドライラン）はまだ実装されていません。
• 引き出しは常に可能です。 自分の資金を引き出す際に確認ゲートはありません（ただし、ポジションサイズは検証されます）。

コマンド

doctor

ウォレットの STX 残高（ガス用）、sBTC 残高、Zest コントラクトの利用可能性、現在のポジション、保留中の報酬を確認します。いつでも安全に実行できます。読み取り専用です。

bun run zest-yield-manager/zest-yield-manager.ts doctor

run

中核となる実行コマンドです。サブコマンドを受け付けます：

ポジションを確認（デフォルト、読み取り専用）：

bun run zest-yield-manager/zest-yield-manager.ts run --action=status

利回りを得るために sBTC を供給：

bun run zest-yield-manager/zest-yield-manager.ts run --action=supply --amount=50000

プールから sBTC を引き出し：

bun run zest-yield-manager/zest-yield-manager.ts run --action=withdraw --amount=50000

wSTX インセンティブ報酬を請求：

bun run zest-yield-manager/zest-yield-manager.ts run --action=claim

install-packs

必須の依存関係である @stacks/transactions と @stacks/network を確認し、結果を報告します。

bun run zest-yield-manager/zest-yield-manager.ts install-packs --pack all

出力仕様

すべての出力は stdout への JSON です。status フィールドに基づいて、エージェントが処理を振り分けます：

ステータス確認（--action=status）：

{
  "status": "success",
  "action": "Idle sBTC detected — consider supplying with --action=supply",
  "data": {
    "position": {
      "supplied_sats": 0,
      "borrowed_sats": 0,
      "rewards_pending_ustx": 0,
      "asset": "sBTC"
    },
    "balances": {
      "sbtc_sats": 295574,
      "stx_ustx": 33405629
    }
  },
  "error": null
}

供給／引き出し／請求（--action=supply|withdraw|claim）：

{
  "status": "success",
  "action": "Execute supply transaction via MCP zest_supply tool",
  "data": {
    "operation": "supply",
    "asset": "sBTC",
    "amount_sats": 1000,
    "mcp_command": {
      "tool": "zest_supply",
      "params": { "asset": "sBTC", "amount": "1000" }
    },
    "pre_checks_passed": {
      "gas_sufficient": true,
      "balance_sufficient": true,
      "within_spend_limit": true
    }
  },
  "error": null
}

ブロック（安全性チェック失敗時）：

{
  "status": "blocked",
  "action": "Reduce amount or set --max-supply-sats=600000 to override",
  "data": {},
  "error": {
    "code": "exceeds_limit",
    "message": "Requested 600000 sats exceeds max supply limit of 500000 sats",
    "next": "Reduce amount or set --max-supply-sats=600000 to override"
  }
}

主なフィールド：

• rewards_pending_ustx（数値）— microSTX 単位の wSTX インセンティブ報酬です。請求するかどうかを判断するには、> 0 かどうかを確認してください。
• mcp_command — エージェントのフレームワークが実行する、正確な MCP ツール呼び出しとパラメーターです。
• pre_checks_passed — トランザクションペイロードの生成前に通過した安全性チェックです。

既知の制約

• ガス代として STX が必要です（1 トランザクションあたり約 50,000 uSTX）。Doctor コマンドで確認できます。
• Pyth オラクルに接続できる必要があります（Zest は価格フィードに使用します）。まれに停止することがあります。
• Zest はメインネットで borrow-helper-v2-1-7 を使用します。古いバージョンでは失敗します。
• プールの利用率が 100％（供給された資金がすべて借りられている状態）の場合、出金に失敗することがあります。後で再試行してください。
• 前回の請求以降に報酬が発生していない場合、wSTX の報酬請求は 0 を返します。
• v1 は供給専用です。借入は実装されておらず、有効化するフラグもありません。

開発の経緯

AIBTC x Bitflow Skills Pay the Bills コンペティション Day 1 の優勝作品です。 原作者：@secret-mars コンペティション PR：https://github.com/BitflowFinance/bff-skills/pull/11