Query builder

EvmQueryBuilder assembles a typed portal query from a field selection and one or more data-request clauses. Pass .build() to outputs (or to .pipe()) on an EVM source. The resulting object is consumed by evmPortalStream() and by the evmDecoder which composes on top of it.

`evmQuery()`

Returns a fresh EvmQueryBuilder.

import { evmQuery } from '@subsquid/pipes/evm'

const query = evmQuery()
  .addFields({
    block: { timestamp: true },
    log: { address: true, topics: true, data: true },
  })
  .addLog({
    range: { from: 20_000_000 },
    request: { topic0: ['0xddf252ad…'] },
  })
  .build()

`EvmQueryBuilder<F>`

class EvmQueryBuilder<F extends FieldSelection = {}> {
  addFields<T>(fields: Subset<T, FieldSelection>): EvmQueryBuilder<F & T>
  addLog(options: RequestOptions<LogRequest>): this
  addTransaction(options: RequestOptions<TransactionRequest>): this
  addTrace(options: RequestOptions<TraceRequest>): this
  addStateDiff(options: RequestOptions<StateDiffRequest>): this
  addRange(range: PortalRange): this
  merge(other?: EvmQueryBuilder<F>): this
  build(opts?: { setupQuery?: SetupQueryFn<EvmQueryBuilder<F>> }): QueryAwareTransformer
}

The generic parameter F narrows the block type produced by the stream — only fields explicitly selected with .addFields() appear on the decoded records, at both compile and runtime.

`RequestOptions<R>`

type RequestOptions<R> = { range: PortalRange; request: R }
type PortalRange = { from?: number | string | 'latest' | Date; to?: number | string | Date }

PortalRange.from defaults to 0; a Date or numeric timestamp is resolved to a block number via the portal at query start. 'latest' is resolved to the current head.

`.addFields(fields)`

Add to the field selection. Repeated calls are merged recursively. Block hash and number are returned regardless of selection.

`block`

Field	Type
`number`	`number` (always returned)
`hash`	`string` (always returned)
`parentHash`	`string`
`timestamp`	`number` (Unix seconds)
`transactionsRoot`	`string`
`receiptsRoot`	`string`
`stateRoot`	`string`
`logsBloom`	`string`
`sha3Uncles`	`string`
`extraData`	`string`
`miner`	`string`
`nonce`	`string`
`mixHash`	`string`
`size`	`number`
`gasLimit`	`bigint`
`gasUsed`	`bigint`
`difficulty`	`bigint`
`totalDifficulty`	`bigint?`
`baseFeePerGas`	`bigint`
`blobGasUsed`	`bigint`
`excessBlobGas`	`bigint`
`l1BlockNumber`	`number?` (L2 only)

`transaction`

Field	Type
`transactionIndex`	`number`
`hash`	`string`
`nonce`	`bigint`
`from`	`string`
`to`	`string?`
`input`	`string`
`value`	`bigint`
`gas`	`bigint`
`gasPrice`	`bigint`
`maxFeePerGas`	`bigint?`
`maxPriorityFeePerGas`	`bigint?`
`v`, `r`, `s`, `yParity`	`bigint`/`string`/`string`/`number?`
`chainId`	`number?`
`sighash`	`string?` (first 4 bytes of `input`)
`contractAddress`	`string?` (for create transactions)
`gasUsed`	`bigint`
`cumulativeGasUsed`	`bigint`
`effectiveGasPrice`	`bigint`
`type`	`number`
`status`	`number` (0 = fail, 1 = success)
`blobVersionedHashes`	`string[]?`
`l1Fee`, `l1FeeScalar`, `l1GasPrice`, `l1GasUsed`, `l1BlobBaseFee`, `l1BlobBaseFeeScalar`, `l1BaseFeeScalar`	L2 fee metadata

`log`

Field	Type
`logIndex`	`number`
`transactionIndex`	`number`
`transactionHash`	`string`
`address`	`string`
`data`	`string`
`topics`	`string[]`

`trace`

Trace records are a tagged union over type. Each type has its own action and (optionally) result sub-objects; the field selection is flat with create…/call…/suicide…/reward… prefixes. Shared:

Field	Type
`type`	`'create' \| 'call' \| 'suicide' \| 'reward'`
`transactionIndex`	`number`
`traceAddress`	`number[]`
`subtraces`	`number`
`error`	`string \| null`
`revertReason`	`string?`

Type-specific (appears only on that trace type):

Field	Action/result	Type
`createFrom`, `createValue`, `createGas`, `createInit`	create action	`string` / `bigint` / `bigint` / `string`
`createResultGasUsed`, `createResultCode`, `createResultAddress`	create result	`bigint` / `string?` / `string`
`callCallType`, `callFrom`, `callTo`, `callValue`, `callGas`, `callInput`, `callSighash`	call action	`string` / `string` / `string` / `bigint?` / `bigint` / `string` / `string?`
`callResultGasUsed`, `callResultOutput`	call result	`bigint` / `string?`
`suicideAddress`, `suicideRefundAddress`, `suicideBalance`	suicide action	`string` / `string` / `bigint`
`rewardAuthor`, `rewardValue`, `rewardType`	reward action	`string` / `bigint` / `string`

`stateDiff`

State diffs are a tagged union over kind ('+' = add, '-' = delete, '*' = change, '=' = no-change).

Field	Type
`transactionIndex`	`number`
`address`	`string`
`key`	`'balance' \| 'code' \| 'nonce' \| string` (storage slot)
`kind`	`'+' \| '-' \| '*' \| '='`
`prev`	`string` (present for `-`, `*`)
`next`	`string` (present for `+`, `*`)

`.addLog(options)`

Filter logs. All list filters AND across fields but OR within a field. Request options:

Field	Type	Meaning
`address`	`string[]`	Emitting contract addresses (lowercase).
`topic0`	`string[]`	First topic (typically the event signature hash).
`topic1`, `topic2`, `topic3`	`string[]`	Remaining indexed topics.
`transaction`	`boolean`	Also fetch the parent transaction of each matching log.
`transactionTraces`	`boolean`	Also fetch traces of parent transactions.
`transactionLogs`	`boolean`	Also fetch all logs from parent transactions.
`transactionStateDiffs`	`boolean`	Also fetch state diffs caused by parent transactions.

An empty request: {} matches every log in the range.

evmQuery().addLog({
  range: { from: 20_000_000, to: 20_000_100 },
  request: {
    address: ['0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'],
    topic0: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
    transaction: true,
  },
})

`.addTransaction(options)`

Filter transactions.

Field	Type	Meaning
`from`	`string[]`	Sender addresses (lowercase).
`to`	`string[]`	Recipient addresses (lowercase).
`sighash`	`string[]`	First 4 bytes of `input` (e.g. `0xa9059cbb` for ERC-20 `transfer`).
`type`	`number[]`	Transaction type (0 legacy, 2 EIP-1559, 3 blob, etc.).
`logs`	`boolean`	Also fetch emitted logs.
`traces`	`boolean`	Also fetch execution traces.
`stateDiffs`	`boolean`	Also fetch state diffs.

`.addTrace(options)`

Filter execution traces.

Field	Type	Meaning
`type`	`('create' \| 'call' \| 'suicide' \| 'reward')[]`	Restrict to given trace types.
`createFrom`	`string[]`	Creator address for `create` traces.
`callFrom`	`string[]`	Caller address for `call` traces.
`callTo`	`string[]`	Callee address for `call` traces.
`callSighash`	`string[]`	`input` sighash for `call` traces.
`suicideRefundAddress`	`string[]`	Refund address for `suicide` traces.
`rewardAuthor`	`string[]`	Author of `reward` traces.
`transaction`	`boolean`	Fetch parent transactions of matching traces.
`transactionLogs`	`boolean`	Fetch all logs emitted by parent transactions.
`subtraces`	`boolean`	Fetch all subtraces of matching traces.
`parents`	`boolean`	Fetch parent traces of matching traces.

`.addStateDiff(options)`

Filter storage diffs.

Field	Type	Meaning
`address`	`string[]`	Contract or account addresses (lowercase).
`key`	`string[]`	Storage keys or pseudo-keys (`balance`, `code`, `nonce`).
`kind`	`('+' \| '-' \| '*' \| '=')[]`	Type of change.
`transaction`	`boolean`	Fetch parent transactions.

`.addRange(range)`

Push a range-only request with no filters. Mostly useful to bound the stream or in combination with includeAllBlocks set elsewhere.

evmQuery().addRange({ from: 20_000_000, to: 20_001_000 })

`.merge(other)`

Merge another builder’s requests and fields in-place. Overlapping ranges are reconciled at build time.

`.build(opts?)`

Return a QueryAwareTransformer suitable for use as a source output.

evmPortalStream({
  portal: 'https://portal.sqd.dev/datasets/ethereum-mainnet',
  outputs: { transfers: evmQuery().addLog({/*…*/}).build() },
})

opts.setupQuery is an advanced hook called when the query is finalized: it receives { query, logger } and can mutate query (e.g. merge additional requests from runtime data). Default behaviour is to merge this into the stream’s root query.

Overview

Pipes SDK

Squid SDK

Alternative clients

`evmQuery()`

`EvmQueryBuilder<F>`

`RequestOptions<R>`

`.addFields(fields)`

`block`

`transaction`

`log`

`trace`

`stateDiff`

`.addLog(options)`

`.addTransaction(options)`

`.addTrace(options)`

`.addStateDiff(options)`

`.addRange(range)`

`.merge(other)`

`.build(opts?)`

See also

​evmQuery()

​EvmQueryBuilder<F>

​RequestOptions<R>

​.addFields(fields)

​block

​transaction

​log

​trace

​stateDiff

​.addLog(options)

​.addTransaction(options)

​.addTrace(options)

​.addStateDiff(options)

​.addRange(range)

​.merge(other)

​.build(opts?)

​See also

`evmQuery()`

`EvmQueryBuilder<F>`

`RequestOptions<R>`

`.addFields(fields)`

`block`

`transaction`

`log`

`trace`

`stateDiff`

`.addLog(options)`

`.addTransaction(options)`

`.addTrace(options)`

`.addStateDiff(options)`

`.addRange(range)`

`.merge(other)`

`.build(opts?)`

See also