Revert Reason

The primary mechanism for generating revert reasons. It validates a condition and, if false, reverts the transaction with a specified message.

Example: require(balance >= amount, "Insufficient funds for transfer");

• Gas Refund: Reverts with require() or revert() refund all remaining gas to the caller, unlike the older throw keyword or failed assert().

An unconditional function that immediately halts execution and reverts state changes. It can accept a custom error string or a custom error type.

Example with string: revert("Transaction expired");

Example with custom error (gas-efficient): revert UnauthorizedCaller();

• Flexibility: Allows for more complex conditional logic than require().

Introduced in Solidity v0.8.4, custom errors are a gas-efficient alternative to string error messages. They are defined with the error keyword.

Definition: error InsufficientBalance(uint256 available, uint256 required);

Usage: revert InsufficientBalance(balance, amount);

• Benefits: Significantly cheaper gas cost because the error signature and parameters are ABI-encoded, not a full string stored on-chain.

The revert reason is returned to the caller as ABI-encoded data. For string messages, it's encoded as a function call to Error(string). For custom errors, it's encoded as a call to the error's signature.

• Off-Chain Decoding: Wallets and block explorers decode this data to display the human-readable message.
• Inspection: The raw data is visible in transaction receipts as the revertReason or within the output field of a failed call.

Revert reasons transform cryptic transaction failures into actionable insights.

For Developers:

• Pinpoints the exact failing condition in a smart contract.
• Essential for testing and integration.

For Users:

• Wallets can display clear messages like "Insufficient liquidity" instead of a generic "transaction failed".
• Improves transparency and trust in dApp interactions.

Understanding gas implications is crucial.

• Gas Refund: All gas is refunded for a revert triggered by require(), revert(), or a custom error.
• No Refund for assert(): The assert() function consumes all remaining gas, used for checking internal invariants that should never fail.
• Bubble Up: Reverts propagate up the call chain, undoing all state changes in the entire transaction.

The primary Solidity function for implementing revert reasons is require(). It validates a condition and, if false, reverts the transaction with a specified error string.

• Syntax: require(condition, "Descriptive error message");
• Example: require(msg.value >= 1 ether, "Insufficient payment");
• Gas: The error string consumes gas, so it's often omitted in production for non-critical checks to save costs.

The revert() function unconditionally aborts execution and can be used with a custom error or a string reason. It's more gas-efficient than require() for complex conditional logic.

• Syntax with string: revert("Operation failed");
• Syntax with custom error: revert CustomError(arg1, arg2);
• Use Case: Ideal for complex validation in the middle of a function or in if/else blocks where require() is less suitable.

Introduced in Solidity 0.8.4, custom errors are a gas-efficient alternative to string reasons. They are defined with the error keyword and can take parameters.

• Definition: error InsufficientBalance(uint256 available, uint256 required);
• Usage: revert InsufficientBalance(balance, amount);
• Advantage: Significantly cheaper than string messages, as only the 4-byte selector and ABI-encoded parameters are stored on-chain.

At the lowest level, revert reasons are implemented by the REVERT opcode (0xfd). This opcode halts execution, rolls back state changes, and can optionally return a memory segment containing the error data.

• Mechanism: The opcode takes two stack arguments: an offset and a size within memory where the error data (e.g., ABI-encoded string or custom error) is stored.
• Result: This data is returned to the caller in the transaction receipt's output field for a call, or as part of the receipt for a transaction.

When a transaction reverts, the reason is captured in the transaction receipt, enabling off-chain tools and user interfaces to display what went wrong.

• Field: The revertReason or decoded error is typically parsed from the receipt's output or status data.
• Tooling: Wallets (MetaMask), block explorers (Etherscan), and developer frameworks (Hardhat, Foundry) automatically decode and display these messages.
• Critical for UX: This transforms a generic "transaction failed" into a specific, actionable error like "ERC20: transfer amount exceeds balance".

Including revert reasons has a gas cost, leading to established optimization practices.

• String vs. Custom Error: A string reason can cost ~20k+ gas, while a custom error costs only ~100 gas for the selector.
• Production vs. Development: Use descriptive strings in development and testing. For production, consider:
  • Using custom errors.
  • Omitting the string in require() for non-user-facing checks.
  • Providing error codes that map to off-chain explanations.

A revert reason is a string of text that explains why a smart contract transaction failed. It is emitted by the require(), revert(), or assert() statements in Solidity. This provides developers and users with immediate, on-chain feedback for debugging and understanding transaction failures, moving beyond opaque generic errors like "execution reverted."

Storing the revert reason string on-chain consumes gas. The cost scales with the length of the message. This creates a trade-off: detailed error messages aid debugging but increase the gas cost of a failed transaction. For this reason, production contracts often use short, coded error messages (e.g., "INSUFFICIENT_BALANCE") or custom error types introduced in Solidity 0.8.4, which are more gas-efficient.

Introduced in Solidity 0.8.4, custom errors are defined with the error keyword (e.g., error InsufficientBalance(uint256 available, uint256 required)). They provide a more gas-efficient and type-safe alternative to string revert reasons. When a custom error is used with revert, only a 4-byte selector is stored on-chain, saving significant gas compared to storing full strings, especially for frequent failure conditions.

• Avoid Sensitive Data: Never include private keys, passwords, or internal state details in revert messages, as they are publicly visible on-chain.
• Use for Input Validation: Clearly state which invariant was violated (e.g., require(msg.value >= price, "PRICE_NOT_MET")).
• Prevent Information Leakage: In access-controlled functions, use generic errors like "UNAUTHORIZED" to avoid revealing system architecture.
• Balance Clarity with Cost: Use coded messages or custom errors for common failures to optimize gas.

solidityCopy
// Using a string revert reason (more gas)
require(balance >= amount, "Insufficient balance for transfer");

// Using a custom error (gas-optimized)
error InsufficientBalance(uint256 available, uint256 required);
if (balance < amount) {
    revert InsufficientBalance(balance, amount);
}

The custom error provides structured data (the available and required amounts) without the gas overhead of a long string.

• Revert: The opcode that halts execution and rolls back state changes.
• Require(): A Solidity function that checks a condition and reverts with an optional message.
• Assert(): Used for internal invariants; prior to Solidity 0.8.0, it consumed all gas on failure.
• Gas Refund: Failed transactions still consume gas for computation up to the point of revert, but any remaining gas is refunded to the caller.
• Error Handling: The broader pattern of managing failures in smart contract interactions.

A Solidity function used to validate conditions and revert transactions with a custom error message. It is the most common way to generate a revert reason.

• Syntax: require(condition, "Error message")
• Gas: Consumes all remaining gas if the condition fails (pre-EIP-150).
• Use Case: Validating user inputs, checking pre-conditions, and enforcing access control.

A Solidity function used to check for internal errors and invariants that should never be false. A failed assert() indicates a bug in the contract.

• Syntax: assert(condition)
• Gas: Consumes all gas (post-EIP-150) upon failure.
• Revert Reason: Generates a generic Panic error (e.g., 0x01 for an assertion failure), not a custom string message.

A gas-efficient Solidity feature (introduced in v0.8.4) for defining and throwing custom error types using the revert statement.

• Syntax: revert CustomErrorName(arg1, arg2);
• Advantage: Significantly cheaper than require() with string messages, as the error signature and arguments are ABI-encoded into the revert data.
• Use Case: Replacing expensive require() statements to optimize gas costs.

A set of standardized error codes used by the EVM and Solidity's assert() and certain internal checks. They are encoded in the revert data.

• Examples: 0x01 (assertion failed), 0x11 (arithmetic overflow), 0x12 (division by zero).
• Format: A 4-byte selector followed by ABI-encoded data.
• Purpose: Provides a machine-readable reason for a revert without the gas cost of a string message.

A Solidity control structure (introduced in v0.6.0) for handling external call failures and reverts in a controlled manner.

• Function: Allows a contract to react to a failed external call without reverting its own execution.
• Catches: Can catch specific error types, including revert reasons (Error(string)) and panic codes (Panic(uint256)).
• Use Case: Gracefully handling failures in interactions with other contracts or unknown code.

The low-level EVM instruction (0xFD) that triggers a state reversion. It is the fundamental operation behind all high-level revert mechanisms.

• Mechanism: Halts execution, reverts all state changes, and can optionally return data (the revert reason) to the caller.
• Gas Handling: Returns any remaining gas to the caller (post-EIP-150).
• Foundation: All Solidity revert statements (require, assert, revert) ultimately compile down to this opcode.