Documentation Index
Fetch the complete documentation index at: https://beta.docs.sqd.dev/llms.txt
Use this file to discover all available pages before exploring further.
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
}
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):
| 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. |
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.
See also
