Block building and MEV lab: mempool, sandwiches, auctions and defences in Python
This lab gives each student a JupyterLab of their own with a toy chain written in plain Python, short enough to read in full: a public mempool, a constant-product swap pool, block builders ordering transactions, a relay, a sealed-bid auction for the block and a proposer. Twelve small scripts each print what one idea does, the same every time.
It is taught defensively. Students measure what front-running and a sandwich do to a simulated user so that they can design and use systems that resist them: slippage limits, private submission, batch auctions, commit-reveal and fair ordering. The two tokens, red and blue, are invented and worth nothing, nothing here is about trading or money, and every copy has no route to the internet and none to any other student.
What students learn
Why the order of transactions matters: the mempool is a public queue anybody can read, and the same five transactions give different results in arrival order and in tip order. How a constant-product pool prices a swap, and what a sandwich does to it: a swap of 500 red pays 476 blue alone and 395 when a bot swaps 1000 red just before it, and the bot ends with 88 more red. How proposer-builder separation works, with a relay refusing two invalid bids and the proposer signing the best valid one. How a slippage limit of 1% shrinks the largest attack from 3000 red to 56 and its gain from 205 to 4, how private submission, batch auctions, commit-reveal and ordering by the median time defend users, and how to measure who receives the value and how few builders build most blocks. It suits blockchain, distributed systems and security 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 mev.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 Block building: mempool, sandwiches and auctions.
- 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 mev.py in the file editor. Then press Open terminal and type docker exec jupyter python3 steps/sandwich.py to see what a sandwich around one swap costs the user.
What to ask students to hand in
A notebook of their own that uses mev.py to answer one question they chose, such as how tight a slippage limit must be before a sandwich gains nothing, whether a bigger pool protects a user, or how the order changes when the median of five nodes decides it, 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 say which defence moves trust to somebody else, and to whom.
A basic lesson on this lab
Block Building Basics is a small lesson worked in this lab. In it a student reads the public mempool, swaps on the pool, measures a sandwich, watches a builder auction, sees a slippage limit shrink an attack and checks a commit-reveal.
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 Block building, ordering and MEV, taught defensively, 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: no real chain, client, relay or builder runs in the lab, and the pool charges no fee, so the numbers stay easy to follow. 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-mev-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 bigger pool or other bids in the auction.
- 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.
- Does this teach people to attack users or to trade?
- No. Everything is simulated on invented tokens worth nothing, with no network, and the attack is measured only to show the harm and test the defences. Nothing here is about prices, profit or money, and the lab gives no advice about any product.
- Does the lab run a real chain or MEV-Boost?
- No. The lab is one stock image with nothing downloaded when it starts, and it carries no chain client, relay or builder. They are modelled in a short Python file, and the lessons explain what the real ones add.