Ethereum History

核心用法

Ethereum History 是一个面向 AI Agent 的只读数据接口，专用于查询以太坊主网历史合约的客观事实。核心能力覆盖三大场景：

1. 单合约深度查询：通过 /api/agent/contracts/{address} 获取指定地址的完整档案，包括部署区块/时间戳、部署者地址、运行时字节码、反编译代码（如有）、Etherscan 验证状态、ERC20 代币元数据，以及人工撰写的历史摘要（historical_summary）、历史意义（historical_significance）和时代背景（historical_context）。

2. 批量发现与筛选：通过 /api/agent/contracts 支持按时代（Frontier/Homestead/DAO fork 等）、是否精选、是否缺乏文档描述进行过滤，并支持时间范围查询（ISO 8601 时间戳），适用于研究特定时期的合约生态。

3. 元数据与链接：每个合约附带结构化链接（sources、文档、分析文章）和可扩展的键值元数据，便于交叉验证与深度研究。

所有端点均为 GET 请求，无需认证，返回 JSON 采用 snake_case 键名。

显著优点

• 权威史料整合：不仅提供链上原始数据（字节码、gas 成本），还整合了人工撰写的历史背景与行业共识描述，弥补纯数据接口的叙事缺口。
• 反编译能力：自动反编译合约字节码，即使原始源码未验证也能提供可读的高层级代码结构。
• 时代划分精确：按以太坊硬分叉时代（Frontier → Homestead → DAO → Tangerine → Spurious 等）标记合约，便于进行技术史分期研究。
• 零摩擦接入：无 API Key、无费率限制声明，适合研究型 Agent 高频调用。

潜在局限

• 只读约束：无法执行任何链上操作或模拟交易，仅限历史数据查询。
• 覆盖范围未知：未明确说明归档范围（是否包含全部主网合约，或仅精选子集），可能遗漏极早期或极冷门的合约。
• 依赖外部数据源：Etherscan 合约名称、验证状态等字段依赖第三方，存在同步延迟或失效风险。
• 反编译成功率非 100%：复杂或高度优化的合约可能反编译失败。

适合人群

• 区块链研究者、技术史学家、安全审计员（分析早期合约模式）、DeFi 考古爱好者、需要为链上地址提供上下文说明的 Wallet/Explorer 类 Agent。

常规风险

• 数据时效性：历史摘要为人工撰写，更新频率未明确，可能存在与最新社区共识的偏差。
• 中心化托管风险：服务托管于 ethereumhistory.com，若服务下线或域名变更，Agent 功能将中断。
• 隐私泄露风险低：仅查询公开链上数据，无用户敏感信息交互。
• 无内容安全过滤：反编译代码或历史描述中可能包含恶意合约的原始功能描述，需调用方自行甄别。

核心用法

Ethereum History 是一个专为 Agent 设计的只读数据查询技能，用于检索以太坊主网历史合约的客观事实数据。该技能提供三类核心功能：

单一合约详查：通过合约地址获取完整档案，包括部署区块/时间戳、部署者地址、运行时字节码、去编译代码（如可用）、合约类型启发式分析、ERC20 代币元数据，以及人工编辑的历史摘要和背景说明。适用于用户询问"这个地址是什么合约"的场景。

合约发现浏览：支持按时代（Frontier、Homestead、DAO 分叉期等）、特色标注、文档完整度等维度筛选合约列表，支持时间范围查询（ISO 8601 格式）。适用于研究特定历史时期或探索早期合约生态。

时代脉络追踪：通过 era_id 参数快速定位特定硬分叉时期的合约部署情况，帮助理解以太坊协议演进与合约创新的时间线关系。

所有端点均为 HTTPS GET 请求，无需认证，返回蛇形命名法（snake_case）的 JSON 数据。基础 URL 默认可配置，支持本地/ staging 环境切换。

显著优点

数据来源权威性：直接对接 EthereumHistory.com 的归档数据库，该服务专注于以太坊早期历史合约的系统性收录，包含许多 Etherscan 未完整记录的 Frontier 和 Homestead 时代合约。

技术深度信息：除基础元数据外，提供运行时字节码和去编译代码（Decompiled Code），这对研究早期合约逻辑、分析 Gas 优化模式或审计历史漏洞具有独特价值。启发式分析模块还能自动识别代理合约、自毁指令、ERC20 特征等技术属性。

学术中立立场：明确承诺"非观点性"（non-opinionated）数据原则，仅陈述"某合约是什么/不是什么"，避免市场炒作或投资引导，适合学术研究和链上取证场景。

查询灵活性：支持时间戳范围查询、分页机制（最大 200 条/页）和多维度过滤，既能精确定位单合约，也能进行批量历史分析。

潜在缺点与局限性

数据覆盖盲区：文档明确说明部分合约可能缺乏 short_description 等编辑内容，且当数据库未配置时，发现端点会返回空数组。这意味着完整体验依赖服务端的 PostgreSQL 数据库状态，存在可用性波动风险。

只读单向通道：纯查询设计意味着无法提交新合约信息或修正现有记录，用户发现数据缺失时需通过其他渠道反馈，形成闭环成本。

外部依赖单一性：所有数据流指向 ethereumhistory.com 单一域名，若该服务停运、限速或变更 API 结构，Skill 功能将完全失效，缺乏冗余备份机制。

去编译成功率不确定：decompilation_success 字段的存在暗示并非所有合约都能成功去编译，早期手写汇编合约或复杂优化字节码可能无法还原为可读代码。

适合的目标群体

区块链研究人员：需分析以太坊早期合约部署模式、Gas 使用演变或协议升级影响的学术工作者，可利用时代筛选和时间范围查询构建数据集。

安全审计与取证专家：调查历史漏洞事件、追踪攻击者合约演化链或验证古老合约逻辑时，字节码和去编译代码提供关键证据支持。

Web3 历史爱好者：对以太坊"考古"感兴趣的用户，可通过特色合约列表和人工编辑的历史摘要了解 DAO 分叉、The DAO 合约等里程碑事件的链上细节。

合约开发者：研究早期设计模式、学习历史 Gas 优化技巧，或验证自己的合约是否与历史知名合约存在代码关联。

使用风险与注意事项

来源可信度风险（T3）：该 Skill 由个人开发者（cartoonitunes）通过 ClawHub 平台发布，无知名机构背书。尽管静态扫描未发现恶意代码，但 API 响应内容可能被操控，建议对关键合约数据交叉验证 Etherscan、Dune 等第三方源。

网络监控建议：虽然当前仅涉及 HTTPS GET 请求，但建议在使用环境中监控实际流量，防范未来版本或中间人攻击导致的异常数据上传。避免在受监管环境中查询敏感合约地址，因查询参数会发送至外部服务器。

API 可用性与变更：作为独立服务，ethereumhistory.com 的维护状态、速率限制和 API 版本稳定性存在不确定性。生产环境使用建议实现降级策略（如缓存机制或备用数据源）。

隐私合规边界：虽然符合 GDPR 最小数据原则（仅传输合约地址和查询参数），但需注意这些查询日志可能被服务端记录，形成地址关注度分析的基础数据。