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

Free lesson

Rollup 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 read6 commands

Many transfers, one short entry on the main chain

A busy chain can only run so much. A rollup runs the transfers somewhere else and writes two things on the main chain: the list of transfers, so anybody can check them, and one short hash of every balance after them. This lab shows the idea with a toy you can read, not a real chain.

By the end of this lesson

Note

I can explain how a rollup posts a batch and how a wrong batch is caught.

Key words

  • Rollup: a system that runs transfers off the main chain and posts them on it.
  • Batch: a group of transfers posted together.
  • State root: one hash that stands for every balance.
  • Sequencer: the one who orders the transfers and posts the batch.
  • Challenge window: the time in which a wrong batch can be disputed.
  • Blob: a block of data the main chain keeps for about 18 days.

Starter: what you already know

Note

Answer in your head. 1. What happens to a hash if one letter of the text changes? 2. How many times can you halve 16 before you reach 1? 3. Why can somebody not spend more than they have in a ledger? Answers: it changes completely; four times; every transfer is checked against the balance first.

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 is one container, jupyter, and the terminal reaches its Python with docker exec jupyter, which runs one command inside it. The JupyterLab link opens its web page, 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 batch ends in a state root

The script starts with ana 100, ben 50, chen 20 and dev 0 and runs four transfers. The third, chen sending 500, is skipped because chen has only 90, so its root does not change. The batch is posted at slot 100 as batch number 1. A second batch that does not start from the last root is refused, and prints None.

Command
docker exec jupyter python3 steps/batch.py

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

Bisection finds the one wrong step

A sequencer lies at transfer 11 of 16 and gives somebody 40 that nobody paid. A verifier replays the data and gets a different root. Instead of re-running all 16 steps on the main chain, the two sides ask about the middle: steps 8, 12, 10 and 11. Four questions find step 11, the main chain re-runs that one transfer, and batch 1 is reverted.

Command
docker exec jupyter python3 steps/dispute.py

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

Check

Tip

How many questions would bisection need for 32 steps? Answer: five, because each question halves what is left: 32, 16, 8, 4, 2, 1.

A challenge has to come in time

The window is 50400 slots of 12 seconds, which is 7.0 days. A batch posted at slot 1000 can still be challenged at slot 51399 and not at slot 51400, when it becomes final. A challenge against a step that was right fails, and the batch stands.

Command
docker exec jupyter python3 steps/window.py

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

A few random checks find hidden data

The data is stretched from 64 pieces to 128, so any 64 rebuild it. To hide it, a sequencer has to withhold more than half, so only 63 are published. Each client asks for a few random pieces. With one sample, 496 of 1000 clients notice; with 16 samples, all 1000 do.

Command
docker exec jupyter python3 steps/sampling.py

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

A blob does not last for ever

The blob store keeps a blob for 131072 slots, which is 18.2 days, then prunes it. It is still there when a 7 day window ends, so a challenger can replay it. A 21 day window would outlast the data, which is why the window must be shorter.

Command
docker exec jupyter python3 steps/expiry.py

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

Leaving the rollup takes time

A withdrawal asked for at slot 2000 is in the batch posted at slot 2400. It can leave once that batch is final, 7.1 days later. If the sequencer ignores the user, the user puts the withdrawal in the main chain's inbox, it must be included within a day, and it leaves 8.0 days after it was asked.

Command
docker exec jupyter python3 steps/withdraw.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 main chain checks every rollup transfer. In an optimistic rollup it checks none of them while nobody objects. It only re-runs one step when somebody challenges in time, which is why the data must be published and the window must be long enough.

The same work in a notebook

Open JupyterLab from the bar and double-click start.ipynb. It runs a one-transfer batch, a bisection over 100 steps and the window and blob lengths in days. Click a cell and press Shift and Enter to run it. The last cell is where your own question goes, and rollup.py is short enough to read in full.

Exit check

Tip

Answer without looking back. 1. What two things does a rollup post on the main chain? 2. How does bisection find a wrong step quickly? 3. Why must the challenge window end before a blob is pruned? 4. What can a user do if the sequencer ignores them? Answers: the data and the state root; it halves the steps each question; a challenger needs the data to replay the batch; use the main chain's inbox.

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 one service, JupyterLab with a toy rollup written in the Python standard library, and nothing here marks itself: the student hands in a notebook of their own, downloaded from JupyterLab, and a sentence on what it showed. Key learning points: 1. A rollup posts its data and a state root on the main chain. 2. A wrong batch is caught by bisection inside a challenge window. 3. The data must be published and kept long enough to replay. Common mistake: thinking the main chain checks every transfer. It is a model, not a chain, and has no coin. Equipment: the lab and a browser. Tip: play a guess-the-number game with 16 numbers first, so bisection is familiar. 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: Rollup lab: batches, fraud proofs, data availability and exits in Python

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