Skip to content

The engine

You have now read three games: Snap, Lol and Alba. Each has its own rules, its own state, its own moves, its own secrets and its own proofs. Yet one engine runs all three, and the same browser page and the same server serve them. This last section is about that engine: how it can run games it knows nothing about, and why you can trust what its proofs say.

One protocol, many games

The engine knows no game. It doesn't know what a card is, whose turn it is, or what a vote means. It knows only a list of questions that every game must answer:

  • How do you start a game from a config?
  • How many seats are there?
  • What does a move sent by a client mean, and what happens when someone makes it?
  • What may this viewer see, and which moves are offered to them?
  • What is happening now, in words, and who is the table waiting for?
  • Is the game over, and who won?

Each game answers these questions in its own Game.lean. The engine asks them, and builds everything else from the answers: the view each player is sent, the log of moves, the history of events and who may read each one, the players' names, the keys that open each seat. A game never has to do any of that itself, and the proofs about it are written once, for every game.

The games are separate games. Lol isn't a variant of Snap, and Alba isn't a variant of Lol; they share no rules. They share only the questions.

The files

File What it holds
Engine/Protocol.lean The Game class: the questions every game answers, and the shapes of the answers
Engine/Session.lean A table: a game with its log, events, names and keys, and the functions hosts call on it
Engine/Json.lean The engine's own small JSON type, with a renderer and a parser
Engine/Rng.lean The random number generator and the shuffle, so every deal can be replayed from its seed
Proofs/Engine/Guarantees.lean What the engine is proven to ensure, for every game
Proofs/Engine/Bookkeeping.lean Facts about the engine that every game's proofs use
Ffi/Export.lean The functions the hosts call, for every game, over raw bytes
Tools/Guarantees.lean The program that writes docs/GUARANTEES.md from the checked proofs

There is one more game in Games/: Counter.lean, a toy in which players take turns adding to a number. It exists to test the hosts and the C interface from end to end, with rules simple enough that any failure must be somewhere else.

In this section

  1. One class, many games: type classes, the Game class, and one instance for each game.
  2. A table: the session the engine keeps for each table, views and moves, keys and names, and what is proven about them.
  3. What you have to trust: Lean's checker, sorry and axioms, how the guarantees page is made, and how the proven code is the code that runs.