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

Free lesson

Script: locks, keys and timelocks

After this lesson: I can follow a script on a stack and say whether a spend passes.

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

A padlock written as a tiny program

Every output in the last lesson had a locking script. To spend it, you hand over data that makes the script finish with "true". Nodes all over the network run the same check.

The language is called Script. It has no loops, so every script ends quickly.

By the end of this lesson

Note

I can follow a script on a stack and say whether a spend passes.

Key words

WordWhat it meansExample
Stacka pile where the last item in is the first out
Opcodeone instruction in a scriptOP_DUP
Locking scriptthe rules written on an output
Witnessthe data a spender gives to meet the rules
Timelocka rule that a coin waits until a height
Locktimethe field saying the earliest block for a transaction

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

Script runs on a stack

A script is a list of items read from left to right. A number or some data is pushed on top of the stack. An opcode takes items off the top, works on them and may push a result.

OP_ADD takes two numbers and pushes their sum. OP_EQUAL pushes 1 if the two top items match and 0 if not. The spend passes if the stack ends with a true item on top.

Watch three scripts run

Command
docker exec jupyter python3 steps/stack.py

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

Worked example: Alice spends her coin

ItemWhat it doesStack after
sig:alice, aliceThe spender pushes a signature and a keysig:alice alice
OP_DUPCopies the keysig:alice alice alice
OP_HASH160Hashes the copysig:alice alice 49099657..
49099657..The lock pushes the hash it expectstwo equal hashes on top
OP_EQUALVERIFYStops unless they matchsig:alice alice
OP_CHECKSIGChecks the signature against the key1, so the spend passes

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

Try it: run a script by hand

Code: python
# A Python list makes a good stack: append pushes, pop takes the top.
stack = []
stack.append(7)                 # push 7
stack.append(stack[-1])         # OP_DUP copies the top
right = stack.pop()
left = stack.pop()
stack.append(left + right)      # OP_ADD
print("after OP_ADD:", stack)

stack.append(14)                # push 14
right = stack.pop()
left = stack.pop()
stack.append(1 if left == right else 0)   # OP_EQUAL
print("top of the stack:", stack[-1])
# Change 14 to 15 and run again. Would this script let a coin be spent?

Segwit moves the key into the witness

The old form, pay to public key hash, puts that whole script on the output. Its segwit form, P2WPKH, writes only a version number and the 20-byte key hash.

The node knows what version 0 with 20 bytes means and runs the same check. The signature and key travel in the witness, which weighs less. That is why output 0 showed witness_v0_keyhash.

Two kinds of timelock

OP_CHECKLOCKTIMEVERIFY, or CLTV, is absolute: the coin waits until the chain reaches a height. The spending transaction must set its locktime to at least that height. A transaction with locktime 110 is valid only in block 111 or later.

OP_CHECKSEQUENCEVERIFY, or CSV, is relative: the coin waits a number of blocks after it was confirmed.

Try to spend the timelocked output too early

Command
docker exec bitcoind sh steps/cltv.sh

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

Worked example: two refusals at height 102

SpendThe node saidWhy
Locktime 110non-finalBlock 103 is too early for locktime 110
Locktime 100Locktime requirement not satisfiedThe script asks for at least 110

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

Mine eight empty blocks

Command
docker exec bitcoind sh steps/mine.sh

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

Try the same spend at height 110

Command
docker exec bitcoind sh steps/cltv.sh

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

A common mistake

Warning

Many people think a timelocked coin moves by itself when the height arrives. Nothing moves on its own. The height only makes a spend possible, and somebody still has to sign and send it.

See both rules as a table

Command
docker exec jupyter python3 steps/timelock.py

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

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.