Feedback
Sign in./start

Site navigation

Theme

Learn

  • Roadmaps

Build

  • Projects
  • Developer Tools

Contribute

  • Open Source Projects
  • Issues
  • Reviews
  • First Contribution
  • BountiesSoon
  • Feedback

Prove

  • Builders

Ecosystem

  • Partners
  • Get Funded↗
  • HackathonsSoon
Sign in./start-building

Become an Open Source Builder. Learn. Build. Contribute. Prove.

Feedback welcome — open a GitHub issue.

Learn

RoadmapsStart Building

Build

ProjectsDeveloper Tools

Contribute

Open Source ProjectsIssuesReviewsFirst ContributionSupportFeedback

Prove

Builders Directory

Account

Sign in

Legal

PrivacyTermsCredits

© 2026 Pull // code MIT · curriculum CC BY-SA 4.0

PrivacyTermsCredits

lesson // bitcoin

Descriptors & Miniscript

Express wallet policies as output descriptors and compose safe scripts.

intermediate6 days

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

./sign-in

On this page

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
BIP380output 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

  1. Explain Descriptors & Miniscript to a teammate without jargon - what problem does it solve?
  2. What would break in production if you misunderstood Descriptors & Miniscript?
  3. 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
  1. 01

    Worked mental model

    Re-read the diagrams in this lesson once out loud in plain language. If you cannot explain the flow to a friend without jargon, pause and revisit the Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

  2. 02

    Hands-on habit

    Every protocol idea should be paired with one local experiment. That habit turns reading into builder instinct.

    1. Reproduce the happy path on regtest (or Polar for Lightning)
    2. Break it on purpose (wrong fee, expired invoice, offline peer)
    3. Write down what error you saw and which layer produced it (wallet, node, mempool, peer)
  3. 03

    Glossary check

    Pick three terms from this lesson and define them in one sentence each without opening notes. Weak definitions mean the lesson is not finished yet.

  4. 04

    Resource order

    Use Resources in order: narrative book chapter first, then BIP/BOLT for precision, then implementation docs for commands. Jumping straight to RPC flags without the mental model creates brittle knowledge.

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.

Backup descriptors with seeds

For Taproot script trees and multisig, seed words alone may be insufficient. Store descriptors (and multisig key records) with the same care as seeds.

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.

further reading

  • docsMiniscript
  • docsBitcoin Core descriptors

review // club

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
  1. Does the change solve the stated problem?
  2. Are edge cases and rollout behavior covered?
  3. Are tests or test vectors included?
  4. 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

discussion

Discussion

prevWallet ArchitecturenextBitcoin Core & RPC

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

No questions yet — be the first to ask.