Descriptor Checksum
A descriptor checksum is an 8-character suffix appended to Bitcoin output descriptors that detects typos and errors in descriptor strings.
Key Takeaways
- A descriptor checksum is an 8-character alphanumeric string appended after a # symbol to an output descriptor, allowing wallet software to detect typos, copy errors, and corruption before importing or using the descriptor.
- The checksum uses a BCH error-detecting code similar to bech32 encoding: it guarantees detection of all single-character errors and all errors involving up to 3 symbol substitutions in descriptors up to 49,154 characters long.
- Defined in BIP 380, the checksum is mandatory when importing descriptors into Bitcoin Core and other descriptor wallets, ensuring that wallet migration and backup workflows don't silently accept corrupted data.
What Is a Descriptor Checksum?
A descriptor checksum is a short error-detection code appended to a Bitcoin output descriptor string. Output descriptors define exactly how a wallet derives addresses and constructs spending conditions. Because a single wrong character in a descriptor could cause a wallet to generate entirely different addresses, sending funds to locations nobody controls, the checksum acts as a safety net that catches mistakes before they become costly.
The checksum appears at the end of a descriptor, separated by a # character. For example, a simple pay-to-witness-public-key-hash descriptor with its checksum looks like:
wpkh([d34db33f/84'/0'/0']xpub6DJ.../0/*)#checksumThe 8 characters after the # are computed from every preceding character in the descriptor string. If any character is altered, added, or removed, the checksum will no longer match, and wallet software will reject the descriptor on import.
How It Works
The descriptor checksum algorithm is defined in BIP 380, the specification for output descriptor general operation. It uses a BCH (Bose-Chaudhuri- Hocquenghem) error-detecting code, the same family of codes that underpins bech32 address encoding. The process works as follows:
- Each character in the descriptor string is mapped to a position in a fixed input charset of printable ASCII characters
- Each character's position value is split into a 5-bit symbol and a higher group value
- These symbols are fed into a polynomial modular arithmetic function (polymod) using five generator constants specific to descriptor checksums
- Eight zero symbols are appended, the polymod is computed, and the result is XORed with 1
- The resulting 40-bit value is split into eight 5-bit chunks, each mapped to the bech32 character set to produce the final 8-character checksum
The Polymod Function
At the heart of the checksum is a polymod function operating over GF(32), a finite field with 32 elements. The function uses five 40-bit generator constants that define the error-detecting polynomial:
// Generator constants (from BIP 380)
0xF5DEE51989
0xA9FDCA3312
0x1BAB10E32D
0x3706B1677A
0x644D626FFDThese constants differ from the ones used in bech32 address encoding, because descriptor checksums need to cover a larger input space (the full set of printable ASCII characters used in descriptors rather than just the limited bech32 data alphabet).
Checksum Character Set
The 8-character checksum output uses the same 32-character alphabet as bech32:
qpzry9x8gf2tvdw0s3jn54khce6mua7lThis alphabet deliberately excludes characters that are easily confused with one another (such as 1/l, 0/o, b/6), reducing the chance of transcription errors surviving the checksum validation step.
Verification
To verify a descriptor with a checksum, wallet software feeds the entire string (including the checksum characters but excluding the # separator) through the same polymod function. If the result equals 1, the checksum is valid. Any other value indicates corruption.
# Compute a checksum with Bitcoin Core
bitcoin-cli getdescriptorinfo "wpkh([d34db33f/84'/0'/0']xpub6DJ.../0/*)"
# Returns:
# {
# "descriptor": "wpkh(...)#jkl8mnop",
# "checksum": "jkl8mnop",
# "isrange": true,
# "issolvable": true,
# "hasprivatekeys": false
# }Error Detection Capabilities
The BCH code used in descriptor checksums provides strong mathematical guarantees about which errors it can detect. According to BIP 380:
- All single-character substitution errors are always detected (a single wrong character counts as 1 or 2 symbol errors, both of which are caught)
- All errors involving up to 3 symbol substitutions are detected in descriptors up to 49,154 characters long
- A case error (typing an uppercase letter instead of lowercase or vice versa) always counts as exactly 1 symbol error and is therefore always caught
- Random errors that happen to produce a valid checksum have a probability of approximately 1 in 2^40 (about 1 in 1.1 trillion)
These properties make the checksum highly reliable for catching the kinds of mistakes that occur in practice: copy-paste truncation, manual transcription errors, encoding mismatches, and data corruption during storage or transmission.
Why It Matters
Output descriptors are the modern standard for wallet portability and backup. When users migrate between wallet software, restore from backups, or configure multisig setups, they pass descriptor strings between systems. Without a checksum, a single corrupted character could silently cause a wallet to derive an entirely different set of addresses.
Consider a multisig wallet descriptor where one extended public key (xpub) has a typo. Without checksum validation, the wallet might appear to function normally, generating addresses that look valid. But those addresses would not match the intended spending policy, and any funds sent to them could be permanently unrecoverable.
The checksum transforms this silent failure into an immediate, loud error. Bitcoin Core requires a valid checksum when importing descriptors through the importdescriptors RPC and rejects any descriptor where the checksum does not match. This design choice makes descriptor-based workflows significantly safer than the older approach of importing raw keys or xpubs without integrity verification.
Use Cases
Wallet Migration
When moving from one descriptor wallet to another, users export their descriptors (with checksums) and import them into the new software. The receiving wallet validates the checksum before accepting the descriptor, ensuring the migration is error-free. This is especially important for HD wallets where a single wrong character in a derivation path could generate thousands of incorrect addresses.
Multisig Coordination
Setting up a multisig wallet requires sharing extended public keys and agreeing on a descriptor template among all participants. The checksum ensures that every participant is working with identical descriptor strings, preventing scenarios where a miscommunicated key leads to funds being locked in an unreachable script.
Backup Verification
Descriptor backups stored on paper, in encrypted files, or on hardware wallets can degrade over time or suffer transcription errors. When restoring from backup, the checksum immediately reveals whether the stored descriptor is intact, long before any funds are at risk.
Automated Systems
Payment processors, exchanges, and custody platforms that programmatically generate or import descriptors use checksum validation as a first line of defense against software bugs, network corruption, or database errors that might alter descriptor data in transit or at rest.
Risks and Considerations
Checksum Sensitivity to Notation
The descriptor checksum is computed over the exact character string, not over the semantic meaning of the descriptor. This means two descriptors that produce identical addresses but use different notation (for example, using h versus ' for hardened derivation) will have different checksums. Wallet software must normalize descriptors to a canonical form before comparing checksums, and users should be aware that the same wallet configuration can have multiple valid checksum representations.
Not a Security Mechanism
Descriptor checksums detect accidental errors, not malicious tampering. An attacker who can modify a descriptor string can also recompute a valid checksum for the altered version. The checksum provides data integrity, not authentication. For security-critical workflows, descriptor integrity should be verified through additional means such as digital signatures or secure comparison over authenticated channels.
Import Behavior Varies
While Bitcoin Core requires a valid checksum for descriptor imports, not all wallet software enforces this requirement equally. Some wallets accept descriptors without checksums or with invalid checksums, reducing the safety benefit. When working with descriptors, always use software that validates checksums on import and use Bitcoin Core's getdescriptorinfo RPC to compute and verify checksums when in doubt.
This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.