EVM data reference

This page contains reference about the available data in EVM DNA streams.

Related pages

• EVM data filter reference

All filters have an associated ID. To help clients correlate filters with data, the filter ID is included in the filterIds field of all data objects. This field contains the list of all filter IDs that matched a piece of data.

Important: most fields are nullable to allow evolving the protocol. You should always assert the presence of a field for critical indexers.

The @apibara/evm package defines the following scalar types:

• Address: a 20-byte Ethereum address, represented as a 0x${string} type.
• B256: a 32-byte Ethereum value, represented as a 0x${string} type.
• Bytes: arbitrary length bytes, represented as a 0x${string} type.

Most types are compatible with viem. For example, you can decode logs with the following code:

import type { B256 } from "@apibara/evm";
import { decodeEventLog, parseAbi } from "viem";

const abi = parseAbi([
  "event Transfer(address indexed from, address indexed to, uint256 value)",
]);

// Somewhere in your indexer...
for (const log of logs) {
  const { args, eventName } = decodeEventLog({
    abi,
    topics: log.topics as [B256, ...B256[]],
    data: log.data,
  });
}

Block

The root object is the Block.

export type Block = {
  header?: BlockHeader;
  logs: Log[];
  transactions: Transaction[];
  receipts: TransactionReceipt[];
  withdrawals: Withdrawal[];
};

Header

This is the block header, which contains information about the block.

export type Bloom = Bytes;

export type BlockHeader = {
  blockNumber?: bigint;
  blockHash?: B256,
  parentBlockHash?: B256;
  unclesHash?: B256;
  miner?: Address;
  stateRoot?: B256;
  transactionsRoot?: B256;
  receiptsRoot?: B256;
  logsBloom?: Bloom;
  difficulty?: bigint;
  gasLimit?: bigint;
  gasUsed?: bigint;
  timestamp?: Date;
  extraData?: Bytes;
  mixHash?: B256;
  nonce?: bigint;
  baseFeePerGas?: bigint;
  withdrawalsRoot?: B256;
  totalDifficulty?: bigint;
  blobGasUsed?: bigint;
  excessBlobGas?: bigint;
  parentBeaconBlockRoot?: B256;
};

Properties

• blockNumber: the block number.
• blockHash: the block hash.
• parentBlockHash: the block hash of the parent block.
• unclesHash: the block hash of the uncles.
• miner: the address of the miner.
• stateRoot: the state root.
• transactionsRoot: the transactions root.
• receiptsRoot: the receipts root.
• logsBloom: the logs bloom.
• difficulty: the block difficulty.
• gasLimit: the block gas limit.
• gasUsed: the gas used by transactions in the block.
• timestamp: the block timestamp.
• extraData: extra bytes data picked by the miner.
• mixHash: the mix hash.
• nonce: the nonce.
• baseFeePerGas: the base fee per gas.
• withdrawalsRoot: the withdrawals root.
• totalDifficulty: the total difficulty.
• blobGasUsed: the gas used by transactions posting blob data in the block.
• excessBlobGas: the excess blob gas.
• parentBeaconBlockRoot: the parent beacon block root.

Log

An EVM log. It comes together with the essential information about the transaction that emitted the log.

export type Log = {
  filterIds: number[];
  address?: Address;
  topics: B256[];
  data: Bytes;
  logIndex: number;
  transactionIndex: number;
  transactionHash: B256;
  transactionStatus: "succeeded" | "reverted";
};

Properties

• address: the address of the contract that emitted the log.
• topics: the topics of the log.
• data: the data of the log.
• logIndex: the index of the log in the block.
• transactionIndex: the index of the transaction that emitted the log.
• transactionHash: the hash of the transaction that emitted the log.
• transactionStatus: the status of the transaction that emitted the log.

Relevant filters

• filter.logs
• filter.logs[].includeSiblings
• filter.transactions[].includeLogs

Transaction

An EVM transaction.

export type Transaction = {
  filterIds: number[];
  transactionIndex?: number;
  transactionHash?: B256;
  nonce?: bigint;
  from?: Address;
  to?: Address;
  value?: bigint;
  gasPrice?: bigint;
  gas?: bigint;
  maxFeePerGas?: bigint;
  maxPriorityFeePerGas?: bigint;
  input: Bytes;
  signature?: Signature;
  chainId?: bigint;
  accessList: AccessListItem[],
  transactionType?: bigint;
  maxFeePerBlobGas?: bigint;
  blobVersionedHashes?: B256[];
  transactionStatus: "succeeded" | "reverted";
};

export type Signature = {
  r?: bigint;
  s?: bigint;
  v?: bigint;
  yParity: boolean;
};

export type AccessListItem = {
  address?: Address;
  storageKeys: B256[];
};

Properties

• transactionIndex: the index of the transaction in the block.
• transactionHash: the hash of the transaction.
• nonce: the nonce of the transaction.
• from: the sender of the transaction.
• to: the recipient of the transaction. Empty if it's a create transaction.
• value: the value of the transaction, in wei.
• gasPrice: the gas price of the transaction.
• gas: the gas limit of the transaction.
• maxFeePerGas: the max fee per gas of the transaction.
• maxPriorityFeePerGas: the max priority fee per gas of the transaction.
• input: the input data of the transaction.
• signature: the signature of the transaction.
• chainId: the chain ID of the transaction.
• accessList: the access list of the transaction.
• transactionType: the transaction type.
• maxFeePerBlobGas: the max fee per blob gas of the transaction.
• blobVersionedHashes: the hashes of blobs posted by the transaction.
• transactionStatus: the status of the transaction.

Relevant filters

• filter.transactions
• filter.logs[].includeTransaction

Transaction Receipt

Information about the transaction's execution.

export type TransactionReceipt = {
  filterIds: number[];
  transactionIndex?: number;
  transactionHash?: B256;
  cumulativeGasUsed?: bigint;
  gasUsed?: bigint;
  effectiveGasPrice?: bigint;
  from?: Address;
  to?: Address;
  contractAddress?: Address;
  logsBloom?: Bloom;
  transactionType?: bigint;
  blobGasUsed?: bigint;
  blobGasPrice?: bigint;
  transactionStatus: "succeeded" | "reverted";
};

Properties

• transactionIndex: the transaction index in the block.
• transactionHash: the hash of the transaction.
• cumulativeGasUsed: the cumulative gas used by the transactions.
• gasUsed: the gas used by the transaction.
• effectiveGasPrice: the effective gas price of the transaction.
• from: the sender of the transaction.
• to: the recipient of the transaction. Empty if it's a create transaction.
• contractAddress: the address of the contract created by the transaction.
• logsBloom: the logs bloom of the transaction.
• transactionType: the transaction type.
• blobGasUsed: the gas used by the transaction posting blob data.
• blobGasPrice: the gas price of the transaction posting blob data.
• transactionStatus: the status of the transaction.

Relevant filters

• filter.transactions[].includeReceipt
• filter.logs[].includeReceipt

Withdrawal

A withdrawal from the Ethereum network.

export type Withdrawal = {
  filterIds: number[];
  withdrawalIndex?: number;
  index?: bigint;
  validatorIndex?: number;
  address?: Address;
  amount?: bigint;
};

Properties

• withdrawalIndex: the index of the withdrawal in the block.
• index: the global index of the withdrawal.
• validatorIndex: the index of the validator that created the withdrawal.
• address: the destination address of the withdrawal.
• amount: the amount of the withdrawal, in wei.

Relevant filters

• filter.withdrawals