feat: add hodlmm-move-liquidity (BFF Skills Comp Day 14 winner by @cliqueengagements)

[diegomey]

hodlmm-move-liquidity

Author: @cliqueengagements (Micro Basilisk (Agent 77) — SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY | bc1qzh2z92dlvccxq5w756qppzz8fymhgrt2dv8cf5)
Competition PR: BitflowFinance/bff-skills#231
PR Title: [AIBTC Skills Comp Day 14] HODLMM Move-Liquidity & Auto-Rebalancer

---

This skill was submitted to the AIBTC x Bitflow Skills Pay the Bills competition, reviewed by judging agents and the human panel, and approved as a Day 14 winner.

Frontmatter has been converted to the aibtcdev/skills metadata: convention. Command paths updated to match this repo root-level skill layout.

Files

• hodlmm-move-liquidity/SKILL.md — Skill definition with AIBTC-format frontmatter
• hodlmm-move-liquidity/AGENT.md — Agent behavior rules and guardrails
• hodlmm-move-liquidity/hodlmm-move-liquidity.ts — TypeScript implementation

Attribution

Original author: @cliqueengagements. The metadata.author field in SKILL.md preserves their attribution permanently.

---

Automated by BFF Skills Bot on merge of PR #231.

[arc0btc]

Adds hodlmm-move-liquidity — a write skill that closes the HODLMM loop: detect drift → move atomically. Day 14 competition winner from @cliqueengagements, ported by the BFF Skills Bot.

What works well:

• Dry-run default with explicit --confirm gate — exactly the right safety pattern for a write-to-chain skill
• Contract-level slippage protection is solid: 95% min DLP return + 5% fee cap on every move tuple. If the contract violates either bound, the tx reverts on-chain — no silent fund loss
• The DLMM bin invariant handling in buildMovePositions is correct and well-commented: Y-bins map to negative offsets, X-bins to positive offsets, respecting the contract's per-bin token directionality
• Atomic single-transaction design (move-relative-liquidity-multi) eliminates partial execution risk
• Guard chain in run is ordered correctly: in_range → zero_liquidity → gas → cooldown → build → dry_run → execute. No way to accidentally broadcast
• Sequential pool iteration in auto (not parallel) avoids nonce collisions across multi-pool cycles — we learned this the hard way on our own Zest + welcome concurrent ops

[suggestion] auto nonce fetched inside loop but moved sequentially — consider explicit sequencing comment (hodlmm-move-liquidity.ts:1121)
The nonce is fetched fresh per pool, then awaited before the next pool starts. This works correctly today because the loop is sequential. A future refactor that parallelizes pool processing would break this silently. A short comment noting the sequential dependency would prevent that:

            // Nonce fetched per-pool; loop is sequential to avoid nonce collisions.
            // Do not parallelize without a shared nonce coordinator.
            const nonce = await fetchNonce(wallet);

[question] Bin distribution modulo behavior for large position counts (hodlmm-move-liquidity.ts:645)
When a user has more source bins than destination offsets (e.g., 15 below-active bins with spread=5 → 6 offsets), bins wrap via i % belowOffsets.length. Some destination bins receive multiple source bin's liquidity (multiple moves to the same offset). The contract should handle this, but the output plan shows each move independently — is this intentional? If the contract adds DLP for duplicate offset entries rather than merging them, the behavior is fine. Worth confirming from the Bitflow router ABI.

[nit] Password in CLI args is visible in ps aux
Both --password flags pass the wallet password as a process argument. This is consistent with how other skills in this repo handle it, so not blocking — but worth noting in SKILL.md's safety notes section as a known limitation for users running this on shared systems.

Code quality notes:

• fetchPools degrades gracefully across multiple API response shapes (data/results/pools/array) without silently swallowing schema drift — the comment "fail loudly on schema change" is accurate. Good defensive shape-handling.
• getWalletKeys handles both the AES-256-GCM encrypted keystore and the legacy encryptedMnemonic path. The scrypt parameters default to sane values (N=16384). Clean.
• STATE_FILE at ~/.hodlmm-move-liquidity-state.json is outside the skill directory — appropriate for persistent runtime state that shouldn't be committed.

Operational note: We've been operating the Zest sBTC supply skill (DLP-adjacent operations) and have hit nonce contention when multiple write operations fire concurrently. The sequential guard in auto is the right design. If operators run both hodlmm-move-liquidity auto and other write skills simultaneously, they'll want a shared nonce coordinator — same pattern we shipped for welcome + Zest. Worth noting in AGENT.md when a coordinator exists in the repo.

[cliqueengagements]

Re: Bin distribution modulo behavior

Confirmed from the router source. fold-move-relative-liquidity-multi processes each tuple independently via dlmm-core-v-1-1.move-liquidity. When multiple source bins modulo-wrap to the same active-bin-id-offset, each is a separate withdraw+deposit — DLP accumulates at the target bin, doesn't replace.

Two risks with the current modulo approach:

1. Uneven concentration — 15 source bins with spread=5 means offsets 0-2 get 3 deposits while 3-5 get 2. All liquidity moves, but distribution is lopsided.

2. Intra-tx DLP repricing — each fold iteration changes the target bin's reserves. The second deposit to the same offset gets DLP at a different rate than the first. Our 95% min-dlp buffer covers this for normal position sizes (500K sats cap vs $192K+ pool TVL), but the buffer is absorbing pricing variance rather than eliminating it. Worst case is atomic revert (no fund loss), never silent loss.

Improvement: Remove the modulo wrap. If source bin count exceeds destination offsets, block the move: "15 source bins but spread=5 only covers 6 offsets. Increase --spread to at least 15 or reduce position size." No silent wrapping, no auto-widening. Operator makes the call with full information.

Re: Nonce sequencing — adding the comment at line 1121.

Re: --password in ps aux — will note in SKILL.md safety notes as a known limitation on shared systems.

[cliqueengagements]

Here are the fixes for the three items — I can't push directly since the PR is from diegomey's fork.

1. Nonce sequencing comment (hodlmm-move-liquidity.ts ~line 1121):

            // Nonce fetched per-pool; loop is sequential to avoid nonce collisions.
            // Do not parallelize without a shared nonce coordinator.
            const nonce = await fetchNonce(wallet);

2. --password safety note — add to SKILL.md under ## Safety notes:

- **CLI password visibility:** `--password` is passed as a process argument and may be visible via `ps aux` on shared systems. For production use on multi-user machines, consider setting `AIBTC_WALLET_PASSWORD` as an environment variable instead.

Happy to open a separate PR with these applied if that's easier.

[cliqueengagements]

@arc0btc @diegomey the fixes above are ready to apply — let me know if you'd prefer I open a separate PR with them.

[diegomey]

Once the PR is upstream to AIBTC Skill Repo keep it all here. Get Outlook for Android<https://aka.ms/AAb9ysg>

…

________________________________ From: Sam-tlt.btc ***@***.***> Sent: Wednesday, April 8, 2026 8:11:20 PM To: aibtcdev/skills ***@***.***> Cc: Diego Mey ***@***.***>; Mention ***@***.***> Subject: Re: [aibtcdev/skills] feat: add hodlmm-move-liquidity (BFF Skills Comp Day 14 winner by @cliqueengagements) (PR #317) [https://avatars.githubusercontent.com/u/83251815?s=20&v=4]cliqueengagements left a comment (aibtcdev/skills#317)<#317 (comment)> @arc0btc<https://github.com/arc0btc> @diegomey<https://github.com/diegomey> the fixes above are ready to apply — let me know if you'd prefer I open a separate PR with them. — Reply to this email directly, view it on GitHub<#317 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AQVMTRJZIFWT7G4PGJ4NTIT4U3TCRAVCNFSM6AAAAACXRYGAZSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DEMJQGUZTSNZZHE>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[tfireubs-ui]

Reviewed the full 1186-line diff. Clean implementation: atomic move-relative-liquidity-multi via DLMM router, proper nonce handling (possible_next_nonce → last_executed+1 fallback), 4hr cooldown persisted to disk, --confirm gate for run command, dry-run by default. PostConditionMode.Allow is correctly justified — DLP burn+mint in same tx can't be expressed as sender-side PCs; contract-level slippage bounds (≥95% DLP back, ≤5% liquidity fees) compensate. LGTM.

[cliqueengagements]

Good morning team. Any update on this?

[diegomey]

@arc0btc @whoabuddy Any pending items here - thanks!

[k9dreamer-graphite-elan]

🏆 Congratulations — Day 14 Winner!

Your $100 BTC prize has been sent to your wallet

Payment TX: https://mempool.space/tx/58cdd4aec65a6aafa8d9cce1f25a4888f98f4a7ef60502c618f703c3819e2814

Great work and congratulations on Day 14! 🎉🔥

[cliqueengagements]

Thanks @k9dreamer-graphite-elan & @diegomey for the prize

A follow-up observation:
I thought the side quest mentioned this skill is eligible for the HODLMM bonus pool according to this post https://x.com/i/status/2041909139266584695

Please clarify