EIP-2069: 推荐在 ERC/EIP 中使用 YAML ABI

简单总结

推荐在 EIP 和 ERC 中包含合约 ABI 描述时使用 YAML 格式。

动机

过去，大多数 ERC/EIP 纯粹以 Solidity 合约和/或接口的形式包含 ABI 描述。这有几个缺点：

• 偏向于单一语言，可能会阻碍新语言的开发。
• 将规范锁定到特定版本的 Solidity 语言。
• 允许使用 Solidity 语言的语法元素和特性，这些元素和特性可能无法在 ABI 中很好地表示。这使得其他语言更加不利。

本提案旨在解决所有这些问题。

规范

[标准合约 ABI] 通常表示为 JSON 对象。 这效果很好，并且包括编译器和客户端在内的几个工具都支持它来处理数据编码。

JSON 描述的一个缺点是它无法包含注释。 为了解决这个问题，我们建议使用 YAML 来提供用户可读的规范。 鉴于 YAML 的设计与 JSON 兼容，因此存在几种在两种格式之间进行转换的工具。

以下示例包含一个函数 transfer，它在 YAML 中具有一个输入和一个输出：

# The transfer function. Takes the recipient address
# as an input and returns a boolean signaling the result.
# transfer 函数。 接受接收者地址
# 作为输入并返回一个布尔值来表示结果。
- 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 中有效字段和值的详细信息，请参阅[标准合约 ABI]规范。

相同的 JSON 格式：

[
  {
    "name": "transfer",
    "type": "function",
    "payable": false,
    "constant": false,
    "stateMutability": "nonpayable",
    "inputs": [
      {
        "name": "recipient",
        "type": "address"
      },
      {
        "name": "amount",
        "type": "uint256"
      }
    ],
    "outputs": [
      {
        "name": "",
        "type": "bool"
      }
    ]
  }
]

理由

目的是选择一种工具支持良好且支持注释的表示形式。 虽然发明一种更简洁的描述语言似乎是个好主意，但感觉这是一种不必要的复杂性。

向后兼容性

这对向后兼容性没有影响。

测试用例

待定

实现

yamabi是一个 Javascript 工具，用于在上述 YAML 和更广泛使用的 JSON 格式之间进行转换。

版权

版权及相关权利通过 CC0 放弃。

Citation

Please cite this document as:

Alex Beregszaszi (@axic), "EIP-2069: 推荐在 ERC/EIP 中使用 YAML ABI [DRAFT]," Ethereum Improvement Proposals, no. 2069, February 2017. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-2069.