Bitcoin Script lab: timelocks, multisig, Miniscript and Taproot on a regtest node
This lab gives each student a real Bitcoin Core node on a private regtest chain, and a JupyterLab of plain Python beside it. When it starts, the node mines 101 blocks, sends one transaction that splits a block's reward into six outputs (a payment, a timelock, a 2-of-3 multisig, a Taproot output, a Miniscript policy and change) and mines block 102. Short scripts then show the node fixed, signed spends of those outputs, and it checks each one fully: the same answers every time, because the clock is fixed.
It is technical only: regtest coins exist inside each copy and have no value, the keys are public examples, and no private key is in the lab. Every copy has no route to the internet and none to any other student, the node connects to no other node, and nothing is downloaded into it.
What students learn
How a transaction spends whole outputs and pays change, and how its fee and fee rate are worked out: the lab's transaction pays 626 sats for 313 virtual bytes. How a script runs on a stack, in a toy machine they can read, and how a P2WPKH output checks a key and a signature. How a CLTV timelock refuses a spend as non-final until the chain is high enough, and how a CSV timelock counts blocks since confirmation. How a 2-of-3 multisig behind P2WSH refuses one signature and takes two, and how a spending policy becomes Miniscript and then Script, checked by the node's own descriptors. How a Taproot output is spent by its key path in 99 virtual bytes or by one hidden script in 125, and why that helps privacy. How a payment channel revokes old states and punishes whoever broadcasts one. And how a replacement transaction must pay more than what it pushes out, and what pinning does. It suits blockchain, security and distributed systems courses; check your own awarding body's unit for the exact wording, none is quoted here.
Run it in your browser
The lab starts two services. bitcoind is the stock Bitcoin Core image, which writes its settings and its scripts, builds the chain and leaves one payment in the mempool. jupyter writes btc.py, scriptvm.py, miniscript.py, paychan.py, a starter notebook and short scripts into its work folder. JupyterLab asks for no token, because the platform's own door already knows who is opening it. The terminal beside the lab has neither a node nor Python, so it reaches them with docker exec bitcoind and docker exec jupyter, followed by the command to run inside.
- Open the Container page. Open Build on the bar and choose Run a container. Anybody may open it, and the Git lab and the SQL lab start with no account. Every other lab needs a free account: create one, sign in, then press Start.
- Find the lab. The Sample labs card lists every sample. Find Bitcoin Script: timelocks, multisig and Taproot on regtest.
- Press Start. Start runs it as it is, in one press. Edit the file first opens the compose file so you can change it before you start.
- Open it. Press Open terminal and type docker exec bitcoind sh steps/cltv.sh to see a timelocked spend refused as non-final at height 102. Then press the JupyterLab link on the lab bar to open JupyterLab in your browser and read miniscript.py in the file editor.
What to ask students to hand in
A notebook of their own that uses these files to answer one question they chose, such as which signers can spend a policy they wrote, how much larger a script path spend is than a key path spend, or who gets the coins when an old channel state is broadcast and nobody is watching, downloaded from JupyterLab with File, Download. Then a sentence or two in their own words on what they found. Nothing is marked automatically: the sentence shows whether it was understood. For stronger work ask them to explain why a P2WSH spend shows every branch of its script and a Taproot script path spend shows only one.
A basic lesson on this lab
Bitcoin Script Basics is a small lesson worked in this lab. In it a student reads the chain and its unspent outputs, runs a script on a stack, tries a timelocked spend, spends a 2-of-3 multisig and a Taproot output, and sees an old payment channel state punished.
Free personal accounts have it in the Basics module, which is on Home, and every college can copy it from the Library's Basics folder. It is deliberately small: it shows a teacher what a lesson worked in a lab is, and the lab does the rest. Copy it into a module of your own to change it. The undergraduate module Bitcoin Script, Taproot and payment channels on regtest is worked in the same lab.
The code on GitHub
The compose file has no Dockerfile: it runs two stock public images, Bitcoin Core (bitcoin/bitcoin, MIT) and the Jupyter Docker Stacks' own scipy-notebook (BSD-3-Clause), each pinned to a tag and run as its own unprivileged account, the node with 192 MB of memory and JupyterLab with 512 MB. Neither image is distributed by us. The file writes every script from fixed text when it starts, the node's clock is fixed and every spend was signed in advance, so every copy prints the same and nothing is downloaded. The limits are honest ones: no Lightning node runs in the lab, so a payment channel is a Python model of its rules, and the policy compiler is a tiny one of our own whose output the node checks. Nothing is kept when the lab stops, so a student downloads their notebook first.
Set it as work
Say in the task what to hand in.
- Make the lab. In your module add a task and choose the Container lab card, then In a GitHub repository. Give https://github.com/mitsurutech/lab-bitcoin-lab with the branch main. The compose file is the default, compose.yaml. Fork the repository first if you want to change it, for example to add a spend of your own or a different policy for the toy compiler.
- Publish and try it. Publish pins the commit you were shown, so a later change in the repository does not alter a lab you have already set. Start your own copy first.
- Hand it out. Assign it like any task, with a due date if you want one, and say in the task what to do and what to hand in.
- Mark what is handed in. Open a student’s copy and the work they handed in, mark it, and send it back with a reason if it needs more.
Try this lab, and what it costs
A free personal account can work through the basic lessons in this lab, with enough free credit each month to follow most lessons and no card. For a class, a school or college has its first 365 days free for up to 50 students, then pays per student a year, with every lab included and staff free.
Questions people ask
- Are these real bitcoins?
- No. Regtest is a private test chain inside each student's lab. Its coins cannot leave it and have no value, and the lab has no route to the internet. The module is about how the system works, never about prices or trading.
- Why does the terminal use docker exec bitcoind and docker exec jupyter?
- The lab's terminal carries a few clients, and neither a Bitcoin node nor Python. docker exec runs a command inside one of the lab's own containers: bitcoind has the node and bitcoin-cli, and jupyter has Python.
- Why does every run print the same?
- The node's clock is fixed and it talks to no other node, so the blocks it mines at start have the same hashes every time. The spends a lesson shows were signed in advance and are only shown to the node with testmempoolaccept, which checks them and changes nothing. The one script that mines more blocks changes the height, which the lesson says.
- Does the lab run a Lightning node?
- No. No image that runs one offline on a regtest chain, with nothing downloaded, is pinned for this lab. The payment channel lesson uses paychan.py, a short Python model of a channel's states, revocation and punishment, and explains the real mechanism.