{"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":"python","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,"search_vec":"'1.5.4':77 '158':15 'activ':60 'bip':14 'bip157':82 'bip158':2,83 'block':20,48,56 'blockchain':40,89 'build':72 'c':24 'chia':1,10,43,88,93 'chia-blockchain':87 'chiabip158':3 'client':38,86 'code':25,80 'compact':19 'contain':49 'creat':28 'current':74 'determin':45 'download':53 'effici':27 'entir':55 'filter':21,32 'golomb':79,91 'golomb-coded-set':78 'golomb-ric':90 'implement':12 'improv':71 'librari':7,58 'light':37,85 'light-client':84 'like':42 'maintain':61 'manag':30 'network':41 'new':67 'process':73 'provid':9 'python':6,68 'regular':63 'relev':50 'rice':92 'set':81 'specif':17 'support':66 'transact':51 'updat':64 'use':35 'version':69,76 'without':52 'wrap':23","created_at":"2026-04-16T13:42:26.522383+00:00","updated_at":"2026-04-16T13:42:26.522383+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nImportError: cannot import name 'GCSFilter' from 'chiabip158' (/tmp/tmpoaykv6mi/venv/lib/python3.12/site-packages/chiabip158.cpython-312-x86_64-linux-gnu.so)"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.5.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Chia-Network/chiabip158","docs":null,"changelog":null,"pypi":"https://pypi.org/project/chiabip158/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"skip","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-08-01","install_tag":null}}