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

# JSONRPCProvider

> EIP-1193 compliant Ethereum JSON-RPC provider with branded primitives and EventEmitter pattern

<Info>
  **Looking for ethers or viem-style providers?** See our [Provider Skills](/skills/ethers-provider)—copyable implementations you can customize. This page documents the low-level EIP-1193 interface that Skills build upon.
</Info>

<Info>
  Source:
  [Provider.ts](https://github.com/evmts/voltaire/blob/main/src/provider/Provider.ts) •
  [HttpProvider.ts](https://github.com/evmts/voltaire/blob/main/src/provider/HttpProvider.ts) •
  [InMemoryProvider.ts](https://github.com/evmts/voltaire/blob/main/src/provider/InMemoryProvider.ts) •
  [WebSocketProvider.ts](https://github.com/evmts/voltaire/blob/main/src/provider/WebSocketProvider.ts)

  Tests:
  [HttpProvider.test.ts](https://github.com/evmts/voltaire/blob/main/src/provider/HttpProvider.test.ts) •
  [WebSocketProvider.test.ts](https://github.com/evmts/voltaire/blob/main/src/provider/WebSocketProvider.test.ts) •
  [InMemoryProvider.test.ts](https://github.com/evmts/voltaire/blob/main/src/provider/InMemoryProvider.test.ts) •
  [EIP1193Provider.test.ts](https://github.com/evmts/voltaire/blob/main/src/provider/EIP1193Provider.test.ts)
</Info>

<Warning>
  **Future Plans:** This page is planned and under active development. Examples are not final and will be replaced with accurate, tested content.
</Warning>

# JSONRPCProvider

EIP-1193 compliant Ethereum JSON-RPC provider interface with branded primitive types and standard event emitter pattern. All types auto-generated from the [official OpenRPC specification](https://github.com/ethereum/execution-apis).

<Tip>
  New to JSONRPCProvider? Start with [Getting Started](/jsonrpc-provider/getting-started) for installation and your first requests.
</Tip>

## Overview

JSONRPCProvider implements the EIP-1193 provider interface for interacting with Ethereum nodes via JSON-RPC:

* **EIP-1193 compliant** - Standard `request(args)` method
* **Branded primitives** - Type-safe params using Address, Hash, Hex, Quantity
* **Throws on error** - Standard error handling with exceptions
* **EventEmitter pattern** - Standard on/removeListener for events
* **Auto-generated types** - Generated from ethereum/execution-apis OpenRPC spec

### Provider Interface

```typescript theme={null}
export interface Provider {
  // Single request method (EIP-1193)
  request(args: RequestArguments): Promise<unknown>;

  // Event emitter methods (EIP-1193)
  on(event: string, listener: (...args: any[]) => void): void;
  removeListener(event: string, listener: (...args: any[]) => void): void;
}
```

### Request Arguments

Create requests using request builders:

```typescript theme={null}
import * as Rpc from '@tevm/voltaire/jsonrpc';

// Request builders return RequestArguments
const request = Rpc.Eth.BlockNumberRequest();
// { method: "eth_blockNumber", params: [] }

const result = await provider.request(request);
// Returns result directly or throws on error
```

## Key Features

<CardGroup cols={2}>
  <Card title="EIP-1193 Compliant" icon="code" href="/jsonrpc-provider/method-api">
    Standard request(args) method. Compatible with all EIP-1193 tools and libraries.
  </Card>

  <Card title="Branded Primitives" icon="shield-check" href="/jsonrpc-provider/type-system">
    Compile-time type safety with Address, Hash, Hex, and Quantity branded types.
  </Card>

  <Card title="EventEmitter Pattern" icon="bolt" href="/jsonrpc-provider/events">
    Standard on/removeListener for accountsChanged, chainChanged, connect, disconnect events.
  </Card>

  <Card title="Auto-Generated Types" icon="code-branch" href="/jsonrpc-provider/type-system">
    All types generated from ethereum/execution-apis OpenRPC specification. Always in sync.
  </Card>

  <Card title="Request Builders" icon="circle-exclamation" href="/jsonrpc-provider/error-handling">
    Type-safe request constructors that return RequestArguments objects.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/jsonrpc-provider/error-handling">
    Throws standard EIP-1193 errors. Use try/catch for error handling.
  </Card>
</CardGroup>

## Architecture

```
OpenRPC Specification (ethereum/execution-apis)
           ↓
  JSON-RPC Type Definitions
    (eth, debug, engine)
           ↓
   Request Builders
   (Rpc.Eth.*, Rpc.Debug.*, Rpc.Engine.*)
           ↓
   EIP-1193 Provider Interface
   (request(args) method)
           ↓
    Transport Layer
 (HTTP, WebSocket, IPC, Custom)
```

## API Methods

### Method Namespaces

<CardGroup cols={3}>
  <Card title="eth Methods" icon="ethereum" href="/jsonrpc-provider/eth-methods">
    40 standard Ethereum methods for blocks, transactions, state, logs, and gas estimation.
  </Card>

  <Card title="debug Methods" icon="bug" href="/jsonrpc-provider/debug-methods">
    5 debugging methods for transaction tracing and block analysis.
  </Card>

  <Card title="engine Methods" icon="gears" href="/jsonrpc-provider/engine-methods">
    20 consensus layer methods for Engine API integration.
  </Card>
</CardGroup>

### Core Concepts

<CardGroup cols={3}>
  <Card title="Method API" icon="function" href="/jsonrpc-provider/method-api">
    Direct method calls, parameters, response handling, and request options.
  </Card>

  <Card title="Type System" icon="shield" href="/jsonrpc-provider/type-system">
    Auto-generated types, branded primitives, and type hierarchy.
  </Card>

  <Card title="Events" icon="rss" href="/jsonrpc-provider/events">
    Async generator subscriptions for newHeads, logs, pending transactions.
  </Card>
</CardGroup>

### Advanced Topics

<CardGroup cols={3}>
  <Card title="Adapters" icon="plug" href="/jsonrpc-provider/adapters">
    EIP-1193 adapter, HTTP handler, and creating custom providers.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/jsonrpc-provider/error-handling">
    Response structure, error codes, and retry strategies.
  </Card>

  <Card title="Performance" icon="gauge-high" href="/jsonrpc-provider/performance">
    Batching, caching, connection pooling, and optimization.
  </Card>
</CardGroup>

## Types

<Tabs>
  <Tab title="Provider">
    ```typescript theme={null}
    export interface Provider {
      // Single request method (EIP-1193)
      request(args: RequestArguments): Promise<unknown>;

      // Event emitter methods (EIP-1193)
      on(event: string, listener: (...args: any[]) => void): void;
      removeListener(event: string, listener: (...args: any[]) => void): void;
    }

    interface RequestArguments {
      readonly method: string;
      readonly params?: readonly unknown[] | object;
    }
    ```
  </Tab>

  <Tab title="Request Builders">
    ```typescript theme={null}
    import * as Rpc from '@tevm/voltaire/jsonrpc';

    // eth namespace (40 methods)
    Rpc.Eth.BlockNumberRequest();
    Rpc.Eth.GetBalanceRequest(address, blockTag);
    Rpc.Eth.GetTransactionCountRequest(address, blockTag);
    Rpc.Eth.GetCodeRequest(address, blockTag);
    Rpc.Eth.GetStorageAtRequest(address, slot, blockTag);
    Rpc.Eth.CallRequest(params, blockTag);
    Rpc.Eth.EstimateGasRequest(params);
    Rpc.Eth.SendRawTransactionRequest(signedTx);
    Rpc.Eth.GetTransactionByHashRequest(hash);
    Rpc.Eth.GetTransactionReceiptRequest(hash);
    Rpc.Eth.GetLogsRequest(filter);
    // ... 29 more eth methods

    // debug namespace (5 methods)
    Rpc.Debug.TraceTransactionRequest(hash, options);
    // ... 4 more debug methods

    // engine namespace (20 methods)
    Rpc.Engine.NewPayloadV3Request(payload);
    // ... 19 more engine methods

    // All return RequestArguments: { method: string, params: unknown[] }
    ```
  </Tab>

  <Tab title="Error Handling">
    ```typescript theme={null}
    // Provider throws on error (EIP-1193)
    try {
      const blockNumber = await provider.request(
        Rpc.Eth.BlockNumberRequest()
      );
      console.log('Block number:', blockNumber);
    } catch (error) {
      if (error.code) {
        console.error('RPC error:', error.code, error.message);
      } else {
        console.error('Unexpected error:', error);
      }
    }
    ```

    **EIP-1193 Error Structure:**

    ```typescript theme={null}
    interface ProviderRpcError extends Error {
      code: number;
      data?: unknown;
    }
    ```
  </Tab>

  <Tab title="Common Types">
    ```typescript theme={null}
    // Block tags
    type BlockTag = 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized' | Quantity;

    // Branded primitives
    import type { brand } from '@tevm/voltaire/brand';

    type Address = Uint8Array & { readonly [brand]: "Address" };
    type Hash = Uint8Array & { readonly [brand]: "Hash" };
    type Hex = string & { readonly [brand]: "Hex" };
    type Quantity = string & { readonly [brand]: "Quantity" };  // Hex-encoded numbers

    // Request types
    interface CallParams {
      from?: Address;
      to: Address;
      gas?: Quantity;
      gasPrice?: Quantity;
      value?: Quantity;
      data?: Hex;
    }

    interface LogFilter {
      fromBlock?: BlockTag;
      toBlock?: BlockTag;
      address?: Address | Address[];
      topics?: (Hash | Hash[] | null)[];
    }
    ```
  </Tab>
</Tabs>

## Usage Patterns

### Check Balance and Nonce

```typescript theme={null}
import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Address } from '@tevm/voltaire/Address';

const address = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0');

// Create requests using builders
const balanceReq = Rpc.Eth.GetBalanceRequest(address, 'latest');
const nonceReq = Rpc.Eth.GetTransactionCountRequest(address, 'latest');

try {
  const [balance, nonce] = await Promise.all([
    provider.request(balanceReq),
    provider.request(nonceReq)
  ]);

  console.log('Balance:', balance);
  console.log('Nonce:', nonce);
} catch (error) {
  console.error('RPC error:', error.message);
}
```

### Query Contract State

```typescript theme={null}
import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Address } from '@tevm/voltaire/Address';
import { Hex } from '@tevm/voltaire/Hex';

const contractAddress = Address('0x...');

try {
  // Check if contract exists
  const code = await provider.request(
    Rpc.Eth.GetCodeRequest(contractAddress, 'latest')
  );

  if (code !== '0x') {
    // Contract exists, call totalSupply()
    const result = await provider.request(
      Rpc.Eth.CallRequest({
        to: contractAddress,
        data: Hex('0x18160ddd')  // totalSupply() selector
      }, 'latest')
    );

    console.log('Total supply:', result);
  }
} catch (error) {
  console.error('Query failed:', error.message);
}
```

### Monitor Contract Events

```typescript theme={null}
import { Address } from '@tevm/voltaire/Address';
import { Hash } from '@tevm/voltaire/Hash';

const contractAddress = Address('0x...');
const transferSignature = Hash(
  '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
);

// Subscribe using EIP-1193 event emitter
provider.on('message', (event) => {
  if (event.type === 'eth_subscription') {
    const log = event.data.result;
    console.log('Transfer event:');
    console.log('  Block:', log.blockNumber);
    console.log('  Transaction:', log.transactionHash);
    console.log('  From:', log.topics[1]);
    console.log('  To:', log.topics[2]);
  }
});

// Or use chainChanged, accountsChanged events
provider.on('chainChanged', (chainId) => {
  console.log('Chain changed to:', chainId);
});
```

### Wait for Transaction Confirmation

```typescript theme={null}
import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Hash } from '@tevm/voltaire/Hash';

async function waitForConfirmation(
  txHash: Hash,
  confirmations: number = 3
): Promise<void> {
  try {
    const receipt = await provider.request(
      Rpc.Eth.GetTransactionReceiptRequest(txHash)
    );

    if (!receipt) {
      throw new Error('Transaction not found');
    }

    const targetBlock = BigInt(receipt.blockNumber) + BigInt(confirmations);

    // Poll for block number
    while (true) {
      const currentBlock = await provider.request(
        Rpc.Eth.BlockNumberRequest()
      );

      if (BigInt(currentBlock) >= targetBlock) {
        console.log(`Transaction confirmed with ${confirmations} confirmations`);
        break;
      }

      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  } catch (error) {
    console.error('Confirmation failed:', error.message);
    throw error;
  }
}
```

## Tree-Shaking

Import only what you need for optimal bundle size:

```typescript theme={null}
// Import Provider interface (no implementations)
import type { Provider } from '@tevm/voltaire/provider';

// Import specific primitives used
import { Address } from '@tevm/voltaire/Address';
import { Hash } from '@tevm/voltaire/Hash';

// Only these primitives included in bundle
// Unused primitives (Bytecode, Transaction, etc.) excluded
```

<Tip>
  Importing primitives individually enables tree-shaking. Unused methods and types are excluded from your bundle.
</Tip>

## Key Features Compared to Other Libraries

| Feature          | Standard EIP-1193             | Voltaire JSONRPCProvider           |
| ---------------- | ----------------------------- | ---------------------------------- |
| Method calls     | `request({ method, params })` | `request(Rpc.Eth.MethodRequest())` |
| Parameters       | Plain strings/objects         | Branded primitive types            |
| Events           | `on(event, listener)`         | `on(event, listener)`              |
| Errors           | Throws exceptions             | Throws exceptions                  |
| Type safety      | Basic inference               | Full inference with brands         |
| Request builders | Manual object creation        | Type-safe builder functions        |

See [Comparison](/jsonrpc-provider/comparison) for detailed differences and migration guides.

## Related

### Primitives

* [Address](/primitives/address) - 20-byte Ethereum addresses with EIP-55 checksumming
* [Keccak256](/crypto/keccak256) - 32-byte keccak256 hashes
* [Hex](/primitives/hex) - Hex-encoded byte strings
* [Transaction](/primitives/transaction) - Transaction types and encoding

### Cryptography

* [Keccak256](/crypto/keccak256) - Hashing for address derivation
* [Secp256k1](/crypto/secp256k1) - Signature verification

### Guides

* [Usage Patterns](/jsonrpc-provider/usage-patterns) - Recipe collection for common tasks
* [Comparison](/jsonrpc-provider/comparison) - vs EIP-1193, ethers, viem

## Specifications

* [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) - Ethereum Provider JavaScript API
* [ethereum/execution-apis](https://github.com/ethereum/execution-apis) - JSON-RPC specification
* [OpenRPC](https://open-rpc.org/) - JSON-RPC API description format
* [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675) - Upgrade consensus to Proof-of-Stake (Engine API)
* [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) - Shard Blob Transactions