python-codex32

Reference implementation of BIP-0093 (codex32): checksummed, SSSS-aware BIP32 seed strings.

This repository implements the codex32 string format described by BIP-0093. It provides encoding/decoding, regular/long codex32 checksums, CRC padding for base conversions, Shamir secret sharing scheme (SSSS) interpolation helpers and helpers to build codex32 strings from seed bytes.

Features

• Encode/decode codex32 data via from_string and from_unchecksummed_string.
• Regular checksum (13 chars) and long checksum (15 chars) support.
• Construct codex32 strings from raw seed bytes via from_seed.
• CRC-based default padding scheme for from_seed.
• Default from_seed identifier is the bech32-encoded BIP32 fingerprint.
• Interpolate/recover shares via interpolate_at.
• Parse codex32 strings and access parts via properties.
• Mutate codex32 strings by reassigning is_upper, hrp, k, ident, share_idx, data, and pad_val.
• Contains module and tests for Bech32/Bech32m and segwit addresses.

Security

Caution: This is reference code. Verify carefully before using with real funds.

Installation

Compatibility: Python 3.10–3.14

Recommended: use a virtual environment

Linux / macOS

python -m venv .venv
source .venv/bin/activate
pip install codex32

Windows

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install codex32

Quick usage

fromcodex32importCodex32String# Create from seed bytess=Codex32String.from_seed(
bytes.fromhex('ffeeddccbbaa99887766554433221100'),
"ms13cashs", # prefix string, (HRP + '1' + header)0# padding value (default "CRC", otherwise integer)
)
print(s.s) # codex32 string# Parse an existing codex32 string and inspect partsa=Codex32String("ms13casha320zyxwvutsrqpnmlkjhgfedca2a8d0zehn8a0t")
print(a.hrp) # human-readable partprint(a.k) # threshold parameterprint(a.ident) # 4 character identifierprint(a.share_idx) # share index characterprint(a.payload) # payload partprint(a.checksum) # checksum partprint(len(a)) # length of the codex32 stringprint(a.is_upper) # case is upper True/Falseprint(s.data.hex()) # raw seed bytes as hexprint(a.pad_val) # padding value integer, (MSB first)# Create from unchecksummed string (will append checksum)c=Codex32String.from_unchecksummed_string("ms13cashcacdefghjklmnpqrstuvwxyz023")
print(str(c)) # equivalent to print(c.s)# Interpolate shares to recover or derive target share indexshares= [s, a, c]
derived_share_d=Codex32String.interpolate_at(shares, target='d')
print(derived_share_d.s)
# Create Codex32String object from existing codex32 string and validate any HRPe=Codex32String.from_string("cl", "cl10lueasd35kw6r5de5kueedxyesqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqanvrktzhlhusz")
print(e.ident)
print(e.s)
# Relabel a Codex32String objecte.ident="cln2"print(e.ident)
print(e.s)
# Uppercase a Codex32String object (for encoding in QR codes or handwriting)e.is_upper=Trueprint(e.s)

Tests

pip install -e .[dev]
pytest