Getting Started

Install Voltaire and start making type-safe JSON-RPC requests to Ethereum nodes.

Installation

npm install @tevm/voltaire

Creating a Provider

Use a standard EIP-1193 provider (like window.ethereum, viem, or ethers):

// From window.ethereum (MetaMask, etc.)
const provider = window.ethereum;

// From viem
import { createJsonRpcProvider } from '@tevm/voltaire/jsonrpc';
const provider = createJsonRpcProvider('https://eth.llamarpc.com');

// From ethers
import { createJsonRpcProvider } from '@tevm/voltaire/jsonrpc';
const provider = createJsonRpcProvider('https://eth.llamarpc.com');

All EIP-1193 providers work with Voltaire’s request builders.

Your First Request

Get Block Number

Simplest request - no parameters:

import * as Rpc from '@tevm/voltaire/jsonrpc';

try {
  const blockNumber = await provider.request(Rpc.Eth.BlockNumberRequest());
  console.log('Current block:', blockNumber);
} catch (error) {
  console.error('Error:', error.message);
}

Get Account Balance

Request with branded Address parameter:

import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Address } from '@tevm/voltaire/Address';

const address = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0');

try {
  const balance = await provider.request(
    Rpc.Eth.GetBalanceRequest(address, 'latest')
  );
  const balanceEth = Number(BigInt(balance)) / 1e18;
  console.log(`Balance: ${balanceEth} ETH`);
} catch (error) {
  console.error('Failed to get balance:', error);
}

Call Contract Method

Execute read-only contract call:

import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Address } from '@tevm/voltaire/Address';
import { Hex } from '@tevm/voltaire/Hex';

const contractAddress = Address('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'); // USDC
const methodSignature = Hex('0x18160ddd'); // totalSupply()

try {
  const result = await provider.request(
    Rpc.Eth.CallRequest({
      to: contractAddress,
      data: methodSignature
    }, 'latest')
  );
  const totalSupply = BigInt(result);
  console.log('Total supply:', totalSupply);
} catch (error) {
  console.error('Call failed:', error);
}

Error Handling

Requests throw errors on failure:

import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Address } from '@tevm/voltaire/Address';

const address = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0');

try {
  const balance = await provider.request(
    Rpc.Eth.GetBalanceRequest(address, 'latest')
  );
  console.log('Balance:', balance);
} catch (error) {
  // Error object contains code and message
  console.error('RPC error:', error.code, error.message);
}

Subscribing to Events

Subscribe to blockchain events using EventEmitter pattern:

// Subscribe to new blocks
provider.on('accountsChanged', (accounts) => {
  console.log('Accounts changed:', accounts);
});

provider.on('chainChanged', (chainId) => {
  console.log('Chain changed:', chainId);
});

provider.on('connect', (connectInfo) => {
  console.log('Connected to chain:', connectInfo.chainId);
});

provider.on('disconnect', (error) => {
  console.log('Disconnected:', error);
});

Unsubscribe

Remove event listeners:

const handler = (accounts) => {
  console.log('Accounts:', accounts);
};

provider.on('accountsChanged', handler);

// Later, remove listener
provider.removeListener('accountsChanged', handler);

Common Patterns

Check Account State

Get balance, nonce, and code in parallel:

import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Address } from '@tevm/voltaire/Address';

const address = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0');

try {
  const [balance, nonce, code] = await Promise.all([
    provider.request(Rpc.Eth.GetBalanceRequest(address, 'latest')),
    provider.request(Rpc.Eth.GetTransactionCountRequest(address, 'latest')),
    provider.request(Rpc.Eth.GetCodeRequest(address, 'latest'))
  ]);

  console.log('Balance:', balance);
  console.log('Nonce:', nonce);
  console.log('Is contract:', code !== '0x');
} catch (error) {
  console.error('Failed to fetch account state:', error);
}

Estimate Gas for Transaction

import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Address } from '@tevm/voltaire/Address';
import { Hex } from '@tevm/voltaire/Hex';

try {
  const gasEstimate = await provider.request(
    Rpc.Eth.EstimateGasRequest({
      from: Address('0x...'),
      to: Address('0x...'),
      value: '0x0',
      data: Hex('0xa9059cbb...') // transfer(address,uint256)
    })
  );

  const gas = BigInt(gasEstimate);
  console.log('Estimated gas:', gas);

  // Add 20% buffer
  const gasLimit = gas * 120n / 100n;
  console.log('Recommended gas limit:', gasLimit);
} catch (error) {
  console.error('Gas estimation failed:', error);
}

Query Historical State

Use block numbers to query historical data:

import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Address } from '@tevm/voltaire/Address';

const address = Address('0x...');
const blockNumber = '0xF4240'; // Block 1,000,000

try {
  const balance = await provider.request(
    Rpc.Eth.GetBalanceRequest(address, blockNumber)
  );
  console.log('Balance at block 1M:', balance);
} catch (error) {
  console.error('Failed to query historical state:', error);
}

Next Steps

Method API

Learn about method calls, parameters, and response handling.

Type System

Understand auto-generated types and branded primitives.

Events

Master async generator subscriptions for real-time updates.

Usage Patterns

Explore recipes for common blockchain interaction patterns.

Troubleshooting

”Type ‘string’ is not assignable to type ‘Address’”

Use branded primitive constructors:

import * as Rpc from '@tevm/voltaire/jsonrpc';
import { Address } from '@tevm/voltaire/Address';

// ❌ Error: string not assignable to Address
const badReq = Rpc.Eth.GetBalanceRequest('0x...', 'latest');

// ✅ Correct: use Address constructor
const goodReq = Rpc.Eth.GetBalanceRequest(Address('0x...'), 'latest');

Request returns RequestArguments not result

Request builders return {method, params} objects, not results. Always use with provider.request():

import * as Rpc from '@tevm/voltaire/jsonrpc';

// ❌ Wrong: request builder doesn't execute anything
const request = Rpc.Eth.BlockNumberRequest();
console.log(request); // { method: 'eth_blockNumber', params: [] }

// ✅ Correct: send through provider
const result = await provider.request(request);
console.log(result); // '0x112a880'

Method API - Detailed method documentation
eth Methods - All 40 eth namespace methods
Events - Event handling patterns
Address - Address primitive documentation
Hex - Hex primitive documentation

Documentation Index

​Getting Started

​Installation

​Creating a Provider

​Your First Request

​Get Block Number

​Get Account Balance

​Call Contract Method

​Error Handling

​Subscribing to Events

​Unsubscribe

​Common Patterns

​Check Account State

​Estimate Gas for Transaction

​Query Historical State

​Next Steps