Blockchain lab: a toy chain in Python to read, break, mine and sign

This lab gives each student a JupyterLab of their own with a toy blockchain written in plain Python, short enough to read in full: blocks that hold each other's hashes, mining, a ledger that works out balances from payments, a signature made only of hashes, and two chains that disagree. Six small scripts print what each idea does, the same every time.

It is a toy that teaches the ideas. It has no coin, no network, no market and no price, it gives no advice about money, and it is not secure enough to use for real. It is not an attack lab either: every copy has no route to the internet and none to any other student, and nothing is downloaded into it.

What students learn

How a hash is a fingerprint of some data, and how a block that holds the hash of the one before it makes a chain. They break a chain by changing one amount and see the check fail at the changed block, then mine that block again and see it fail at the next one instead. They see mining as trial and error, 15 tries for one leading zero and 109028 for four, so the work grows fast with the difficulty. They work balances out from payments and see an overspend refused, check a hash-based signature and watch one changed letter break it, and settle a fork by following the chain with more work. It suits introductions to computer security, distributed systems and data structures; check your own awarding body's unit for the exact wording, none is quoted here.

Run it in your browser

The lab starts one service, jupyter, which writes chain.py, ledger.py, lamport.py, a starter notebook and the short scripts into its work folder, with nothing downloaded. JupyterLab asks for no token, because the platform's own door already knows who is opening it. The terminal beside the lab has no Python of its own, so it reaches the lab's with docker exec jupyter, followed by the command to run inside.

  1. 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.
  2. Find the lab. The Sample labs card lists every sample. Find Blockchain: a toy chain in Python.
  3. 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.
  4. Open it. On the lab's page, the lab bar has a link called JupyterLab: press it to open JupyterLab in your browser and read chain.py in the file editor. Then press Open terminal and type docker exec jupyter python3 steps/link.py to see three blocks, each with the hash of the one before it.

What to ask students to hand in

A notebook of their own that uses chain.py to answer one question they chose, such as how the number of tries grows with the difficulty, what it takes to change an old block and still have a valid chain, or what happens to a fork when one side has a higher difficulty, 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 valid chain does not show that every payment in it is true.

A basic lesson on this lab

Blockchain Basics is a small lesson worked in this lab. In it a student links three blocks, changes one amount and watches the check fail, mines a block at four difficulties, works out balances and sees an overspend refused, signs a message and breaks the signature with one letter, and settles a fork by the chain with more work.

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 code on GitHub

The compose file has no Dockerfile: it runs one stock public image, the Jupyter Docker Stacks' own scipy-notebook, pinned to a dated tag, as its own unprivileged account with 512 MB of memory, and the toy uses only Python's standard library. The image is licensed BSD-3-Clause and is not distributed by us. The file writes every Python file from fixed text when it starts, mining always begins at nonce 0 and the signature keys come from a fixed seed, so every copy prints the same and nothing is downloaded. The limits are honest ones: it is one machine and not a network, a block holds a short list of payments, the signature key signs one message only, and 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.

  1. 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-blockchain-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 change the toy chain.
  2. 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.
  3. 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.
  4. 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

Why is there no token or password to type?
A lab's web page is reached only through the platform's own door, which already knows who you are and lets in only you and the staff who teach your module. So JupyterLab is started with no token. Do not run it like that on a machine anybody else can reach.
Why does the terminal use docker exec jupyter?
The lab's terminal carries a few clients and no Python. docker exec jupyter runs a command inside the lab's own container, which has Python. JupyterLab also has a terminal of its own, under File, New, Terminal.
Is this a real blockchain?
It is a toy for the ideas. It shows how hashes link blocks, how mining is trial and error, how a ledger and a signature fit in and how a fork is settled. It has no network, no coin and no value, and it is not safe to use for real. Nothing in it is advice about money.