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
| Word | What it means | Example |
|---|---|---|
| Multisig | a lock needing several signatures | 2 of 3 |
| Threshold | how many of the listed keys must sign | |
| P2WSH | an output locked to the hash of a script | |
| Policy | who may spend, written for people to read | |
| Miniscript | a structured way to write Script that tools can analyse | |
| Descriptor | a 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
docker exec bitcoind sh steps/multisig.shShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: what the node said
| Witness | Allowed | Why |
|---|---|---|
| Empty item, Alice's signature, script | false | Operation not valid with the current stack size |
| Empty item, Alice's and Bob's signatures, script | true | Two 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
docker exec jupyter python3 steps/policy.pyShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: policy, Miniscript, script
| Step | Alice, or Bob after 144 blocks |
|---|---|
| Policy | or(pk(alice),and(pk(bob),older(144))) |
| Miniscript | or_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 |
| Size | 77 bytes |
| Ways to spend | alice; bob after 144 blocks |
The cells students fill in are left blank in this preview.
Let the node check the same policy
docker exec bitcoind sh steps/miniscript.shShown 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?
# 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?