Ethereum 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.frontier.eth_types.Log, Ellipsis])ethereum.frontier.eth_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)