This ERC proposes a standard for handling bubbled up reverts in Ethereum smart contracts using a dedicated custom error. This standard aims to improve the clarity and usability of revert reasons by allowing additional context to be passed alongside the raw bytes of the bubbled up revert. The WrappedError custom error should wrap reverts from called contracts and provide a consistent interface for parsing and handling reverts in tools like Etherscan or Tenderly.
Motivation
Currently, when a smart contract calls another and the called contract reverts, the revert reason is usually bubbled up and thrown as is. This can make it more difficult to tell which context the error came from. By standardizing the use of custom errors with additional context, more meaningful and informative revert reasons can be provided. This will improve the debugging experience and make it easier for developers and infrastructure providers like Etherscan to display accurate stack traces.
Specification
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.
In order to wrap a revert, a contract MUST revert with the following error that corresponds to the following signature 0x90bfb865:
target is the address of the called contract that reverted.
selector is the selector of the called function that reverted. If the call was an ETH transfer without any data, the selector MUST be bytes4(0)
reason is the raw bytes of the revert reason.
details is optional additional context about the revert. In cases where no additional context is needed, the details bytes can be empty. In cases with additional context, the details bytes MUST be an ABI encoded custom error declared on the contract that emits the WrappedError error.
Rationale
By including the called contract and function, raw revert bytes and additional context, developers can provide more detailed information about the failure. Additionally, by standardizing the way reverts are bubbled up, it also enables nested bubbled up reverts where multiple reverts thrown by different contracts can be followed recursively. The reverts can also be parsed and handled by tools like Etherscan and Foundry to further enhance the readability and debuggability of smart contract interactions, as well as facilitating better error handling practices in general.
Backwards Compatibility
This ERC does not introduce any backwards incompatibilities. Existing contracts can adopt this standard incrementally.
Test Cases
// SPDX-License-Identifier: MIT
pragmasolidity0.8.26;contractToken{mapping(address=>uint256)publicbalanceOf;eventTransfer(addressindexedsender,addressindexedrecipient,uintamount);functiontransfer(addressto,uint256amount)externalreturns(bool){require(balanceOf[msg.sender]>=amount,"insufficient balance");balanceOf[msg.sender]-=amount;balanceOf[to]+=amount;emitTransfer(msg.sender,to,amount);returntrue;}}contractVault{Tokentoken;errorWrappedError(addresstarget,bytes4selector,bytesreason,bytesdetails);errorERC20TransferFailed(addressrecipient);constructor(Tokentoken_){token=token_;}functionwithdraw(addressto,uint256amount)external{// logic
trytoken.transfer(to,amount){}catch(bytesmemoryerror){revertWrappedError(address(token),token.transfer.selector,error,abi.encodeWithSelector(ERC20TransferFailed.selector,to));}}}contractRouter{Vaultvault;errorWrappedError(addresstarget,bytes4selector,bytesreason,bytesdetails);constructor(Vaultvault_){vault=vault_;}functionwithdraw(uint256amount)external{// logic
tryvault.withdraw(msg.sender,amount){}catch(bytesmemoryerror){revertWrappedError(address(vault),vault.withdraw.selector,error,"");}}}contractTest{functiontest_BubbledNestedReverts(uint256amount)external{Tokentoken=newToken();Vaultvault=newVault(token);Routerrouter=newRouter(vault);tryrouter.withdraw(amount){}catch(bytesmemorythrownError){bytesmemoryexpectedError=abi.encodeWithSelector(Router.WrappedError.selector,address(vault),vault.withdraw.selector,abi.encodeWithSelector(Vault.WrappedError.selector,address(token),token.transfer.selector,abi.encodeWithSignature("Error(string)","insufficient balance"),abi.encodeWithSelector(Vault.ERC20TransferFailed.selector,address(this))),"");assert(keccak256(thrownError)==keccak256(expectedError));}}}
Reference Implementation
When catching a revert from a called contract, the calling contract should revert with a custom error following the above conventions.
Smart contracts could either drop or purposefully suppress the bubbled up reverts along the revert chain. Additionally, smart contracts may also lie or incorrectly report the wrapped reverts, so the information is not guaranteed to be accurate.
Daniel Gretzke (@gretzke), Sara Reynolds (@snreynolds), Alice Henshaw (@hensha256), Marko Veniger <marko.veniger@tenderly.co>, Hadrien Croubois (@Amxx), "ERC-7751: Wrapping of bubbled up reverts [DRAFT]," Ethereum Improvement Proposals, no. 7751, August 2024. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7751.