bitflow-hodlmm-deposit

# Bitflow HODLMM Deposit ## What it does `bitflow-hodlmm-deposit` deposits wallet assets into selected Bitflow HODLMM bins on Stacks mainnet. It is a primitive write skill: one action, one HODLMM add-liquidity transaction, and proof-ready JSON output. The skill is pool-agnostic across Bitflow HODLMM pools that satisfy the expected liquidity-router, token, `pool-token`, and `pool-token-id` interface. Selected bins may already have wallet LP position state or may be first-time wallet position targets. The bin itself must exist in the protocol pool; the skill does not create protocol bins. It supports first-time deposits into valid selected bins and only uses existing wallet position state to adjust the postcondition plan. ## Why agents need it Agents need a reliable HODLMM entry primitive before they can build full economic loops such as Zest-to-HODLMM routing or HODLMM range deployment. Without this primitive, a router can identify that capital should enter HODLMM, but it cannot safely execute the HODLMM deposit leg. ## Safety notes - This is a write skill and can move funds. - It deposits wallet token balances into HODLMM liquidity bins on mainnet. - It requires explicit `--confirm=DEPOSIT` before broadcast. - It blocks unsupported pool/router/token interfaces before broadcast. - It validates one-sided and two-sided deposit rules for the selected bins. - It supports both topping up existing wallet bin positions and initializing wallet position state in valid selected protocol bins. - It uses active-bin tolerance, minimum DLP protection, liquidity-fee bounds, balance checks, pending-transaction checks, and deny-mode postconditions where expressible. - It is not a withdrawal, recentering, DCA, keeper order, swap, APY router, or cross-protocol workflow. ## Commands ### doctor Checks environment, selected pool readiness, router interface, token contracts, token balances, STX gas reserve, and pending transaction depth. Safe to run anytime. ```bash bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts doctor --wallet <stacks-address> --pool-id <pool-id> ``` ### status Builds a read-only deposit preview. It reports selected bins, active-bin offsets, token amounts, minimum DLP, fee bounds, wallet balance requirements, active-bin tolerance, and postcondition plan. ```bash bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts status --wallet <stacks-address> --pool-id <pool-id> --amount-x <amount> --amount-y <amount> ``` Useful selection options: ```bash bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts status --wallet <stacks-address> --pool-id <pool-id> --offsets -1,0,1 --amount-x <amount> --amount-y <amount> bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts status --wallet <stacks-address> --pool-id <pool-id> --range -2:2 --amount-x <amount> --amount-y <amount> bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts status --wallet <stacks-address> --pool-id <pool-id> --plan-json '[{"offset":0,"xAmount":"1000","yAmount":"1000"}]' ``` ### run Rechecks all live state, builds the HODLMM add-liquidity transaction, broadcasts only after explicit confirmation, and returns proof JSON. ```bash bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts run --wallet <stacks-address> --pool-id <pool-id> --amount-x <amount> --amount-y <amount> --confirm=DEPOSIT ``` Without `--confirm=DEPOSIT`, `run` refuses before broadcast. ## Agent selection surface The skill exposes the same kind of strategy surface as the withdrawal primitive, with deposit-specific amount controls. | Option | Required | Purpose | |---|---:|---| | `--wallet <stacks-address>` | Yes | Wallet that owns the tokens and signs the write. | | `--pool-id <pool-id>` | Yes | HODLMM pool to inspect and deposit into. | | `--amount-x <amount>` | Conditional | Token X amount to deposit in base units. | | `--amount-y <amount>` | Conditional | Token Y amount to deposit in base units. | | `--bin-id <id>` | No | Deposit into one absolute bin. | | `--bin-ids <ids>` | No | Deposit into a comma-separated selected set of bins. | | `--offsets <offsets>` | No | Deposit into active-bin-relative offsets. | | `--range <start:end>` | No | Deposit across an active-bin-relative range. | | `--distribution <mode>` | No | `equal` or `explicit`. | | `--plan-json <json>` | No | Explicit per-bin amounts for advanced agent composition. | | `--slippage-bps <bps>` | No | Minimum DLP and fee-bound tolerance. | | `--active-bin-max-deviation <bins>` | No | Abort if active bin drifts too far before broadcast. | | `--min-gas-reserve-ustx <uSTX>` | No | Minimum STX reserve to preserve after deposit and fee. | | `--confirm DEPOSIT` | Run only | Explicit write confirmation. | | `--wait-seconds <seconds>` | No | Inclusion/status wait window. | Exactly one selector may be used at a time: `--plan-json`, `--bin-id`, `--bin-ids`, `--offsets`, or `--range`. If no selector is provided, the default is the current active bin. At least one nonzero token amount is required through `--amount-x`, `--amount-y`, or `--plan-json`. ## Output contract All outputs are JSON to stdout. Success: ```json { "status": "success", "action": "status", "data": {}, "error": null } ``` Blocked: ```json { "status": "blocked", "action": "run", "data": {}, "error": { "code": "CONFIRMATION_REQUIRED", "message": "This write skill requires explicit confirmation.", "next": "Re-run with --confirm=DEPOSIT." } } ``` Fatal error: ```json { "error": "descriptive message" } ``` ## Known constraints - Mainnet only. - The selected pool must be a live Bitflow HODLMM pool with the shared `dlmm-liquidity-router-v-1-1` interface. - The proof path targets `add-relative-liquidity-same-multi`. - The default plan deposits into the current active bin if no bin selector is provided. - The default active-bin deviation is `0`, meaning broadcast uses an exact active-bin match unless `--active-bin-max-deviation` is increased. - Below-active bins accept only token Y; above-active bins accept only token X; active-bin deposits may be one-sided or two-sided. - The skill prefers active/restored AIBTC wallet sessions before fallback signer inputs. A locked wallet returns JSON guidance rather than prompting interactively. - Nonce serialization across multiple write legs belongs in a composed skill or workflow guide, not inside this primitive. ## Origin Winner of AIBTC x Bitflow Skills Pay the Bills competition. Original author: @macbotmini-eng Competition PR: https://github.com/BitflowFinance/bff-skills/pull/556 ## Post-condition correctness update (2026-07-15 field audit F-7) Per-bin position-NFT post-conditions are keyed on **actual NFT ownership** (Hiro NFT holdings), not only `userLiquidity > 0`. Root cause: the pool's `tag-pool-token-id` burns and re-mints the bin NFT on every mint/burn where the wallet already owns it — and ownership **persists at zero liquidity**, so re-entering a previously fully-withdrawn bin moves the NFT even though the positions endpoint shows no liquidity. Without the PC, such a deposit aborts in Deny mode and burns the fee.