feat(hodlmm-risk): add HODLMM volatility risk monitoring skill#224
feat(hodlmm-risk): add HODLMM volatility risk monitoring skill#224locallaunchsc-cloud wants to merge 11 commits intoaibtcdev:mainfrom
Conversation
arc0btc
left a comment
arc0btc
left a comment
There was a problem hiding this comment.
Adds a read-only HODLMM volatility risk monitoring skill — pool bin spread, reserve imbalance, and concentration metrics wrapped in a clean Commander CLI. The concept is solid and the integration with BitflowService follows repo conventions.
What works well:
- Parallel
Promise.all()for API calls in all three subcommands — right pattern for independent fetches - Clean separation of
computePoolRiskMetricsandcomputeSignals— easy to reason about and test independently - Network guard at the top of each action is clear and consistent
- Error handling for "No bins returned" and "Address has no position" covers the obvious API edge cases
[blocking] Empty bins crash: Math.min(...[]) produces Infinity when all bins have zero reserves (hodlmm-risk/hodlmm-risk.ts:61–66)
If nonEmptyBins is empty (pool just created, fully withdrawn, or API returns all-zero reserves), binIds is []. Spreading an empty array into Math.min/Math.max returns Infinity/-Infinity, making binSpread produce NaN. That NaN propagates into volatilityScore and regime, giving the calling agent a nonsensical signal.
const nonEmptyBins = bins.filter(
(b) => Number(b.reserve_x) > 0 || Number(b.reserve_y) > 0
);
if (nonEmptyBins.length === 0) {
throw new Error("No active liquidity in this pool — all bins are empty");
}
const binIds = nonEmptyBins.map((b) => b.bin_id);
[blocking] regime-history is a stub but SKILL.md advertises it as multi-sample (hodlmm-risk/hodlmm-risk.ts:251–295, hodlmm-risk/SKILL.md)
The CLI accepts --samples <count> (SKILL.md documents default 10, max 50, example shows 10 points returned), but the implementation ignores the argument and always returns exactly 1 snapshot with trend: "stable" hardcoded. An agent calling regime-history --samples 10 expecting a trend signal will always see "stable" regardless of actual market movement — a false safety signal in elevated/crisis conditions.
Two options:
- Implement actual multi-sample behavior (requires caching or repeated API polling)
- Rename to
regime-snapshot, remove--samples, update SKILL.md example to showsamples: 1, and add a note that trend history requires an external time-series store
Until this is resolved, agents should not rely on trend output from regime-history. The current code comment acknowledges this ("currently returns 1 live snapshot") but the public interface doesn't make it obvious.
[suggestion] driftScore uses average bin offset but reports nearest offset (hodlmm-risk/hodlmm-risk.ts:225–235)
driftScore is derived from avgOffset (average distance across all position bins from active bin), but the output field nearestPositionBinOffset reports the minimum. These measure different things. A position spread across bins 440–460 with active bin at 447 has a low nearestOffset (0) but potentially high avgOffset. Calling agents comparing driftScore to nearestPositionBinOffset will get confusing results. Consider either:
- Deriving
driftScorefromnearestOffset(more conservative — penalizes entire position moving out of range), or - Exposing
avgBinOffsetalongsidenearestPositionBinOffsetso the caller can see what's driving the score
[nit] SKILL.md JSON example has a typo in the output key (hodlmm-risk/SKILL.md:58)
"safeTo AddLiquidity" (space in the key) should be "safeToAddLiquidity".
Code quality notes:
computePoolRiskMetricscould be exported and unit-tested independently — the pure-function design is good, worth calling out in SKILL.md as testable- The three weight constants (40/30/30 for spread/imbalance/concentration) are undocumented magic numbers. A brief comment explaining the weighting rationale would help future contributors recalibrate without guessing
regime-historyaccepting but silently ignoring--samples > 1is a footgun. If the stub path stays, addif (parseInt(opts.samples) > 1) throw new Error("Multi-sample history not yet implemented")to fail loudly rather than return misleading single-point data
Operational context: We run the defi-bitflow skill in production against these same Bitflow BFF endpoints. The getHodlmmPool/getHodlmmPoolBins APIs do return empty bins periodically for low-liquidity pools — the empty-bins guard isn't theoretical.
- Fix empty bins crash: guard nonEmptyBins.length === 0 - Rename regime-history to regime-snapshot, remove --samples - Add avgBinOffset to assess-position output - Document volatility weight constants (40/30/30) - Bump to v0.2.0
Adds read-only volatility risk monitoring for Bitflow DLMM pools. No wallet or funds required. Mainnet only. Subcommands: - list-pools: list all active HODLMM pools - assess-pool: compute volatility score (0-100) and regime classification - assess-position: evaluate LP position drift and concentration risk - regime-history: scan all pools sorted by risk level Risk model weights three signals: - Bin spread (30%): fraction of bins with liquidity — low = risky - Reserve imbalance (40%): |X_usd - Y_usd| / total — high = skewed pool - Active bin concentration (30%): active bin share of total liquidity Regime classification: - calm (0-33): proceed normally - elevated (34-66): reduce exposure per maxExposurePct signal - crisis (67-100): do not add liquidity Fail-safe: API errors default to crisis regime. Closes aibtcdev#224
Adds read-only volatility risk monitoring for Bitflow DLMM pools. No wallet or funds required. Mainnet only. Subcommands: - list-pools: list all active HODLMM pools - assess-pool: compute volatility score (0-100) and regime classification - assess-position: evaluate LP position drift and concentration risk - regime-history: scan all pools sorted by risk level Risk model weights three signals: - Bin spread (30%): fraction of bins with liquidity - Reserve imbalance (40%): |X_usd - Y_usd| / total - Active bin concentration (30%): active bin share of total Regime: calm (0-33) / elevated (34-66) / crisis (67-100) Fail-safe: API errors default to crisis regime. Closes aibtcdev#224
Update: Added
|
Read-only volatility risk monitoring for Bitflow DLMM pools. No wallet or funds required. Mainnet only. Subcommands: list-pools, assess-pool, assess-position, regime-history Risk model: bin spread (30%) + reserve imbalance (40%) + active bin concentration (30%) Regime: calm (0-33) / elevated (34-66) / crisis (67-100) Fail-safe: API errors default to crisis regime. Closes aibtcdev#224
|
@arc0btc Hey, just following up — I’ve addressed all the requested changes. When you get a chance, could you re-review? Thanks! |
Adds read-only volatility risk monitoring for Bitflow DLMM pools. No wallet or funds required. Mainnet only. Subcommands: - list-pools: list all active HODLMM pools - assess-pool: compute volatility score (0-100) and regime classification - assess-position: evaluate LP position drift and concentration risk - regime-history: scan all pools sorted by risk level Risk model weights three signals: - Bin spread (30%): fraction of bins with liquidity — low = risky - Reserve imbalance (40%): |X_usd - Y_usd| / total — high = skewed pool - Active bin concentration (30%): active bin share of total liquidity Regime classification: - calm (0-33): proceed normally - elevated (34-66): reduce exposure per maxExposurePct signal - crisis (67-100): do not add liquidity Fail-safe: API errors default to crisis regime. Closes aibtcdev#224
Read-only volatility risk monitoring for Bitflow DLMM pools. No wallet or funds required. Mainnet only. Subcommands: list-pools, assess-pool, assess-position, regime-history Risk model: bin spread (30%) + reserve imbalance (40%) + active bin concentration (30%) Regime: calm (0-33) / elevated (34-66) / crisis (67-100) Fail-safe: API errors default to crisis regime. Closes aibtcdev#224
|
Hey @locallaunchsc-cloud is this work intended for the Bitflow Skills Pay the Bills competition? If so it needs to be submitted at this repo otherwise it wouldn't be eligible for credit: Let me know, happy to continue the review process if it's unrelated! |
Adds read-only volatility risk monitoring for Bitflow DLMM pools. No wallet or funds required. Mainnet only. Subcommands: - list-pools: list all active HODLMM pools - assess-pool: compute volatility score (0-100) and regime classification - assess-position: evaluate LP position drift and concentration risk - regime-history: scan all pools sorted by risk level Risk model weights three signals: - Bin spread (30%): fraction of bins with liquidity — low = risky - Reserve imbalance (40%): |X_usd - Y_usd| / total — high = skewed pool - Active bin concentration (30%): active bin share of total liquidity Regime classification: - calm (0-33): proceed normally - elevated (34-66): reduce exposure per maxExposurePct signal - crisis (67-100): do not add liquidity Fail-safe: API errors default to crisis regime. Closes aibtcdev#224
Read-only volatility risk monitoring for Bitflow DLMM pools. No wallet or funds required. Mainnet only. Subcommands: list-pools, assess-pool, assess-position, regime-history Risk model: bin spread (30%) + reserve imbalance (40%) + active bin concentration (30%) Regime: calm (0-33) / elevated (34-66) / crisis (67-100) Fail-safe: API errors default to crisis regime. Closes aibtcdev#224
|
@whoabuddy Yes, this is intended for the Bitflow Skills Pay the Bills competition. I'll submit it to the @arc0btc I've addressed all the review feedback:
Ready for re-review when you get a chance. |
1 similar comment
|
@whoabuddy Yes, this is intended for the Bitflow Skills Pay the Bills competition. I'll submit it to the @arc0btc I've addressed all the review feedback:
Ready for re-review when you get a chance. |
3 participants
New Skill:
hodlmm-riskAdds a read-only HODLMM volatility risk monitoring skill for Bitflow DLMM pools. This skill provides risk intelligence that other agents can call before adding, holding, or withdrawing HODLMM liquidity.
Subcommands
assess-pool- Computes volatility score (0-100), regime classification (calm/elevated/crisis), and position-sizing signals for a HODLMM poolassess-position- Scores an existing LP position's drift from active bin, concentration risk, and recommends hold/withdraw/rebalanceregime-history- Returns a volatility regime snapshot with trend indicatorRisk Metrics
Key Properties
BitflowServicefromsrc/lib/services/bitflow.service.tsFiles Added
hodlmm-risk/SKILL.md- Skill frontmatter and documentationhodlmm-risk/AGENT.md- Agent operation rules and safety checkshodlmm-risk/hodlmm-risk.ts- Commander CLI with 3 subcommandsUse Case
LP agents should call
assess-poolbefore anybitflow add-liquidity-simpleoperation. If regime iscrisis, the agent should not add liquidity. Ifelevated, reduce exposure persignals.maxExposurePct.