---
title: "Checksums"
description: "Base58 with check and bech32 in both variants verify themselves on decode. A segwit address comes back as its version and program"
canonical_url: "https://encodings.agntn.dev/guide/checksums"
---
# Checksums

> Base58 with check and bech32 in both variants verify themselves on decode. A segwit address comes back as its version and program

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.

```ts
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?

```text
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](https://keys.agntn.dev) 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.

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

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

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

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


## Sitemap

See the full [sitemap](https://encodings.agntn.dev/sitemap.md) for all pages.
