Skip to content

Commit 7839339

Browse files
diegomeyClankOSbiwasxyzclaude
authored
feat: add hodlmm-flow (BFF Skills Comp Day 19 winner by @ClankOS) (#328)
* feat: add hodlmm-flow skill (BFF Skills Comp Day 19 winner) Submitted by @ClankOS (Grim Seraph) via the AIBTC x Bitflow Skills Pay the Bills competition. Competition PR: BitflowFinance/bff-skills#257 * chore: fix CI validation failures - contract-preflight: replace invalid tags with controlled vocabulary, drop unknown "network" dependency - stacking-delegation: user-invocable false, add missing AGENT.md frontmatter - regenerate skills.json Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: ClankOS <ClankOS@users.noreply.github.com> Co-authored-by: biwasbhandari <biwas2059@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 5472699 commit 7839339

4 files changed

Lines changed: 1375 additions & 1 deletion

File tree

‎hodlmm-flow/AGENT.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
name: hodlmm-flow-agent
3+
skill: hodlmm-flow
4+
description: "Agent that analyzes HODLMM swap flow to assess LP safety, detect toxic flow, and predict range lifespan for concentrated liquidity positions."
5+
---
6+
7+
# Agent Behavior — HODLMM Flow
8+
9+
## Decision order
10+
11+
1. Run `doctor` first. If Hiro events API fails, stop — flow analysis requires it.
12+
2. For a specific pool question, run `flow --pool-id <id>`.
13+
3. For a protocol-wide overview, run `flow --all`.
14+
4. Use `--window 24h` when the user asks about recent conditions specifically.
15+
5. Parse JSON output and route on `verdict.lpSafety`.
16+
17+
## Guardrails
18+
19+
- **Read-only skill** — never attempts to move funds or submit transactions
20+
- **Never expose API keys** in logs or output
21+
- **Rate limit awareness** — if Hiro rate limit is hit mid-analysis, partial results are returned. Suggest `--hiro-api-key` or reducing `--swaps` count
22+
- **Default to 100 swaps** when no count specified — balances depth vs API cost
23+
24+
## Interpreting metrics
25+
26+
| Metric | Threshold | Agent action |
27+
|---|---|---|
28+
| flowToxicity > 0.7 | Danger | Warn user: informed flow is adversely selecting LPs |
29+
| directionBias > ±0.4 | Warning | Suggest asymmetric range or reduced exposure on drained side |
30+
| binVelocity > 30 | Danger | Recommend widening range or waiting for volatility to settle |
31+
| whaleConcentration > 0.5 | Warning | Single actor dominates — flow may reverse suddenly when they stop |
32+
| liquidationPressure > 0.2 | Warning | Lending market stress — monitor underlying collateral health |
33+
| botFlowRatio > 0.8 | Info | Flow is mostly automated — organic price discovery limited |
34+
35+
## Verdict routing
36+
37+
| lpSafety | Agent action |
38+
|---|---|
39+
| safe | Report conditions, confirm range parameters are appropriate |
40+
| caution | Surface specific risk factors, suggest monitoring or range adjustment |
41+
| danger | Recommend reducing exposure or exiting position until conditions normalize |
42+
43+
## On error
44+
45+
- Log the full error payload
46+
- Do not retry silently — surface to user with guidance
47+
- If rate-limited: suggest `--hiro-api-key` or narrower `--swaps` count
48+
- If no swap txs found: pool may be dormant, suggest checking a different pool
49+
50+
## On success
51+
52+
- Lead with the LP safety verdict and score
53+
- Highlight the most concerning metric (lowest-scoring component)
54+
- If rangeLifespanHours < 12, emphasize this prominently
55+
- Surface top actors with their labels
56+
57+
## Integration with other skills
58+
59+
- **hodlmm-deadweight** → Flow analysis reveals *why* capital is stranded (directional flow pushed price away from positions)
60+
- **hodlmm-advisor** → Pair flow verdict with pool health for a complete picture before entering a position
61+
- **hodlmm-pulse** → Flow metrics complement volume/fee data — toxicity explains *quality* of volume, not just quantity

‎hodlmm-flow/SKILL.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
name: hodlmm-flow
3+
description: "Swap flow intelligence for Bitflow HODLMM — analyzes on-chain swap transactions to compute direction bias, flow toxicity, bin velocity, whale concentration, and bot/organic classification for LP decision-making."
4+
metadata:
5+
author: "ClankOS"
6+
author-agent: "Grim Seraph"
7+
user-invocable: "false"
8+
arguments: "doctor | install-packs | flow --pool-id <id> | flow --all"
9+
entry: "hodlmm-flow/hodlmm-flow.ts"
10+
requires: ""
11+
tags: "l2, defi, read-only, mainnet-only"
12+
---
13+
14+
# HODLMM Flow
15+
16+
Swap flow intelligence for Bitflow HODLMM concentrated liquidity pools.
17+
18+
## What it does
19+
20+
Every other HODLMM tool looks at pool *state* — TVL, bin distribution, positions. This one looks at swap *flow*: what's actually trading, in what direction, by whom, and what it means for LPs.
21+
22+
Fetches on-chain swap transactions from Hiro API, parses DLMM core contract events to extract per-bin-hop volumes, and computes six market microstructure metrics: direction bias, flow toxicity, bin velocity, whale concentration, liquidation pressure, and bot/organic classification. Produces an LP safety verdict with a predicted range lifespan.
23+
24+
## Why agents need it
25+
26+
Concentrated liquidity LPs face adverse selection — informed traders extract value from stale positions. Without flow analysis, an agent choosing range parameters is flying blind. This skill gives agents the data to:
27+
28+
- **Detect toxic flow** — consecutive same-direction swaps signal informed trading that picks off LPs
29+
- **Predict range lifespan** — bin velocity tells you how long a ±N-bin position will stay in range
30+
- **Identify who's trading** — bot vs organic vs liquidator classification reveals market structure
31+
- **Assess directional risk** — strong bias means one side of your position is getting drained
32+
- **Spot liquidation cascades** — Zest liquidation flow through HODLMM pools signals collateral stress
33+
34+
## Safety notes
35+
36+
- **Read-only** — never submits transactions or moves funds
37+
- **No wallet required** — safe to call from any agent without authentication
38+
- **Mainnet-only** — Bitflow HODLMM is mainnet-only
39+
- Uses Hiro transactions + events APIs. A Hiro API key (`--hiro-api-key`) is recommended for analyzing more than 100 swaps to avoid rate limits
40+
41+
## Commands
42+
43+
### doctor
44+
Checks connectivity to Hiro API (transactions, events) and Bitflow APIs (quotes, app). Verifies the full data pipeline is accessible.
45+
46+
```bash
47+
bun run hodlmm-flow/hodlmm-flow.ts doctor
48+
```
49+
50+
### install-packs
51+
No-op subcommand for registry compatibility. This skill has no additional packs to install.
52+
53+
```bash
54+
bun run hodlmm-flow/hodlmm-flow.ts install-packs
55+
```
56+
57+
### flow --pool-id
58+
Analyze swap flow for a single pool. Default: last 100 swaps.
59+
60+
```bash
61+
bun run hodlmm-flow/hodlmm-flow.ts flow --pool-id dlmm_3
62+
```
63+
64+
### flow --pool-id --window
65+
Time-windowed analysis. Analyzes swaps within the specified duration.
66+
67+
```bash
68+
bun run hodlmm-flow/hodlmm-flow.ts flow --pool-id dlmm_3 --window 24h
69+
```
70+
71+
### flow --all
72+
Protocol-wide flow summary across all 8 HODLMM pools (dlmm_1 through dlmm_8).
73+
74+
```bash
75+
bun run hodlmm-flow/hodlmm-flow.ts flow --all
76+
```
77+
78+
Options:
79+
- `--pool-id <id>` — Pool to analyze (dlmm_1 through dlmm_8)
80+
- `--window <duration>` — Time window (e.g. 24h, 7d, 30m)
81+
- `--swaps <count>` — Number of swaps to analyze (default: 100)
82+
- `--all` — Analyze all 8 HODLMM pools
83+
- `--hiro-api-key <key>` — Hiro API key for elevated rate limits
84+
85+
## Output contract
86+
87+
All outputs are JSON to stdout.
88+
89+
**Success (single pool):**
90+
```json
91+
{
92+
"status": "success",
93+
"network": "mainnet",
94+
"timestamp": "2026-04-09T20:00:00.000Z",
95+
"poolId": "dlmm_3",
96+
"pair": "STX/USDCx",
97+
"swapsAnalyzed": 100,
98+
"timeSpanHours": 4.2,
99+
"metrics": {
100+
"directionBias": -0.31,
101+
"directionBiasLabel": "Moderate sell-X pressure",
102+
"flowToxicity": 0.62,
103+
"flowToxicityLabel": "Elevated — directional momentum present",
104+
"binVelocity": 12.5,
105+
"binVelocityLabel": "Moderate — normal volatility",
106+
"whaleConcentration": 0.45,
107+
"whaleConcentrationLabel": "Concentrated — few actors drive most volume",
108+
"liquidationPressure": 0.02,
109+
"liquidationPressureLabel": "Low — 1 liquidation(s), minimal impact",
110+
"botFlowRatio": 0.72,
111+
"botFlowRatioLabel": "Bot-heavy — majority of flow is automated"
112+
},
113+
"verdict": {
114+
"lpSafety": "caution",
115+
"score": 52,
116+
"reasoning": "Strong directional pressure (selling X). Concentrated flow — few actors dominating volume.",
117+
"recommendation": "Monitor flow direction. Consider asymmetric range if bias persists.",
118+
"rangeLifespanHours": 0.8
119+
},
120+
"topActors": [
121+
{ "address": "SP2V3J7G...", "swapCount": 45, "volumeShare": 82.1, "label": "bot" }
122+
]
123+
}
124+
```
125+
126+
**Error:**
127+
```json
128+
{ "error": "descriptive message" }
129+
```
130+
131+
## Metrics reference
132+
133+
| Metric | Range | What it measures |
134+
|---|---|---|
135+
| Direction bias | [-1, +1] | Net buying vs selling pressure. -1 = all selling X, +1 = all buying X |
136+
| Flow toxicity | [0, 1] | Consecutive same-direction ratio. >0.6 = informed flow adversely selecting LPs |
137+
| Bin velocity | bins/hour | Active bin change rate. Predicts how fast positions go out of range |
138+
| Whale concentration | [0, 1] | Herfindahl index on swap volume. >0.25 = concentrated, >0.5 = monopolistic |
139+
| Liquidation pressure | [0, 1] | Volume fraction from Zest `liquidate-with-swap` transactions |
140+
| Bot flow ratio | [0, 1] | Volume fraction from automated addresses (>10 swaps/hour or >30% of flow) |
141+
142+
## Data source
143+
144+
Swap data is sourced from Hiro API (`/extended/v1/address/{pool}/transactions` + `/extended/v1/tx/events`). Each swap transaction's DLMM core contract logs are parsed to extract per-bin-hop amounts (dx, dy), active bin IDs, callers, and swap direction.
145+
146+
Bitflow does not currently expose swap history via their own API. This skill recommends they add a `/trades` or `/swaps` endpoint — they already have the data server-side. This would eliminate Hiro dependency and enable real-time flow monitoring.
147+
148+
## Known constraints
149+
150+
- Free-tier Hiro supports ~100 swaps per run (~100-150 API calls). Use `--hiro-api-key` for larger analyses
151+
- Only ~25-30% of transactions hitting pool contracts are swaps — the rest are add/withdraw liquidity. The skill pages through until it collects enough swap txs
152+
- Multi-hop swap transactions (crossing multiple bins) produce multiple events per tx — all are aggregated correctly
153+
- `swap-simple-multi` function calls don't indicate direction in the function name — direction is resolved from contract events
154+
- Stale data: Hiro API indexes with a slight delay (~1-2 blocks). Very recent swaps may not appear immediately
155+
156+
## Origin
157+
158+
Winner of AIBTC x Bitflow Skills Pay the Bills competition.
159+
Original author: @ClankOS
160+
Competition PR: https://github.com/BitflowFinance/bff-skills/pull/257

0 commit comments

Comments
 (0)