EVM 合约事件日志抓取

要解决的问题

排查链上行为时，最硬的证据通常不是数据库里的某张表，而是合约 emit 出来的原始事件日志。比如一笔 Transfer 的 amount 对不上、一个 Claim 事件在某个区块莫名消失、或者某条 L2 上的 DEX 合约行为跟主网不一致——这类问题都得回到 eth_getLogs 的返回里逐条核对。

难点从来不在「调一个接口」，而在把日志拉全、拉对、再解析成能直接读的结构：

• 合约 ABI 不会以明文存在链上，光凭 eth_getCode 拿到的字节码推不出事件签名。
• 多 RPC 环境下限流、节点落后是常态，拉到一半断了就得手动重跑。
• 大区块区间必须分页，topic0 过滤拼错一个签名会静默返回空结果，很难察觉。

技能如何工作

这个技能封装了从「给我一个合约地址」到「拿到结构化日志」的完整链路，核心特点是与具体协议无关：不限定 ERC-20、NFT、DEX 或发行合约，任何暴露标准 JSON-RPC eth_getLogs 的 EVM 链都能用，包括主网、测试网、L2、侧链和自定义链。

工作流分五步：

1. 初始化项目：在本地生成脚手架，所有脚本和配置都放在项目目录内，不依赖外部仓库。
2. 收集参数：向用户确认 chainId 和 contractAddress（两者必填），可选的 RPC URL、startBlock/endBlock、tokenDecimals 一并收集，缺失时给合理默认。
3. 获取 ABI：优先走 Sourcify（免 API key），其次走 Etherscan 兼容接口（需 key）。两条公开路径都失败时，明确要求用户提供 ABI JSON 或本地文件路径——绝不猜测或编造 ABI。
4. 确认事件列表：把 ABI 里解析出的事件展示给用户，让其选择「全部」或指定若干事件名，避免盲目拉取大量无关日志。
5. 配置并运行：rpc 支持传数组，失败后自动重试并轮转到下一个 URL；eventNames 设为 '*' 拉全量日志，设为数组则按 topic0 OR 过滤。

输出是解析后的日志条目，不是原始 hex，可以直接进入后续分析或落库。

适用边界与注意点

• 未验证合约或私有链：公开源拿不到 ABI，此时必须由用户提供，技能不会阻塞流程而是明确提示下一步。
• 大区块区间：pageSize 默认 1000，区间太大时建议下调，否则容易撞上节点响应超时。
• ABI 文件命名：必须是 abi_{address}_{chainId}.json，地址小写，否则加载逻辑找不到文件。
• 不做什么：不做聚合统计和 CSV 导出（那是 evm-log-stats 的活），也不部署合约、不写 Solidity、不回答不涉及日志的泛泛链上问题。
• 节点容错：把多个 RPC 放进 rpc: [...] 数组，是应对限流和单点故障最有效的一招。