ERC-838 ABI Specification for REVERT Error Reason (ABI specification for REVERT reason string)
Draft · Other · created 2020-08-20
Adds a way to include named errors with arguments in the REVERT reason that a smart contract emits on failure to the ABI (Application Binary Interface) specification, so that wallets and libraries can read out the cause of failure.
Why it is needed
When an Ethereum transaction fails, users and developers need to know what went wrong. The REVERT opcode can carry a message describing the failure in its reason parameter, which is a step in the right direction, but the implementation then being considered in Solidity only offered a low-level interface that took a single string. In other words, there was no standard way to give an error a name, attach arguments such as an amount, and have the client side parse it back out. Standardizing how these errors in the reason parameter are returned to the client brings many benefits for both users and developers. Contract development languages can provide syntax to declare and throw errors, and libraries like web3 can easily reconstruct and display them.
What to implement
{ "type": "error", "name": "InsufficientBalance", "arguments": [ { "name": "amount", "type": "uint256" } ] }: An example of an error declaration included in the JSON ABI. It describes the error's name and list of arguments.error InsufficientFunds(uint256 amount);: An example of the syntax for declaring an error in a high-level language. Defines an error that takes a single uint256 argument.function transfer(address _to, uint256 _amount) throws(InsufficientFunds);: Syntax proposed in the extension that lets a function declare to its caller which errors it may throw.
In depth
Error declarations in the JSON ABI
A compiler following this specification should include error declarations in the JSON ABI it generates, alongside functions and events. Each error object must include a name (string) key and an arguments key (of the same type as a function's inputs list), and the type value must be "error". The example is an InsufficientBalance error with a single uint256 argument named amount. Keywords like MUST and SHOULD follow the definitions in RFC 2119.
Selector and argument encoding
The error's selector is computed from its signature, the same way it is currently done for public functions and events (in the example, InsufficientBalance()). This selector must be included in the reason string so clients can look it up. The error's arguments are RLP-encoded the same way as function return values. However, the exact format for carrying the selector and arguments has not yet been finalized. The Solidity implementation mentioned in the source text leaves room for extension by prefixing the free-form string with uint256(0).
High-level language syntax
High-level languages like Solidity can implement error declaration and throw syntax on top of this. In the reference example, the MyToken contract declares error InsufficientFunds(uint256 amount), and inside the transfer function, if balances[msg.sender] is less than or equal to _amount, it throws the error with throw InsufficientFunds(_amount). The compiler encodes errors declared this way into the reason parameter of REVERT in a format that libraries can easily decode.
Extension 1: NatSpec default messages
You can provide a default error message with a NatSpec comment above the error declaration. Inside the message string, you can interpolate the error's arguments using familiar NatSpec syntax. In the reference example, the comment /// @notice You don't have enough funds to transfer `amount`. is placed above the InsufficientFunds declaration.
Extension 2: Declaring a function's error list
Another proposed extension lets a function declare to callers which errors it may throw. This error list should be included under the errors key in the function's JSON ABI entry. The syntax example is function transfer(address _to, uint256 _amount) throws(InsufficientFunds). Supporting similar syntax in the future would require special consideration for error overloading, since errors with the same name but different arguments produce different selectors.
Backward compatibility
Apps and tools that do not implement this specification can simply ignore the encoded reason string when it does not start with 0, since the structure distinguishes the existing free-form string approach from the new encoded-error approach by prefix.
Proposal in Draft status
This proposal is in Draft status. Its contents may still change, and the exact encoding format for selectors and arguments has not been finalized. The Rationale and Security Considerations sections in the original text only note that further discussion is needed. Check the latest status before implementing or depending on it.