> 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/proofs/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. **Execution Block:** The execution block is verified via `ETH_EL_PROOF_UNION` (`c4_verify_block`). This yields a verified RLP EL header and its keccak `blockHash`.
2. **Receipt Inclusion:** For each transaction that produced a matching log, a Patricia Merkle proof against the header's `receiptsRoot` delivers the raw receipt (the leaf).
3. **Transaction Binding:** A Patricia Merkle proof against the header's `transactionsRoot` delivers the raw transaction (used for `transactionHash` and sender recovery).
4. **Log Matching:** Each returned log is checked against the decoded receipt logs (`transactionIndex`, `logIndex`, topics, data, address) and bound to the verified `blockHash` / `blockNumber`.

Completeness (that no matching log was omitted over a block range) is a separate proof, see `LogsCompletenessProof` below.

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)
* [eth\_verifyLogs](https://www.alchemy.com/docs/node/op-mainnet/op-mainnet-api-endpoints/eth-verify-logs)

## EthLogsCompletenessProof

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.** The newest block (`toBlock`) is proven via the shared `ETH_EL_PROOF_UNION` (`c4_verify_block`), which yields a verified RLP execution header and its keccak `blockHash`. Every older block in the range is a raw RLP header chained by `parentHash`: `keccak(headers[i]) == parentHash(headers[i+1])` (and `keccak(headers[last]) == parentHash(anchor)`), together with a gap-free `blockNumber` sequence `fromBlock..toBlock`. No execution-payload SSZ proof is required; `logsBloom`, `receiptsRoot`, `transactionsRoot`, `blockNumber` and `timestamp` are fields of the EL header. **Per block** one of two variants (covers the three scenarios of issue #128):

* `NONE`: the header's `logsBloom` is proven by the parentHash chain. 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.
* `FullReceipts`: all RLP receipts are delivered so the verifier rebuilds the receipts trie and compares it to the header's `receiptsRoot`, then filters the logs locally. Matching transactions are bound via Patricia proofs against the header's `transactionsRoot` (the leaf is the raw tx, used for `transactionHash`). 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 EL headers and binds them to the request. For an open-ended `toBlock` (`latest`) the freshness gate reads the anchor header's `timestamp`. CompletenessTx is LogsTx without `receiptProof`: receipts are delivered in full. The Patricia leaf of `transactionProof` is the raw transaction (for transactionHash).

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#L356).

```python
class EthLogsCompletenessProof(Container):
    elProof : Union [                  # proof for the newest execution block (toBlock / anchor)
        Bytes32,                       # 0: cached: verifier already holds this verified EL header
        EthClHeaderProof,              # 1: full consensus-layer proof of the EL header
        EthSequencerProof,             # 2: sequencer-signed execution payload (OP-Stack)
        EthWitnessHeaderProof]         # 3: reserved; c4_verify_block rejects until ecrecover+allow-list exist
    headers : ProgList [bytesList]     # RLP EL headers ascending fromBlock .. toBlock-1 (parentHash chain)
    blocks  : List [ Union [           # per-block payload ascending fromBlock..toBlock (NONE or FullReceipts)
        None,                          # 0: no matching log possible (bloom check against the EL header)
        EthCompletenessFullReceipts] ] # 1: all receipts delivered, filtered locally
```

**Referenced Types**

* [EthClHeaderProof](/specification-colibri-stateless/specifications/ethereum/proofs/consensus-layer-header-proof.md#ethclheaderproof)
* [EthSequencerProof](/specification-colibri-stateless/specifications/ethereum/proofs/execution-layer-header-proof.md#ethsequencerproof)
* [EthWitnessHeaderProof](/specification-colibri-stateless/specifications/ethereum/proofs/execution-layer-header-proof.md#ethwitnessheaderproof)

## 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#L312).

```python
class EthCompletenessFullReceipts(Container):
    receipts         : ProgList [bytesList] # all RLP-serialized receipts of the block
    transactionProof : ProgList [bytesList] # Multi Patricia Merkle Proof which contains all nodes of the tries used by all the txs.
    txs              : ProgList [uint32Def] # index of the matching txs, bound via Multi Patricia proofs against transactionsRoot
```

## 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#L301).

```python
class EthLogsBlock(Container):
    blockNumber      : Uint64                # the execution block number
    transactionProof : ProgList [bytesList]  # the Patricia Merkle Proof of the transaction, the leaf contains the raw transaction.
    receiptProof     : ProgList [bytes_1024] # the Multi Patricia Merkle Proof of the receipt, the leaf contains the raw receipt.
    txs              : ProgList [EthLogsTx]  # the transactions used by the resulting events
    elProof          : Union [               # the proof for the execution block containing the transaction
        Bytes32,                             # 0: cached: verifier already holds this verified EL header
        EthClHeaderProof,                    # 1: full consensus-layer proof of the EL header
        EthSequencerProof,                   # 2: sequencer-signed execution payload (OP-Stack)
        EthWitnessHeaderProof]               # 3: reserved; c4_verify_block rejects until ecrecover+allow-list exist
```

**Referenced Types**

* [EthLogsTx](#ethlogstx)
* [EthClHeaderProof](/specification-colibri-stateless/specifications/ethereum/proofs/consensus-layer-header-proof.md#ethclheaderproof)
* [EthSequencerProof](/specification-colibri-stateless/specifications/ethereum/proofs/execution-layer-header-proof.md#ethsequencerproof)
* [EthWitnessHeaderProof](/specification-colibri-stateless/specifications/ethereum/proofs/execution-layer-header-proof.md#ethwitnessheaderproof)

## 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#L294).

```python
class EthLogsTx(Container):
    logIndex         : Uint32 # the logIndex within the block for the first event of the tx (can only be verified with all previous receipts, which is not the case today)
    transactionIndex : Uint32 # the index of the transaction in the block
```

## 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#L138).

```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           : ProgList [bytes32] # the topics of the log
    data             : Bytes[1073741824]  # the data of the log
```