EIP-2069 解读在 EIP/ERC 规范中使用 YAML ABI 的推荐方案【免费下载链接】EIPsThe Ethereum Improvement Proposal repository项目地址: https://gitcode.com/GitHub_Trending/ei/EIPs导读EIP-2069 是一份 Informational 类型的以太坊改进提案核心主张是建议 EIP 与 ERC 规范文档中的合约 ABI 描述改用 YAML 格式编写以弥补 JSON ABI 无法书写注释的短板。本文将以该提案为骨架结合本仓库EIPs中大量以 Solidity 接口描述合约行为的 EIP 文件剖析传统 Solidity 式 ABI 描述的三重缺陷、YAML ABI 的完整字段规范与示例以及 JSON/YAML 两种格式之间的转换工具链帮助你在编写或阅读 ERC/EIP 规范时准确理解并采用这一推荐做法。提案背景为什么规范文档需要独立的 ABI 描述传统做法的痛点在 EIP-2069 提出之前绝大多数 ERC/EIP 都把合约 ABI 描述直接写成一份 Solidity 合约或接口源码。这种用 Solidity 充当规范载体的做法存在三个已被社区公认的缺陷语言偏见Solidity 只是众多以太坊开发语言中的一种把 ABI 规范绑定在 Solidity 语法上会阻碍 Rust、Vyper、Yul 等其他语言生态的发展版本锁定规范会被锁定到特定版本的 Solidity 语言特性上语法演进会带来规范漂移表达失真Solidity 允许使用 ABI 中难以表达、甚至无法表达的语法元素与语言特性导致其他语言在实现同一规范时处于更不利的地位。EIP-2069 的目标正是同时解决以上三个问题为 EIP/ERC 提供一种与具体语言解耦、贴近 ABI 本质的描述方式。为什么是 JSON ABI 而不是别的提案明确指出标准合约 ABIStandard Contract ABI通常以 JSON 对象表示这一做法已被广泛支持——包括各类编译器与客户端在内的工具都能消费 JSON ABI 来处理数据编码。但 JSON 描述有一个显而易见的短板JSON 语法本身不支持注释。规范文档往往需要解释每个字段的语义、边界条件与设计意图而这些恰恰是注释最擅长的。因此 EIP-2069 的解决思路非常务实继续使用与 JSON 兼容的 YAML 来承载面向人阅读的规范描述。YAML 在设计之初就刻意保持了对 JSON 的兼容性YAML 1.2 是 JSON 的超集并且天然支持#注释同时市面上存在大量工具可以在两种格式之间互相转换。换句话说机器编码继续用 JSON人类阅读与规范审阅改用 YAML。规范YAML ABI 的字段结构与完整示例transfer 函数的 YAML 表示EIP-2069 给出了一个仅含单个函数transfer一个输入、一个输出的 YAML ABI 示例完整继承如下# The transfer function. Takes the recipient address # as an input and returns a boolean signaling the result. - name: transfer type: function payable: false constant: false stateMutability: nonpayable inputs: - name: recipient type: address - name: amount type: uint256 outputs: - name: type: bool对照结构逐字段解读顶层列表整个 ABI 是一个顶层 YAML 列表- name: ...之前的-每个元素描述一个合约函数、事件或错误与 JSON ABI 的数组语义完全一致name函数名如transfertype条目类型此处为function其他合法取值还包括event、constructor、fallback、receive、error等具体以标准 ABI 规范为准payable/constant旧式布尔标记分别表示函数是否可接收以太币、是否不修改状态不修改状态即 view/purestateMutability现代 Solidity 中的状态可变性修饰符取值包括nonpayable、payable、view、pureinputs输入参数列表每个参数同样由name与type描述如recipient: address、amount: uint256outputs输出参数列表这里的name: 表示返回值未命名type: bool表示返回布尔值以反映转账结果。提案特别强调鼓励规范作者在 YAML ABI 中写入注释如示例顶部对 transfer 行为的两行注释这是 JSON 无法做到、也正是 YAML 方案的核心价值所在。同一 ABI 的 JSON 等价形式为了说明两种格式的等价性EIP-2069 给出了与上述 YAML 完全对应的 JSON 版本[ { name: transfer, type: function, payable: false, constant: false, stateMutability: nonpayable, inputs: [ { name: recipient, type: address }, { name: amount, type: uint256 } ], outputs: [ { name: , type: bool } ] } ]可以直观看到两个版本在数据语义上逐字段一一对应差异仅在于 YAML 允许插入#注释、缩进更轻量、手写与审阅更友好。关于 ABI 中合法字段与取值的完整定义提案明确指引读者查阅标准合约 ABI 规范。仓库佐证JSON ABI 在 EIP 中的实际形态YAML ABI 的字段结构并非凭空设计它与以太坊生态中大量 EIP 实际使用的 JSON ABI 完全同构。以本仓库 EIP-2566 为例该提案在eth_sendTransactionToContractFunction的调用参数中内嵌了一个abi字段其内容正是标准的函数 ABIabi: { inputs: [{ name: _address, type: address }, { name: _value, type: uint256 }], name: transferTokens, outputs: [{ name: success, type: bool }], stateMutability: nonpayable, type: function }这段 JSON 与 EIP-2069 的 YAML 示例呈现出完全一致的字段集合name、type、stateMutability、inputs、outputs。EIP-2566 的 Rationale 部分还说明客户端拿到该abi字段后可以结合data字段解析出人类可读的函数调用信息——这印证了 ABI 描述在规范与工具链中的核心地位它是数据编码与解码的契约。从仓库整体来看EIP-2014、EIP-7896 等文件同样使用了stateMutability等 ABI 术语而本仓库assets目录下如 assets/eip-2330/Extsload.sol 这样的 Solidity 实现文件也展示了合约源码中view等状态可变性修饰符的真实写法该文件第 6-9 行即声明了external view函数。这些资料共同说明无论是 Solidity 源码、JSON ABI 还是 YAML ABI描述的都是同一套函数签名 参数类型 状态可变性的抽象契约而 EIP-2069 只是把这套契约的书写载体从源码/JSON 迁移到了更可读、可注释的 YAML。设计权衡为什么 YAML 而不是自造语言Rationale复用而非发明EIP-2069 的 Rationale 直白地阐述了设计取舍目标是选择一种工具支持良好且支持注释的表示形式。虽然发明一种更简洁的自定义描述语言听起来很有吸引力但提案认为那是不必要的复杂度层an unnecessary layer of complexity。这一判断基于两个现实兼容性红利YAML 与 JSON 的兼容性意味着现有编译器、客户端、ABI 编解码工具几乎无需改动即可继续工作只需在规范文档书写层做一次转换生态惯性JSON ABI 已经是编译器和客户端的既成标准YAML ABI 定位为面向人的规范载体两者通过转换工具衔接而不是另起炉灶再造一个无法与现有工具链互操作的格式。向后兼容性提案在 Backwards Compatibility 一节明确声明本提案对向后兼容性没有任何影响。因为它只是对 EIP/ERC 规范文档的书写建议既不改变链上行为也不改变 ABI 的 JSON 编码标准本身。工具链与实现JSON 与 YAML 的双向转换EIP-2069 在 Implementation 一节给出了一份配套工具yamabi这是一个 JavaScript 实现的转换工具用于在上述 YAML ABI 与更广泛使用的 JSON ABI 之间互相转换。典型工作流如下规范编写阶段作者以 YAML 编写 ABI 并写入注释供人类审阅工具消费阶段通过 yamabi或其他 YAML/JSON 转换工具将 YAML ABI 转换为标准 JSON ABI交给编译器、客户端、测试框架等既有工具链使用双向维护格式转换是双向的JSON ABI 也可以反转为带注释的 YAML便于规范文档的持续维护与版本对比。对于希望在自己的规范文档中采用 YAML ABI 的开发者可以遵循以下实践路径参照本文第二节的字段结构编写 YAML ABI务必为每个函数、参数和边界条件添加注释使用 yamabi 将 YAML 导出为 JSON接入你现有的编码/解码测试验证字段与 JSON 版本完全等价将 YAML ABI 作为规范文档的权威版本提交到 EIP/ERC 提案中JSON 仅作为机器消费的导出产物。结语EIP-2069 以一份简洁的 Informational 提案解决了一个长期困扰规范生态的表述问题如何在不绑定具体编程语言的前提下为 EIP/ERC 提供既机器可消费、又人可阅读的 ABI 描述。它的答案是——复用 YAML 对 JSON 的超集兼容性与注释能力将规范书写层与机器编码层解耦。虽然该提案当前状态为 Stagnant停滞其推荐的 YAML ABI 书写风格与 JSON/YAML 双格式工作流对任何希望编写高质量、可维护、多语言友好的合约规范的人而言仍是一份值得遵循的实用指南。参考EIP-2069 原始文档EIP-2566JSON ABI 在 RPC 参数中的实际用法EIP-2014 与 EIP-7896仓库中同样使用 ABI 术语的提案assets/eip-2330/Extsload.sol合约源码中状态可变性修饰符的实例【免费下载链接】EIPsThe Ethereum Improvement Proposal repository项目地址: https://gitcode.com/GitHub_Trending/ei/EIPs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考