Skip to main content
Version: Current

General settings


The method documentation is also available inline and can be accessed via suggestions in most IDEs.

The following setters configure the global settings of EvmBatchProcessor. They return the modified instance and can be chained.

Certain configuration methods are required:

Here's how to choose the data sources depending on your use case:

setGateway(url: string | GatewaySettings)

Adds a Subsquid Network data source. The argument is either a string URL of a dataset served by a Subsquid Network gateway or

url: string // dataset URL
requestTimeout?: number // in milliseconds

See EVM datasets for public dataset URLs.

setRpcEndpoint(rpc: ChainRpc)

Adds a RPC data source. If added, it will be used for

A node RPC endpoint can be specified as a string URL or as an object:

type ChainRpc = string | {
url: string // http, https, ws and wss are supported
capacity?: number // num of concurrent connections, default 10
maxBatchCallSize?: number // default 100
rateLimit?: number // requests per second, default is no limit
requestTimeout?: number // in milliseconds, default 30_000

Setting maxBatchCallSize to 1 disables batching completely.


We recommend using private endpoints for better performance and stability of your squids. For Subsquid Cloud deployments you can use the RPC proxy. If you use an external private RPC, keep the endpoint URL in a Cloud secret.

setDataSource(ds: {archive?: string, chain?: ChainRpc}) (deprecated)

Replaced by setGateway() and setRpcEndpoint().

setRpcDataIngestionSetting(settings: RpcDataIngestionSettings)

Specify the RPC ingestion settings.

type RpcDataIngestionSettings = {
disabled?: boolean
preferTraceApi?: boolean
useDebugApiForStateDiffs?: boolean
debugTraceTimeout?: string
headPollInterval?: number
newHeadTimeout?: number


  • disabled: Explicitly disables data ingestion from an RPC endpoint.
  • preferTraceApi: By default, debug_traceBlockByHash is used to obtain call traces. This flag instructs the processor to utilize trace_ methods instead. This setting is only effective for finalized blocks.
  • useDebugApiForStateDiffs: By default, trace_replayBlockTransactions is used to obtain state diffs for finalized blocks. This flag instructs the processor to utilize debug_traceBlockByHash instead. This setting is only effective for finalized blocks. WARNING: this will significantly increase the amount of data retrieved from the RPC endpoint. Expect download rates in the megabytes per second range.
  • debugTraceTimeout: If set, the processor will pass the timeout parameter to debug trace config.
  • headPollInterval: Poll interval for new blocks in milliseconds. Poll mechanism is used to get new blocks via HTTP connections. Default: 5000.
  • newHeadTimeout: When ingesting from a websocket, this setting specifies the timeout in milliseconds after which the connection will be reset and subscription re-initiated if no new blocks were received. Default: no timeout.

setFinalityConfirmation(nBlocks: number)

Sets the number of blocks after which the processor will consider the consensus data final. Use a value appropriate for your network. For example, for Ethereum mainnet a widely cited value is 15 minutes/75 blocks.

setBlockRange({from: number, to?: number})

Limits the range of blocks to be processed. When the upper bound is specified, processor will terminate with exit code 0 once it reaches it.

Note that block ranges can also be specified separately for each data request. This method sets global bounds for all block ranges in the configuration.

includeAllBlocks(range?: {from: number, to?: number})

By default, processor will fetch only blocks which contain requested items. This method modifies such behavior to fetch all chain blocks. Optionally a range of blocks can be specified for which the setting should be effective.

setPrometheusPort(port: string | number)

Sets the port for a built-in prometheus health metrics server (serving at http://localhost:${port}/metrics). By default, the value of PROMETHEUS_PORT environment variable is used. When it is not set, processor will pick an ephemeral port.