Ethereum Logs Bloom

Table of Contents

Introduction
Module Contents
- Functions
Module Details
- add_to_bloom
- logs_bloom

Introduction

This modules defines functions for calculating bloom filters of logs. For the general theory of bloom filters see e.g. Wikipedia. Bloom filters are used to allow for efficient searching of logs by address and/or topic, by rapidly eliminating blocks and reciepts from their search.

Module Contents

Functions

`add_to_bloom`	Add a bloom entry to the bloom filter (bloom).
`logs_bloom`	Obtain the logs bloom from a list of log entries.

Module Details

add_to_bloom

add_to_bloom(bloom: bytearray, bloom_entry: bytes) → None

Add a bloom entry to the bloom filter (bloom).

The number of hash functions used is 3. They are calculated by taking the least significant 11 bits from the first 3 16-bit words of the keccak_256() hash of bloom_entry.

Parameters

bloom – The bloom filter.
bloom_entry – An entry which is to be added to bloom filter.

def add_to_bloom(bloom: bytearray, bloom_entry: bytes) -> None:
    hash = keccak256(bloom_entry)

    for idx in (0, 2, 4):
        # Obtain the least significant 11 bits from the pair of bytes
        # (16 bits), and set this bit in bloom bytearray.
        # The obtained bit is 0-indexed in the bloom filter from the least
        # significant bit to the most significant bit.
        bit_to_set = Uint.from_be_bytes(hash[idx : idx + 2]) & 0x07FF
        # Below is the index of the bit in the bytearray (where 0-indexed
        # byte is the most significant byte)
        bit_index = 0x07FF - bit_to_set

        byte_index = bit_index // 8
        bit_value = 1 << (7 - (bit_index % 8))
        bloom[byte_index] = bloom[byte_index] | bit_value

logs_bloom

logs_bloom(logs: Tuple[ethereum.berlin.fork_types.Log, Ellipsis]) → ethereum.berlin.fork_types.Bloom 

Obtain the logs bloom from a list of log entries.

The address and each topic of a log are added to the bloom filter.

Parameters: logs – List of logs for which the logs bloom is to be obtained.
Returns: logs_bloom – The logs bloom obtained which is 256 bytes with some bits set as per the caller address and the log topics.
Return type: Bloom

def logs_bloom(logs: Tuple[Log, ...]) -> Bloom:
    bloom: bytearray = bytearray(b"\x00" * 256)

    for log in logs:
        add_to_bloom(bloom, log.address)
        for topic in log.topics:
            add_to_bloom(bloom, topic)

    return Bloom(bloom)