rtshkmr/paxos_ocaml_demo

#+OPTIONS: toc:nil num:nil
#+STARTUP: inlineimages
#+AUTHOR: Ritesh Kumar

• 🐫 Paxos in OCaml — Desert Consensus Simulator

A deterministic, dependency-free event simulator demonstrating the Paxos consensus protocol through the metaphor of Saharan caravans coordinating across an unreliable desert. Custom scenarios can be built to play around too!

[[file:docs/pictures/complete_run_v2.gif]]

Read the full story: [[https://blog.rtshkmr.com/posts/songs_of_the_ocaml_compiler_i/][Songs of the OCaml Compiler — A 3-part series]]

---

** Quickstart
Please see the [[file:Makefile][Makefile to understand the available targets]] and read the runner scripts before doing this -- it's a good habit!

Assuming that you're running a unix-based machine (Linux, MacOS, BSD...), we shall build and run this locally (typically faster than fresh docker builds).

*** OCaml folks

Just run =make magic=!

*** First time setup
For folks who are trying OCaml for the first time, there's 3 steps to take:

1. Run =make setup=

   This setup script is for convenience and follows the instructions [[https://ocaml.org/install#linux_mac_bsd][from the official docs]]:

   • It installs [[https://opam.ocaml.org/][opam]] (the package manager)
   • It creates a local OCaml switch in =paxos/_opam=
   • It installs ocaml and dune using opam
   • It installs all dependencies that have been locked for this project

2. Update your =PATH= variable and reload your shell.

   Follow the instructions that =make setup= provides at the end of its run. Some common sources of error:

   • Remember to reload the shell (either by restarting your terminal or sourcing your config file e.g. =source ~/.zshrc=).

   • You'll need to be able to access =opam= and =dune= from your shell, updating the =PATH= variable will allow you to do so. If you call =which opam=, it should point you to when =opam= has been placed.

   • Remember to set your =opam switch= to the local switch. Calling =which dune= and =which ocaml= should be showing locations within the local opam switch.

3. Run =make magic=!
   It will:

   • check =opam= / =dune= are accessible
   • activates local opam switch
   • builds the project incrementally
   • runs simulators with the flags you supply it

This will spawn the simulator. If you need help, just type =/help= into the repl-like interface after the prompt (=>>>=).

---

** What This Is

This simulator shows how distributed systems achieve consensus under realistic failure conditions:

• Network partitions (sandstorms blocking communication between caravan formations)
• Node crashes (messengers collapsing mid-journey)
• Message delays (couriers taking uncertain paths across the dunes)

Five caravans — /Aghilas, Taziri, Amastan, Itri, and Tassadit/ — must agree on a campsite despite these challenges. The Paxos protocol ensures they never make contradictory decisions, even when the desert turns hostile.

Why a simulator? Distributed systems are invisible. This makes causality, message ordering, and failure modes /observable/ in a way that reading papers or studying production code cannot. You can pause time, replay scenarios, and actually /see/ why certain invariants matter.

Run =make magic max_log_level=debug= to see what's happening under the hood.

---

** Learn More

*** Blog Series
Deep dive into the design, implementation, and lessons learned

• [[https://blog.rtshkmr.com/posts/songs_of_the_ocaml_compiler_i/][Part I: Motivations & Design Grammar]]
• [[https://blog.rtshkmr.com/posts/songs_of_the_ocaml_compiler_ii/][Part II: Implementation & OCaml Ergonomics]] (coming soon)
• Part III: Evolution & Retrospectives /(coming soon)/

*** Key References:

• [[https://lamport.azurewebsites.net/pubs/paxos-simple.pdf]["Paxos Made Simple" – Leslie Lamport]]
• [[https://understandingpaxos.wordpress.com/]["Understanding Paxos"]] (blog post explainer)
• [[https://tigerbeetle.com/blog/2023-07-11-we-put-a-distributed-database-in-the-browser/][TigerBeetle's Deterministic Simulator]] (browser-based WASM game)

*** Prior Art:

• [[https://github.com/cocagne/paxos][Tom Cocagne's Paxos]] and [[https://github.com/cocagne/multi-paxos-example][Multi-Paxos]] implementations (Python)
• [[https://github.com/komamitsu/oraft][oraft]] — Raft consensus in OCaml
• [[https://github.com/openacid/abstract-paxos][Abstract Paxos]] — unified abstraction for clean architecture ideas

---

** Contributing / Feedback

This is a pedagogical project designed to make learning visible. I'm currently gathering feedback to iterate on this. If you have ideas for making it more teachable, clearer, or more engaging — please open an issue or reach out via email [[mailto:hello@rtshkmr.com][hello@rtshkmr]]!

The goal isn't /just/ working code; it's code that /teaches/ effectively.