Descriptors & Miniscript

Express wallet policies as output descriptors and compose safe scripts.

intermediate6 days

Public lesson — sign in to track progress on this roadmap.

Learning objectives

Read and write basic output descriptors
Explain why descriptors beat ad-hoc path assumptions
Use Miniscript as a policy language mindset

study // plan

Lessons are primers. Start with Step 1 (required reading) when present, then follow the numbered steps in the article. Depth comes from primary sources, labs, reflection, and evidence.

Research on Bitcoin Search

BIP380 output descriptors

Step 1 // Required reading

Complete these before the numbered steps in the lesson body. Links are listed here once — not repeated below.

bipBIP-380 Output Script Descriptors

Reflection prompts

Explain Descriptors & Miniscript to a teammate without jargon - what problem does it solve?
What would break in production if you misunderstood Descriptors & Miniscript?
Which BIP, book chapter, or Core doc is authoritative here, and what did you verify?

Lab // Decode a descriptor

Complete Steps 2–3. On regtest, run getdescriptorinfo on a sample descriptor (or listdescriptors from a lab wallet) and explain receive vs change in one sentence.

evidence required

getdescriptorinfo (or listdescriptors) output excerpt
One sentence on what the descriptor commits to (wpkh/tr/multi…)
Link to BIP-380 or Core descriptors doc you used

Output descriptors are a standard way to describe what scripts/keys a wallet controls. Miniscript helps compile human policies into safe Script fragments.

Complete Step 1 // Required reading in the study plan above, then continue here.

Step 2 — Core idea: portable policy, not path folklore

“m/84'/0'/0'” alone is incomplete if you forget whether you meant wpkh, tr, multisig, or a custom tree. Descriptors make imports, hardware coordination, and recoveries unambiguous.

Analogy: A descriptor is a precise parts list and assembly diagram for your locks. Miniscript is a grammar that prevents you from building a lock that jams shut forever.

wpkh([fingerprint/84h/1h/0h]tpub.../0/*)
tr([fingerprint/86h/1h/0h]tpub.../0/*)
wsh(multi(2,key1,key2,key3))

Bitcoin Core RPCs like importdescriptors and listdescriptors operationalize this.

Loading diagram…

Policies compile to scripts wrapped by portable descriptors.

Done when: You can read a wpkh(...) / tr(...) line and say what locking condition it describes.

Step 3 — Try it: getdescriptorinfo (lab)

bitcoin-cli -regtest getdescriptorinfo "wpkh(tpubD6NzVbkrYhZ4XgiXtGrdW5XDAPFCL9h7we1vwNCpn8tZpoxq8n3nS8/0/*)"
# Or after creating a wallet:
bitcoin-cli -regtest listdescriptors

(Use a throwaway/example key material — never paste real mainnet xpubs into shared notes.)

Common mistakes

Exporting xpubs without origin info / fingerprints
Mixing receive and change descriptor chains
Assuming Miniscript supports every opcode policy you can imagine

Done when: Lab evidence (RPC excerpt + commitment sentence + source link) is complete.

Next lesson

Bitcoin Core & RPC — drive the reference node for wallets, chain, and tests.

Review club

Practice on real Bitcoin OSS changes tied to this chapter. Read the diff, use the checklist, and optionally paste your review comment URL in your lab notes.

BIP-380 output descriptors
Study output descriptors and write how you'd express a simple 2-of-3 policy as a descriptor string.
spec review
policy expressionimport/export
40 min·intermediateopen on GitHub

review checklist

Does the change solve the stated problem?
Are edge cases and rollout behavior covered?
Are tests or test vectors included?
Is the diff minimal and clearly explained?

More repos and GFIs on /discover and /issues.

progress // sign in

Reading is public. Sign in to mark lessons complete, sync across devices, and unlock your roadmap.

./sign-in-to-track

prevWallet Architecture nextBitcoin Core & RPC

Step 2 — Core idea: portable policy, not path folklore

“m/84'/0'/0'” alone is incomplete if you forget whether you meant wpkh, tr, multisig, or a custom tree. Descriptors make imports, hardware coordination, and recoveries unambiguous.

Analogy: A descriptor is a precise parts list and assembly diagram for your locks. Miniscript is a grammar that prevents you from building a lock that jams shut forever.

wpkh([fingerprint/84h/1h/0h]tpub.../0/*)
tr([fingerprint/86h/1h/0h]tpub.../0/*)
wsh(multi(2,key1,key2,key3))

Bitcoin Core RPCs like importdescriptors and listdescriptors operationalize this.

Loading diagram…

Policies compile to scripts wrapped by portable descriptors.

Done when: You can read a wpkh(...) / tr(...) line and say what locking condition it describes.

Step 3 — Try it: getdescriptorinfo (lab)

bitcoin-cli -regtest getdescriptorinfo "wpkh(tpubD6NzVbkrYhZ4XgiXtGrdW5XDAPFCL9h7we1vwNCpn8tZpoxq8n3nS8/0/*)"
# Or after creating a wallet:
bitcoin-cli -regtest listdescriptors

(Use a throwaway/example key material — never paste real mainnet xpubs into shared notes.)

Exporting xpubs without origin info / fingerprints

Mixing receive and change descriptor chains

Assuming Miniscript supports every opcode policy you can imagine

Done when: Lab evidence (RPC excerpt + commitment sentence + source link) is complete.

Bitcoin Core & RPC — drive the reference node for wallets, chain, and tests.

Descriptors & Miniscript

Learning objectives

Step 1 // Required reading

Reflection prompts

Lab // Decode a descriptor

How to study this lesson

Step 2 — Core idea: portable policy, not path folklore

Step 3 — Try it: getdescriptorinfo (lab)

Common mistakes

Next lesson

further reading

Review club

Descriptors & Miniscript

Learning objectives

Step 1 // Required reading

Reflection prompts

Lab // Decode a descriptor

How to study this lesson

Step 2 — Core idea: portable policy, not path folklore

Step 3 — Try it: getdescriptorinfo (lab)

Common mistakes

Next lesson

further reading

Review club