ethereum.berlin.bloomethereum.london.bloom

Ethereum Logs Bloom ^^^^^^^^^^^^^^^^^^^

.. contents:: Table of Contents :backlinks: none :local:

Introduction

This modules defines functions for calculating bloom filters of logs. For the general theory of bloom filters see e.g. Wikipedia <https://en.wikipedia.org/wiki/Bloom_filter>_. Bloom filters are used to allow for efficient searching of logs by address and/or topic, by rapidly eliminating blocks and receipts from their search.

add_to_bloom

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:
31
    """
32
    Add a bloom entry to the bloom filter (`bloom`).
33
34
    The number of hash functions used is 3. They are calculated by taking the
35
    least significant 11 bits from the first 3 16-bit words of the
36
    `keccak_256()` hash of `bloom_entry`.
37
38
    Parameters
39
    ----------
40
    bloom :
41
        The bloom filter.
42
    bloom_entry :
43
        An entry which is to be added to bloom filter.
44
    """
45
    hash = keccak256(bloom_entry)
46
47
    for idx in (0, 2, 4):
48
        # Obtain the least significant 11 bits from the pair of bytes
49
        # (16 bits), and set this bit in bloom bytearray.
50
        # The obtained bit is 0-indexed in the bloom filter from the least
51
        # significant bit to the most significant bit.
52
        bit_to_set = Uint.from_be_bytes(hash[idx : idx + 2]) & Uint(0x07FF)
53
        # Below is the index of the bit in the bytearray (where 0-indexed
54
        # byte is the most significant byte)
55
        bit_index = 0x07FF - int(bit_to_set)
56
57
        byte_index = bit_index // 8
58
        bit_value = 1 << (7 - (bit_index % 8))
59
        bloom[byte_index] = bloom[byte_index] | bit_value

logs_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 : Bloom The logs bloom obtained which is 256 bytes with some bits set as per the caller address and the log topics.

def logs_bloom(​logs: Tuple[Log, ...]​) -> Bloom:
63
    """
64
    Obtain the logs bloom from a list of log entries.
65
66
    The address and each topic of a log are added to the bloom filter.
67
68
    Parameters
69
    ----------
70
    logs :
71
        List of logs for which the logs bloom is to be obtained.
72
73
    Returns
74
    -------
75
    logs_bloom : `Bloom`
76
        The logs bloom obtained which is 256 bytes with some bits set as per
77
        the caller address and the log topics.
78
    """
79
    bloom: bytearray = bytearray(b"\x00" * 256)
80
81
    for log in logs:
82
        add_to_bloom(bloom, log.address)
83
        for topic in log.topics:
84
            add_to_bloom(bloom, topic)
85
86
    return Bloom(bloom)