{"id":6320,"library":"bech32","title":"Bech32","description":"The `bech32` Python library provides a reference implementation for the Bech32 and Segwit address encoding scheme (BIP-173). It offers functionalities for encoding binary data into human-readable Bech32 strings and decoding them back. The current version is 1.2.0, with an infrequent release cadence focused on maintaining the reference standard.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/fiatjaf/bech32","tags":["bitcoin","blockchain","cryptocurrency","address encoding","bech32","segwit","bip173"],"install":[{"cmd":"pip install bech32","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"bech32_encode","correct":"from bech32 import bech32_encode"},{"symbol":"bech32_decode","correct":"from bech32 import bech32_decode"},{"note":"Essential for converting data between 8-bit bytes and 5-bit integers required by Bech32 encoding.","symbol":"convertbits","correct":"from bech32 import convertbits"}],"quickstart":{"code":"from bech32 import bech32_encode, bech32_decode, convertbits\n\n# Example 1: Encoding a Segwit v0 P2WPKH address data (20-byte hash)\nhrp = \"bc\"  # Human-Readable Part for Bitcoin mainnet\nwitness_version = 0 # Witness version 0\n# Example 20-byte hash (in 8-bit groups)\ndata_8bit = [0x75, 0x1e, 0x76, 0xe8, 0x19, 0x91, 0x96, 0xd4, 0x54, 0x94,\n             0x1c, 0x45, 0xd1, 0xb3, 0xa3, 0x23, 0xf1, 0x43, 0x3b, 0xd6]\n\n# Convert 8-bit data to 5-bit groups, prepending witness version\n# convertbits returns None if conversion fails\ndata_5bit = convertbits(data_8bit, 8, 5)\nif data_5bit is None:\n    print(\"Error converting data to 5-bit groups.\")\n    exit()\n\n# The final data for encoding includes the witness version (0-31) and the converted 5-bit data\nencoded_data = [witness_version] + data_5bit\n\n# Encode to Bech32\nbech32_address = bech32_encode(hrp, encoded_data)\nprint(f\"Encoded Bech32 address: {bech32_address}\")\n# Expected: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq\n\n# Example 2: Decoding a Bech32 address\naddress_to_decode = \"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq\"\nhrp_decoded, data_5bit_decoded = bech32_decode(address_to_decode)\n\nif hrp_decoded is None or data_5bit_decoded is None:\n    print(f\"Error decoding address: {address_to_decode}\")\nelse:\n    print(f\"Decoded HRP: {hrp_decoded}\")\n    print(f\"Decoded Data (5-bit groups): {data_5bit_decoded}\")\n\n    # Extract witness version and program\n    wit_version = data_5bit_decoded[0]\n    wit_program_5bit = data_5bit_decoded[1:]\n\n    # Convert 5-bit program back to 8-bit bytes\n    wit_program_8bit = convertbits(wit_program_5bit, 5, 8, pad=False)\n\n    if wit_program_8bit is None:\n        print(\"Error converting 5-bit program to 8-bit bytes.\")\n    else:\n        print(f\"Witness Version: {wit_version}\")\n        print(f\"Witness Program (8-bit hex): {bytes(wit_program_8bit).hex()}\")","lang":"python","description":"This quickstart demonstrates encoding and decoding a Bitcoin Segwit v0 P2WPKH address using `bech32_encode` and `bech32_decode`. It highlights the essential `convertbits` utility for converting data between 8-bit bytes and 5-bit groups, which is critical for correct Bech32 implementation. Remember to handle potential `None` returns from `bech32_decode` and `convertbits`."},"warnings":[{"fix":"Use a Bech32m-compatible library or function for Segwit v1+ addresses. This `bech32` library is specifically for BIP-173 (Bech32).","message":"This library implements Bech32 (BIP-173) for Segwit version 0 addresses. For Segwit version 1 (Taproot) and later, Bech32m (BIP-350) is required, which uses a different checksum. Attempting to encode/decode Bech32m addresses with this library will result in invalid checksums or decoding errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use the `convertbits` helper function to correctly transform your raw 8-bit byte data into the required list of 5-bit integers before encoding. For decoding, remember that `bech32_decode` returns data in 5-bit groups, which often need to be converted back to 8-bit bytes using `convertbits`.","message":"Input data for `bech32_encode` and `convertbits` (when converting to 5-bit) must be provided as a list of integers, where each integer represents a 5-bit value (0-31) for encoding, or an 8-bit value (0-255) for converting to 5-bit. Incorrect bit grouping or data types (e.g., raw bytes without conversion) are common pitfalls.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the HRP provided to `bech32_encode` and the witness version embedded in the data (typically the first element after the HRP in the data part) are consistent with the target blockchain network and address type.","message":"The `bech32_encode` function requires a Human-Readable Part (HRP) that matches the intended network (e.g., 'bc' for Bitcoin mainnet, 'tb' for testnet). Mismatching the HRP with the network or the witness version used in the data can lead to valid but incorrect addresses or validation failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always check if the return value of `bech32_decode` or `convertbits` is `None` before attempting to access its components or use the result. Implement appropriate error handling or logging based on these checks.","message":"Functions like `bech32_decode` and `convertbits` return `None` (for both HRP and data in the case of `bech32_decode`) if the input string is invalid (e.g., incorrect checksum, invalid characters, malformed structure), rather than raising an exception. This requires explicit `None` checks in your code.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}