hodlmm-move-liquidity

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HODLMM Move-Liquidity & Auto-Rebalancer

HODLMM 流动性转移与自动再平衡工具

What it does

功能介绍

When the active bin drifts away from your LP position, move your liquidity to the active bin. One atomic transaction via the Bitflow DLMM liquidity router's

move-relative-liquidity-multi

function: withdraw from old bins and deposit into the active bin in a single on-chain call. No intermediate state, no nonce sequencing, no partial execution risk.

The active bin is where all trades flow and fees accrue. Capital in any other bin earns zero. This skill concentrates your liquidity where it earns.

The

auto

command runs as an autonomous rebalancer — it monitors all pools on a configurable interval and automatically moves liquidity when drift exceeds a threshold. No manual intervention required. Set it, and the agent keeps your capital in the active bin around the clock.

当活跃仓位偏离你的LP（流动性提供者）头寸时，将你的流动性转移至活跃仓位。通过Bitflow DLMM流动性路由器的

move-relative-liquidity-multi

函数完成一笔原子交易：在单次链上调用中从旧仓位提取并存入活跃仓位。无中间状态，无需排序随机数，无部分执行风险。

活跃仓位是所有交易流动和手续费累积的地方。其他任何仓位中的资金都无法产生收益。本工具将你的流动性集中在能产生收益的位置。

auto

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

Why agents need it

Agent为何需要它

Every HODLMM read skill in the competition hits the same wall. They detect drift, score risk, recommend action — then stop. Capital sits in dead bins earning nothing while the active bin moves on without it.

This skill closes the loop. The

run

command moves liquidity on demand. The

auto

command makes it autonomous — an agent running this skill keeps its capital productive without human intervention, 24/7.

竞赛中所有HODLMM只读工具都面临同一个瓶颈：它们检测偏离、评估风险、建议操作——然后就停止了。当活跃仓位转移后，资金仍留在无收益的仓位中无法产生利润。

本工具闭环解决了这个问题。

run

命令可按需转移流动性。

auto

命令使其实现自主化——运行本工具的Agent无需人工干预，就能24/7保持资金的收益性。

Safety notes

安全说明

Writes to chain. One atomic transaction per rebalance via
```
move-relative-liquidity-multi
```
. Withdraw + deposit happen in a single on-chain call — either both succeed or neither does.
Moves funds. Liquidity is removed from old bins and placed in new bins. No tokens leave the LP's wallet — they pass through the DLMM liquidity router contract.
Mainnet only. All contract addresses are mainnet Stacks.
--confirm
required for
run
. Without it,
```
run
```
outputs a dry-run preview with full plan details. No transaction is broadcast. The
```
auto
```
command executes directly (operator opts in by starting it).
postConditionMode: Allow — HODLMM operations mint and burn DLP tokens in the same transaction, which cannot be expressed as sender-side post-conditions. Contract-level slippage protection compensates: each move requires ≥95% DLP shares back (
```
min-dlp
```
) and caps liquidity fees at 5% of the amount (
```
max-x-liquidity-fee
```
,
```
max-y-liquidity-fee
```
). If the contract violates either bound, the transaction reverts on-chain. Additional safety:
```
--confirm
```
gate, cooldown, in-range check, and gas check.
4-hour cooldown between moves on the same pool, enforced in code and persisted to disk.

写入区块链：每次再平衡通过
```
move-relative-liquidity-multi
```
完成一笔原子交易。提取+存入在单次链上调用中完成——要么全部成功，要么全部失败。
转移资金：流动性从旧仓位移除并放入新仓位。代币不会离开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小时冷却期：代码中强制执行并持久化到磁盘。

Commands

命令

doctor

Check API access, wallet readiness, and dependency availability.

bash

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

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

bash

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

scan

Read-only scan of all HODLMM pools. Shows each position's in-range status, bin range, active bin, and drift distance.

bash

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

对所有HODLMM池进行只读扫描。显示每个头寸的范围内状态、仓位范围、活跃仓位和偏离距离。

bash

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

run

Assess a specific pool and generate a move plan. Dry-run by default.

bash

undefined

评估特定池并生成转移计划。默认试运行模式。

bash

undefined

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)

自定义范围（默认：活跃仓位前后±5个仓位）

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>


Options:
- `--spread <n>` — bin spread ±N around active bin (default: 5, max: 10)
- `--force` — force rebalance even if position is in range (recenter around active bin)

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


选项：
- `--spread <n>` —— 活跃仓位前后±N个仓位的范围（默认：5，最大值：10）
- `--force` —— 即使头寸在范围内也强制再平衡（围绕活跃仓位重新中心化）

auto

Autonomous rebalancer. Monitors all pools on a loop, auto-moves liquidity when drift exceeds threshold.

bash

undefined

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

bash

undefined

Start auto-rebalancer (checks every 15 minutes, moves when drift ≥ 3 bins)

启动自动再平衡器（每15分钟检查一次，偏离≥3个仓位时触发转移）

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


Options:
- `--interval <minutes>` — check interval (default: 15, minimum: 5)
- `--drift-threshold <bins>` — minimum drift to trigger move (default: 3)
- `--spread <n>` — bin spread ±N around active bin (default: 5, max: 10)
- `--max-moves <n>` — max moves per cycle, 0 = unlimited (default: 0)
- `--once` — run one cycle then exit

bun run hodlmm-move-liquidity/hodlmm-move-liquidity.ts auto --wallet <addr> --password <pass> --once


选项：
- `--interval <minutes>` —— 检查间隔（默认：15，最小值：5）
- `--drift-threshold <bins>` —— 触发转移的最小偏离值（默认：3）
- `--spread <n>` —— 活跃仓位前后±N个仓位的范围（默认：5，最大值：10）
- `--max-moves <n>` —— 每次循环的最大转移次数，0表示无限制（默认：0）
- `--once` —— 运行一次循环后退出

install-packs

No external packs required.

bash

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

无需外部包。

bash

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

Output contract

输出合约

All commands emit JSON to stdout.

scan — success:

json

{
  "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 — in range (no action):

json

{
  "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 — dry-run:

json

{
  "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 — executed:

json

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

auto — cycle report:

json

{
  "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
}

Error:

json

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

Blocked:

json

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

所有命令均向标准输出（stdout）发送JSON。

scan —— 成功：

json

{
  "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 —— 在范围内（无操作）：

json

{
  "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 —— 试运行：

json

{
  "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 —— 已执行：

json

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

auto —— 循环报告：

json

{
  "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
}

错误：

json

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

被阻止：

json

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

Known constraints

已知限制

Requires
```
@stacks/transactions
```
and
```
@stacks/wallet-sdk
```
to be installed in the runtime environment.
Single atomic transaction via
```
move-relative-liquidity-multi
```
— either all bins move or none do. No partial execution risk.
Liquidity is distributed across ±spread bins around the active bin (default ±5). The DLMM bin invariant requires bins below active to hold only Y token and bins above active to hold only X token — source bins below active map to destination offsets [-spread, 0] and source bins above active map to [0, +spread].

运行时环境需安装
```
@stacks/transactions
```
和
```
@stacks/wallet-sdk
```
。
通过
```
move-relative-liquidity-multi
```
完成单次原子交易——要么所有仓位都转移，要么都不转移。无部分执行风险。
流动性分布在活跃仓位前后±spread个仓位中（默认±5）。DLMM仓位不变性要求活跃仓位下方的仓位仅持有Y代币，活跃仓位上方的仓位仅持有X代币——来源仓位在活跃下方映射到目标偏移[-spread, 0]，来源仓位在活跃上方映射到[0, +spread]。

Origin

起源

Winner of AIBTC x Bitflow Skills Pay the Bills competition. Original author: @cliqueengagements Competition PR: https://github.com/BitflowFinance/bff-skills/pull/231

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