hodlmm-move-liquidity

What this skill does

# HODLMM Move-Liquidity & Auto-Rebalancer

## 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.

## Why agents need it

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.

## 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.

## Commands

### doctor

Check API access, wallet readiness, and dependency availability.

```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
```

### run

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

```bash
# 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>
```

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)

### auto

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

```bash
# 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
```

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

### install-packs

No external packs required.

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

## 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 m