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

Free lesson

Bitcoin Script Basics

The whole lesson is free and interactive. Read it here, or press Start lab to run it for real in a live lab, with no account needed.

Container lab10 min read7 commands

Rules written into the coins themselves

Every coin on a Bitcoin chain carries a tiny program that says who may spend it. It might say one key, any two of three keys, or not before a certain block. This lab gives you a private chain called regtest, where you mine the blocks yourself. Its coins have no value, so you can try anything.

By the end of this lesson

Note

I can explain how a script on an output decides who may spend it.

Key words

  • Output: an amount locked by a script.
  • Script: the small program that locks an output.
  • Stack: a pile where the last item in is the first out.
  • Timelock: a rule that a coin waits until a block height.
  • Multisig: a lock that needs several signatures.
  • Taproot: an output that is one key, with hidden backup scripts.

Starter: what you already know

Note

Answer in your head. 1. What does a digital signature prove? 2. What happens to a hash if you change one letter of the message? 3. Why does each block hold the hash of the one before? Answers: that the holder of a private key agreed; it changes completely; so changing an old block breaks the chain.

Before you start

Note

Press Start the lab on the bar at the top of this lesson and wait until it says it is running. There are two containers. bitcoind is the node, and jupyter has Python. The terminal reaches them with docker exec bitcoind and docker exec jupyter, which run one command inside each. The JupyterLab link opens the notebook, port 8888. Each Run button below types its command into your lab's terminal, one after another in the same session. To watch them, or to type your own, press Open terminal on the bar.

A chain of your own

When the lab started, its node mined 101 blocks and paid every reward to Alice. A reward can only be spent once 100 more blocks are on top. Then it sent one transaction and mined block 102, so the node answers 102.

Command
docker exec bitcoind bitcoin-cli getblockcount

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

Coins are outputs, not balances

The node keeps the outputs nobody has spent. Block 1's reward is spent, so the node prints nothing for it. The lab's transaction made six outputs: 10 coins to Bob, four of 5 coins locked by scripts, and 19.99999374 coins of change back to Alice. The missing 0.00000626 is the fee.

Command
docker exec bitcoind sh steps/utxo.sh

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

A script runs on a stack

Script reads items left to right. Data goes on top of a stack, and an opcode works on the top items. In this toy, Alice's key matches the hash in the lock and her spend ends with 1, so it passes. Bob's key hashes to something else, so his spend stops at OP_EQUALVERIFY.

Command
docker exec jupyter python3 steps/stack.py

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

A timelock makes a coin wait

Output 1 says 110 OP_CHECKLOCKTIMEVERIFY: it cannot be spent before block 111. The chain is at 102, so the node refuses a signed spend as non-final. A spend that claims a smaller locktime fails the script: Locktime requirement not satisfied.

Command
docker exec bitcoind sh steps/cltv.sh

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

Check

Tip

What would make the timelocked spend acceptable? Answer: more blocks. Once the chain reaches height 110, the next block is 111 and the same spend is allowed.

Two signatures out of three

Output 2 needs any two of Alice, Bob and Carol. The node refuses a spend with Alice's signature alone and allows one with Alice's and Bob's. The node checks real signatures here, and no private key is in the lab: the spends were signed in advance.

Command
docker exec bitcoind sh steps/multisig.sh

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

Taproot: one key, hidden scripts

Output 3 is Taproot. Alice can spend it with one signature, the key path: 99 virtual bytes. Or Bob can show one hidden script and a short proof it belongs: the script path, 125 virtual bytes. Scripts nobody uses are never shown.

Command
docker exec bitcoind sh steps/taproot.sh

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

A payment channel punishes an old state

A channel lets two people pay each other many times with only two transactions on chain. Each payment makes a new state and cancels the old one. If Alice broadcasts an old state and Bob is watching, Bob takes all 100000 sats. This part is a Python model: no Lightning node runs in the lab.

Command
docker exec jupyter python3 steps/cheat.py

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

A common mistake

Warning

Many people think the chain stores a balance for each person. It stores unspent outputs, each with its own lock. A balance is a sum a wallet works out by adding up the outputs it can unlock.

The same work in a notebook

Open JupyterLab from the bar and double-click start.ipynb. It reads the lab's transaction, runs a script, compiles a policy and broadcasts a channel state. Click a cell and press Shift and Enter to run it. The last cell is where your own question goes.

Exit check

Tip

Answer without looking back. 1. What does the node keep instead of balances? 2. Why did Bob's toy spend stop? 3. How many signatures does the 2-of-3 output need? 4. Which Taproot spend is smaller? Answers: unspent outputs; his key did not match the hash; two; the key path.

For teachers

Tip

This lesson is a small example of a lesson worked in a lab: the steps and the Run buttons are the lesson, and the lab is each student's own copy. The lab is two services, a Bitcoin Core node on regtest and a JupyterLab of plain Python, and nothing here marks itself: the student hands in a notebook of their own and a sentence on what it showed. Key learning points: 1. Outputs are locked by scripts. 2. Timelocks, multisig and Taproot are rules a node checks. 3. A channel keeps payments off chain. Common mistake: thinking the chain stores balances. Regtest coins have no value; keep it technical. Equipment: the lab and a browser. Tip: draw six boxes with padlocks for the six outputs before the first Run. Copy it into your own module and change it, or build one from scratch with the Lab menu in the lesson builder.

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

Teaching a class? Set these lessons for your students with marking and a lab for every student.