Chia BIP158

1.5.4 · active · verified Thu Apr 16

Chiabip158 is a Python library that provides Chia's implementation of BIP 158, a specification for compact block filters. It wraps C++ code to efficiently create and manage these filters, which are used by light clients in blockchain networks (like Chia) to determine if a block contains relevant transactions without downloading the entire block. The library is actively maintained, with regular updates to support new Python versions and improve build processes, currently at version 1.5.4.

Common errors

```
ModuleNotFoundError: No module named 'chiabip158'
```
cause The `chiabip158` library is not installed in the current Python environment.

fix Install the library using pip: `pip install chiabip158`.
```
ImportError: cannot import name 'GCSFilter' from 'chiabip158' (.../chiabip158.py)
```
cause This error often occurs if a local file named `chiabip158.py` exists in the current directory or on the Python path, shadowing the installed package.

fix Rename or remove the conflicting `chiabip158.py` file, or ensure your `PYTHONPATH` does not incorrectly point to a directory with a similarly named script.

Warnings

gotcha When developing with `chiabip158` as part of the Chia blockchain ecosystem, be aware that its master branch might be ahead of the version required by `chia-blockchain`'s release version. Always check `chia-blockchain`'s dependencies if integrating directly.
Fix: Consult the `chia-blockchain` project's `pyproject.toml` or `setup.py` for the exact `chiabip158` version it requires for a given release.
gotcha For users attempting to build `chiabip158` from source on macOS, particularly with older setups, there might be issues with `clang` not finding `libboost_thread` due to Homebrew providing `libboost_thread-mt` instead of `libboost_thread`.
Fix: A known workaround is to create symbolic links: `cd /usr/local/lib && ln -s libboost_thread-mt.a libboost_thread.a && ln -s libboost_thread-mt.dylib libboost_thread.dylib`. Alternatively, rely on pre-built wheels.
deprecated The versioning scheme shifted with 1.5.0 to use three segments (e.g., 1.5.0 instead of 1.4) to align more closely with semantic versioning. While not a breaking API change, users relying on two-segment version parsing might need to adapt.
Fix: Update any scripts or tools that parse `chiabip158` version numbers to expect a `MAJOR.MINOR.PATCH` format.

Install

pip install chiabip158 Install with pip

Imports

GCSFilter
```
from chiabip158 import GCSFilter
```
Key
```
from chiabip158 import Key
```
match_filters
```
from chiabip158 import match_filters
```

Quickstart

This quickstart demonstrates how to create a `GCSFilter` object and use its `match_any` method. The `P` parameter (19) is a standard value from BIP158. `Key` objects represent the items to search for within the filter. Note that `filter_data_hex` and `key_data` should be replaced with actual block filter data and a SipHash key derived from a block's hash for real-world usage. False positives are possible with GCS filters, as designed by BIP158.

from chiabip158 import GCSFilter, Key

# Example data (replace with actual block filter and key data)
# A real filter would be much longer and derived from block data.
# Key is typically derived from the block hash.
filter_data_hex = "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20"
key_data = b'\x00' * 16 # Placeholder: A real key is a 128-bit SipHash key

P = 19 # P parameter as defined in BIP158

# Create a GCSFilter object
try:
    gcs_filter = GCSFilter(P, bytes.fromhex(filter_data_hex))
    print(f"GCSFilter created: {gcs_filter}")

    # Example: Check for a match (this will likely be False with dummy data)
    search_keys = [Key(b'search_item_1'), Key(b'search_item_2')]
    if gcs_filter.match_any(key_data, search_keys):
        print("Filter matched at least one item.")
    else:
        print("Filter did not match any item (or false positive not triggered).")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →