ethereum.tangerine_whistle.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.
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)
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.
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.