ethereum.muir_glacier.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:
29
    """
30
    Add a bloom entry to the bloom filter (`bloom`).
31
32
    The number of hash functions used is 3. They are calculated by taking the
33
    least significant 11 bits from the first 3 16-bit words of the
34
    `keccak_256()` hash of `bloom_entry`.
35
36
    Parameters
37
    ----------
38
    bloom :
39
        The bloom filter.
40
    bloom_entry :
41
        An entry which is to be added to bloom filter.
42
    """
43
    hash = keccak256(bloom_entry)
44
45
    for idx in (0, 2, 4):
46
        # Obtain the least significant 11 bits from the pair of bytes
47
        # (16 bits), and set this bit in bloom bytearray.
48
        # The obtained bit is 0-indexed in the bloom filter from the least
49
        # significant bit to the most significant bit.
50
        bit_to_set = Uint.from_be_bytes(hash[idx : idx + 2]) & 0x07FF
51
        # Below is the index of the bit in the bytearray (where 0-indexed
52
        # byte is the most significant byte)
53
        bit_index = 0x07FF - bit_to_set
54
55
        byte_index = bit_index // 8
56
        bit_value = 1 << (7 - (bit_index % 8))
57
        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:
61
    """
62
    Obtain the logs bloom from a list of log entries.
63
64
    The address and each topic of a log are added to the bloom filter.
65
66
    Parameters
67
    ----------
68
    logs :
69
        List of logs for which the logs bloom is to be obtained.
70
71
    Returns
72
    -------
73
    logs_bloom : `Bloom`
74
        The logs bloom obtained which is 256 bytes with some bits set as per
75
        the caller address and the log topics.
76
    """
77
    bloom: bytearray = bytearray(b"\x00" * 256)
78
79
    for log in logs:
80
        add_to_bloom(bloom, log.address)
81
        for topic in log.topics:
82
            add_to_bloom(bloom, topic)
83
84
    return Bloom(bloom)