hodlmm-move-liquidity

HODLMM 流动性迁移与自动再平衡器

功能说明

当活跃 bin 偏离你的 LP 仓位时，将流动性迁移到活跃 bin。通过 Bitflow DLMM 流动性路由器的 move-relative-liquidity-multi 函数，在一次原子交易中完成操作：从旧 bin 提取流动性，并存入活跃 bin。没有中间状态、无需按 nonce 排序，也没有部分执行的风险。

活跃 bin 是所有交易流经并累积手续费的地方。存放在其他任何 bin 中的资金都无法赚取收益。此技能会将你的流动性集中到能产生收益的地方。

auto 命令会作为自主再平衡器运行——按可配置的间隔监控所有池，并在偏离超过阈值时自动迁移流动性。无需人工干预。设置好后，Agent 会全天候将你的资金保持在活跃 bin 中。

Agent 为什么需要它

竞赛中的每个 HODLMM 只读技能都会遇到同样的瓶颈。它们能检测偏离、评估风险并给出建议，然后就停止了。资金仍留在无法产生收益的 bin 中，而活跃 bin 已经移到别处。

此技能可闭合这一环节。run 命令可按需迁移流动性。auto 命令则让整个过程自主运行——运行此技能的 Agent 无需人工干预，即可让资金持续产生收益，全天候运作。

安全须知

• 会向链上写入数据。 每次再平衡都通过 move-relative-liquidity-multi 执行一笔原子交易。提取和存入会在一次链上调用中完成——要么两者都成功，要么两者都不执行。
• 会迁移资金。 流动性会从旧 bin 中移除并存入新 bin。代币不会离开 LP 的钱包——它们会经由 DLMM 流动性路由器合约转移。
• 仅限主网。 所有合约地址均为 Stacks 主网地址。
• run 必须指定 --confirm。 未指定时，run 会输出包含完整计划详情的试运行预览，不会广播交易。auto 命令会直接执行（操作员选择启动该命令即表示同意）。
• postConditionMode: Allow — HODLMM 操作会在同一笔交易中铸造和销毁 DLP 代币，这无法通过发送方侧的后置条件来表达。合约级滑点保护可弥补这一点：每次迁移要求至少返还 95% 的 DLP 份额（min-dlp），并将流动性手续费限制在金额的 5% 以内（max-x-liquidity-fee、max-y-liquidity-fee）。如果合约违反任一限制，交易会在链上回滚。其他安全措施包括：--confirm 门槛、冷却时间、区间内检查和 gas 检查。
• 同一池的迁移间隔为 4 小时，由代码强制执行并持久化到磁盘。

命令

doctor

检查 API 访问权限、钱包就绪状态和依赖项可用性。

bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts doctor --wallet SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY

scan

以只读方式扫描所有 HODLMM 池。显示每个仓位是否在区间内、bin 范围、活跃 bin 和偏离距离。

bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts scan --wallet SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY

run

评估指定池并生成迁移计划。默认进行试运行。

# Preview (no on-chain action)
bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts run --wallet <addr> --pool dlmm_1

# Execute
bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts run --wallet <addr> --pool dlmm_1 --confirm --password <pass>

# Custom spread (default: ±5 bins around active)
bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts run --wallet <addr> --pool dlmm_1 --spread 3 --confirm --password <pass>

# Force recenter an in-range position
bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts run --wallet <addr> --pool dlmm_1 --force --confirm --password <pass>

选项：

• --spread <n> — 活跃 bin 周围 ±N 个 bin 的范围（默认值：5，最大值：10）
• --force — 即使仓位在区间内也强制再平衡（围绕活跃 bin 重新居中）

auto

自主再平衡器。循环监控所有池，并在偏离超过阈值时自动迁移流动性。

# Start auto-rebalancer (checks every 15 minutes, moves when drift ≥ 3 bins)
bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts auto --wallet <addr> --password <pass>

# Custom interval and threshold
bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts auto --wallet <addr> --password <pass> --interval 30 --drift-threshold 5

# Single cycle (no loop)
bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts auto --wallet <addr> --password <pass> --once

选项：

• --interval <minutes> — 检查间隔（默认值：15，最小值：5）
• --drift-threshold <bins> — 触发迁移的最小偏离 bin 数（默认值：3）
• --spread <n> — 活跃 bin 周围 ±N 个 bin 的范围（默认值：5，最大值：10）
• --max-moves <n> — 每个周期的最大迁移次数，0 = 不限（默认值：0）
• --once — 运行一个周期后退出

install-packs

无需外部 pack。

bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts install-packs

输出约定

所有命令都会将 JSON 输出到 stdout。

scan — 成功：

{
  "status": "success",
  "action": "scan",
  "data": {
    "wallet": "SP...",
    "pools_scanned": 8,
    "positions_found": 2,
    "out_of_range": 1,
    "positions": [
      {
        "pool_id": "dlmm_1",
        "pair": "sBTC/USDCx",
        "active_bin": 510,
        "user_bins": [500, 501, 502, 503, 504],
        "user_bin_min": 500,
        "user_bin_max": 504,
        "in_range": false,
        "drift": 8,
        "total_x": "50000",
        "total_y": "120000000",
        "total_dlp": "980000"
      }
    ]
  },
  "error": null
}

run — 在区间内（无操作）：

{
  "status": "success",
  "action": "run",
  "data": {
    "decision": "IN_RANGE",
    "reason": "Position is already in the active range — earning fees. No move needed. Use --force to recenter.",
    "health": { "..." : "..." }
  },
  "error": null
}

run — 试运行：

{
  "status": "success",
  "action": "run",
  "data": {
    "decision": "MOVE_NEEDED",
    "mode": "dry-run",
    "reason": "Position drifted 8 bins from active. Add --confirm --password <pass> to execute.",
    "health": { "..." : "..." },
    "plan": {
      "pool_id": "dlmm_1",
      "pair": "sBTC/USDCx",
      "active_bin": 510,
      "atomic": true,
      "spread": 5,
      "old_range": { "min": 500, "max": 504, "bins": 5 },
      "new_range": { "min": 505, "max": 515, "bins": 11 },
      "moves": [
        { "from": 500, "to_offset": -5, "to_bin": 505, "dlp": "196000" },
        { "from": 501, "to_offset": -4, "to_bin": 506, "dlp": "196000" }
      ],
      "stx_balance": 12.5,
      "estimated_gas_stx": 0.05
    }
  },
  "error": null
}

run — 已执行：

{
  "status": "success",
  "action": "run",
  "data": {
    "decision": "EXECUTED",
    "health": { "..." : "..." },
    "plan": { "..." : "..." },
    "transaction": {
      "txid": "0xabc...",
      "explorer": "https://explorer.hiro.so/txid/0xabc...?chain=mainnet"
    }
  },
  "error": null
}

auto — 周期报告：

{
  "status": "success",
  "action": "auto",
  "data": {
    "mode": "loop",
    "interval_minutes": 15,
    "drift_threshold": 3,
    "spread": 5,
    "cycle": 1,
    "moves": 1,
    "skipped": 0,
    "errors": 0,
    "next_check": "2026-04-08T12:30:00.000Z"
  },
  "error": null
}

错误：

{ "status": "error", "action": "run", "data": null, "error": "descriptive message" }

已阻止：

{ "status": "blocked", "action": "run", "data": { "cooldown_minutes": 42 }, "error": "Cooldown active — 42 minutes remaining" }

已知限制

• 运行环境中必须已安装 @stacks/transactions 和 @stacks/wallet-sdk。
• 通过 move-relative-liquidity-multi 执行单笔原子交易——要么所有区间都移动，要么一个都不移动。没有部分执行的风险。
• 流动性分布在活跃区间上下 ±spread 个区间内（默认 ±5）。DLMM 区间不变量要求活跃区间下方的区间只能持有 Y 代币，活跃区间上方的区间只能持有 X 代币——活跃区间下方的源区间映射到目标偏移量 [-spread, 0]，活跃区间上方的源区间映射到 [0, +spread]。

来源

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