Skip to main content

EVM Protobuf Streams

You can find the schema here.

EVM blockchains produce blocks at varying intervals depending on the network. Ethereum mainnet targets ~12 seconds per block, while other EVM chains may have different block times.

Structure of On-Chain Data​

The EVM Protobuf Streams provide three main message types for different use cases:

  • BlockMessage: Full blocks with detailed transaction traces
  • TokenBlockMessage: Focused on token transfers with currency metadata
  • DexBlockMessage: Specialized for DEX (Decentralized Exchange) trading activity

Block-Level Data​

Each block in the stream includes a BlockHeader with fields such as:

  • Hash: The unique identifier of the block
  • ParentHash: Hash of the previous block
  • Number: Block number/height in the chain
  • GasLimit: Maximum gas allowed in this block
  • GasUsed: Actual gas consumed by transactions
  • Time: Block timestamp
  • BaseFee: Base fee per gas (EIP-1559)

The BlockMessage also includes:

  • Chain: Information about the blockchain (ChainId, Config)
  • Uncles: Uncle/ommer blocks (Ethereum PoW)
  • Transactions: All transactions in the block
  • L1Header: For Layer 2 chains, information about the corresponding L1 block

Transaction-Level Data​

Transactions include:

  • TransactionHeader: Core transaction data
    • Hash: Transaction hash
    • Gas: Gas limit for this transaction
    • Value: Amount of native currency transferred
    • Data: Call data for contract interactions
    • From/To: Sender and recipient addresses
    • GasPrice, GasFeeCap, GasTipCap: Fee parameters
    • Special fields for EIP-4844 blob transactions
  • Signature: Transaction signature (R, S, V values)
  • Receipt: Execution results
    • Status: Success or failure
    • GasUsed: Actual gas consumed
    • Logs: Event logs emitted
  • Trace: Detailed execution trace
    • Calls: Internal contract calls
    • CaptureStates: State modifications

Token Data​

The TokenBlockMessage stream provides information about token transfers:

  • TokenTransfer: Records token movements with:

    • Sender: Address sending tokens
    • Receiver: Address receiving tokens
    • Amount: Amount of tokens transferred
    • Id: Token ID (for non-fungible tokens)
    • Currency: Detailed token information
    • Success: Whether the transfer succeeded

  • TokenInfo: Metadata about each token:

    • SmartContract: Token contract address
    • Name: Token name
    • Symbol: Token symbol
    • Decimals: Token decimal places
    • Fungible: Whether token is fungible (ERC-20) or non-fungible (ERC-721/1155)

DEX (Decentralized Exchange) Data​

The DexBlockMessage stream specializes in DEX trading activity:

  • DexTrade: Records of trades executed on DEXs

    • Buy/Sell: Both sides of the trade
    • Dex: Information about the exchange
    • Success: Whether the trade succeeded
    • Fees: Trading fees paid

  • DexInfo: Details about the exchange:

    • SmartContract: Exchange contract address
    • ProtocolName: Name of the protocol (e.g., "Uniswap", "SushiSwap")
    • ProtocolFamily: Family of DEX protocols
    • ProtocolVersion: Version of the protocol
    • Pair: Trading pair information

  • TradeSide: Details about each side of a trade:

    • Buyer/Seller: Addresses involved
    • OrderId: Identifier for the order
    • Assets: What was traded

Layer 2 Support​

EVM Protobuf Streams provide dedicated fields for Layer 2 chains:

  • L1Header: Corresponding L1 block information
  • Optimism-specific fields: SequenceNumber, BatcherAddr, L1FeeOverhead, etc.
  • Arbitrum-specific fields: GasL1 for L1 data costs

Using This Stream in Python, JavaScript, and Go​

Python, JavaScript, and Go code samples can be used with these streams by changing the topic to one of:

  • eth.transactions.proto
  • eth.tokens.proto
  • eth.dextrades.proto
  • eth.raw.proto (for raw block data)
  • eth.broadcasted.transactions.proto (for broadcasted transactions)
  • eth.broadcasted.tokens.proto (for broadcasted token transfers)
  • eth.broadcasted.dextrades.proto (for broadcasted DEX trades)
  • eth.broadcasted.raw.proto (for raw broadcasted block data)

The Python package bitquery-pb2-kafka-package includes all schema and is up to date so you don't have to manually install schema files.

Video Tutorial to Track Deposits and Withdrawals for Exchange Wallets Using Kafka​

Video Tutorial to Get Latest Four Meme Trades Using Kafka​