> For the complete documentation index, see [llms.txt](https://corpus-core.gitbook.io/specification-colibri-stateless/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/logs-proof.md).

# 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](https://www.alchemy.com/docs/node/ethereum/ethereum-api-endpoints/eth-get-logs) - currently everthing except the logIndex is verified
* [eth\_verifyLogs](https://www.alchemy.com/docs/node/ethereum/ethereum-api-endpoints/eth-verify-logs)
* [eth\_getLogs](https://www.alchemy.com/docs/node/op-mainnet/op-mainnet-api-endpoints/eth-get-logs) - currently everthing except the logIndex is verified
* [eth\_verifyLogs](https://www.alchemy.com/docs/node/op-mainnet/op-mainnet-api-endpoints/eth-verify-logs)

## 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](https://github.com/corpus-core/colibri-stateless/blob/dev/src/chains/eth/ssz/verify_proof_types.h#L225).

```python
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](https://github.com/corpus-core/colibri-stateless/blob/dev/src/chains/eth/ssz/verify_proof_types.h#L233).

```python
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](https://ethereum.github.io/consensus-specs/specs/phase0/beacon-chain/#beaconblockheader)
* [EthSignatureBlockProof](/specification-colibri-stateless/specifications/ethereum/header-proof.md#ethsignatureblockproof)
* [EthHistoricBlockProof](https://github.com/corpus-core/colibri-stateless-doc/tree/main/specification/specifications/ethereum/historic-block-proof.md#ethhistoricblockproof)
* [EthHeadersBlockProof](https://github.com/corpus-core/colibri-stateless-doc/tree/main/specification/specifications/ethereum/historic-block-proof.md#ethheadersblockproof)
* [EthCheckpointProof](/specification-colibri-stateless/specifications/ethereum/header-proof.md#ethcheckpointproof)
* [EthLogsTx](#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 `ProofHeader`s 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](https://github.com/corpus-core/colibri-stateless/blob/dev/src/chains/eth/ssz/verify_proof_types.h#L269).

```python
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](https://github.com/corpus-core/colibri-stateless/blob/dev/src/chains/eth/ssz/verify_proof_types.h#L276).

```python
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](https://github.com/corpus-core/colibri-stateless/blob/dev/src/chains/eth/ssz/verify_proof_types.h#L283).

```python
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](#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](https://github.com/corpus-core/colibri-stateless/blob/dev/src/chains/eth/ssz/verify_proof_types.h#L313).

```python
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](https://ethereum.github.io/consensus-specs/specs/phase0/beacon-chain/#beaconblockheader)
* [ProofHeader](https://github.com/corpus-core/colibri-stateless-doc/tree/main/specification/specifications/ethereum/historic-block-proof.md#proofheader)
* [EthSignatureBlockProof](/specification-colibri-stateless/specifications/ethereum/header-proof.md#ethsignatureblockproof)
* [EthHistoricBlockProof](https://github.com/corpus-core/colibri-stateless-doc/tree/main/specification/specifications/ethereum/historic-block-proof.md#ethhistoricblockproof)
* [EthHeadersBlockProof](https://github.com/corpus-core/colibri-stateless-doc/tree/main/specification/specifications/ethereum/historic-block-proof.md#ethheadersblockproof)
* [EthCheckpointProof](/specification-colibri-stateless/specifications/ethereum/header-proof.md#ethcheckpointproof)
* [EthCallBlockContext](/specification-colibri-stateless/specifications/ethereum/account-proof.md#ethcallblockcontext)
* [EthStateCheckpointProof](/specification-colibri-stateless/specifications/ethereum/account-proof.md#ethstatecheckpointproof)
* EthCompletenessBlock

## EthReceiptDataLog

A log entry in the receipt.

The Type is defined in [src/chains/eth/ssz/verify\_data\_types.h](https://github.com/corpus-core/colibri-stateless/blob/dev/src/chains/eth/ssz/verify_data_types.h#L133).

```python
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
```