BA-04 · LESSON 05

Descriptors and miniscript policy

KEY DEFINITIONS

Terms used in this lesson

Descriptor: A machine-readable description of the scripts, keys, and derivation paths a Bitcoin wallet watches or can spend.
Miniscript: A structured way to compose and analyze Bitcoin Script spending policies.
Witness: Signatures, scripts, or other data supplied to satisfy a Bitcoin output’s spending condition.
P2WSH: Pay to Witness Script Hash: a native SegWit output that commits to a witness script.
Hashlock: A spending condition that requires revealing data matching a committed hash.
Taproot: A Bitcoin output and spending design that can combine a public-key path with privately committed alternative scripts.
SHA-256: A cryptographic hash function used throughout Bitcoin to produce fixed-size 256-bit digests.

A wallet descriptor is a precise recipe for finding keys and constructing spending conditions. Miniscript is a structured way to express some of those conditions safely.

35 min Difficulty 1/5 Not started

VISUAL MODEL

See the whole mechanism before going step by step

Use the diagrams to orient yourself. Then the guided explanation below teaches every part in depth.

4 explanatory views

CONCEPT-SPECIFIC MAP · key derivationWallet material becomes a spending destinationSelect any state to inspect its exact role.

RELATIONSHIP MAPCommitment and derivation tree

01
BACKUPEntropy and policy
Recovery starts from secret entropy plus any passphrase and wallet policy data.
02
TREEDerivation path
A deterministic path selects one child key without changing earlier branches.
03
KEYDescriptors and miniscript policy
The Descriptors and miniscript policy step determines what secret or public material is available.
04
SCRIPTSpending condition
The destination commits to a script or witness program, not a human identity.
05
OUTPUTValue and script
A payment creates a new output that can be spent only by satisfying its condition.

Rule shown: A wallet derives keys and scripts; the blockchain records spendable outputs, not a wallet account.

STAGE 1 OF 5BACKUP: Entropy and policy

Recovery starts from secret entropy plus any passphrase and wallet policy data.

Governing relationship: A wallet derives keys and scripts; the blockchain records spendable outputs, not a wallet account. Complete path: 1. BACKUP, Entropy and policy. Recovery starts from secret entropy plus any passphrase and wallet policy data. 2. TREE, Derivation path. A deterministic path selects one child key without changing earlier branches. 3. KEY, Descriptors and miniscript policy. The Descriptors and miniscript policy step determines what secret or public material is available. 4. SCRIPT, Spending condition. The destination commits to a script or witness program, not a human identity. 5. OUTPUT, Value and script. A payment creates a new output that can be spent only by satisfying its condition.

1. State transitionWhat exists, what changes, and what results

BEFORE

Consider wsh(or_d(pk(A),and_v(v:older(144),pk(B)))).

MECHANISM

Start with participants and conditions: signatures, hashlocks, or absolute and relative timelocks. This is the authorization intent.

AFTER

A descriptor backs up what to watch and how to spend, not merely one secret key.

Text equivalent: Starting from Consider wsh(or_d(pk(A),and_v(v:older(144),pk(B)))). The mechanism begins when Start with participants and conditions: signatures, hashlocks, or absolute and relative timelocks. This is the authorization intent. The resulting lesson is A descriptor backs up what to watch and how to spend, not merely one secret key.

2. Mechanism pathSelect a stage to inspect its job

STAGE 1 OF 5

Write the spending policy

Start with participants and conditions: signatures, hashlocks, or absolute and relative timelocks. This is the authorization intent.

Complete path: 1. Write the spending policy: Start with participants and conditions: signatures, hashlocks, or absolute and relative timelocks. This is the authorization intent. 2. Compile analyzable Miniscript: For supported script contexts, Miniscript represents the policy with typed fragments whose satisfaction cost and safety properties can be analyzed. 3. Embed it in a descriptor: The descriptor selects an output family such as wsh or tr, concrete keys or key origins, derivation wildcards, and the script expression. 4. Derive actual scripts: At an index, the wallet derives keys, constructs the witness script or Taproot commitment, and then derives the address. 5. Back up and verify the descriptor: The descriptor checksum detects transcription changes. Recovery imports the descriptor and rescans the relevant range, while private signing material may be stored separately.

3. Rule and failure boundaryWhat accepts the result and where it can stop

ACCEPTED PATH

The parser consumes the complete descriptor grammar, validates keys and delay, derives the witness program, verifies the selected branch signature, and enforces sequence age on the delayed branch.

CHANGED CONDITION

Malformed keys are rejected before script construction, while the recovery signature cannot satisfy its branch until the relative delay is reached.

Important distinction: A descriptor containing public keys is always safe to publish because it cannot sign. It may reveal complete wallet structure, derivation, balances, future addresses, and transaction links. Watch-only information still has significant privacy sensitivity.

Text equivalent: The accepted path is enforced by The parser consumes the complete descriptor grammar, validates keys and delay, derives the witness program, verifies the selected branch signature, and enforces sequence age on the delayed branch. If the required condition changes, Malformed keys are rejected before script construction, while the recovery signature cannot satisfy its branch until the relative delay is reached.

Loading lesson visuals...

Learn the idea

An output descriptor is a machine-readable expression describing the scripts and keys a wallet watches or can spend. Miniscript is a structured language for composing and analyzing certain Bitcoin Script policies. In the worked expression, wsh means a pay-to-witness-script-hash output, shortened to P2WSH; or_d selects one of two branches, pk requires a key signature, and older(144) requires a 144-block relative delay; and_v requires both delayed conditions to succeed. A policy expresses intent such as 'key A now, or key B after 144 blocks'; a descriptor fixes the concrete keys, derivation, script wrapper, and checksum needed to construct outputs.

GUIDED EXPLANATION1/5 ideas inspected

Write the spending policy

Start with participants and conditions: signatures, hashlocks, or absolute and relative timelocks. This is the authorization intent.

The worked example follows the explanation

Inspect every idea above to open it.

Important distinction“A descriptor containing public keys is always safe to publish because it cannot sign.”

It may reveal complete wallet structure, derivation, balances, future addresses, and transaction links. Watch-only information still has significant privacy sensitivity.

FINISH LEARNING FIRST

The questions unlock after every required learning activity

Inspect every guided idea, open the worked example, rebuild its mechanism, and complete the deterministic lesson tool. Your progress is saved automatically.