Install & Compatibility
Where this runs
tested against v1.5.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 1.8s
py 3.11
✕ build_error
✓ 1.73s
py 3.12
✕ build_error
✓ 1.65s
py 3.13
✕ build_error
✓ 1.6s
py 3.9
✕ build_error
✕ build_error
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GCSFilter
✓ from chiabip158 import GCSFilter
Key
✓ from chiabip158 import Key
match_filters
✓ from chiabip158 import match_filters
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}")
Debug
Known issues
gotchaWhen 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.fixConsult the `chia-blockchain` project's `pyproject.toml` or `setup.py` for the exact `chiabip158` version it requires for a given release.
affects: All versions
gotchaFor 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`.fixA 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.
affects: Potentially older versions or specific macOS environments when building from source.
deprecatedThe 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.fixUpdate any scripts or tools that parse `chiabip158` version numbers to expect a `MAJOR.MINOR.PATCH` format.
affects: >=1.5.0
Upgrade
Version history
1.5.4latest on PyPI · released Nov 6, 2025
Audit
Dependencies
C++ compileroptionalThe library wraps C++ code and may require a C++ compiler (like g++ or clang) if building from source, though pre-built wheels are typically available.
BoostoptionalOlder macOS builds from source could encounter issues finding Boost.Thread libraries, requiring manual symlinks.