{"id":"ERC-7751","name":"Wrapping of Bubbled Up Reverts","status":"Final","chain":"both","category":{"id":"comprehension","name":"Comprehension & Display","description":"Making blockchain data readable to humans"},"journeyStages":[{"id":"reading","name":"Reading & Understanding","description":"Interpreting what you're being asked to do"}],"uxImpact":"ERC-7751 standardizes wrapped errors so participating contracts can report nested failure context. Clients can display the reported layers in plain language, but the chain can be incomplete or inaccurate. Verify state or simulation evidence before asserting a root cause or offering a recovery transaction.","officialUrl":"https://ercs.ethereum.org/ERCS/erc-7751","lastReviewed":"2026-09-18","lastUpdated":"2026-09-18","kind":"proposal","hasDetailedContent":true,"content":{"id":"ERC-7751","summary":"ERC-7751 standardizes wrapped errors so participating contracts can report nested failure context. Clients can display the reported layers in plain language, but the chain can be incomplete or inaccurate. Verify state or simulation evidence before asserting a root cause or offering a recovery transaction.","applicability":{"whenToUse":["Participating contracts return recognizable wrapped errors.","Your client can present partial reported context and independently verify a proposed remedy."],"whenToAvoid":["You need a guaranteed complete or truthful root-cause chain.","Unknown or malformed errors cannot be decoded safely; use the fallback instead."]},"designerTakeaways":["Show a reported wrapped-error chain in plain language while marking missing or unknown layers.","Use reported authorization or expiry context as a troubleshooting clue, then verify the relevant state before suggesting approval.","Use wrapped context to locate a failed step, but keep the root-cause claim tied to receipt, trace, simulation, or state evidence."],"problemsSolved":[{"problem":"Error messages lose context as they propagate","oldWay":"\"execution reverted\" - no idea what failed or why","newWay":"Reported error chain: \"Swap failed → Pool error → Insufficient liquidity\"","impact":"critical"},{"problem":"Users can't take action on vague errors","oldWay":"\"Transaction failed\" - what should user do?","newWay":"\"Authorization expired 2 minutes ago - please approve again\"","impact":"critical"},{"problem":"Debugging requires guessing what went wrong","oldWay":"Trial and error, check each step manually","newWay":"Reported context can help diagnose a failed step","impact":"high"},{"problem":"Different contracts return different error formats","oldWay":"Parse error differently for each protocol","newWay":"Standard wrapping format enables consistent parsing","impact":"medium"}],"uxPatterns":[{"name":"Contextual Error Display","description":"Show available reported error layers, including unknown or missing context","userFlow":["Transaction fails","Parse wrapped error chain","Display hierarchy of what failed","Extract actionable suggestion","Offer relevant next steps"]},{"name":"Authorization Expiry Error","description":"Handle common authorization-related failures","userFlow":["Swap fails with approval error","Parse reported context and independently check the suspected cause","Show specific approval issue","Verify the allowance and spender, then preview any needed approval for explicit consent","Suggest prevention for future"]},{"name":"Multi-Step Error Tracing","description":"Show which step in a batch failed","userFlow":["Multi-step batch fails mid-way","Identify which step failed","Read execution outcomes separately from receipt, state or trace evidence before showing completed, failed or skipped steps","Explain the reported failure and distinguish verified evidence from contract-reported context","Offer fix for specific failure"]},{"name":"Developer Debug View","description":"Technical error details for power users","userFlow":["User clicks \"Show details\"","Display the available technical error layers and mark partial or unknown context","Show contract addresses and selectors","Allow copy for bug reports","Link to transaction explorer"]}],"uiComponents":[{"name":"ErrorChainDisplay","description":"Nested display of wrapped errors","states":["collapsed","expanded","highlighted"],"props":["errors[]","onExpand","highlightRoot"]},{"name":"ActionableError","description":"Error with suggested resolution action","states":["error","suggesting","resolving"],"props":["error","suggestion","action","onAction"]},{"name":"BatchStepIndicator","description":"Show progress through batch with failure point","states":["pending","success","failed","skipped"],"props":["steps[]","failedStep","errorDetail"]},{"name":"TechnicalErrorView","description":"Developer-focused error details","states":["collapsed","expanded"],"props":["error","contract","selector","params"]}],"antiPatterns":[{"pattern":"Showing raw error selector codes","why":"\"0x4e487b71\" means nothing to users","instead":"Translate to human-readable: \"Insufficient liquidity\"","severity":"critical"},{"pattern":"Hiding error details entirely","why":"Power users need details for debugging","instead":"Show friendly message + expandable technical details","severity":"high"},{"pattern":"No suggested actions","why":"User sees error but doesn't know what to do","instead":"Parse error type, suggest specific resolution","severity":"high"},{"pattern":"Losing nested error context","why":"Root cause hidden, only surface error shown","instead":"Preserve and display reported error chain","severity":"medium"}],"keyTakeaways":["Wrapped errors tell the reported context for what went wrong","Translate recognized technical errors to human-readable messages and mark unknown layers","Provide a bounded suggestion only after checking the reported error against relevant state","Show the reported error hierarchy with its verification limits"],"technicalNotes":"ERC-7751 defines WrappedError(address target, bytes4 selector, bytes reason, bytes details). details is optional. Participating contracts may wrap lower-level errors, but any contract can omit, suppress or misreport context. Decode defensively, preserve unknown layers and verify the relevant state or simulation before claiming a definitive cause. A reported allowance or expiry error does not authorize another approval.","lastUpdated":"2026-09-18","lastReviewed":"2026-09-18","specConstraints":[{"id":"wrapped-revert-propagation","constraint":"Calling contracts SHOULD wrap caught reverts in the standard custom error so nested failure context remains available to tools.","appliesTo":"account-implementation","normativity":"normative","specQuote":"When catching a revert from a called contract, the calling contract should revert with a custom error following the above conventions.","specSection":"Reference Implementation","specUrl":"https://ercs.ethereum.org/ERCS/erc-7751#reference-implementation","designImplication":"Where a flow depends on nested failure context, preserve the target, selector, raw reason, and optional details through each wrapping layer; present decoded causes as reported context, not proof."},{"id":"wrapped-error-details-option","constraint":"WrappedError details are OPTIONAL; when present, they MUST be ABI-encoded custom-error data declared by the emitting contract.","appliesTo":"account-implementation","normativity":"normative","specQuote":"- `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.","specSection":"Specification","specUrl":"https://ercs.ethereum.org/ERCS/erc-7751#specification","designImplication":"Allow an empty details state and only show decoded additional context when the emitting contract's declared custom-error schema is known; keep unknown bytes visibly unparsed."},{"id":"wrapped-revert-untrusted","constraint":"Wrapped revert data may be dropped, suppressed, or reported incorrectly by contracts and is not guaranteed to be accurate.","appliesTo":"application","normativity":"security-considerations","specQuote":"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.","specSection":"Security Considerations","specUrl":"https://ercs.ethereum.org/ERCS/erc-7751#security-considerations","designImplication":"Use wrapped errors to explain a failure, not to authorize a new action or assert that the decoded cause is trustworthy."}],"sources":[{"label":"ERC-7751 official specification","url":"https://ercs.ethereum.org/ERCS/erc-7751","type":"official-spec"}]},"sources":[{"label":"Official specification","url":"https://ercs.ethereum.org/ERCS/erc-7751","type":"official-spec"},{"label":"Discussion search","url":"https://ethereum-magicians.org/search?q=ERC-7751","type":"discussion"}],"urls":{"canonical":"https://www.eipsfordesigners.com/standards/ERC-7751","markdown":"https://www.eipsfordesigners.com/standards/ERC-7751/content.md","agent":"https://www.eipsfordesigners.com/standards/ERC-7751/agent.md","api":"https://www.eipsfordesigners.com/api/standards/ERC-7751","official":"https://ercs.ethereum.org/ERCS/erc-7751","discussion":"https://ethereum-magicians.org/search?q=ERC-7751"},"freshness":{"lastReviewed":"2026-09-18","lastUpdated":"2026-09-18"}}