Where you are. Module 1 ended with a machine. miniledger v1 is an importable, double-entry, two-tier world whose submit/settle API can refuse a payment, name the exact moment one becomes final, and relabel reserves at the central bank without minting or losing a unit - and you proved it over a full scripted day. Module 0 gave you the map that machine implements: the two tiers, the clearing house, netting as compaction. What you have not seen is how a real economy drives the machine - not one hand-scripted payment at a time, but a whole country’s day of them, pushed through purpose-built systems that all end in the same reserve relabelling you can already narrate line by line. This module is those systems. This lesson is its map, and the workbench every later lesson stands on.
Four payments, four machines
Yesterday, if it was an ordinary weekday, four payments probably touched your life. Your salary landed on the dot, alongside every colleague’s. Your rent left overnight, unwatched. You tapped for a coffee and the terminal said yes before the cup was warm - the very tap module 0 lesson 1 dissected into five parties. And somewhere in your city, a conveyancer pressed a key and the price of a house crossed town alone, at once, in nothing’s company, because for that payment nobody tolerates company.
By module 1 lesson 8’s anatomy, these four are the same event: a payer’s deposit down, a payee’s deposit up, reserves relabelled at the central bank. Same ledger arithmetic, same two tiers, same six changed lines. Yet no country routes them through one system. Four different machines carried them, because a machine careful enough to move a house price is a wasteful way to move a coffee, and a machine cheap enough for coffee is a reckless way to move a house.
The idea in one paragraph
A country moves money on a handful of rails, and each rail is a different settlement of the three-way trade between speed, cost and size. Settle every payment the moment it arrives and you buy certainty at the price of reserves parked in advance; collect the day and net it, as module 0’s clearing house did, and everyday payments become nearly free at the price of everyone waiting; answer in seconds around the clock and someone must park the money before the payment exists; say yes now and move the money later and you have invented cards, plus the dispute machinery that choice drags behind it. This module rebuilds each of those answers as a program on the miniledger you built - the same World, the same submit and settle, driven four different ways. And because a comparison is honest only when the input is identical, the module opens by freezing its traffic: one seeded, deterministic day of 300 payments among six banks, which every rail you build will replay.
The map, lesson by lesson
Here is the whole module on one map.
Wider than the screen; scroll it sideways.
Before any machine, lesson 2 sharpens the two words every machine is arranged around: clearing, the work of agreeing who owes what, and settlement, the ledger commit that makes it final. You have used both words since module 0. What is new is treating the gap between them as a design axis - every lane in the figure is a different answer to when each happens.
Lessons 3 to 6 build the heavy-duty rail: the one the house purchase rode. It settles each payment one by one, at once, in reserves, and what it settles is final on the spot - which is exactly why it is reserved for payments too large or too urgent to share a machine with anyone. The price of that immediacy is the subject of lesson 4; lesson 5 measures the trade between reserves parked and delay accepted; and lesson 6 stages the rail’s characteristic failure - a queue where every bank waits to be paid before it pays, a deadlock you will cause on purpose - and the elegant cure that settles the whole stuck cycle at once with almost no money moving.
Lessons 7 and 8 build the batch that nets a day: the rail your salary and rent rode. It collects payments for hours, cancels offsetting flows with the netting you already know, and settles only the differences - module 0’s clearing house pattern, finally running as a program you wrote. Netting is what makes everyday payments cheap; lesson 8 walks the fine print, which is that on this rail a payment can arrive and still bounce later, because arrived and final are different days.
Lessons 9 and 10 build the always-on rail: settlement in seconds, at 3 a.m. on a Sunday, for coffee-sized payments - and the trick that pays for it, which is money parked before the payment exists. Lesson 10 is the scoreboard: a dated snapshot of where such rails actually run in the world, and the first of this module’s claims you will learn to re-research rather than trust.
Lessons 11 to 13 take cards, the strange one: a yes in seconds, the money days later, choreographed among four parties. Lesson 12 follows who pays whom on every sale and why regulators keep a hand on that dial; lesson 13 shows how a disputed payment is unwound with new entries rather than deletions, because nothing on a ledger is ever erased.
Two lessons close the loop. Lesson 14 puts wallets and pay-by-bank apps in their place: overlays riding rails you will by then have built yourself, and one question to ask of any of them - which rail settles this? Lesson 15 turns to what every lane in the figure has in common: none of these machines touches money without being told to, and the telling is a message. The language those messages speak - one structured, machine-readable grammar replacing decades of free text - feeds every rail on the map, and it gets the module’s last full lesson before the project.
The module ends where module 1 did, with a project: lesson 16 assembles the rails simulator, which runs the settling engines you will have built over one identical day of traffic and measures what each paid, in reserves parked and in waiting, to move it.
One day, every rail
Comparing rails is a benchmarking problem, and the first rule of benchmarking is to fix the workload. If the heavy-duty rail settles one day of traffic and the batch settles a different one, every number you measure is contaminated by the difference in traffic. So the module freezes one day and replays it: 300 payments among six banks - Alder, Birch and Cedar, which you drove in module 1’s project, joined by Dogwood, Elm and Fir - each bank serving five customers with mechanical names, fir-c5 for Fir’s fifth. Amounts are stylised, 10 to 500, everyday-sized on purpose; arrival minutes run 0 to 1439, one full day. The day is generated from a seeded random number generator, so it is the same day on every machine, every run, for every reader.
Check yourself
1. Name the four rails this module rebuilds, each by the trade it makes rather than by any official name.
The heavy-duty rail trades parked reserves for settlement that is immediate and final, one payment at a time, at any size. The batch trades delay for near-zero cost, by netting a day and settling only differences. The always-on rail trades money parked in advance for finality in seconds, around the clock. Cards trade a fast yes for money that moves days later, plus the dispute machinery that gap requires.
2. Why must every rail in this module replay the same fixture day, rather than each lesson inventing fresh traffic?
Because the module’s measurements are comparisons. If two rails settle different traffic, a difference in reserves parked or delay accepted could belong to either the machine or the traffic, and you cannot tell which. Freezing one seeded day makes the traffic a constant, so every measured difference belongs to the rail - and the seed makes the day identical on every reader’s machine, so your numbers are comparable with anyone’s.
3. The fixture contains no same-bank payments. What would one exercise, if it were included?
Nothing this module builds. Module 1 lesson 8 showed that a payment between two customers of one bank is two deposit edits on that bank’s own ledger: no reserves move, nothing crosses the two tiers, no other bank needs squaring with. Rails exist for the interbank case. A same-bank payment in the fixture would inflate the payment count while never touching a rail.
4. Before generating anything, the workbench settles one cross-bank sanity payment and asserts on both tiers. What is that guarding?
That the module’s foundation is the machine module 1 actually built. The sanity payment proves the canonical miniledger import resolves and its submit/settle still moves deposits at both banks and relabels reserves at the central bank - the whole two-tier anatomy - before the module builds fifteen more lessons on top. It also enforces the course rule that there is one canonical miniledger: the workbench imports it; it does not copy it.
Do this
Fifteen minutes, from module-02-domestic-rails. Open code/rails_workbench.py and run it as shipped:
python code/rails_workbench.pyThe sanity payment settles and prints its line; then the run dies at NotImplementedError, because generate_fixture is yours. Work the TODO(you): seed random.Random(7), draw 300 payments in exactly the draw order the comment specifies - minute, payer bank, payer, payee bank, payee, amount - then sort by minute (Python’s sort is stable, so ties keep draw order), number the sorted list 1 to 300, and return the dict. The asserts in the main block are the spec: exactly 300 payments, a second generation identical to the first, every payment cross-bank, every minute inside the day, every amount between 10 and 500, and arrival order from morning to midnight. Green ends with the line
fixture written: 300 payments, total value 76908, 6 banks - one day that every rail in this module will replayand fixture_day.json sitting next to the script: the day itself, written down, which later lessons read back through load_fixture(). The total is worth a glance. If yours is not 76908, your day is not the module’s day - the seed guarantees the same sequence of draws only if everyone draws in the same order, so a different total means a different draw order; reread the comment. The completed version is solutions/rails_workbench.py; compare after you are green.
What you can now do. You can run the module’s workbench and prove its foundation sound: one canonical miniledger import, one cross-bank payment settled across both tiers. You can regenerate the module’s seeded day - 300 payments, six banks, byte for byte identical on every run - and say why every rail must replay that same day for the module’s comparisons to mean anything. And you can name the four rails this module rebuilds by the trade each makes: immediacy paid for in parked reserves, cheapness paid for in delay, seconds-finality paid for in advance, and a fast yes paid for in deferred money and disputes. Lesson 2 sharpens the pair of words every one of those machines schedules differently - clearing and settlement - and turns the gap between them into the axis the whole module measures along.