Checksums
Most encodings will decode a typo without blinking. Swap two base64 characters and you get different bytes, no error, no warning. Fine for a data URL. Not fine for an address you're about to send money to.
Two of them carry a checksum and check it every time you decode. Base58 does when you ask for check. Bech32 always does, in both its variants.
Base58Check
Bitcoin's form for addresses, WIF keys and extended keys. The payload, then the first four bytes of its double SHA-256, all in base58. check: true turns it on.
import { base58, hex } from "@agntn/encodings";
hex.encode(base58.decode("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", { check: true }));
// "0062e907b15cbf27d5425399ebf6f0fb50ebb88f18"
That's the genesis block's address. One byte of version, 0x00 for mainnet P2PKH. Then the 20-byte HASH160 of Satoshi's key. Now change the last character from a to b. What happens?
base58: checksum does not match
It throws ChecksumError, a subclass of DecodeError. Catch the one you care about. The version bytes stay in the payload. check checks the checksum and nothing else. Which version means which network? That's @agntn/keys territory.
A WIF key decodes the same way. Private key 1, compressed, is 80, then 31 zero bytes and 01, then one more 01 that says "compressed". Thirty-four bytes. An xpub is seventy-eight.
Bech32 and bech32m
A prefix, a 1, then 5-bit words and six characters of BCH checksum. Lowercase or uppercase, never mixed. The checksum catches any four wrong characters, which is better than base58 ever did.
import { bech32 } from "@agntn/encodings";
bech32.encode("test", new TextEncoder().encode("gm"));
// "test1vaks69jerm"
bech32.decode("test1vaks69jerm");
// { prefix: "test", bytes: Uint8Array [103, 109] }
Bech32m is the same thing with a different constant in the checksum. Why change it? Bech32 had a quiet flaw. When the last character is p, you can add or drop q characters right before it. The old checksum still passes. Feed one variant's text to the other and the error tells you.
bech32: checksum is bech32m's
Strings over 90 characters are rejected by default, like BIP173 says. Lightning invoices are longer. Pass a limit when you mean it.
Segwit addresses
A segwit address is bech32 with one extra rule. The first word is the witness version, the rest is the program. Version 0 uses bech32 and a 20 or 32-byte program. Versions 1 to 16 use bech32m. Taproot is version 1.
import { segwit, hex } from "@agntn/encodings";
const address = segwit.decode("bc1p0xlxvlhemja6c4dqv22uapctqupfhlxm9h8z3k2e72q4k9hcz7vqzk5jj0");
address.version; // 1
hex.encode(address.program); // "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798"
Recognize that program? It's the x coordinate of the secp256k1 generator, and the whole address is one of BIP350's test vectors. A real Taproot address tweaks its key first, so don't go looking for coins there.
The registry does this for you. decode("bech32", …) on a valid segwit address returns the program as bytes and witnessVersion in details. On anything else, a Nostr npub say, it returns the bytes the words carry. Bech32m is m: true there. Read a version 0 address with it and it fails, because that's exactly the mix-up bech32m exists to catch.
Just the words
Some formats borrow bech32's alphabet and its bit shuffle, then bring their own checksum. CashAddr does that with a 40-bit one. So bech32.decode is no help there. What you want is the regrouping alone, 8-bit bytes into 5-bit words and back.
import { fromWords, toWords } from "@agntn/encodings/bech32";
toWords(new Uint8Array([0xff])); // [31, 28]
fromWords([31, 28]); // Uint8Array [255]
fromWords([31, 29]); // throws "bech32: padding bits after the last byte are not zero"
fromWords keeps BIP173's rule. At most four bits of padding, all of them zero, or you get a DecodeError. Just checking whether some words spell bytes at all? fromWordsUnsafe returns undefined instead of throwing, and that's what an address validator wants anyway.
All three come from @agntn/encodings/bech32 only. The root import keeps to whole encodings.