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