Logs Proof

A Logs Proof verifies that specific log entries, returned by eth_getLogs, are correctly included within transaction receipts of a verified execution block.

1. Transaction Root Calculation: For each transaction producing a log entry, the transaction payload is used to compute its SSZ hash tree root.

2. Execution Payload Proof: An SSZ Merkle proof is constructed, linking the transactions field within the ExecutionPayload to the blockBodyRoot. The total proof depth for this structure is 29.

3. Consensus Reference: The BeaconBlockHeader is included in the proof to provide the slot information. This identifies which sync committee is responsible for signing the corresponding block root.

4. Sync Committee Signature: The BLS aggregate signature of the following block’s sync committee is verified against the SignData that includes the block hash. The signing domain is derived from the fork version and the Genesis Validator Root. Successful verification confirms that the block—and therefore all contained receipts and logs—is part of the canonical chain.

Each log proof must reference its corresponding receipt proof, ensuring that every verified log entry is linked to a valid transaction and included in a verified execution block.

This Proof is used for the following RPC-Methods:

• eth_getLogs - currently everthing except the logIndex is verified

• eth_verifyLogs

• eth_getLogs - currently everthing except the logIndex is verified

• eth_verifyLogs

EthLogsTx

Represents one single transaction receipt with the required transaction and receipt-proof. The proof contains the raw receipt as part of its last leaf.

The Type is defined in src/chains/eth/ssz/verify_proof_types.h.

class EthLogsTx(Container):
    transaction      : Bytes[1073741824]      # the raw transaction payload
    transactionIndex : Uint32                 # the index of the transaction in the block
    proof            : List [bytes_1024, 256] # the Merkle Patricia Proof of the transaction receipt ending in the receipt root

EthLogsBlock

A single Block with its proof containing all the receipts or txs required to prove the logs.

The Type is defined in src/chains/eth/ssz/verify_proof_types.h.

class EthLogsBlock(Container):
    blockNumber  : Uint64                # the number of the execution block containing the transaction
    blockHash    : Bytes32               # the blockHash of the execution block containing the transaction
    proof        : List [bytes32, 1024]  # the multi proof of the transaction, receipt_root,blockNumber and blockHash
    header       : BeaconBlockHeader     # the header of the beacon block
    header_proof : Union [               # the proof for the correctness of the header
        EthSignatureBlockProof,          # proof by providing the signature of the sync committee
        EthHistoricBlockProof,           # proof for a historic block using the state_root of a current block
        EthHeadersBlockProof,            # proof block giving a chain of headers up to a verifiable header
        EthCheckpointProof]              # WSP anchor via LightClientBootstrap (currentSyncCommittee branch)
    txs          : List [EthLogsTx, 256] # the transactions of the block

Referenced Types

• BeaconBlockHeader

• EthSignatureBlockProof

• EthHistoricBlockProof

• EthHeadersBlockProof

• EthCheckpointProof

• EthLogsTx

EthCompletenessTx

A Logs Completeness Proof proves for a contiguous range of execution blocks [fromBlock, toBlock] that no matching log for the eth_getLogs filter was omitted. The normal Logs Proof only proves inclusion of the returned logs; this proof additionally guarantees completeness. Continuity. A single signed anchor header (the beacon block of toBlock) plus a parent_root chain of ProofHeaders down to fromBlock. Because the execution-layer blockNumber increments by exactly 1 per non-empty beacon block, an unbroken parent_root chain together with a gap-free blockNumber sequence fromBlock..toBlock guarantees that no block was skipped. Only one sync-committee BLS signature (over the anchor) is required. Per block one of two variants (covers the three scenarios of issue #128):

• BloomNegative: blockNumber + logsBloom are proven via a multi-merkle proof against the block's bodyRoot. The verifier computes the query bloom(s) from the filter and asserts that none is a bit-subset of the block's logsBloom, hence no matching log can exist in this block.

• FullReceipts: blockNumber + blockHash + receiptsRoot (and the matching transactions) are proven; all RLP receipts are delivered so the verifier rebuilds the receipts trie, compares it to the proven receiptsRoot, and filters the logs locally. An empty match set corresponds to scenario 2, a non-empty one to scenario 3 (the raw transactions provide the transaction hashes). A slim transaction entry (raw payload + index) used to reconstruct transaction hashes for matched logs; the transaction is bound to the block via the block's multi proof.

The Type is defined in src/chains/eth/ssz/verify_proof_types.h.

class EthCompletenessTx(Container):
    transaction      : Bytes[1073741824] # the raw transaction payload
    transactionIndex : Uint32            # the index of the transaction in the block

EthCompletenessBloomNegative

Bloom-negative block: proves that the query bloom is not a subset of the block's logsBloom.

The Type is defined in src/chains/eth/ssz/verify_proof_types.h.

class EthCompletenessBloomNegative(Container):
    blockNumber : Uint64              # the execution block number
    logsBloom   : ByteVector [256]    # the block's logsBloom (execution payload)
    proof       : List [bytes32, 256] # multi proof of blockNumber + logsBloom to bodyRoot

EthCompletenessFullReceipts

Full-receipts block: all receipts are delivered so the verifier rebuilds the receipts trie.

The Type is defined in src/chains/eth/ssz/verify_proof_types.h.

class EthCompletenessFullReceipts(Container):
    blockNumber : Uint64                        # the execution block number
    blockHash   : Bytes32                       # the execution block hash (for reconstructed log entries)
    receipts    : List [bytesList, 65536]       # all RLP-serialized receipts of the block
    txs         : List [EthCompletenessTx, 256] # raw transactions of the matching logs (for transactionHash)
    proof       : List [bytes32, 1024]          # multi proof of blockNumber + blockHash + receiptsRoot + matched txs to bodyRoot

Referenced Types

• EthCompletenessTx

EthLogsCompletenessProof

The main proof data for a logs completeness proof over a contiguous block range. The claim (the requested block range) comes from the RPC request, so the range endpoints are NOT carried in the proof; the verifier derives fromBlock/toBlock from the (proven) per-block payloads and binds them to the request. header is the full beacon header of the oldest block; headers is the ascending parentRoot chain up to the anchor (the newest block). The anchor's canonicity is established via the shared header_proof union (signature / header-chain / historic summaries), exactly like every other proof type -- the verifier reconstructs the anchor header from the chain and passes it to c4_verify_header. tag_proof proves the anchor's block tag for an open-ended toBlock (the same union that account proofs use): the timestamp variant (proven via tag_proof_branch against the anchor's bodyRoot) gates the latest freshness, while the checkpoint_proof variant is reserved for safe/finalized (structurally prepared; verification pending). For a pinned toBlock the none variant is used.

The Type is defined in src/chains/eth/ssz/verify_proof_types.h.

class EthLogsCompletenessProof(Container):
    header           : BeaconBlockHeader                 # full beacon header of the oldest block (parentRoot anchors the chain)
    headers          : List [ProofHeader, 4096]          # ProofHeaders ascending, one per block after the first (last == anchor)
    header_proof     : Union [                           # proof for the correctness of the reconstructed anchor header
        EthSignatureBlockProof,                          # proof by providing the signature of the sync committee
        EthHistoricBlockProof,                           # proof for a historic block using the state_root of a current block
        EthHeadersBlockProof,                            # proof block giving a chain of headers up to a verifiable header
        EthCheckpointProof]                              # WSP anchor via LightClientBootstrap (currentSyncCommittee branch)
    tag_proof        : Union [                           # anchor block-tag proof (timestamp for `latest`, checkpoint_proof for `safe`/`finalized`, none for pinned)
        None,                                            # no additional block-proof
        Bytes32,                                         # proof for the right blockhash
        Uint64,                                          # proof for the right blocknumber
        EthCallBlockContext,                             # compact header for EVM block context (multi-proof)
        Uint64,                                          # timestamp-only proof for account `latest` freshness gate
        EthStateCheckpointProof]                         # proof for `finalized` or `safe` checkpoints
    tag_proof_branch : List [bytes32, 256]               # multi proof of the tag_proof leaf (timestamp) to the anchor's bodyRoot
    blocks           : List [EthCompletenessBlock, 4096] # per-block payload ascending fromBlock..toBlock

Referenced Types

• BeaconBlockHeader

• ProofHeader

• EthSignatureBlockProof

• EthHistoricBlockProof

• EthHeadersBlockProof

• EthCheckpointProof

• EthCallBlockContext

• EthStateCheckpointProof

• EthCompletenessBlock

EthReceiptDataLog

A log entry in the receipt.

The Type is defined in src/chains/eth/ssz/verify_data_types.h.

class EthReceiptDataLog(Container):
    blockHash        : Bytes32           # the blockHash of the execution block containing the transaction
    blockNumber      : Uint64            # the number of the execution block containing the transaction
    transactionHash  : Bytes32           # the hash of the transaction
    transactionIndex : Uint32            # the index of the transaction in the block
    address          : Address           # the address of the log
    logIndex         : Uint32            # the index of the log in the transaction
    removed          : Boolean           # whether the log was removed
    topics           : List [bytes32, 8] # the topics of the log
    data             : Bytes[1073741824] # the data of the log