Glossary

Miniscript Fragment

A Miniscript fragment is an atomic building block in Bitcoin's Miniscript language representing a single spending condition or logical combinator.

Key Takeaways

  • A Miniscript fragment is an atomic unit of Miniscript that represents a single spending condition (key check, hash preimage, timelock) or a logical combinator (and, or, threshold) that joins other fragments together.
  • Every fragment carries a type from the system B, V, K, or W, which describes its stack behavior. These types enforce composition rules at compile time so that only valid Bitcoin Script can be produced.
  • The policy compiler converts human-readable spending policies into an optimized tree of fragments, choosing the encoding that minimizes witness size and transaction fees for the most likely spending path.

What Is a Miniscript Fragment?

A Miniscript fragment is the smallest meaningful piece of a Miniscript expression. Each fragment maps directly to a specific sequence of Bitcoin Script opcodes, and each one has formally defined properties that make it possible to reason about correctness, security, and spending cost without executing the script.

Miniscript was designed by Pieter Wuille, Andrew Poelstra, and Sanket Kanjalkar to solve a fundamental problem: raw Bitcoin Script is powerful but dangerous to compose by hand. A developer writing a 2-of-3 multisig with a timelock fallback in raw Script must manually arrange opcodes like OP_IF, OP_CHECKMULTISIG, and OP_CHECKSEQUENCEVERIFY while ensuring the stack is clean at every branch. Fragments abstract this away. Each fragment is a proven-correct building block, and the type system guarantees that combining them produces valid Script.

Fragments sit at the middle layer of a three-tier architecture. At the top, policy language lets users express spending conditions in plain terms. The policy compiler translates these into a tree of Miniscript fragments. At the bottom, each fragment maps one-to-one to Bitcoin Script opcodes that the network can verify.

How It Works

Fragments fall into two broad categories: leaf fragments that encode a single condition, and combinator fragments that join sub-expressions together with logical operators.

Leaf Fragments

Leaf fragments represent the atomic spending conditions that Bitcoin supports. They sit at the tips of a Miniscript expression tree.

Key check fragments verify that a valid signature is provided for a given public key:

  • pk_k(key): pushes the raw public key onto the stack, requiring a signature check via a wrapper
  • pk_h(key): checks a key against its hash, expanding to DUP HASH160 <HASH160(key)> EQUALVERIFY in Script

Hash preimage fragments require the spender to reveal a value whose hash matches a committed digest:

  • sha256(h): the spender must provide a 32-byte preimage x such that SHA256(x) equals h
  • hash256(h): the spender must provide a 32-byte preimage x such that HASH256(x) equals h
  • ripemd160(h) and hash160(h): analogous checks using RIPEMD-160 and HASH160 respectively

Timelock fragments enforce time-based spending restrictions:

Multisig fragments handle multi-party signing directly:

  • multi(k, key₁, …, keyₙ): a k-of-n multisig check using OP_CHECKMULTISIG, available only in P2WSH contexts
  • multi_a(k, key₁, …, keyₙ): the Tapscript equivalent using OP_CHECKSIGADD, since OP_CHECKMULTISIG is disabled under Taproot

Combinator Fragments

Combinator fragments join sub-expressions with logical operators, building complex spending policies from simpler pieces:

  • and_v(X, Y): requires both X and Y to be satisfied, concatenating their scripts
  • and_b(X, Y): requires both X and Y, combining their results with OP_BOOLAND
  • or_b(X, Y): requires at least one of X or Y, combining with OP_BOOLOR
  • or_c(X, Y): tries X first, falls through to Y only if X fails
  • or_d(X, Y): tries X, uses OP_IFDUP and OP_NOTIF to try Y if X is dissatisfied
  • or_i(X, Y): uses an OP_IF/OP_ELSE/OP_ENDIF structure to choose between X and Y based on a witness flag
  • andor(X, Y, Z): if X succeeds then Y must also succeed, otherwise Z must succeed
  • thresh(k, X₁, …, Xₙ): exactly k of the n sub-expressions must be satisfied, compiled using a chain of OP_ADD operations followed by an equality check

The Type System

Every Miniscript fragment has one of four base types that describe its stack behavior. The type system is what makes fragments safely composable: the compiler checks types at every node in the expression tree and rejects combinations that would produce invalid Script.

TypeNameStack Behavior
BBasePushes nonzero on satisfaction, pushes 0 on dissatisfaction
VVerifyPushes nothing on satisfaction, aborts on dissatisfaction
KKeyPushes a public key, requires an external CHECKSIG to complete
WWrappedLike B but consumes one additional stack element below its inputs

Beyond the four base types, fragments carry type modifiers that encode additional guarantees: z (zero-arg, consumes nothing from the stack), o (one-arg), n (nonzero on satisfaction), d (has a dissatisfaction path), and u (unit, pushes exactly 1 on satisfaction). Malleability properties s (signed), f (forced), and e (expressive) are tracked separately to ensure that the final script cannot be manipulated by a third party.

Wrapper Fragments

Wrappers are special fragments that transform the type of a sub-expression without changing its spending semantics. They are written as a single-letter prefix followed by a colon. BIP 379 defines ten wrappers: a:, s:, c:, d:, v:, j:, n:, t:, l:, and u:. For example:

  • c: wraps a K-type expression with OP_CHECKSIG, converting it to type B
  • v: appends OP_VERIFY, converting a B-type expression to type V
  • d: wraps with OP_DUP OP_IF … OP_ENDIF, adding a dissatisfaction path
  • s: wraps with OP_SWAP, converting a B-type expression to type W

Wrappers can be chained by dropping the intermediate colons. The expression dv:older(144) applies d: then v: to the older(144) fragment. Three wrappers (t:, l:, and u:) are syntactic sugar for common patterns.

The common shorthand pk(key) is actually c:pk_k(key): the raw key fragment pk_k wrapped with c: to add an OP_CHECKSIG. Similarly, pkh(key) is c:pk_h(key).

From Policy to Fragment Tree

The policy compiler translates human-readable policies into optimized fragment trees. Consider a 2-of-3 multisig with a timelock recovery path:

// Policy: 2 of 3 signers normally, or a recovery key after 1 year
or(
  99@thresh(2, pk(Alice), pk(Bob), pk(Carol)),
  1@and(pk(Recovery), older(52560))
)

The 99@ and 1@ annotations tell the compiler that the multisig path is used 99% of the time, so it should be optimized for lower witness size. The compiler explores many valid fragment encodings and selects the one that minimizes spending cost for the weighted probabilities.

A possible compiled output using Miniscript fragments:

// Compiled Miniscript (one possible encoding)
thresh(2, pk(Alice), s:pk(Bob), s:pk(Carol), sln:older(52560))

// Or with andor for a two-branch structure:
andor(
  pk(Alice),
  s:pk(Bob),
  and_v(v:pk(Recovery), older(52560))
)

Each fragment in the tree maps to specific opcodes. The andor fragment becomes an OP_NOTIF/OP_ELSE/OP_ENDIF structure, pk(Alice) becomes <Alice_pubkey> OP_CHECKSIG, s:pk(Bob) swaps the stack and checks Bob's key, and older(52560) becomes <52560> OP_CHECKSEQUENCEVERIFY.

Fragment-to-Script Mapping

One of Miniscript's defining properties is that every fragment has a deterministic mapping to Bitcoin Script opcodes. This table shows common fragments and their Script translations:

FragmentBitcoin ScriptType
pk_k(key)<key>K
pk_h(key)DUP HASH160 <HASH160(key)> EQUALVERIFYK
older(n)<n> CHECKSEQUENCEVERIFYB
after(n)<n> CHECKLOCKTIMEVERIFYB
sha256(h)SIZE <0x20> EQUALVERIFY SHA256 <h> EQUALB
and_v(X, Y)[X] [Y]Depends on Y
or_d(X, Y)[X] IFDUP NOTIF [Y] ENDIFB
multi(k, keys…)<k> <key₁>…<keyₙ> <n> CHECKMULTISIGB

Use Cases

Descriptor Wallets

Descriptor wallets use output descriptors to define exactly how funds can be spent. Miniscript fragments are the building blocks inside descriptors like wsh() and tr(). A descriptor such as wsh(andor(pk(A), s:pk(B), and_v(v:pk(C), older(1000)))) precisely defines a spending policy using composable fragments, and any wallet that understands Miniscript can sign for it.

Corporate Treasury

Businesses can encode governance rules directly into Bitcoin spending conditions. A corporate treasury might require 3-of-5 board members to approve spending, with a 6-month timelock fallback to 2-of-5. The thresh and older fragments encode this logic without trusted intermediaries.

Inheritance Planning

Time-locked recovery paths let heirs access funds after a predefined period without the original key holders. Combining multi-party key checks with the older fragment creates dead-man-switch patterns where funds become accessible to a recovery path if the primary signers do not move them within the timelock window.

Hash-Locked Contracts

The sha256 and hash256 fragments enable hash time-locked contracts and atomic swap patterns. Combined with timelocks and key checks, they can express conditional payments where revealing a preimage on one chain unlocks funds on another.

Hardware Signing Device Compatibility

Because Miniscript fragments have formally defined properties, hardware wallets can analyze an arbitrary spending script to determine whether a specific signing path is safe. This enables hardware signing devices to support complex policies without custom firmware for each use case.

Why It Matters

Before Miniscript, constructing anything beyond simple pay-to-key or basic multisig scripts in Bitcoin required deep expertise in Script's stack machine. Errors were common and often undetectable until funds were at risk. Fragments solve this by providing a vocabulary of proven-correct components with a type system that prevents invalid compositions.

Bitcoin Core, the Bitcoin Dev Kit (BDK), and multiple hardware wallets now support Miniscript, making fragments a practical tool for wallet developers. Platforms like Spark benefit from this infrastructure because it standardizes how complex spending conditions are expressed, analyzed, and signed across the Bitcoin ecosystem.

For a deeper exploration of how policies compile into fragment trees and how the compiler optimizes for spending cost, see the research article on Miniscript and Bitcoin spending policies.

Risks and Considerations

Script Size Limits

Complex fragment trees produce large scripts. P2WSH scripts are limited to 10,000 bytes, and each Tapscript leaf has a similar budget. Deeply nested policies with many branches or large threshold sets can exceed these limits, forcing developers to restructure their spending conditions.

Timelock Mixing Restrictions

Bitcoin enforces a rule that absolute and relative timelocks using block heights cannot be mixed with timelocks using timestamps in the same transaction. The Miniscript type system tracks this and will reject fragment compositions that violate this constraint, but developers must still be aware of the limitation when designing policies.

Witness Size and Fee Impact

Every fragment adds opcodes and data to the witness. More complex policies mean larger witnesses and higher fee rates. The compiler optimizes for the most likely spending path, but less-likely paths (like timelock recovery) may have significantly higher fees. Developers should evaluate witness size across all spending paths, not just the primary one.

P2WSH vs. Tapscript Differences

Some fragments behave differently depending on the script context. The multi fragment uses OP_CHECKMULTISIG, which is only available in P2WSH. Under Taproot, multi_a must be used instead, as it relies on OP_CHECKSIGADD. The type system and compiler handle this distinction, but developers must choose the correct context when defining output descriptors.

Specification Status

Miniscript is formalized in BIP 379. While Miniscript has been widely adopted in production wallets and Bitcoin Core, developers should track the specification for updates to fragment definitions or type rules.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.