Skip to main content
Skill — Copyable reference implementation. Use as-is or customize. See Skills Philosophy.

Ethers v6 Style Provider

This Skill documents an ethers v6-compatible JsonRpcProvider implementation built on Voltaire primitives. It provides the same API surface as ethers v6 while leveraging Voltaire’s batching, retry, and polling utilities.

Overview

The EthersProvider class implements the full ethers v6 provider API:
  • Network detection and management
  • Account queries (balance, nonce, code, storage)
  • Transaction execution (call, estimateGas, broadcastTransaction)
  • Block and log retrieval
  • Event subscription system
  • Request batching and caching

Installation

The provider is located in examples/ethers-provider/:

Quick Start

Configuration

The provider accepts configuration options matching ethers v6:

API Reference

Network Methods

Account Methods

Transaction Methods

Block Methods

Log Methods

Event Subscriptions

Raw RPC

Lifecycle

Request Batching

The provider automatically batches requests using Voltaire’s BatchQueue:
Configuration:
  • batchStallTime: Wait time before sending batch (default: 10ms)
  • batchMaxCount: Maximum requests per batch (default: 100)
  • batchMaxSize: Maximum batch size in bytes (default: 1MB)

Request Caching

Identical requests within the cache window share the same promise:
Configuration:
  • cacheTimeout: Cache duration in ms (default: 250ms, -1 to disable)

Retry Logic

Failed requests are automatically retried with exponential backoff:
  • Max retries: 3
  • Initial delay: 100ms
  • Exponential backoff with jitter

Error Handling

The provider maps JSON-RPC errors to ethers-compatible error codes:
Error codes:
  • CALL_EXCEPTION - Contract call reverted
  • INSUFFICIENT_FUNDS - Not enough ETH
  • NONCE_EXPIRED - Nonce already used
  • REPLACEMENT_UNDERPRICED - Gas too low for replacement
  • NETWORK_ERROR - Network issue
  • TIMEOUT - Request timeout
  • UNSUPPORTED_OPERATION - Method not supported
  • ACTION_REJECTED - User rejected

Network Support

Built-in network detection for:
  • Ethereum Mainnet (chainId: 1)
  • Sepolia (chainId: 11155111)
  • Goerli (chainId: 5)
  • Arbitrum (chainId: 42161)
  • Optimism (chainId: 10)
  • Polygon (chainId: 137)
  • Base (chainId: 8453)

Voltaire Primitives Used

The implementation leverages these Voltaire utilities:
  • BatchQueue - Request batching
  • retryWithBackoff - Retry logic
  • poll - Transaction confirmation polling
  • Address - Address validation (optional)

Migration from ethers v6

The API is designed to be drop-in compatible:

Differences from ethers v6

Current limitations:
  1. ENS resolution - resolveName() and lookupAddress() not implemented
  2. CCIP Read - EIP-3668 off-chain data not supported
  3. Transaction replacement detection - Not implemented
  4. Plugin system - Network plugins not supported
These can be added as needed.

Source Files

  • examples/ethers-provider/EthersProvider.js - Implementation
  • examples/ethers-provider/EthersProviderTypes.ts - TypeScript types
  • examples/ethers-provider/EthersProvider.test.ts - Tests
  • examples/ethers-provider/REQUIREMENTS.md - Full API requirements