hodlmm-range-keeper

What this skill does

# HODLMM Range Keeper

## What it does
Actively manages HODLMM concentrated-liquidity positions by monitoring active-bin drift, estimating fee accrual, and re-centering LP ranges when the market moves away. Unlike signal-only analytics skills, this closes the full management loop: detect drift, plan the re-center, simulate the outcome, execute via MCP tools, and verify. Supports autonomous `run` mode that scans all pools and re-centers any drifted position in a single cycle.

## Why agents need it
HODLMM concentrated liquidity earns fees only when the active bin is within your position range. When price moves, the active bin drifts away and your liquidity sits idle — earning nothing while exposed to impermanent loss. Manual monitoring is impractical across multiple pools. This skill turns passive LP deposits into actively managed positions: it tracks where your bins are, where the market is, and moves your liquidity to stay in range and keep earning.

## Safety notes
- **Writes to chain**: Withdraws liquidity and re-deposits into new bins. Real funds move.
- **Drift threshold**: Will not re-center unless the active bin drifts >= 3 bins from your position center (configurable).
- **Cooldown**: 30-minute cooldown between recenters on the same pool to prevent churn.
- **Gas cap**: 50 STX maximum per cycle. Will not execute if gas estimate exceeds cap.
- **Dust filter**: Ignores positions < 5,000 sats to avoid unprofitable micro-recenters.
- **--confirm gate**: The `recenter` command requires explicit `--confirm` flag. Without it, nothing executes.
- **Fee preservation**: Tracks deposit baselines per bin. On re-center, fees above baseline are harvested (kept); only principal is re-deployed.
- **Mainnet only**: HODLMM is not available on testnet.
- **MCP execution**: Actual on-chain transactions are emitted as MCP tool calls (`bitflow_hodlmm_remove_liquidity`, `bitflow_hodlmm_add_liquidity`). The agent runtime executes them.

## Commands

### doctor
Check wallet, HODLMM API access, pool availability, existing positions, and MCP tool requirements. Read-only, safe to run anytime.
```bash
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts doctor
```

### status
Analyze all LP positions: drift magnitude, range efficiency (% of bins in active range), estimated fees, and whether re-centering is needed. Records fee baselines locally on first observation; otherwise read-only.
```bash
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts status
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts status --pool dlmm_1
```

### plan
Dry-run a re-center: simulate withdraw and re-deposit, show expected bin layout, fees harvested, gas cost. No funds move.
```bash
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts plan --pool dlmm_1
```

### recenter
Execute the re-center: withdraw from drifted bins, harvest fees, re-deposit principal around active bin. Requires --confirm.
```bash
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts recenter --pool dlmm_1 --confirm
```

### run
Full autonomous cycle: scan all pools, assess drift, plan and execute recenters where needed. Use --confirm for live execution, omit for dry-run.
```bash
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts run
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts run --confirm
```

### history
Show past re-center events from local ledger. Useful for auditing position management.
```bash
bun run hodlmm-range-keeper/hodlmm-range-keeper.ts history
bun run hodlmm-range-keeper/hodlmm-range-keeper.ts history --pool dlmm_1 --limit 10
```

## Output contract

All outputs are JSON to stdout. Logs go to stderr.

**Success:**
```json
{ "status": "success", "action": "status", "data": { "positionsAnalyzed": 2, "needsRecenter": 1, "positions": [...] }, "error": null }
```

**Recenter ready:**
```json
{ "status": "success", "action": "execute_mcp", "data": { "step1_withdraw": { "tool": "bitflow_hodlmm_remove_liquidity", "params": {...} }, "step2_deposit": { "tool": "bitflow_hodlmm_add_liquidity", "params": {...} }, "summary": {...} }, "error": null }
```

**Blocked:**
```json
{ "status": "blocked", "action": "recenter", "data": { "cooldownRemainingMinutes": 15 }, "error": "Cooldown active." }
```

**Error:**
```json
{ "status": "error", "action": "recenter", "data": null, "error": "Pool dlmm_99 not found." }
```

### install-packs
No external packs required. Returns success immediately.
```bash
bun run hodlmm-range-keeper/hodlmm-range-keeper.ts install-packs --pack all
```

## Known constraints
- Mainnet only — HODLMM has no testnet deployment
- Fee estimation requires a baseline — first `status` after fresh install records current state as baseline (zero estimated fees until next check)
- Position re-centering executes as two sequential MCP calls (withdraw then deposit) — partial failure is possible if the deposit tx fails after a successful withdraw. In that case, funds are in the wallet, not lost. State is recorded optimistically before MCP execution; on partial failure, baselines reset and the next `status` call re-establishes them from current on-chain state.
- Active bin can move between the plan and recenter steps. The skill uses the latest active bin at execution time.
- HODLMM API (`bff.bitflowapis.finance`) may lag 1-2 blocks behind chain state
- Gas estimation is conservative (4 STX for 2 txs). Actual gas is typically lower.