Bech32

Warnings

• gotcha 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.
  Fix: Use a Bech32m-compatible library or function for Segwit v1+ addresses. This `bech32` library is specifically for BIP-173 (Bech32).
• gotcha 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.
  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`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install bech32 Install with pip

Imports

• bech32_encode

  from bech32 import bech32_encode

• bech32_decode

  from bech32 import bech32_decode

• convertbits

  from bech32 import convertbits

  Essential for converting data between 8-bit bytes and 5-bit integers required by Bech32 encoding.

Quickstart

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`.

from bech32 import bech32_encode, bech32_decode, convertbits

# Example 1: Encoding a Segwit v0 P2WPKH address data (20-byte hash)
hrp = "bc"  # Human-Readable Part for Bitcoin mainnet
witness_version = 0 # Witness version 0
# Example 20-byte hash (in 8-bit groups)
data_8bit = [0x75, 0x1e, 0x76, 0xe8, 0x19, 0x91, 0x96, 0xd4, 0x54, 0x94,
             0x1c, 0x45, 0xd1, 0xb3, 0xa3, 0x23, 0xf1, 0x43, 0x3b, 0xd6]

# Convert 8-bit data to 5-bit groups, prepending witness version
# convertbits returns None if conversion fails
data_5bit = convertbits(data_8bit, 8, 5)
if data_5bit is None:
    print("Error converting data to 5-bit groups.")
    exit()

# The final data for encoding includes the witness version (0-31) and the converted 5-bit data
encoded_data = [witness_version] + data_5bit

# Encode to Bech32
bech32_address = bech32_encode(hrp, encoded_data)
print(f"Encoded Bech32 address: {bech32_address}")
# Expected: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

# Example 2: Decoding a Bech32 address
address_to_decode = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"
hrp_decoded, data_5bit_decoded = bech32_decode(address_to_decode)

if hrp_decoded is None or data_5bit_decoded is None:
    print(f"Error decoding address: {address_to_decode}")
else:
    print(f"Decoded HRP: {hrp_decoded}")
    print(f"Decoded Data (5-bit groups): {data_5bit_decoded}")

    # Extract witness version and program
    wit_version = data_5bit_decoded[0]
    wit_program_5bit = data_5bit_decoded[1:]

    # Convert 5-bit program back to 8-bit bytes
    wit_program_8bit = convertbits(wit_program_5bit, 5, 8, pad=False)

    if wit_program_8bit is None:
        print("Error converting 5-bit program to 8-bit bytes.")
    else:
        print(f"Witness Version: {wit_version}")
        print(f"Witness Program (8-bit hex): {bytes(wit_program_8bit).hex()}")