> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# ErrorSignature

> 4-byte error selector for Solidity custom errors

# ErrorSignature

An **ErrorSignature** is a 4-byte identifier used for Solidity custom errors in revert data. It's computed as the first 4 bytes of the Keccak-256 hash of the error signature, similar to function selectors.

## Type Definition

```typescript theme={null}
type ErrorSignatureType = Uint8Array & {
  readonly [brand]: "ErrorSignature";
  readonly length: 4;
};
```

## Creating Error Signatures

### From Signature String

```typescript theme={null}
import * as ErrorSignature from '@tevm/primitives';

const insufficientBalance = ErrorSignature.fromSignature(
  'InsufficientBalance(uint256,uint256)'
);

console.log(ErrorSignature.toHex(insufficientBalance));
// '0xcf479181'
```

### From Hex String

```typescript theme={null}
const sig = ErrorSignature.fromHex('0xcf479181');
```

### From Bytes

```typescript theme={null}
const bytes = new Uint8Array([0xcf, 0x47, 0x91, 0x81]);
const sig = ErrorSignature.from(bytes);
```

## Operations

### Convert to Hex

```typescript theme={null}
const hex = ErrorSignature.toHex(signature);
// '0xcf479181'
```

### Compare Signatures

```typescript theme={null}
const sig1 = ErrorSignature.fromSignature('Unauthorized()');
const sig2 = ErrorSignature.fromSignature('Error(string)');
const equal = ErrorSignature.equals(sig1, sig2); // false
```

## Standard Error Signatures

### Built-in Errors

Solidity has two built-in error signatures:

```typescript theme={null}
// Error(string) - Used by require()
const errorString = ErrorSignature.fromSignature('Error(string)');
// 0x08c379a0

// Panic(uint256) - Used by assert()
const panic = ErrorSignature.fromSignature('Panic(uint256)');
// 0x4e487b71
```

### Panic Codes

When using `assert()` or encountering specific errors, Solidity reverts with `Panic(uint256)` and a code:

* `0x00` - Generic panic
* `0x01` - Assert failed
* `0x11` - Arithmetic overflow/underflow
* `0x12` - Division by zero
* `0x21` - Invalid enum value
* `0x22` - Invalid storage byte array access
* `0x31` - Pop on empty array
* `0x32` - Array out of bounds
* `0x41` - Out of memory
* `0x51` - Invalid internal function call

## Custom Errors

Custom errors are more gas-efficient than `require()` with strings:

```solidity theme={null}
// Define custom error
error InsufficientBalance(uint256 available, uint256 required);

// Use in contract
if (balance < amount) {
  revert InsufficientBalance(balance, amount);
}
```

```typescript theme={null}
const sig = ErrorSignature.fromSignature('InsufficientBalance(uint256,uint256)');
// 0xcf479181
```

## Common Custom Errors

### Access Control

```typescript theme={null}
const unauthorized = ErrorSignature.fromSignature('Unauthorized()');
const onlyOwner = ErrorSignature.fromSignature('OnlyOwner()');
const invalidRole = ErrorSignature.fromSignature('InvalidRole(bytes32)');
```

### Token Operations

```typescript theme={null}
const insufficientBalance = ErrorSignature.fromSignature(
  'InsufficientBalance(uint256,uint256)'
);
const insufficientAllowance = ErrorSignature.fromSignature(
  'InsufficientAllowance(uint256,uint256)'
);
const invalidRecipient = ErrorSignature.fromSignature('InvalidRecipient(address)');
```

### DeFi

```typescript theme={null}
const slippageTooHigh = ErrorSignature.fromSignature(
  'SlippageTooHigh(uint256,uint256)'
);
const deadlineExpired = ErrorSignature.fromSignature('DeadlineExpired(uint256)');
const insufficientLiquidity = ErrorSignature.fromSignature('InsufficientLiquidity()');
```

## Revert Data Structure

When a custom error is thrown, the revert data contains:

```
[selector (4 bytes)][encoded parameters]
```

Example for `InsufficientBalance(1000, 2000)`:

```
0xcf479181                                                          // selector
0000000000000000000000000000000000000000000000000000000000003e8  // 1000
0000000000000000000000000000000000000000000000000000000000007d0  // 2000
```

## Decoding Errors

Use error signatures to decode revert data:

```typescript theme={null}
const revertData = '0xcf479181...'; // from transaction
const selector = revertData.slice(0, 10); // '0xcf479181'

const errorSig = ErrorSignature.fromHex(selector);
// Identify: InsufficientBalance(uint256,uint256)

// Decode parameters from revertData.slice(10)
```

## Signature Format

Error signatures must use **canonical type names**:

✅ Correct:

* `InsufficientBalance(uint256,uint256)`
* `Unauthorized()`
* `InvalidSwap(address,uint256,bytes)`

❌ Incorrect:

* `InsufficientBalance(uint, uint)` (should be uint256)
* `InsufficientBalance(uint256, uint256)` (has spaces)
* `insufficientBalance(uint256,uint256)` (wrong capitalization)

**Note**: Error names conventionally start with uppercase.

## How Error Signatures Work

1. **Error Signature**: Start with the canonical error signature
2. **Hash**: Compute `keccak256(signature)`
3. **Truncate**: Take the first 4 bytes

```
InsufficientBalance(uint256,uint256)
  ↓ keccak256
0xcf4791819f1b70c0f30aefb0f54ba2bc...
  ↓ slice(0, 4)
0xcf479181
```

## Gas Efficiency

Custom errors are significantly more gas-efficient than `require()` with strings:

```solidity theme={null}
// ❌ Expensive (~24k gas)
require(balance >= amount, "Insufficient balance");

// ✅ Efficient (~1k gas)
if (balance < amount) revert InsufficientBalance(balance, amount);
```

## Handling Errors

```typescript theme={null}
try {
  await contract.transfer(recipient, amount);
} catch (error) {
  if (error.data) {
    const selector = error.data.slice(0, 10);

    const insufficientBalanceSig = ErrorSignature.fromSignature(
      'InsufficientBalance(uint256,uint256)'
    );

    if (selector === ErrorSignature.toHex(insufficientBalanceSig)) {
      // Handle insufficient balance error
      console.log('Not enough balance');
    }
  }
}
```

## API Reference

### Constructors

* `from(value: ErrorSignatureLike): ErrorSignatureType` - Create from various inputs
* `fromHex(hex: string): ErrorSignatureType` - Create from hex string
* `fromSignature(signature: string): ErrorSignatureType` - Compute from error signature

### Operations

* `toHex(sig: ErrorSignatureType): string` - Convert to hex string
* `equals(a: ErrorSignatureType, b: ErrorSignatureType): boolean` - Compare signatures

## See Also

* [Selector](/primitives/selector) - 4-byte function selector
* [FunctionSignature](/primitives/function-signature) - Extended function selector
* [EventSignature](/primitives/event-signature) - 32-byte event topic
* [ABI](/primitives/abi) - ABI encoding and decoding