<em>Miniscript</em> is a language for writing (a subset of) Bitcoin Scripts in a structured way, enabling analysis, composition, generic signing and more.
Bitcoin Script is an unusual stack-based language with many edge cases, designed for implementing spending conditions consisting of various combinations of
<li>Given a two scripts, construct a script that implements a composition of their spending conditions (e.g. a multisig where one of the "keys" is another multisig).</li>
Miniscript functions as a representation for scripts that makes these sort of operations possible. It has a structure that allows composition. It is very easy to
statically analyze for various properties (spending conditions, correctness, security properties, malleability, ...). It can be targeted by spending policy compilers
(see further). Finally, compatible scripts easily can be converted to miniscript - avoiding the need for additional metadata for e.g. signing devices that support it.
For now, Miniscript is really only designed for P2WSH and P2SH-P2WSH embedded scripts. Most of its constructions works fine in P2SH as well, but some of the (optional) security properties
rely on Segwit-specific rules. Furthermore, the implemented policy compilers assume a Segwit-specific cost model.
The <code>and_n</code> fragment and <code>t:</code>, <code>l:</code>, and <code>u:</code> wrappers are syntactic sugar for other Miniscripts, as listed in the table above.
In what follows, they will not be included anymore, as their properties can be derived by looking at their expansion.
Not every Miniscript expression can be composed with every other. Some return their result by putting zero or false on the stack; others distinguish by aborting or continuing.
Some require subexpressions that consume an exactly known number of arguments, while others need a subexpression that has a nonzero top stack element to satisfy. To model all
these properties, we define a correctness type system for Miniscript.
</p>
<p>
Every miniscript expression has one of four basic types:<ul>
<li><b>"B"</b> Base expressions:<ul>
<li>Takes its inputs from the top of the stack.</li>
<li>When satisfied, pushes a nonzero value of up to 4 bytes onto the stack.</li>
<li>When dissatisfied, pushes a 0 onto the stack.</li>
<li>This is used for most expressions, and required for the top level one.</li>
<li>A "V" can be obtained using the <code>v:</code> wrapper on a "B" expression, or by combining other "V" expressions using <code>and_v</code>, <code>or_i</code>, <code>or_c</code>, or <code>andor</code>.</li>
Then there are 5 type modifiers, which guarantee additional properties:<ul>
<li><b>"z"</b> Zero-arg: this expression always consumes exactly 0 stack elements.</li>
<li><b>"o"</b> One-arg: this expression always consumes exactly 1 stack element.</li>
<li><b>"n"</b> Nonzero: no satisfaction for this expression requires a top stack element that is zero.</li>
<li><b>"d"</b> Dissatisfiable: this expression can be dissatisfied by anyone.</li>
<li><b>"u"</b> Unit: when satisfied, this expression will put an exact 1 on the stack (as opposed to any nonzero value).</li>
</ul>
</p>
<p>
This tables lists the correctness requirements for each of the Miniscript expressions, and its type properties in function of those of their subexpressions:
<tr><td><code>and_v(<em>X</em>,<em>Y</em>)</code></td><td><em>X</em> is V; <em>Y</em> is B, K, or V</td><td>same as <em>Y</em></td><td>z=z<sub>X</sub>z<sub>Y</sub>; o=z<sub>X</sub>o<sub>Y</sub> or z<sub>Y</sub>o<sub>X</sub>; n=n<sub>X</sub> or z<sub>X</sub>n<sub>Y</sub>; u=u<sub>Y</sub></td></tr>
<tr><td><code>and_b(<em>X</em>,<em>Y</em>)</code></td><td><em>X</em> is B; <em>Y</em> is W</td><td>B</td><td>z=z<sub>X</sub>z<sub>Y</sub>; o=z<sub>X</sub>o<sub>Y</sub> or z<sub>Y</sub>o<sub>X</sub>; n=n<sub>X</sub> or z<sub>X</sub>n<sub>Y</sub>; d=d<sub>X</sub>d<sub>Y</sub>; u</td></tr>
<tr><td><code>or_b(<em>X</em>,<em>Z</em>)</code></td><td><em>X</em> is Bd; <em>Z</em> is Wd</td><td>B</td><td>z=z<sub>X</sub>z<sub>Z</sub>; o=z<sub>X</sub>o<sub>Y</sub> or z<sub>Y</sub>o<sub>X</sub>; d; u</td></tr>
<tr><td><code>or_c(<em>X</em>,<em>Z</em>)</code></td><td><em>X</em> is Bdu; <em>Z</em> is V</td><td>V</td><td>z=z<sub>X</sub>z<sub>Z</sub>; o=o<sub>X</sub>z<sub>Z</sub></td></tr>
<tr><td><code>or_d(<em>X</em>,<em>Z</em>)</code></td><td><em>X</em> is Bdu; <em>Z</em> is B</td><td>B</td><td>z=z<sub>X</sub>z<sub>Z</sub>; o=o<sub>X</sub>z<sub>Z</sub>; d=d<sub>Z</sub>; u=u<sub>Z</sub></td></tr>
<tr><td><code>or_i(<em>X</em>,<em>Z</em>)</code></td><td>both are B, K, or V</td><td>same as X/Z</td><td>o=z<sub>X</sub>z<sub>Z</sub>; u=u<sub>X</sub>u<sub>Z</sub>; d=d<sub>X</sub> or d<sub>Z</sub></td></tr>
<tr><td><code>andor(<em>X</em>,<em>Y</em>,<em>Z</em>)</code></td><td><em>X</em> is Bdu; <em>Y</em> and <em>Z</em> are both B, K, or V</td><td>same as Y/Z</td><td>z=z<sub>X</sub>z<sub>Y</sub>z<sub>Z</sub>; o=z<sub>X</sub>o<sub>Y</sub>o<sub>Z</sub> or o<sub>X</sub>z<sub>Y</sub>z<sub>Z</sub>; u=u<sub>Y</sub>u<sub>Z</sub>; d=d<sub>Z</sub></td></tr>
<tr><td><code>thresh(k,<em>X<sub>1</sub><em>,...,<em>X<sub>n</sub></em>)</code></td><td>1 < k < n; <em>X<sub>1</sub></em> is Bdu; others are Wdu</td><td>B</td><td>z=all are z; o=all are z except one is o; d; u</td></tr>
<tr><td><code>thresh_m(k,key<sub>1</sub>,...,key<sub>n</sub>)</code></td><td>1 ≤ k ≤ n</td><td>B</td><td>n; d; u</td></tr>
<tr><td><code>a:X</code></td><td><em>X</em> is B</td><td>W</td><td>d=d<sub>X</sub>; u=u<sub>X</sub></td></tr>
<tr><td><code>s:X</code></td><td><em>X</em> is Bo</td><td>W</td><td>d=d<sub>X</sub>; u=u<sub>X</sub></td></tr>
<tr><td><code>c:X</code></td><td><em>X</em> is K</td><td>B</td><td>o=o<sub>X</sub>; n=n<sub>X</sub>; d=d<sub>X</sub>; u</td></tr>
<tr><td><code>d:X</code></td><td><em>X</em> is Vz</td><td>B</td><td>o=z<sub>X</sub>; n; u; d</td></tr>
<tr><td><code>v:X</code></td><td><em>X</em> is B</td><td>V</td><td>z=z<sub>X</sub>; o=o<sub>X</sub>; n=n<sub>X</sub></td></tr>
<tr><td><code>j:X</code></td><td><em>X</em> is Bn</td><td>B</td><td>o=o<sub>X</sub>; n; d; u=u<sub>X</sub></td></tr>
<tr><td><code>n:X</code></td><td><em>X</em> is B</td><td>B</td><td>z=z<sub>X</sub>; o=o<sub>X</sub>; n=n<sub>X</sub>; d=d<sub>X</sub>; u</td></tr>
Various types of Bitcoin Scripts have different resource limitations, either through consensus or standardness. Some of them affect otherwise valid Miniscripts: <ul>
<li>Scripts over 10000 bytes are invalid by consensus (bare, P2SH, P2WSH, P2SH-P2WSH).</li>
<li>Scripts over 520 bytes are invalid by consensus (P2SH).</li>
<li>Script satisfactions where the total number of non-push opcodes plus the number of keys participating in all executed <code>thresh_m</code>s, is above 201, are invalid by consensus (bare, P2SH, P2WSH, P2SH-P2WSH).</li>
<li>Anything but <code>c:pk(key)</code> (P2PK), <code>c:pk_h(key)</code> (P2PKH), and <code>thresh_m(k,...)</code> up to n=3 is invalid by standardness (bare).</li>
<li>Scripts over 3600 bytes are invalid by standardness (P2WSH, P2SH-P2WSH).</li>
<li>Script satisfactions with a serialized <samp>scriptSig</samp> over 1650 bytes are invalid by standardness (P2SH).</li>
<li>Script satisfactions with a witness consisting of over 100 stack elements (excluding the script itself) are invalid by standardness (P2WSH, P2SH-P2WSH).</li>
The type system above guarantees that the corresponding Bitcoin Scripts are:<ul>
<li><b>consensus and standardness complete</b>: Assuming the resource limits listed in the previous section are not violated, for every way that the spending conditions associated with the Miniscript can be met, a witness can be constructed that passes Bitcoin's consensus rules and common standardness rules.</li>
<li><b>consensus sound</b>: It is not possible to construct a witness that is consensus valid for a Script unless the spending conditions are met. Since standardness rules permit only a subset of consensus-valid satisfactions (by definition), this property also implies <b>standardness soundness</b>.
The completeness property has been extensively tested for P2WSH by verifying large numbers of random satisfactions for random Miniscript expressions against Bitcoin Core's consensus and standardness implementation.
<p>In order for these properties to not just apply to script, but to an entire transaction, it's important that the witness commits to all data relevant for verification. In practice
this means that scripts whose conditions can be met without any digital signature are insecure. For example, if an output can be spent by simply passing a certain <samp>nLockTime</samp>
(an <code>after(n)</code> fragment in Miniscript) but without any digital signatures, an attacker can modify the <samp>nLockTime</samp> field in the spending transaction.
<h3class="card-header">Satisfactions and malleability</h3>
<divclass="card-block">
<h4>Basic satisfactions</h4>
<p>
The following table shows how to construct valid satisfactions and dissatisfactions for every Miniscript, using satisfactions and dissatisfactions of its subexpressions.
While following the table above to construct satisfactions is sufficient for meeting the completeness and soundness properties, it does not guarantee non-malleability.
</p>
<p>
Malleability is the ability for a third party (<em>not</em> a participant in the script) to modify an existing satisfaction into another valid satisfaction.
Since Segwit, malleating a transaction no longer breaks the validity of unconfirmed descendant transactions. However, unintentional malleability may still have a number of
much weaker undesirable effects. If a witness can be stuffed with additional data, the transaction's feerate will go down, potentially to the point where its ability to
propagate and get confirmed is impacted. Additionally, malleability can be exploited to add roundtrips to BIP152 block propagation, by trying to get different miners to mine different versions
of the same transaction.
</p>
<p>
Because of these reasons, Miniscript is actually designed to permit non-malleable signing. As this guarantee is restricted in nob-obvious ways, let's first state the assumptions:<ul>
<li>The attacker does not have access to any of the private keys of public keys that participate in the Script. Limiting the impact a rogue participant can have is a distinct attack model.</li>
<li>The attacker gets to see exactly one satisfying witness of the script. If he sees multiple, the protections defined here are not necessarily valid anymore.</li>
<li>No public keys appear more than once in the script.</li>
<li>We want something that works even when the attacker has access to all the hash preimages the honest participants have access to (even if the honest participants choose a satisfaction that does not reveal that preimage).</li>
Several ways to introduce malleability under the assumptions above exist:<ul>
<li>Dissatisfactions for <code>sha256(h)</code> and other hash locks are always malleable, as any 32-byte input suffices. An attacker can modify any such dissatisfaction into another one. Because of this, inside a non-malleable satisfaction, a hash lock can never be directly dissatisfied. Instead if must be protected by an <samp>OP_IF</samp> (e.g. <code>u:</code>) that skip execution of the hash lock check entirely when its satsifaction is not required.</li>
<li>For certain conjunctions (<code>and_b</code>, <code>andor</code>, and <code>thresh</code>) a dissatisfaction could be constructed that involves subexpressions that are actually satisfied. To prevent this, we must require that satisfying those subexpressions requires a digital signature. In that case, a malleability attacker cannot construct a satisfaction as we assume he has no access to private keys.</li>
<li>For <code>or_i</code> two possible ways for dissatisfying the expression exist: one involving the left subexpression and one involving the right one. To prevent the dissatisfaction from being malleable, we must make sure that at most one of the two is dissatisfiable.</code>
<li>For disjunctions (<code>or_*</code>, <code>andor</code>, and <code>thresh</code>) multiple ways of satisfaction exist. We must prevent malleability attackers from changing a satsifaction from one branch to another. Whenever a satisfaction exists for an expression that does not involve any signatures, we must take it. Otherwise the attacker could change the satisfaction to the non-signature requiring one. Whenever multiple ways exist that all require no signature, the result is inevitably malleable.</li>
<li><b>pk(HEX)</b>: Require public key HEX to sign.</li>
<li><b>time(NUMBER)</b>: Require that a relative time NUMBER has passed since creating the output.</li>
<li><b>hash(HEX)</b>: Require that the SHA256 preimage of HEX is revealed.</li>
<li><b>and(EXPR,EXPR)</b>: Require that both subexpressions are satisfied.</li>
<li><b>or([N@]EXPR,[N@]EXPR)</b>: Require that one of the subexpressions is satisfied. The numbers N indicate the relative probability of each of the subexpressions.</li>
<li><b>thresh(NUM,EXPR,EXPR,...)</b>: Require that NUM out of the following subexpressions are satisfied.</li>
</ul>
Shorthands:
<ul>
<li><b>C</b>: A dummy compressed public key (usable as argument to pk or multi)</li>
<li><b>U</b>: A dummy uncompressed public key (usable as argument to pk or multi)</li>
<li><b>H</b>: A dummy hash (usable as argument to hash)</li>
<tr><th>Type</th><th>Shorthand</th><th>Behavior under honest inputs</th><th>Behavior under adverserial inputs</th></tr>
<tr><td>Base</td><td>B</td><td>Takes its inputs from the top of the stack. Pushes a nonzero value of up to 4 bytes if the condition is satisfied, exactly zero otherwise.</td><td>Pushes zero onto the stack, or aborts.</td></tr>
<tr><td>Key</td><td>K</td><td>Takes its inputs from the top of the stack. Pushes a public key with which a checksig is to be done onto the stack.</td><td>Aborts.</td></tr>
<tr><td>Verify</td><td>V</td><td>Takes its inputs from the top of the stack, which must satisfy the condition. Does not push anything onto the stack.</td><td>Aborts.</td></tr>
<tr><td>Wrapped</td><td>W</td><td>Takes from the stack its inputs + element X at the top. If the inputs satisfy the condition, [t X] or [X t] is pushed, where t is a nonzero value of up to 4 bytes. If not, [0 X] or [X 0] is pushed.</td><td>Pushes [0 X] or [X 0] onto the stack, or aborts.</td></tr>
</table>
In addition, every expression can have zero or more of the following properties used for reasoning about correctness:<ul>
<li><b>z</b> "zero": Known to consume exactly zero stack elements. Conflicts with "o".</li>
<li><b>o</b> "one": Known to consume exactly one stack element. Conflicts with "z".</li>
<li><b>n</b> "nonzero": Known to consume at least one stack element, and the top element is never required to be 0 to satisfy the condition. Conflicts with "z". Impossible for W.</li>
<li><b>d</b> "dissatisfiable": There is a guaranteed way to this dissatisfy the expression. Impossible for V.</li>
<li><b>u</b> "unit": Satisfaction always results in an exact 1 on the stack (as opposed to arbitrary nonzero value). Impossible for V. Implied by K</li>
</ul>
There are also four more properties that let us reason about nonmalleability:<ul>
<li><b>e</b> "expr": A unique way to dissatisfy this expression exists which cannot be modified into another dissatisfaction by an attacker. Conflicts with "f". Implies "d". Impossible for V.</li>
<li><b>f</b> "forced": There is no way to dissatisfy the expression, either under honest or malicious input. Conflicts with "d" and "e". Implied by V.</li>
<li><b>s</b> "safe": Satisfying this expression requires at least one signature. This means a dissatisfaction cannot be converted into a satisfaction for this expression. Implied by K.</li>
<li><b>m</b> "nonmalleable": For every way the condition can be met, a unique satisfaction exists which cannot be modified into another satisfaction by an attacker. Implied by Z.</li>
