# ADR-002: Custom Errors for Gas Efficiency

**Status**: Accepted
**Date**: 2024-12-12
**Deciders**: Development Team

## Context

Solidity 0.8.4+ introduced custom errors as a gas-efficient alternative to `require()` statements with string messages. Custom errors save gas because they don't store string data in bytecode.

## Decision

We will use custom errors throughout the codebase instead of `require()` statements with string messages:

1. **Error Organization**: Group errors by contract/module:
   - `TokenErrors.sol` - eMoneyToken errors
   - `BridgeErrors.sol` - BridgeVault138 errors
   - `RegistryErrors.sol` - Registry contract errors
   - `FactoryErrors.sol` - TokenFactory138 errors

2. **Naming Convention**: Use descriptive, prefixed names:
   - `BridgeZeroToken()` instead of `ZeroToken()`
   - `DebtLienNotActive()` instead of `LienNotActive()`
   - Prevents naming conflicts across modules

## Rationale

- **Gas Savings**: Custom errors are ~200-300 gas cheaper than string errors
- **Better UX**: Errors can include parameters (addresses, amounts) for better debugging
- **Type Safety**: Compile-time checking of error signatures
- **Code Clarity**: Errors are defined alongside contracts

## Consequences

### Positive
- Significant gas savings on revert paths
- Better error messages with parameters
- Type-safe error handling
- Cleaner code organization

### Negative
- Requires updating all test files to use new error selectors
- Slightly more verbose error definitions

## Alternatives Considered

1. **Keep require() strings**: Traditional approach
   - Rejected: Higher gas costs, less informative errors

2. **Mixed approach**: Custom errors for common paths, strings for rare cases
   - Rejected: Inconsistent, harder to maintain

## Implementation

- All `require()` statements replaced with custom errors
- Error files organized by contract module
- Tests updated to use error selectors
- Documentation updated