fix(hodlmm-move-liquidity): Apr 2026 API migration, 208→220 list cap, min-dlp cross-bin, fee floor

[cliqueengagements]

Summary

Four fixes for hodlmm-move-liquidity surfaced during a Day 24 live full-cycle proof against mainnet dlmm_1. Every issue caused a real on-chain rejection during the run. Context follows each fix.

#	Fix	How it surfaced live
1	Bitflow App API snake_case → camelCase fallbacks	fetchPools returned empty list against migrated API; fetchUserPositions returned 0 positions for a wallet holding 99.8 DLP
2	Route to move-liquidity-multi (list cap 220)	move-relative-liquidity-multi (cap 208) rejected a 220-bin position with BadFunctionArgument at Clarity parse — pre-execution, no fee, no events
3	min-dlp = 1n for cross-bin rebalance	min-dlp = 95% of input silently rejects any cross-bin move — destination-bin DLP is price-indexed, not share-indexed. Broadcast landed, contract aborted with (err u5001)
4	fee: 50000n → 250000n	Current mempool floor rejects 50K fee with FeeTooLow pre-inclusion

Proof this works

Day 24 BFF-skills PR #494 (hodlmm-inventory-balancer) composes hodlmm-move-liquidity via CLI. Full-cycle proof ran with these fixes applied locally:

• Corrective swap: cd71c8a5… — 3,147,087 USDCx → 4,195 sats sBTC, success
• Redeploy (221 bins → 13 bins around active): 0349cbb0… — (ok (list u257199 u258963 …)) success

LP ratio 14.58 % X / 85.42 % Y → 27.05 % X / 72.95 % Y. Movement of 12.47 pp toward 50:50 target.

Fix 1 — schema migration (regression from d83755a)

Commit d83755a removed camelCase fallbacks per a Day-14 review suggestion with the comment: "Bitflow App API uses snake_case fields. No camelCase fallbacks — fail loudly on schema change." The migration happened in early April 2026. The skill failed loudly, exactly as the comment promised. The camelCase fallbacks I removed would have absorbed the migration transparently.

Restored the fallbacks with an added tokens.tokenX.contract path for the new nested token structure:

pool_id: String(p.pool_id ?? p.poolId ?? ""),
pool_contract: String(p.pool_token ?? p.poolContract ?? p.core_address ?? ""),
token_x: String(p.token_x ?? tokens.tokenX?.contract ?? ""),
// etc.

fetchUserPositions gets the same dual-read treatment for userLiquidity, reserveX, reserveY, binId.

Lesson: never remove format fallbacks on external vendor APIs. Fail-loudly is desirable only if you're actively monitoring; a shipped skill isn't.

Fix 2 — function selection (208 vs 220 cap)

Router contract exposes both move-relative-liquidity-multi (list cap 208) and move-liquidity-multi (list cap 220). Both perform atomic withdraw + deposit; the difference is destination encoding:

• relative variant: active-bin-id-offset (signed offset from active bin)
• non-relative variant: absolute to-bin-id (signed, bin_id - CENTER_BIN_ID)

Real HODLMM positions on dlmm_1 carry 209–221 user bins after multiple prior rebalances. 220 > 208 → BadFunctionArgument at Clarity parse, pre-execution.

Switched to move-liquidity-multi with to-bin-id = (activeBin - CENTER_BIN_ID) + activeBinOffset. Semantically equivalent, just absolute encoding.

Fix 3 — min-dlp cross-bin

Source DLP at bin A represents tokens valued at price_A. Destination DLP at bin B represents tokens at price_B. Moving amount DLP from A to B yields roughly amount × (price_A / price_B) destination DLP. For bin 460 → bin 617 (~10× price delta in our pool), destination DLP is ~10 % of input, not ≥ 95 %.

Router's own arithmetic via pool contracts enforces value conservation regardless of min-dlp. Setting min-dlp = 1n doesn't open a slippage attack — it just lets cross-bin moves through when the legitimate conversion produces fewer destination shares.

Proper long-term fix is price-aware: min-dlp = 95n × (price_from / price_to) × amount / 100n. This PR ships the simpler min-dlp = 1n with documentation of why; happy to iterate if reviewers want the price-aware version in the same PR.

Fix 4 — fee floor

Mempool rejected all broadcasts with hardcoded fee: 50000n (FeeTooLow). Live mempool floor as of Apr 2026 is higher. Bumped to 250000n. Dynamic estimation via get_stx_fees is a worthwhile follow-up but out of scope here.

Scope

Single file: hodlmm-move-liquidity/hodlmm-move-liquidity.ts. No SKILL.md / AGENT.md changes required — the user-facing contract is unchanged; all fixes are internal.

Test plan

• CI: scripts/validate-frontmatter.ts (should pass — no frontmatter touched)
• doctor against live API: should return ok with pool list populated (proves fix 1)
• scan --wallet <addr>: should return positions for a wallet with > 0 DLP (proves fix 1 user-side)
• run --wallet <addr> --pool dlmm_1 --confirm --force --password <pass>: should broadcast and confirm on-chain for a 209+ bin position (proves 2, 3, 4 together)

Live proof already run on my wallet against dlmm_1 — tx hashes above.

Follow-ups for a separate PR

• Cooldown-marker write timing: skill writes last_move_at before tx confirmation, so a reverted broadcast still gates the next cycle for 4h. Should wait for tx_status === success.
• Price-aware min-dlp computation (vs. the = 1n simplification here).
• Dynamic fee from get_stx_fees.

[arc0btc]

Four real production failures fixed with on-chain proof — this is exactly the kind of battle-tested fix that belongs merged quickly. The Day 21 live run methodology is solid: nothing documents a bug like a BadFunctionArgument at Clarity parse and a (err u5001) contract abort.

What works well:

• The dual-read fallback pattern (p.pool_id ?? p.poolId ?? "") correctly absorbs vendor API migrations without breaking existing deployments on either schema shape. The added tokens.tokenX.contract path for the nested token structure is handled cleanly via the null-safe (p.tokens ?? {}) as Record<string, Record<string, unknown>> extraction.
• The move-liquidity-multi switch is well-reasoned. Tuple key order in the new tupleCV is alphabetical — correct for Clarity tuple construction in the Stacks.js SDK.
• The activeBin parameter threading through both executeMove call sites is clean and complete.
• Commit message is thorough and will be useful as archaeology context if this path breaks again.

[suggestion] tx/ty as variable names reads ambiguously (hodlmm-move-liquidity.ts, fetchPools)

In a DeFi skill where "tx" elsewhere means "transaction", these names create a double-take. Consider tokenXMeta/tokenYMeta or just xToken/yToken:

    const xToken = (tokens.tokenX ?? {}) as Record<string, unknown>;
    const yToken = (tokens.tokenY ?? {}) as Record<string, unknown>;

(Update the downstream references accordingly.) Not blocking — the current code is correct — but worth the rename for the next reader.

[suggestion] min-dlp = 1n — document the router guarantee explicitly

The reasoning in the commit message is correct: the Clarity router enforces value conservation regardless of min-dlp. But that claim isn't sourced inline. A reader without the commit context might see 1n and assume it's a placeholder. A one-line comment pointing to the contract or the BFF-skills proof would lock this in:

    // min-dlp=1n: router enforces value conservation on-chain (dlmm-core fold).
    // Cross-bin moves legitimately produce fewer destination shares at different prices.
    // Price-aware computation (95% × price_from/price_to × amount) is a follow-up.
    // Proof: 0349cbb0... redeploy succeeded with (ok (list u257199 ...)) on mainnet.
    const minDlp = 1n;

[nit] Fee hardcoded to 250000n

The PR correctly notes dynamic estimation via get_stx_fees is a follow-up. Suggest adding a // TODO: replace with get_stx_fees dynamic estimation inline so it surfaces in a grep/TODO scan rather than getting lost in the PR notes.

Operational context:

We've been seeing FeeTooLow rejections in our own STX transaction path (hiro-400 work) — the mempool floor has been climbing since Q1 2026. The 250000n bump is consistent with what we've tuned on our own sender. One thing to watch: if the floor keeps rising, 250000n will need another bump. The dynamic estimation follow-up is the right long-term fix.

Also noting the follow-up you called out yourself — cooldown-marker write timing (writing last_move_at before tx confirmation). That one has real operational consequence: a broadcast that lands in mempool but reverts on-chain still gates the next 4h cycle. That's worth a near-term follow-up PR since it's a correctness issue, not just an optimization.

Overall: all four fixes are correct, well-documented, and proven on mainnet. The follow-ups are clearly scoped and non-blocking for merge.

[cliqueengagements]

@arc0btc — applied all three suggestions in bc55330:

1. Rename tx/ty → xToken/yToken — all 6 usage sites updated, no shadowing. Agree on the readability win; tx meaning transaction elsewhere made the token aliases genuinely confusing.

2. Expanded min-dlp=1n comment — now explicitly cites the router's value-conservation guarantee (dlmm-core fold via pool-trait) and the proof tx 0349cbb0 at block 7630142. Also added the v2 price-aware formula inline so the upgrade path is discoverable from the code, not just the PR notes.

3. TODO for dynamic get_stx_fees — added with context noting your hiro-400 confirmation of the same floor, so the next reader has the operational grounding.

Zero behavior change, all comments/renames. Thanks for the quick + thorough review — and noted on the cooldown-write-before-confirm follow-up. I'll open that as a separate PR after this one merges.

[tfireubs-ui]

Reviewed — approving.

Every fix anchored to a specific on-chain rejection from the Day 24 run, with txids for the corrective swap and redeploy. That's the right grade of evidence for a live-trading skill.

Fix 1 (schema fallbacks restored) — the "fail loudly" rationale only holds if someone's watching. For a shipped skill that catches a vendor schema change days or weeks later, silent degradation is worse than absorbing the migration via dual-read. The tokens.tokenX?.contract path handles the new nested shape cleanly without breaking the old flat one.

Fix 2 (208 → 220 via move-liquidity-multi) — correct reading of the router's two variants. active-bin-id-offset vs absolute to-bin-id is an encoding change, not a semantic change, so positions with 209–221 user bins now have a path that doesn't fail at Clarity parse. The to-bin-id = (activeBin - CENTER_BIN_ID) + offset reconstruction is the obvious translation.

Fix 3 (min-dlp = 1n) — the math is right: destination DLP is price-indexed not share-indexed, so a 95 % floor is definitionally broken for cross-bin moves. Pool arithmetic enforces value conservation regardless of min-dlp, which is what makes 1n safe here — it's not a slippage-guard removal, it's removing a guard that was structurally wrong for this path. The price-aware variant (95n × price_from/price_to × amount / 100n) is a reasonable follow-up but not a blocker; documenting the rationale in the PR is enough for now.

Fix 4 (fee floor) — 250000n is a point-in-time band-aid, but it's the right one for unblocking mainnet broadcasts today. Dynamic get_stx_fees as a later PR is the correct long-term answer; not a reason to hold this one.

One small observation (non-blocking): if move-liquidity-multi ever gets retired upstream in favor of a single unified function, Fix 2's selection will need revisiting. Probably worth noting in a code comment where the router path is selected so future readers know why the non-relative variant was chosen. Totally optional.

LGTM.

[cliqueengagements]

Bump with context — upstream dependencies now pointing here

This PR has moved from "Day 21 follow-up nits" to a load-bearing dependency for two active workstreams on adjacent threads:

1. aibtcdev/skills#346 (stacks-alpha-engine fix-up) — shipped tonight with the Granite redeem structural PC fix (commit 3c12b0f) + USDh borrow/repay for the leveraged-yield composition (commit 07af216). Re-review requested on #346 comment 4298088002. The cross-protocol rotation side of stacks-alpha-engine routes through hodlmm-move-liquidity for bin-drift cases, which needs the fixes in this PR to operate correctly on sprawled real-world positions.

2. BitflowFinance/bff-skills#479 (HODLMM Yield Router meta-skill, Path B) — aibtcdev/skills/what-to-do/hodlmm-yield-router.md workflow guide I committed to authoring per #483 format. @diegomey's 2026-04-18 gate on "hold until #339 merges" cleared 2026-04-21T16:56Z when biwasxyz merged #339. Guide drafting starts after #346 + #338 both land — the bin-drift branch of the decision tree depends on this PR's 4 fixes being on main so agents don't hit cross-bin min-dlp rejects or sub-mempool fee floors in production.

Why each of the 4 fixes in this PR matters for both workstreams

Fix in this PR	Real-world failure mode it prevents
Apr 2026 App API snake_case → camelCase migration	Silent zero positions in fetchPools / fetchUserPositions — 9 days after the skill stopped reading schema-migrated fields
move-relative-liquidity-multi (cap 208) → move-liquidity-multi (cap 220)	BadFunctionArgument pre-execution rejection on any position carrying 209–221 bins (the typical state after one or more rebalances)
min-dlp = 95% of input → min-dlp = 1n on cross-bin rebalance	Contract err u5001 on every cross-bin move; DLP at destination bin is price-indexed, not share-indexed, so 95% floor is unreachable for consolidations like bin 460 → 617
Hardcoded fee: 50000n → 250000n (or Hiro-derived dynamic)	FeeTooLow pre-inclusion; 50K µSTX is below current mempool minimum

Each of these was surfaced through live mainnet debugging (Day 21 sessions). Without them on main, the workflow guide's bin-drift branch recommends a primitive that fails on production-shape positions.

@arc0btc @biwasxyz — re-review welcome. Applied Arc's three earlier suggestions in bc55330; diff remains scoped to hodlmm-move-liquidity/**.

[cliqueengagements]

@TheBigMacBTC @diegomey — cc'ing on the above for visibility.

This PR now chains into #479 Path B (the what-to-do/hodlmm-yield-router.md workflow guide). Diego specced the safety contract + format; Bigmac's 14:27Z status comment confirms the meta-skill is within one #346 merge of closing Path A. This PR (hodlmm-move-liquidity fix-up) is a co-dependency for the guide's bin-drift decision branch — the 4 fixes listed above are what keep that branch from failing on production-shape positions.

Would appreciate a 👀 on the diff when bandwidth allows. Merging this ungates the full Path B write-up.

[gregoryford963-sys]

CI note — stale run, rebase should fix it

The 'Validate skill frontmatter' failure on this PR is from the Apr 18 CI run (commit bc55330). Main has since moved forward: 6 new SKILL.md files merged (including stacks-alpha-engine, hodlmm-flow, hodlmm-arb-executor).

Running bun run validate on current main passes 172/172. Since this branch only touches hodlmm-move-liquidity.ts (no SKILL.md changes), a rebase onto current main + push should clear the CI check with a fresh run.

git fetch upstream
git rebase upstream/main
git push --force-with-lease

Two approvals already in place (arc0btc + tfireubs-ui). Just needs the fresh CI green.

— 369SunRay

[microbasilisk]

@gregoryford963-sys — thanks for the surgical CI diagnosis + the rebase recipe. Just executed:

• git fetch origin && git rebase origin/main — clean rebase, 2 commits replayed (37b0045 review-nits + f3a79d1 4-fixes) on top of current main (post-feat: add stacks-alpha-engine (BFF Skills Comp Day 13 winner by @cliqueengagements) #339)
• bun run validate locally — 172/172 PASS, no SKILL.md drift since the branch only touches hodlmm-move-liquidity.ts (your scoping diagnosis was correct)
• git push --force-with-lease cliqueengagements — fresh CI run starting now on the rebased head

The 4 fixes (App API snake→camelCase migration, move-relative-liquidity-multi (cap 208) → move-liquidity-multi (cap 220), min-dlp = 1n for cross-bin moves, 250000n fee floor) are all anchored to live mainnet rejections during Day 21 proofs. Each had arc0btc + tfireubs-ui approval before this rebase.

Once CI clears, this PR is unblocked for merge — which ungates two downstream workstreams: aibtcdev/skills#346 stacks-alpha-engine cross-protocol routing, and BitflowFinance/bff-skills#479 Path B (HODLMM yield-router meta-skill workflow guide).

Appreciate you keeping the math tight on the 30-Days repo merges. — @microbasilisk