base58-bech32

Base58, Base58Check, bech32, bech32m, SS58 and CashAddr: the binary-to-text codecs of cryptocurrency addresses and keys, in typed Python, with nothing of any chain above them.

It is fully annotated and ships py.typed, and it imports nothing but the standard library.

What is here

• Base58, plain and checked: Bitcoin's alphabet, Ripple's, or any other 58 distinct ascii bytes, and Base58Check's double SHA-256 checksum (base58)
• bech32 and bech32m, with a length limit the caller sets, bech32_decode's docstring giving the default and why, and convertbits, the regrouping of bytes into 5-bit values and back (bech32)
• SS58, the address format of Polkadot and the Substrate chains, with both prefix forms (ss58)
• CashAddr, the address format of Bitcoin Cash (cashaddr)

At the base are exceptions and _utils. The independent base58 and bech32 codecs build on them; ss58 reuses base58, and cashaddr reuses bech32's alphabet and bit regrouping.

Every refusal is a ValueError or a TypeError, under one base, Base58Bech32Exception (exceptions). No decoder's refusal quotes the string it was handed: what reaches a decoder can be a private key.

What the bytes mean -- a witness program, a public key hash, a WIF -- is not here: btclib is the library above this one for bitcoin. The migration page maps each function of the base58 and bech32 packages to its equivalent here.

The suite answers to vectors their authors publish -- Bitcoin Core's, the base58 package's, Substrate's and the CashAddr specification's -- and tests/_data/README.md pins each vendored file to the upstream commit it was copied from.

Installing

python -m pip install --upgrade base58-bech32

An address of each format

from base58_bech32 import base58, bech32, cashaddr, ss58

wif = base58.b58encode_check(bytes.fromhex("80" + "11" * 32 + "01"))
assert base58.b58decode_check(wif, out_size=34)[0] == 0x80

hrp, values, m = bech32.bech32_decode("bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4")
# BIP350: bech32 for witness version 0, bech32m for every later one
assert m == (bech32.BECH32_1_CONST if values[0] == 0 else bech32.BECH32_M_CONST)
program = bytes(bech32.convertbits(values[1:], 5, 8, False))
assert (hrp, values[0], program.hex()[:8]) == ("bc", 0, "751e76e8")

alice = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
prefix, account = ss58.ss58_decode(alice)
assert prefix == 42
polkadot = ss58.ss58_encode(0, account)
assert polkadot == b"15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5"

address = "bitcoincash:qr6m7j9njldwwzlg9v7v53unlr4jkmx6eylep8ekg2"
assert cashaddr.cashaddr_decode(address)[:2] == ("bitcoincash", 0)

tests/readme_test.py runs every Python block of this file, so the example above is the one the suite checks.

Security

SECURITY.md says how to report a vulnerability, which versions are supported, and how a published file is traced back to the run that built it. ASSURANCE_CASE.md argues why what it promises holds: the threat model, the trust boundaries, and the weaknesses a package of this kind is exposed to.

Contributing

CONTRIBUTING.md has the commands each CI job runs, verbatim. uv sync creates the environment; uv is the only tool that has to be installed. REVIEWING.md is what a pull request is answered against.

How the organization decides, and who holds which role, is its GOVERNANCE.md; what it intends to do, and what it deliberately does not, is its ROADMAP.md.

Links

• Documentation: https://base58-bech32.readthedocs.io/
• Source: https://github.com/btclib-org/base58-bech32
• Releases: https://github.com/btclib-org/base58-bech32/releases
• CHANGELOG.md, and RELEASE_NOTES.md for what a release asks a user to act on

The btclib organization and its projects are actively supported by DGI and CheckSig.