Zero-knowledge proofs lab: commitments, Schnorr, Fiat-Shamir and Merkle proofs in Python
This lab gives each student a JupyterLab of their own with zero-knowledge proofs written in plain Python, short enough to read in full: the cave game played for many rounds, a hash commitment and a Pedersen commitment, the Schnorr identification protocol, the Fiat-Shamir step that makes it non-interactive, a Merkle tree with membership proofs, and a tiny arithmetic circuit with a range check. Nine small scripts each print what one idea does, the same every time.
The numbers are tiny on purpose, so every value fits on a line, and they are not secure: the group has 509 elements and one script finds a secret by trying them all. 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
What a proof of knowledge is, and its three properties: an honest prover always passes, a cheater passes 20 rounds of the cave game about once in a million, and the verifier learns nothing but the answer. They commit to a value with a hash and a salt and open it, add two Pedersen commitments without opening them, run Schnorr with a secret of 65 and a public key of 227, and see the secret fall out when a prover reuses its random number. A simulator fakes a transcript that checks out, which is why a transcript gives nothing away. They turn the protocol into a proof anybody can check with Fiat-Shamir, check that one name is in a list of 8 with a Merkle proof of 3 hashes, and check a witness against the gates of a small circuit, which is the statement a SNARK proves. It suits applied cryptography, security and blockchain courses; 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 zk.py, merkle.py, circuit.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.
- 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 Zero-knowledge: commitments, Schnorr and Merkle proofs.
- 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. On the lab's page, the lab bar has a link called JupyterLab: press it to open JupyterLab in your browser and read zk.py in the file editor. Then press Open terminal and type docker exec jupyter python3 steps/schnorr.py to see one Schnorr proof checked, and a secret worked out from two answers that reused a random number.
What to ask students to hand in
A notebook of their own that uses these files to answer one question they chose, such as how many cave rounds make cheating unlikely enough for a given risk, what goes wrong when a Schnorr prover reuses its random number, or how long a Merkle proof is for 16 or 1024 items, 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 simulated transcript shows that the protocol gives nothing away.
A basic lesson on this lab
Zero-Knowledge Proof Basics is a small lesson worked in this lab. In it a student plays the cave game for many rounds, commits to a move and opens it, runs the Schnorr protocol, fakes a transcript, makes a proof non-interactive with a hash, and checks that one name is on a list with a Merkle proof.
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 Zero-knowledge proofs from scratch is worked in the same lab.
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 and every random choice comes from a fixed seed, so every copy prints the same and nothing is downloaded. The limits are honest ones: the group and the field are tiny, so nothing here is secure, and no real circuit language or proof system runs in the lab, so circuits are plain Python gates and the proof system is explained in words. 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-zk-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 use a different group or another statement in the circuit.
- 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
- 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 secure enough to use?
- No. The group has 509 elements and the field 97, so every value fits on a line and a secret can be found by trying them all, which one script does. Real systems use numbers of about 256 bits and reviewed libraries. The lab is for learning the ideas.
- Does the lab run Noir or a real SNARK?
- No. The lab is one stock image with nothing downloaded when it starts, and it carries no circuit language or prover. The circuit is modelled as Python gates over a small field, which is the statement a SNARK proves, and the lessons explain what the proof system adds.