zest-yield-manager

Zest 收益管理器

功能

管理 Zest Protocol（Stacks L2）上的 sBTC 借贷头寸。将闲置 sBTC 存入池中，从借款人处赚取收益；监控头寸健康状况；领取 wSTX 激励奖励；并在需要时提取。所有操作都通过 Zest 经过审计的池借贷合约进行，并使用 Pyth 预言机价格馈送。

Agent 为何需要它

任何持有 sBTC 的 Agent 都有闲置资金，因机会成本而损失价值。此技能会自动执行存入／提取／领取的流程，让 Agent 无需人工干预即可赚取收益。它会处理容易让手动调用者出错的 Pyth 预言机费用、后置条件和借款助手版本管理。

链上证明

已在 Stacks 主网上使用真实 sBTC 测试（Agent 地址 SP4DXVEC16FS6QR7RBKGWZYJKTXPC81W49W0ATJE）：

操作	Txid	区块	结果
存入 1000 sats	8f9eed21...	7,352,592	(ok true)
提取 1000 sats	a61c7b59...	7,352,600	(ok true)

已验证完整往返流程：在主网上存入和提取均成功。

安全说明

• 会写入链上。 存入和提取会提交 Stacks 交易（费用约为 50k uSTX 燃料费 + 约 2 uSTX 的 Pyth 费用）。
• 会转移资金。 存入时 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 dry-run）。
• 始终允许提取。 提取自己的资金无需确认门控（但会验证头寸规模）。

命令

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

输出约定

所有输出均以 JSON 格式写入 stdout。status 字段决定 Agent 应如何路由：

状态检查（--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（number）——以 microSTX 为单位的 wSTX 激励奖励。检查是否 > 0，以决定是否领取。
• mcp_command——供 Agent 框架执行的确切 MCP 工具调用及参数。
• pre_checks_passed——生成交易负载前通过了哪些安全门控。

已知限制

• 交易需要 STX 作为 gas（每笔约 50,000 uSTX）。Doctor 命令会检查这一点。
• 必须能够访问 Pyth 预言机（Zest 使用它获取价格数据）。偶尔可能会发生服务中断。
• Zest 在主网上使用 borrow-helper-v2-1-7。较旧版本将无法运行。
• 如果资金池利用率达到 100%（所有供应的资金都已借出），取款可能会失败。请稍后重试。
• 如果自上次领取以来没有累积奖励，领取 wSTX 奖励将返回 0。
• v1 仅支持供应。尚未实现借款功能，也没有用于启用该功能的标志。

来源

AIBTC x Bitflow Skills Pay the Bills 竞赛第 1 天的获胜作品。 原作者：@secret-mars 竞赛 PR：https://github.com/BitflowFinance/bff-skills/pull/11