用途
onchain-monitor 用于监控区块链地址与合约，发现值得关注的活动（如大额转账、交易所充提、去中心化交易所兑换、跨链桥转移、铸造与销毁等），并以通知形式提醒操作者。
主要能力
- 观察列表：从
memory/on-chain-watches.yml读取观察项，每项包含 label、address、chain、type（wallet 或 contract）、threshold_usd，合约还可配置可选的event_topics（仅对指定 topic0 哈希告警）。支持链：ethereum、base、arbitrum、optimism、polygon。 - 地址标签词典：可选文件
memory/known-addresses.yml，用小写键映射对手方标签，用于把告警中出现的地址人性化（例如交易所、路由器、跨链桥、零地址）。 - 增量抓取：每个观察项记录上次处理到的区块（last_block），从该区块拉到最新。首次运行初始化为当前区块 − 2400。
- 数据来源：优先使用 Alchemy（若设置了 ALCHEMY_API_KEY）；钱包用
alchemy_getAssetTransfers（分别按 to 与 from 查询后合并），合约用eth_getLogs。回退路径为 Etherscan v2 统一端点（通过 chainid 支持多链，可无 key 低速率使用）。 - 美元估值：汇总去重后的 (chain, token_contract) 后，通过 CoinGecko 批量获取价格；原生币用
simple/price。无法获取价格的代币标记为 UNPRICED，保留在日志但不进入通知。 - 过滤：丢弃低于设定阈值（默认 1000 美元）的事件、低于 0.10 美元的粉尘事件、已在近期告警记录中的交易（跨次运行去重），以及不符合 event_topics 的日志类事件。
- 事件分类标签：CEX-IN / CEX-OUT、DEX-SWAP、BRIDGE、MINT / BURN、WHALE-TRANSFER（超过该观察项 30 天中位数的 10 倍）、UNKNOWN-IN / UNKNOWN-OUT。每个事件只取一个标签，优先级为 CEX > DEX > BRIDGE > MINT/BURN > WHALE > UNKNOWN。
- 告警格式：每次运行只发一条通知，按 value_usd 降序全局排序、按观察项标签分组，开头给出一句 TL;DR 点出最大一笔。正文最多 10 条事件，超出时提示查看日志。附带各数据源的运行状态与最新区块。
- 状态与日志：状态写入
memory/on-chain-state.json（通过临时文件 + mv 原子写入，避免中途失败损坏）。日志追加到memory/logs/${today}.md，包含所有已解码事件（含被过滤项）及统计，便于审计。
使用方式
- 触发参数：
${var}可指定要检查的观察项标签或链；为空则监控全部。 - 通过 Telegram 强制回复添加观察项：当配置文件缺失或观察列表为空时，工具会发送一条邀请粘贴地址的强制回复提示（同一提示 2 天内去重，避免反复打扰）。回复格式为
add-address:<0x… [chain]>，由配置捕获分支处理：校验地址格式（^0x[0-9a-f]{40}$），规范化并追加到memory/on-chain-watches.yml，默认 type 为 wallet、threshold_usd 为 1000、label 为缩短后的地址，随后退出且本次不做监控。若地址已存在则提示已在监控。更精细的配置（链、类型、阈值）需直接编辑该 YAML 文件。 - 执行流程：读取记忆与配置及最近 2 天日志 → 处理配置捕获 → 逐观察项抓取、解码、估值、过滤、分类、格式化告警 → 持久化状态与日志。
- 结束状态：全部运行且有事件存活则通知并记录；全部运行但无事件存活则不发通知，记录 ON_CHAIN_OK；部分失败则仅在存在存活事件时通知，并记录 ON_CHAIN_DEGRADED；全部失败则记录 ON_CHAIN_ERROR 并向操作者发送带来源页脚的通知；配置缺失或为空则记录 ON_CHAIN_NO_CONFIG 并退出，不发送告警。
适用场景
- 追踪指定钱包的进出账与大额异动；
- 关注特定合约的日志事件（可限定 topic0）；
- 借助地址标签词典，把人名化的对手方（交易所、路由器、跨链桥、零地址）体现在告警里；
- 在 Telegram 中通过强制回复快速添加监控地址。
限制与说明
- 支持的链为文档明确列出的 ethereum、base、arbitrum、optimism、polygon，其它链暂未提供。
- 需要配置密钥／服务：ALCHEMY_API_KEY（可选，优先路径）、ETHERSCAN_API_KEY（回退路径可选，可无 key 低速率使用）、COINGECKO_API_KEY（可选）。密钥通过带
{ENV_NAME}占位符的调用方式传入 URL，避免明文密钥出现在命令行。 - CoinGecko 不可达或查不到某代币价格时，该事件标为 UNPRICED，保留日志但不进入通知（无法用美元阈值衡量）。
- 所有抓取到的字段（资产符号、from/to、对手方标签等）都视为不可信内容，不应插入 shell 命令。
- 关于安装方式、具体费用与价格、运行环境要求等，原始资料中暂未提供。