Learn how Bitcoin output descriptors combine keys, derivation paths and script types, and why recovering keys alone may not recover a wallet.
A key is only part of a wallet
Suppose you restore a key and the wallet displays no transactions. That does not immediately mean the backup is wrong. The software also needs to know which scripts to search for. The same public key can participate in several output constructions, and an HD key can derive many branches.
An output descriptor records that construction as an expression. It can describe one script or a family of scripts. It does not move funds, create an account on the blockchain or prove that an address has ever received money. Think of it as the instructions a wallet follows to recreate its set of locks.
Read the outer function first
The wrapper tells you the output family. pkh(KEY) describes a public-key-hash construction; wpkh(KEY) describes native witness version 0 with a key hash. Nesting matters: sh(wpkh(KEY)) wraps that witness program inside P2SH. Those expressions do not produce interchangeable addresses.
tr(KEY) describes a Taproot output. Taproot also allows script-tree information, which must be included when the policy depends on it. Merely knowing that an address starts with a particular prefix is not a complete policy backup.
The symbols in these expressions are explanatory placeholders. A real descriptor must use a supported key expression, valid syntax and any checksum required by the receiving application.
Follow the key expression
A descriptor may contain a single public key, an extended key, origin information and a derivation suffix. Origin information can identify a master fingerprint and the path to an exported key. A suffix can describe the branch and the changing address index. A wildcard represents a range, not an instruction to scan forever.
One shop, two address branches
A merchant may watch a receive branch for new invoices and a separate change branch for spending transactions. Importing only the receive descriptor can show customer payments while missing change. Importing both public descriptors into a compatible watch-only wallet lets it reconstruct those scripts without receiving the merchant's spending keys.
Keep the range and branch assumptions with the backup. A limited imported range can miss addresses beyond its end, even when the descriptor itself is correct.
Public does not mean harmless
A descriptor containing only public information generally cannot authorize a spend. It can still reveal a large portion of a wallet's address history and future receiving addresses. Treat public descriptors and xpubs as sensitive financial metadata. A descriptor containing private keys has a much more serious consequence: it can expose spending capability.
Do not paste a real private descriptor into a website to test whether it looks valid. This lesson and the explorer do not require it.
Check recovery as a complete policy
A recovery check should establish the script type, key origins, required cosigners, receive and change branches, address range, and compatibility with the destination wallet. Compare several known addresses rather than trusting a single successful parse. See Watch-only wallets and Derivation paths for the surrounding concepts.
A descriptor is a precise description of scripts. A seed, a descriptor, a wallet file and the blockchain each preserve different information; none should be assumed to replace all the others.
Sources and further reading
Key takeaways
- Descriptors explain how keys become output scripts; they are not blockchain accounts.
- Wrappers, branches and ranges affect which addresses a restored wallet finds.
- Public descriptors reveal financial metadata; private descriptors can expose spending keys.
Common questions
Does a descriptor contain my balance?
No. The wallet must inspect relevant chain data to determine activity for the scripts described.
Is an xpub the same as a descriptor?
No. An xpub does not by itself specify every script wrapper, branch or policy needed by a wallet.