hodlmm-risk

HODLMM 风险技能

功能介绍

监控 Bitflow 上 HODLMM（DLMM）池的波动性和 LP 风险。计算 bin 价差、储备失衡和集中度指标，以判定市场状态并发出仓位规模信号。

为什么 Agent 需要它

管理 HODLMM 流动性的 Agent 在添加、持有或撤出流动性之前需要一道风险关卡。此技能可提供这一关卡——输出数值波动评分和状态标签，供下游 Agent 据此决定是否采取行动。

安全说明

• 只读——绝不会写入链上或转移资金。
• 仅限主网——Bitflow HODLMM API 仅支持主网。
• 无需钱包或资金。
• 储备全为零的池会返回错误，而不是给出误导性指标。

命令

assess-pool

评估 HODLMM 池的波动性和风险指标。

bun run hodlmm-risk/hodlmm-risk.ts assess-pool --pool-id <pool_id>

选项：

• --pool-id（必填）— HODLMM 池标识符（例如 dlmm_3）

输出：

{
  "network": "mainnet",
  "poolId": "dlmm_3",
  "activeBinId": 447,
  "totalBins": 69,
  "binSpread": 0.021,
  "reserveImbalanceRatio": 0.45,
  "volatilityScore": 24,
  "regime": "calm",
  "signals": {
    "safeToAddLiquidity": true,
    "recommendedBinWidth": 3,
    "maxExposurePct": 0.25
  },
  "timestamp": "2026-03-24T20:00:00.000Z"
}

assess-position

评估特定钱包在某个池中的 HODLMM 仓位风险。

bun run hodlmm-risk/hodlmm-risk.ts assess-position --pool-id <pool_id> --address <stx_address>

选项：

• --pool-id（必填）— HODLMM 池标识符
• --address（必填）— 要检查的 Stacks 地址

输出：

{
  "network": "mainnet",
  "poolId": "dlmm_3",
  "address": "SP2...",
  "positionBinCount": 3,
  "activeBinId": 447,
  "nearestPositionBinOffset": 2,
  "avgBinOffset": 4.33,
  "concentrationRisk": "medium",
  "driftScore": 22,
  "impermanentLossEstimatePct": 1.76,
  "recommendation": "rebalance",
  "timestamp": "2026-03-24T20:00:00.000Z"
}

regime-snapshot

获取池的单点波动状态快照。

bun run hodlmm-risk/hodlmm-risk.ts regime-snapshot --pool-id <pool_id>

选项：

• --pool-id（必填）— HODLMM 池标识符

输出：

{
  "network": "mainnet",
  "poolId": "dlmm_3",
  "volatilityScore": 24,
  "regime": "calm",
  "activeBinId": 447,
  "binSpread": 0.021,
  "reserveImbalanceRatio": 0.45,
  "note": "Single-point snapshot. For trend analysis, store snapshots externally over time.",
  "timestamp": "2026-03-24T20:00:00.000Z"
}

输出约定

所有输出均为直接写入 stdout 的扁平 JSON（无外层封装）。

出错时：

{ "error": "descriptive error message" }

已知限制

• 仅限主网——Bitflow HODLMM API 在测试网上不可用。
• 无需钱包——所有操作均为只读。
• 波动评分范围为 0-100：0-30 = 平静，31-60 = 升高，61-100 = 危机。
• 评分权重：bin 价差（40%）、储备失衡（30%）、流动性集中度（30%）。
• driftScore 根据 avgBinOffset 计算：Math.min(avgOffset * 5, 100)。每偏移一个 bin，评分增加 +5 分，最高为 100（即偏离活跃 bin 20 个及以上时，评分为 100 = 撤出）。
• impermanentLossEstimatePct 是线性近似值：driftScore * 0.08（driftScore=100 时最高为 8%）。这只是粗略的监控参考值，并非基于价格比率的精确 IL 计算。
• concentrationRisk 阈值：1 个 bin = “高”，2-3 个 bin = “中”，4 个及以上 bin = “低”。
• signals 推导规则：平静 → recommendedBinWidth: 3, maxExposurePct: 0.25；升高 → recommendedBinWidth: 7, maxExposurePct: 0.10；危机 → recommendedBinWidth: 15, maxExposurePct: 0.0。
• regime-snapshot 返回与 assess-pool 相同的波动性计算结果，但不包含信号。LP 操作前进行决策门控时使用 assess-pool；日志记录／监控工作流中使用 regime-snapshot。
• regime-snapshot 返回单个时间点的读数。要进行趋势分析，请随时间在外部保存快照。
• 储备全为零的池会返回错误，而不是给出误导性指标。
• 此技能根据 bin 分布计算当前状态的波动性参考值，而非历史已实现波动率。不会进行时间序列或迁移跟踪。

起源

AIBTC x Bitflow Skills Pay the Bills 竞赛第 2 天优胜者。 原作者：@locallaunchsc-cloud 竞赛 PR：https://github.com/BitflowFinance/bff-skills/pull/23