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