> ## 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.

# Utils

> Generic utilities for building robust Ethereum applications

<Warning>
  **This page is a placeholder.** All examples on this page are currently AI-generated and are not correct. This documentation will be completed in the future with accurate, tested examples.
</Warning>

# Utils

Voltaire provides a collection of generic utilities essential for building robust Ethereum applications. These utilities handle common patterns like retry logic, rate limiting, polling, timeouts, and batch processing.

## Why Utils?

Ethereum applications face unique challenges:

* **Transient failures**: RPC nodes may be temporarily unavailable or rate-limited
* **Async operations**: Transactions and state changes require polling for confirmation
* **Rate limits**: Public RPC endpoints enforce strict rate limits
* **Long operations**: Block production and transaction confirmation take time
* **Batch optimization**: Multiple similar requests can be batched for efficiency

These utilities provide battle-tested solutions to these challenges.

## Available Utilities

### Retry with Exponential Backoff

Automatically retry failed operations with exponential backoff and jitter.

```typescript theme={null}
import { retryWithBackoff } from '@tevm/voltaire/utils';

const blockNumber = await retryWithBackoff(
  () => provider.eth_blockNumber(),
  {
    maxRetries: 5,
    initialDelay: 1000,
    factor: 2,
    jitter: true
  }
);
```

[Learn more →](/utils/retry)

### Rate Limiting

Throttle, debounce, and rate-limit function calls.

```typescript theme={null}
import { RateLimiter } from '@tevm/voltaire/utils';

const limiter = new RateLimiter({
  maxRequests: 10,
  interval: 1000,
  strategy: 'queue'
});

const balance = await limiter.execute(
  () => provider.eth_getBalance(address)
);
```

[Learn more →](/utils/rate-limit)

### Polling

Poll operations until they succeed or timeout, with optional backoff.

```typescript theme={null}
import { pollForReceipt } from '@tevm/voltaire/utils';

const receipt = await pollForReceipt(
  txHash,
  (hash) => provider.eth_getTransactionReceipt(hash),
  { timeout: 120000 }
);
```

[Learn more →](/utils/polling)

### Timeout

Add timeouts to promises and async operations.

```typescript theme={null}
import { withTimeout } from '@tevm/voltaire/utils';

const result = await withTimeout(
  provider.eth_call({ to, data }),
  { ms: 5000, message: 'Call timeout' }
);
```

[Learn more →](/utils/timeout)

### Batch Processing

Automatically batch similar operations for efficiency.

```typescript theme={null}
import { BatchQueue } from '@tevm/voltaire/utils';

const queue = new BatchQueue({
  maxBatchSize: 50,
  maxWaitTime: 100,
  processBatch: async (addresses) => {
    return Promise.all(
      addresses.map(addr => provider.eth_getBalance(addr))
    );
  }
});

const balance = await queue.add(address);
```

[Learn more →](/utils/batch)

## Installation

Utils are included with Voltaire. No additional dependencies required.

```bash theme={null}
npm install @tevm/voltaire
# or
bun add @tevm/voltaire
```

## Design Principles

### Vanilla TypeScript

All utilities use standard Promise-based APIs. No framework dependencies.

### Type Safe

Full TypeScript support with generic types for maximum type safety.

### Tree Shakeable

Import only what you need. Each utility is independently importable.

### Zero Runtime Overhead

Minimal abstractions. Direct, efficient implementations.

## Common Patterns

### Resilient RPC Calls

Combine retry and timeout for robust RPC calls:

```typescript theme={null}
import { retryWithBackoff, withTimeout } from '@tevm/voltaire/utils';

const resilientCall = async <T>(fn: () => Promise<T>): Promise<T> => {
  return retryWithBackoff(
    () => withTimeout(fn(), { ms: 10000 }),
    {
      maxRetries: 3,
      shouldRetry: (error) => {
        // Don't retry on timeout
        return error.name !== 'TimeoutError';
      }
    }
  );
};

const blockNumber = await resilientCall(
  () => provider.eth_blockNumber()
);
```

### Rate-Limited Batch Processing

Combine rate limiting and batching:

```typescript theme={null}
import { RateLimiter, BatchQueue } from '@tevm/voltaire/utils';

const limiter = new RateLimiter({
  maxRequests: 10,
  interval: 1000
});

const queue = new BatchQueue({
  maxBatchSize: 50,
  maxWaitTime: 100,
  processBatch: async (addresses) => {
    return limiter.execute(() =>
      Promise.all(
        addresses.map(addr => provider.eth_getBalance(addr))
      )
    );
  }
});
```

### Poll with Timeout and Retry

Combine polling, timeout, and retry:

```typescript theme={null}
import { poll, withTimeout, retryWithBackoff } from '@tevm/voltaire/utils';

const waitForBlock = async (blockNumber: bigint): Promise<Block> => {
  return withTimeout(
    poll(
      () => retryWithBackoff(
        () => provider.eth_getBlockByNumber(blockNumber)
      ),
      {
        interval: 1000,
        validate: (block) => block !== null
      }
    ),
    { ms: 60000 }
  );
};
```

## Next Steps

* [Retry with Backoff →](/utils/retry)
* [Rate Limiting →](/utils/rate-limit)
* [Polling →](/utils/polling)
* [Timeout →](/utils/timeout)
* [Batch Processing →](/utils/batch)