EVM RPC data source

EvmRpcDataSourceBuilder builds a data source that ingests EVM data from any JSON-RPC endpoint. It is the RPC counterpart of the EVM Portal stream: the query surface (setFields, addLog, addTransaction, addTrace, addStateDiff, includeAllBlocks, addQuery) is identical, and the built source runs anywhere a Portal source does — including run() and Processor and the EVM fallback data source. The only difference is setRpc(...) in place of setPortal(...). Use it when a Portal dataset is not available for your network, or as a standby source behind a Portal primary — see High availability.

Install

npm i @subsquid/squid-sdk @subsquid/evm-rpc @subsquid/evm-normalization

@subsquid/evm-rpc and @subsquid/evm-normalization are optional peers of the SDK package — required only when an RPC source is used.

Complete example

import {run} from '@subsquid/squid-sdk/processor'
import {EvmRpcDataSourceBuilder} from '@subsquid/squid-sdk/evm/rpc'

const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
const TRANSFER = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'

const dataSource = new EvmRpcDataSourceBuilder()
  .setRpc({
    url: process.env.RPC_URL!,
    network: 'ethereum-mainnet',
  })
  .setFields({log: {address: true, topics: true, data: true}})
  .addLog({
    where: {address: [USDC], topic0: [TRANSFER]},
    range: {from: 18_000_000},
  })
  .build()

run(dataSource, db, async (ctx) => {
  // Same handler context as with a Portal source.
})

`setRpc(options)`

Accepts a bare endpoint URL string, or an options object:

Option	Meaning
`url`	JSON-RPC endpoint URL (required)
`network`	Known network slug or chainId — selects the per-network preset (block validation, trace/debug method choice)
`rpc`	Explicit validation/finality overrides, merged over the preset
`method`	Explicit trace/stateDiff method overrides, merged over the preset
`capacity`	Max concurrent requests
`rateLimit`	Requests per second cap
`strideSize`	Blocks per ingestion stride
`strideConcurrency`	Concurrent strides

Network presets

Setting network to a known slug (or its chainId) enables block validation and selects the right trace/debug methods for that chain, so the produced dataset matches what the Portal serves: ethereum-mainnet, optimism-mainnet, base-mainnet, arbitrum-one, gnosis-mainnet, polygon-mainnet, cronos-mainnet Known slugs are offered in TypeScript autocomplete. Any other slug or chainId is accepted but runs without a preset.

With no matching preset and no explicit rpc/method overrides, block validation is disabled and dataset parity with the Portal is not guaranteed — the source logs a warning at build time. Supplying your own rpc/method overrides counts as taking ownership of the per-chain configuration and silences the warning.

Query methods

setFields, setBlockRange, addLog, addTransaction, addTrace, addStateDiff, includeAllBlocks, and addQuery behave exactly as on the Portal builder — see the EVM Portal stream reference for the full query surface.

`build()`

Returns an EVM data source with the standard interface (getHead, getFinalizedHead, getStream, getFinalizedStream). Pass it to run() or Processor, use it as a downstream source of an EVM fallback, or consume the stream directly. Throws if setRpc(...) was not called.

Overview

Pipes SDK

Squid SDK

Alternative clients

Install

Complete example

`setRpc(options)`

Network presets

Query methods

`build()`

​Install

​Complete example

​setRpc(options)

​Network presets

​Query methods

​build()

Install

Complete example

`setRpc(options)`

Network presets

Query methods

`build()`