hodlmm-move-liquidity

HODLMM 流動性移動＆自動リバランサー

機能

アクティブビンがLPポジションから離れたら、流動性をアクティブビンへ移動します。Bitflow DLMM流動性ルーターのmove-relative-liquidity-multi関数を介した、1回のアトミックトランザクションで実行します。古いビンから流動性を引き出し、アクティブビンに預け入れる処理を、1回のオンチェーン呼び出しで行います。中間状態やノンスの順序制御がなく、部分実行のリスクもありません。

アクティブビンにはすべての取引が流れ、手数料が蓄積します。それ以外のビンにある資本は収益を生みません。このスキルは、収益を生む場所に流動性を集中させます。

autoコマンドは自律型リバランサーとして動作し、設定可能な間隔ですべてのプールを監視し、ドリフトがしきい値を超えると自動的に流動性を移動します。手動操作は不要です。一度設定すれば、エージェントが24時間体制で資本をアクティブビンに維持します。

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

このコンペティションにあるHODLMMの読み取りスキルは、どれも同じ壁に突き当たります。ドリフトを検出し、リスクを評価して、アクションを推奨しますが、その後は何もしません。アクティブビンが移動しても資本は動かず、使われないビンに留まって収益を生みません。

このスキルは、その一連の処理を完結させます。runコマンドは必要に応じて流動性を移動します。autoコマンドを使えば自律的に実行でき、このスキルを実行するエージェントは、人の介入なしで資本を生産的な状態に保てます。24時間、年中無休で稼働します。

安全に関する注意

• ブロックチェーンに書き込みます。 move-relative-liquidity-multiを介し、リバランスごとに1回のアトミックトランザクションを実行します。引き出しと預け入れは1回のオンチェーン呼び出しで行われ、両方とも成功するか、どちらも実行されません。
• 資金を移動します。 古いビンから流動性を取り除き、新しいビンに配置します。トークンがLPのウォレットから出ることはなく、DLMM流動性ルーターコントラクトを経由します。
• メインネット専用です。 すべてのコントラクトアドレスはStacksのメインネット上にあります。
• runには--confirmが必要です。 指定しない場合、runは計画の詳細をすべて含むドライランのプレビューを出力します。トランザクションはブロードキャストされません。autoコマンドは直接実行されます（オペレーターが起動することで実行を選択します）。
• postConditionMode: Allow — HODLMMの操作では、同じトランザクション内でDLPトークンを発行およびバーンします。これは送信者側のポストコンディションでは表現できません。代わりに、コントラクトレベルのスリッページ保護を適用します。各移動では、DLPシェアの返還量が95％以上（min-dlp）であることを求め、流動性手数料を金額の5％以下に制限します（max-x-liquidity-fee、max-y-liquidity-fee）。コントラクトがいずれかの上限に違反した場合、トランザクションはオンチェーンで取り消されます。追加の安全策として、--confirmゲート、クールダウン、レンジ内チェック、ガスチェックがあります。
• 同じプールでの移動には4時間のクールダウンがあります。 コードで適用され、ディスクに保存されます。

コマンド

doctor

APIへのアクセス、ウォレットの準備状況、依存関係の利用可否を確認します。

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

scan

すべてのHODLMMプールを読み取り専用でスキャンします。各ポジションのレンジ内ステータス、ビン範囲、アクティブビン、ドリフト距離を表示します。

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> — アクティブビンを中心とするビンの幅±N（デフォルト：5、最大：10）
• --force — ポジションがレンジ内でもリバランスを強制します（アクティブビンを中心に再配置）

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> — 移動を開始する最小ドリフト（デフォルト：3）
• --spread <n> — アクティブビンを中心とするビンの幅±N（デフォルト：5、最大：10）
• --max-moves <n> — 1サイクルあたりの最大移動回数。0は無制限（デフォルト：0）
• --once — 1サイクル実行して終了します

install-packs

外部パックは不要です。

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

出力仕様

すべてのコマンドはstdoutにJSONを出力します。

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