ethereum.byzantium.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.

View Source

 1"""
 2Ethereum Logs Bloom
 3^^^^^^^^^^^^^^^^^^^
 4
 5.. contents:: Table of Contents
 6    :backlinks: none
 7    :local:
 8
 9Introduction
10------------
11
12This modules defines functions for calculating bloom filters of logs. For the
13general theory of bloom filters see e.g. `Wikipedia
14<https://en.wikipedia.org/wiki/Bloom_filter>`_. Bloom filters are used to allow
15for efficient searching of logs by address and/or topic, by rapidly
16eliminating blocks and receipts from their search.
17"""
18
19from typing import Tuple
20
21from ethereum.base_types import Uint
22from ethereum.crypto.hash import keccak256
23
24from .fork_types import Bloom, Log
25
26
27def add_to_bloom(bloom: bytearray, bloom_entry: bytes) -> None:
28    """
29    Add a bloom entry to the bloom filter (`bloom`).
30
31    The number of hash functions used is 3. They are calculated by taking the
32    least significant 11 bits from the first 3 16-bit words of the
33    `keccak_256()` hash of `bloom_entry`.
34
35    Parameters
36    ----------
37    bloom :
38        The bloom filter.
39    bloom_entry :
40        An entry which is to be added to bloom filter.
41    """
42    hash = keccak256(bloom_entry)
43
44    for idx in (0, 2, 4):
45        # Obtain the least significant 11 bits from the pair of bytes
46        # (16 bits), and set this bit in bloom bytearray.
47        # The obtained bit is 0-indexed in the bloom filter from the least
48        # significant bit to the most significant bit.
49        bit_to_set = Uint.from_be_bytes(hash[idx : idx + 2]) & 0x07FF
50        # Below is the index of the bit in the bytearray (where 0-indexed
51        # byte is the most significant byte)
52        bit_index = 0x07FF - bit_to_set
53
54        byte_index = bit_index // 8
55        bit_value = 1 << (7 - (bit_index % 8))
56        bloom[byte_index] = bloom[byte_index] | bit_value
57
58
59def logs_bloom(logs: Tuple[Log, ...]) -> Bloom:
60    """
61    Obtain the logs bloom from a list of log entries.
62
63    The address and each topic of a log are added to the bloom filter.
64
65    Parameters
66    ----------
67    logs :
68        List of logs for which the logs bloom is to be obtained.
69
70    Returns
71    -------
72    logs_bloom : `Bloom`
73        The logs bloom obtained which is 256 bytes with some bits set as per
74        the caller address and the log topics.
75    """
76    bloom: bytearray = bytearray(b"\x00" * 256)
77
78    for log in logs:
79        add_to_bloom(bloom, log.address)
80        for topic in log.topics:
81            add_to_bloom(bloom, topic)
82
83    return Bloom(bloom)

def add_to_bloom(bloom: bytearray, bloom_entry: bytes) -> None: View Source

28def 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

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 logs_bloom( logs: Tuple[ethereum.byzantium.fork_types.Log, ...]) -> ethereum.base_types.Bytes256: View Source

60def 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)

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.