MSTR Cat

Blockchain/Level IV · Protocol depth/4.2 Upgrades/Lesson 4

Output descriptors

The grammar of the key: why a seed alone may not restore what you built

MaterialsA running instance of Bitcoin Core (version 23 or later)A hardware wallet capable of exporting public descriptorsA text editor for inspecting and modifying descriptor strings

Wonder

  1. What specific information is missing from a 24-word recovery phrase that makes it insufficient for restoring every address in a multisig wallet?
  2. How does a checksum appended to a descriptor string detect a single transposed character before the software attempts an import?
  3. Why did Bitcoin Core switch new wallets to descriptor mode by default in version 23, and what breaks if you restore an old-style wallet with a modern backup?

Explore

  1. Before descriptors, HD wallets relied on implicit derivation paths. A user backed up a seed phrase or extended public key (xpub) and assumed the software would reconstruct addresses using standard BIP44 conventions. This worked for simple single-signature wallets until Segregated Witness activated in August 2017 at block 481,824. The introduction of P2WPKH and P2WSH address types meant a single xpub no longer described the full structure of how addresses were derived, leading to restoration failures where funds appeared lost because the wallet scanned for the wrong script type.
  2. BIP380 defines Output Script Descriptors as a standard language for describing collections of output scripts used in HD Bitcoin wallets. While BIP380 establishes the framework, BIPs 381 through 386 specify individual expression types like pk(), pkh(), sh(), wpkh(), and wsh(). A descriptor is a structured expression that fully describes an output script (scriptPubKey). For example, ‘wpkh([d34db33f/84’/0’/0’]xpub…/0/*)’ explicitly states the script type, the key origin via master fingerprint and derivation path, the extended public key, and the range of indices to scan. Nothing is left to guesswork.
  3. The format includes a checksum after a ‘#’ character to catch typos. If a user manually edits a descriptor or copies it incorrectly, the software verifies the checksum before accepting the input. This prevents silent corruption where an invalid address would be scanned indefinitely with no results. Hardware wallets can export descriptors containing public keys and derivation paths but explicitly exclude private keys, allowing online nodes to watch over offline assets securely without exposing the seed.
  4. Miniscript, developed by Pieter Wuille, Andrew Poelstra and Sanket Kanjalkar from 2019 and specified in BIP379 (2023), provides a structured way to write and analyze scripts. It allows wallets to combine timelocks, multisig, and hashlocks safely by decomposing complex script logic into simple, analyzable units. Descriptors can then describe time-locked recovery paths and multi-party conditions that a seed phrase alone could never capture.
  5. Bitcoin Core switched new wallets to descriptor wallets by default in version 23 (2022), and version 30 (2025) removed legacy wallets entirely; old ones can only be migrated. Wallets built on BIP39 seed phrases face the same lesson: for anything beyond a standard single-key wallet, the descriptor must be backed up alongside the seed. While this data does not compromise private key security if leaked—since it contains only public information—it requires protection against privacy leaks, as it reveals exactly which addresses a user controls and their derivation structure.
  6. To see this in practice, create a new wallet in Bitcoin Core and run ‘listdescriptors’ to print its descriptors, each ending in a checksum after ‘#’. Copy one, change a single character, and pass it to ‘getdescriptorinfo’: Bitcoin Core rejects it with a checksum error. Note that plain ‘listdescriptors’ shows only public keys, enough for a watch-only copy; restoring spending ability needs ‘listdescriptors true’, which includes private keys and must be guarded accordingly, or a backup of the wallet file.

Key facts

  • BIP380 defines Output Script Descriptors as a standard language for describing HD wallet output scripts.
  • A descriptor explicitly includes script type, key origin (fingerprint/path), public keys, and index ranges.
  • The checksum appended after ‘#’ verifies the integrity of the descriptor string against typos.
  • Bitcoin Core version 23 (2022) made descriptor wallets the default for new wallet creation.
  • Miniscript (BIP379) enables descriptors to represent complex scripts like multisig and timelocks safely.
  • Hardware wallets export public-only descriptors, allowing air-gapped signing with online nodes.

Exercise nine, six, three, one

9CollectList 9 different output script types or wallet configurations (e.g., P2PKH, P2SH-P2WSH, 2-of-3 multisig). For each, note what specific data is required to restore it.
6ClusterGroup the 9 into 6 categories based on whether a standard BIP44 path suffices or if explicit descriptor data is mandatory for correct restoration.
3DistillReduce the 6 groups to 3 core reasons why implicit derivation paths fail for modern wallet types.
1CrystallizeWrite 1 sentence explaining what a descriptor adds to a seed phrase that makes restoration deterministic.

Fact check

Dates, figures and claims checked against the published sources listed below.

Open in the interactive academy →

PT ES ZH JA KO RU DE FR MS