Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

Multisig, spending policies and Miniscript

After this lesson: I can check which signers and waits can spend a policy.

70 min lesson3 commandsBitcoin Script lab: timelocks, multisig, Miniscript and Taproot on a regtest node

Two keys out of three

A club keeps its savings so that any two of its three officers must agree before money leaves. If one officer loses a key, the other two can still act.

Bitcoin can write that rule into an output. This lesson writes rules like it, reads them back and lets the node check them.

By the end of this lesson

Note

I can check which signers and waits can spend a policy.

Key words

WordWhat it meansExample
Multisiga lock needing several signatures2 of 3
Thresholdhow many of the listed keys must sign
P2WSHan output locked to the hash of a script
Policywho may spend, written for people to read
Miniscripta structured way to write Script that tools can analyse
Descriptora text that tells a wallet exactly how an output is locked

The cells students fill in are left blank in this preview.

OP_CHECKMULTISIG counts signatures

The lab's output 2 is locked by "2, three keys, 3, OP_CHECKMULTISIG". The first number is the threshold and the second is how many keys there are.

The whole script is too long for an address, so the output holds its SHA-256 hash. That is P2WSH. The spender shows the script in the witness, and the node checks it matches the hash before running it.

Spend the multisig with one, then two

Command
docker exec bitcoind sh steps/multisig.sh

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: what the node said

WitnessAllowedWhy
Empty item, Alice's signature, scriptfalseOperation not valid with the current stack size
Empty item, Alice's and Bob's signatures, scripttrueTwo of three, in the keys' order

The cells students fill in are left blank in this preview.

Why the witness starts with an empty item

Note

OP_CHECKMULTISIG takes one more item off the stack than it needs. That old bug cannot be fixed without splitting the network, so every multisig spend begins with an empty item for it to take.

A policy is written for people

A policy says who may spend, in plain terms. For example: "Alice, or Bob after 144 blocks." Writing the script for it by hand is easy to get wrong.

Miniscript is a way to write Script from a small set of parts, so a program can check what a script allows. A compiler turns a policy into Miniscript, and Miniscript maps straight onto Script.

Compile two policies with the lab's toy

Command
docker exec jupyter python3 steps/policy.py

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: policy, Miniscript, script

StepAlice, or Bob after 144 blocks
Policyor(pk(alice),and(pk(bob),older(144)))
Miniscriptor_d(pk(alice),and_v(v:pk(bob),older(144)))
Script<alice> OP_CHECKSIG OP_IFDUP OP_NOTIF <bob> OP_CHECKSIGVERIFY 144 OP_CHECKSEQUENCEVERIFY OP_ENDIF
Size77 bytes
Ways to spendalice; bob after 144 blocks

The cells students fill in are left blank in this preview.

Let the node check the same policy

Command
docker exec bitcoind sh steps/miniscript.sh

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

The node and the toy agree

The node read the Miniscript as a descriptor and worked out bcrt1qss48..., the same address the toy printed. So the toy built the same script.

Alice's spend was allowed. Bob's was refused as non-BIP68-final, because the coin is only a few blocks old and his branch waits 144.

A common mistake

Warning

Many people think an address shows the rules of its coins. A P2WSH address is only a hash. The rules appear when the coins are spent, and then every branch of the script is shown, used or not.

Try it: which way opens?

Code: python
# A policy as a list of ways to spend: who signs, and how long to wait.
ways = [
    ({"alice"}, 0),
    ({"bob"}, 144),
]

signed = {"bob"}
age = 50            # blocks since the coin was confirmed

for names, wait in ways:
    ok = names <= signed and age >= wait
    print("needs", sorted(names), "after", wait, "blocks:", ok)
# Change age to 144, then signed to {"alice"}. Which way opens each time?

About this lab and its source: Bitcoin Script lab: timelocks, multisig, Miniscript and Taproot on a regtest node

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.