Learn to Build
a JAM Client.

The Graypaper tells you what a JAM client must do. This course shows you how one actually does it — with lasair, a conformance-passing OCaml implementation, as your executable reference.

Start with JAM Open the Conformance Explorer
406/406 GP 0.8.0 component vectors passing
1000 block-import traces, block for block
bit-exact PVM gas vs. reference polkavm
Targets Graypaper v0.8.0
Building a JAM Prize implementation?

Most lessons here show lasair's code, and lasair is an entry in the JAM Prize. The Prize rules ask teams to build clean-room, from the Graypaper and the public implementers' channel (rule 6), and to declare any JAM-implementation code they view (rule 7). Every lesson that shows lasair's code says so at the top; the conformance track shows it only in its binary-codec lesson.

Build a mixed-testnet JAM service (jamswap, a JAM service, on mixed-client nets) and Learning Observability show no implementation code.

The Path to a Working Client

Every JAM client is built in roughly the same order — each layer is provable against official test vectors before you build the next. This course follows that path:

  1. 1 Codec JAM's serialization — and the round-trip oracle that proves it
  2. 2 Merklization State as a Patricia trie; the root every block certifies
  3. 3 STFs The state transitions, one vector suite at a time
  4. 4 PVM The virtual machine: 13 registers, gas, host calls
  5. 5 Traces Import full blocks end to end, family by family
  6. 6 Conformance The fuzzer, the forensic loop, and proving you're done

Learning Tracks

Electives: OCaml for Lasair Contributors

The main path reads fine without writing OCaml. Take these tracks if you want to follow the examples closely or contribute to lasair itself.

Labs

Interactive explorers from lasair's M1 campaign. Their data comes from Graypaper 0.7.2; the ideas they teach carry over to 0.8.0 unchanged.

Real conformance vectors, opened up: block anatomy, the work-report lifecycle, PVM gas, and the annotated state diff each Merkle root certifies.

Mutation Lab

GP 0.7.2

Corrupt a valid block one way at a time and watch the target hold: never crash, never hang, reject without a state change.

Divergence Lab

GP 0.7.2 + 0.8.0

Sixteen real divergences: the 0.7.2 fuzzer campaign, the official fuzzer's first 0.8.0 batch, and three found by reading the code against the Graypaper, which no vector reaches. The report diff, the trace that found the cause, and the fix.

Real Code

Every example comes from lasair. No toy problems, no invented APIs.

Real Failures

The bugs that cost weeks — codec offsets, entry points, gas signs — taught before you hit them.

Vectors First

Every concept ends at a test vector you can run. If it isn't proven, it isn't done.

What is Lasair?

Lasair (Irish: "flame") is an OCaml implementation of the JAM protocol, targeting the Web3 Foundation JAM Implementer's Prize. It passes the full official conformance suite, and — as far as we know — it is the only JAM client with a teaching companion built alongside it.

This course teaches the protocol through lasair's codebase. By the end you'll understand JAM well enough to build your own client. lasair's source is not public yet, so the lessons quote the code they discuss and name the file it lives in.

Scope: lasair passed M1, the block importer, on Graypaper 0.7.2 (every live-fuzzer lane, tiny and full spec), and now targets Graypaper 0.8.0, passing every published 0.8.0 vector. It is building M2: block authoring, JAMNP-S networking, Safrole and GRANDPA finality. The course teaches the importer first; the networking track covers the M2 frontier.

Ready to Begin?

Start with the Introduction