{"id":7076,"library":"chiabip158","title":"Chia BIP158","description":"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.","status":"active","version":"1.5.4","language":"en","source_language":"en","source_url":"https://github.com/Chia-Network/chiabip158","tags":["Golomb-Coded-Set","Bip157","Bip158","Light-Client","Chia-Blockchain","Golomb-Rice","Chia"],"install":[{"cmd":"pip install chiabip158","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"The 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.","package":"C++ compiler","optional":true},{"reason":"Older macOS builds from source could encounter issues finding Boost.Thread libraries, requiring manual symlinks.","package":"Boost","optional":true}],"imports":[{"symbol":"GCSFilter","correct":"from chiabip158 import GCSFilter"},{"symbol":"Key","correct":"from chiabip158 import Key"},{"symbol":"match_filters","correct":"from chiabip158 import match_filters"}],"quickstart":{"code":"from chiabip158 import GCSFilter, Key\n\n# Example data (replace with actual block filter and key data)\n# A real filter would be much longer and derived from block data.\n# Key is typically derived from the block hash.\nfilter_data_hex = \"0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20\"\nkey_data = b'\\x00' * 16 # Placeholder: A real key is a 128-bit SipHash key\n\nP = 19 # P parameter as defined in BIP158\n\n# Create a GCSFilter object\ntry:\n    gcs_filter = GCSFilter(P, bytes.fromhex(filter_data_hex))\n    print(f\"GCSFilter created: {gcs_filter}\")\n\n    # Example: Check for a match (this will likely be False with dummy data)\n    search_keys = [Key(b'search_item_1'), Key(b'search_item_2')]\n    if gcs_filter.match_any(key_data, search_keys):\n        print(\"Filter matched at least one item.\")\n    else:\n        print(\"Filter did not match any item (or false positive not triggered).\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Consult the `chia-blockchain` project's `pyproject.toml` or `setup.py` for the exact `chiabip158` version it requires for a given release.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"Potentially older versions or specific macOS environments when building from source."},{"fix":"Update any scripts or tools that parse `chiabip158` version numbers to expect a `MAJOR.MINOR.PATCH` format.","message":"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.","severity":"deprecated","affected_versions":">=1.5.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install chiabip158`.","cause":"The `chiabip158` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'chiabip158'"},{"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.","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.","error":"ImportError: cannot import name 'GCSFilter' from 'chiabip158' (.../chiabip158.py)"}]}