ERC-838: REVERT 原因字符串的 ABI 规范

一项关于扩展 ABI 规范，以在 REVERT 原因字符串中包含类型化错误的提案。

摘要

本提案规定了如何在智能合约的 JSON ABI 中编码潜在的错误条件。然后，高级语言可以提供用于声明和抛出这些错误的语法。编译器会将这些错误编码到 REVERT 操作码的原因参数中，以便诸如 web3 之类的库可以轻松地重新构造。

动机

向用户（和开发者）提供关于他们的以太坊交易出错原因的清晰反馈非常重要。REVERT 操作码是朝着正确方向迈出的一步，因为它允许智能合约开发者在 reason 参数中编码描述错误的訊息。Solidity 中有一个正在审查的实现，它接受一个字符串，从而为这个参数提供了一个低级别接口。然而，标准化一种从这个参数将错误传递回客户端的方法，将为用户和开发者带来许多好处。

本文档中的关键词 “MUST”，“MUST NOT”，“REQUIRED”，“SHALL”，“SHALL NOT”，“SHOULD”，“SHOULD NOT”，“RECOMMENDED”，“MAY” 和 “OPTIONAL” 应按照 RFC 2119 中的描述进行解释。

规范

为了符合本规范，生成 JSON ABI 的编译器应该在函数和事件旁边包含错误声明。每个错误对象必须包含键 name（字符串）和 arguments（与函数的 inputs 列表相同的类型）。类型的值必须是 “error”。

示例：

{ "type": "error", "name": "InsufficientBalance", "arguments": [ { "name": "amount", "type": "uint256" } ] }

此错误的 selector 可以从其签名（上面示例中的 InsufficientBalance()）计算得出，其方式与当前对公共函数和事件的处理方式相同。这个 selector 必须包含在 reason 字符串中，以便客户端可以执行查找。错误的任何参数都以与函数返回值相同的方式进行 RLP 编码。selector 和参数被编码的确切格式将被定义。上面提到的 Solidity 实现通过在自由格式字符串前加上 uint256(0) 来为扩展留下空间。

然后，像 Solidity 这样的高级语言可以实现这样的语法：

contract MyToken {
  error InsufficientFunds(uint256 amount);

  function transfer(address _to, uint256 _amount) {
    if (balances[msg.sender] <= _amount)
       throw InsufficientFunds(_amount);
    ...
  }
  ...
}

可能的扩展

1. 错误声明上方的 NatSpec 注释可用于提供默认错误消息。可以使用熟悉的 NatSpec 语法在消息字符串中插入错误的参数。

/// @notice You don't have enough funds to transfer `amount`.
// / @notice 你没有足够的资金来转移 `amount`。
error InsufficientFunds(uint256 amount);

1. 函数可以向其调用者声明它可以抛出哪些错误。这些错误的列表必须包含在该函数的 JSON ABI 项目中，位于 errors 键下。示例：

function transfer(address _to, uint256 _amount) throws(InsufficientFunds);

如果我们希望将来支持类似的语法，则应特别考虑错误重载，因为具有相同名称但参数不同的错误将产生不同的 selector。

理由

需要讨论。

向后兼容性

尚未实现此规范的应用程序和工具可以在 reason 字符串未以零为前缀时忽略它。

安全注意事项

需要讨论。

版权

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

Citation

Please cite this document as:

Federico Bond (@federicobond), Renan Rodrigues de Souza (@RenanSouza2), "ERC-838: REVERT 原因字符串的 ABI 规范 [DRAFT]," Ethereum Improvement Proposals, no. 838, August 2020. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-838.