Compiling RISCV-SAIL Into Lean4 Cpuu

2026-03-22T00:00:00+00:00

These notes re-cap the steps required to transplile the RISC-V sail specification to Lean. NOTE: As confirmed from the original documentation, only the non-computable Lean code builds and compiles cleanly. Some work is still needed to get the executable CPU to work. I do not imagine a whole lot, but as of the date of writing this, the executable build is not clean.</p> </div>

Tested on:</p>

macOS (Apple Silicon)</li>

Intel CPU Arch Linux (TODO:)</li> </ul>

Step 0: Clone Both Repos</h2>

Here I've forked the two repositories with the hope of eventually fixing the executable issue. But there's nothing special about my fork right now. Cloning the original repos will also work.</p>

git</span> clone</span> git@github.com:abiswas3/sail-riscv.git</span></span>
git</span> clone</span> git@github.com:abiswas3/sail.git</span></span></code></pre>parent/</span></span>
├── sail/                  # Sail compiler (transpiler) -- clone from github.com/rems-project/sail</span></span>
└── sail-riscv/            # This repo -- RISC-V ISA model written in Sail</span></span></code></pre>Step 1: Install System Dependencies</h2>

  
  Note To Reader</div>
  
  I do not particularly understand the Sail DSL, nor am I an expert ocaml programmer.
These steps mostly follow the README.md</code>'s in the repo, a bit of googling and some Claude code help.
Hopefully with time, I will be able to write a better version of what the hell is going on.</p>

</div>
macOS (Homebrew)</h3>
xcode-select</span> -</span>-install</span>    #</span> if not already done</span></span>
brew</span> install</span> opam</span> gmp</span> z3</span> pkgconf</span> cmake</span></span></code></pre>Arch Linux</h3>
sudo</span> pacman</span> -</span>S</span> opam</span>        #</span> OCaml package manager -- needed to fetch and install Sail's OCaml dependencies</span></span>
sudo</span> pacman</span> -</span>S</span> gmp</span>         #</span> GNU Multiple Precision arithmetic library -- Sail uses it internally for big integer arithmetic</span></span>
sudo</span> pacman</span> -</span>S</span> z3</span>          #</span> SMT solver from Microsoft Research -- Sail calls Z3 during type-checking to prove</span></span>
                           #</span>   arithmetic constraints on dependent types (e.g. that bitvector widths are correct)</span></span>
sudo</span> pacman</span> -</span>S</span> cmake</span>       #</span> build system generator -- sail-riscv uses CMake to orchestrate the Sail-to-Lean code generation</span></span>
sudo</span> pacman</span> -</span>S</span> base-devel</span>  #</span> C compiler, make, binutils, etc. -- OCaml's runtime is written in C and some opam</span></span>
                           #</span>   packages have C bindings (e.g. GMP). Also provides C++ compiler which sail-riscv's</span></span>
                           #</span>   CMake build needs for the emulator harness, even if you only want Lean output.</span></span>
sudo</span> pacman</span> -</span>S</span> pkgconf</span>     #</span> pkg-config implementation -- CMake uses it to locate system libraries like GMP</span></span></code></pre>Both Platforms: Initialize opam (one-time)</h3>
Run the following code from anywhere -- opam stores its state in ~/.opam/</code>.</p>
TODO:</strong> ocaml crash course</p>
opam</span> init</span>                 #</span> follow prompts, say yes to shell setup</span></span>
eval</span> $(</span>opam</span> env</span>)</span>          #</span> or restart your shell</span></span></code></pre>
opam init</code> creates the ~/.opam/</code> directory, downloads the OCaml package registry, and
installs a default OCaml compiler.
eval $(opam env)</code> sets shell environment variables (PATH</code>, OCAML_TOPLEVEL_PATH</code>, etc.) so that your shell can find the OCaml tools and
libraries that opam installed.
You need to run eval $(opam env)</code> in each new shell session, or let opam's shell hook do it automatically (it offers to set this up during
opam init</code>).</p>
Step 2: Build and Install the Sail Compiler Locally</h2>
You should be in the parent/</code> directory (the one containing both sail/</code> and sail-riscv/</code>).</p>
The Sail compiler is a single binary called sail</code>.
On its own, it can only parse and type-check Sail code.
To actually generate output for a specific language (Lean, C++, Coq, etc.), it needs a backend plugin</strong> loaded at startup.</p>

  
  What The Hell Is A Plugin</div>
  
  Note that I do not understand ocaml's plugin infrastructure properly.
I had to ask Calude and this is what it gave me:</p>
A plugin is a .cmxs</code> file -- an OCaml shared library (see OCaml manual on native plugins</a>).
When sail</code> starts, it scans a known directory for .cmxs</code> files and loads them.
Each plugin registers new command-line flags.
For example, loading sail_plugin_lean.cmxs</code> adds the --lean</code> flag to the sail</code> binary.
There is no separate "lean binary" -- it's all one sail</code> binary with plugins extending its capabilities.</p>

</div>
dune</strong> is OCaml's build system (like make</code> or cargo</code>).
It reads build instructions from dune</code> files in the source tree.
Below, we use three commands. Each is explained with what it does and what it produces:</p>
cd</span> sail</span></span></code></pre>2a. Install OCaml dependencies</h3>
opam</span> install</span> .</span> -</span>-deps-only</span></span></code></pre>
Reads the .opam</code> files in the sail repo and installs all required OCaml libraries
into the current opam switch. Does not build sail itself.</p>
2b. Build the compiler and plugins</h3>
dune</span> build</span> -</span>-release</span></span></code></pre>
Compiles everything in the sail repo. Produces build artifacts under _build/</code>, including:</p>

_build/default/src/bin/sail.exe</code> -- the core sail binary</li>
_build/default/src/sail_lean_backend/sail_plugin_lean.cmxs</code> -- the Lean plugin</li>
</ul>
At this point the binary exists but doesn't know where to find its plugins.</p>
2c. Install into a local prefix</h3>
dune</span> install</span> -</span>-prefix</span> _local_install</span></span></code></pre>
Copies the binary, plugins, and standard library files into a structured directory:</p>

_local_install/bin/sail</code> -- the sail binary</li>
_local_install/share/libsail/plugins/sail_plugin_lean.cmxs</code> -- the Lean plugin</li>
_local_install/share/sail/lib/</code> -- Sail's standard library (prelude, etc.)</li>
</ul>
This is what "installing a plugin" means concretely: copying the .cmxs</code> file into the
share/libsail/plugins/</code> directory where the sail</code> binary knows to look for it.</p>
cd</span> ..</span></span></code></pre>Verify the Lean backend is loaded</h3>
SAIL_DIR</span>=</span>s</span>a</span>i</span>l</span>/</span>_</span>l</span>o</span>c</span>a</span>l</span>_</span>i</span>n</span>s</span>t</span>a</span>l</span>l</span>/</span>s</span>h</span>a</span>r</span>e</span>/</span>s</span>a</span>i</span>l</span> sail/_local_install/bin/sail</span> -</span>-help</span> |</span> grep</span> lean</span></span></code></pre>
SAIL_DIR</code> tells the sail binary where to find its standard library and plugins.
You should see --lean</code> and related flags listed. If you don't, the plugin file is
not in the expected share/libsail/plugins/</code> directory -- re-run dune install</code>.</p>
Step 3: Configure the sail-riscv Build</h2>
From the parent directory (or from sail-riscv/</code>):</p>
cd</span> sail-riscv</span></span>
</span>
SAIL_DIR</span>=</span>$(</span>realpath</span> ../sail/_local_install/share/sail</span>)</span> \</span></span>
cmake</span> -</span>S</span> .</span> -</span>B</span> build</span> \</span></span>
  -</span>DCMAKE_BUILD_TYPE=RelWithDebInfo</span> \</span></span>
  -</span>DSAIL_BIN=</span>$(</span>realpath</span> ../sail/_local_install/bin/sail</span>)</span></span></code></pre>
Key variables:</p>

SAIL_DIR</code> -- points to the installed Sail share directory. This is where the
compiler finds its standard library, include files, and plugins.</li>
SAIL_BIN</code> -- path to the locally-installed sail binary.</li>
</ul>
Important:</strong> Both paths must be absolute</strong>. CMake runs sail --dir</code> internally
to locate the Sail library directory, and the sail binary echoes back whatever
SAIL_DIR</code> was set to. If that's a relative path like ../sail/...</code>, CMake
resolves it relative to the build directory (build/</code>), not the source directory,
causing "Cannot find source file" errors for the C runtime files.</p>
Step 4: Generate Lean Code</h2>
Two variants can be generated. Both take a few minutes (the Sail compiler
type-checks the full model, calling Z3 to solve arithmetic constraints).</p>

  
  I also do not understand any of the Z3 stuff right now.</p>

</div>
Noncomputable (for theorem proving)</h3>
SAIL_DIR</span>=</span>$(</span>realpath</span> ../sail/_local_install/share/sail</span>)</span> \</span></span>
  cmake</span> -</span>-build</span> build</span> -</span>-target</span> generated_lean_rv64d</span></span></code></pre>
Output: build/model/Lean_RV64D/</code> (~155 .lean</code> files)</p>
This version uses noncomputable</code> sections, suitable for interactive proof in Lean.</p>
Executable (for running + theorem provin + theorem provingg)</h3>
SAIL_DIR</span>=</span>$(</span>realpath</span> ../sail/_local_install/share/sail</span>)</span> \</span></span>
  cmake</span> -</span>-build</span> build</span> -</span>-target</span> generated_lean_executable_rv64d</span></span></code></pre>
Output: build/model/Lean_RV64D_executable/</code> (~155 .lean</code> files)</p>
This version generates computable code that can be built and executed with lake build</code>.</p>
RV32 Variants</h3>
Replace rv64d</code> with rv32d</code> in the target names for 32-bit:</p>

generated_lean_rv32d</code></li>
generated_lean_executable_rv32d</code></li>
</ul>
Step 5: Build the Generated Lean Code (Optional)</h2>
Each output directory contains a lakefile.toml</code> and lean-toolchain</code>. To compile:</p>
cd</span> build/model/Lean_RV64D/</span>          #</span> or Lean_RV64D_executable/</span></span>
lake</span> update</span></span>
lake</span> build</span></span></code></pre>
The generated Lean requires a specific Lean toolchain version (specified in
lean-toolchain</code>) and the lean-sail</code> support library (fetched automatically by lake</code>).</p>
Rebuilding After Sail Compiler Changes</h2>
Since you're running from source, after modifying the Sail compiler:</p>
#</span> 1. Rebuild and reinstall the compiler</span></span>
cd</span> ../sail</span></span>
dune</span> build</span> -</span>-release</span></span>
dune</span> install</span> -</span>-prefix</span> _local_install</span></span>
</span>
#</span> 2. Clean stale outputs and re-generate Lean (from sail-riscv)</span></span>
cd</span> ../sail-riscv</span></span>
rm</span> -</span>rf</span> build/model/Lean_RV64D</span> build/model/Lean_RV64D_executable</span></span>
</span>
SAIL_DIR</span>=</span>$(</span>realpath</span> ../sail/_local_install/share/sail</span>)</span> \</span></span>
  cmake</span> -</span>-build</span> build</span> -</span>-target</span> generated_lean_rv64d</span></span>
</span>
SAIL_DIR</span>=</span>$(</span>realpath</span> ../sail/_local_install/share/sail</span>)</span> \</span></span>
  cmake</span> -</span>-build</span> build</span> -</span>-target</span> generated_lean_executable_rv64d</span></span></code></pre>Troubleshooting</h2>


Cannot find source file: ../sail/_local_install/share/sail/lib/elf.c</code></strong>: You used
relative paths for SAIL_DIR</code>. CMake resolves paths relative to the build directory,
not where you ran the command. Use $(realpath ../sail/_local_install/share/sail)</code> to
get an absolute path.</p>
</li>

--lean</code> flag not found</strong>: The plugin wasn't installed. Make sure you ran
dune install --prefix _local_install</code> and that SAIL_DIR</code> points to the
_local_install/share/sail</code> directory (not the repo root or lib/</code>).</p>
</li>

sail: command not found</code> during cmake</strong>: You need to pass -DSAIL_BIN=</code> pointing
to your local install, and set SAIL_DIR</code> as an environment variable.</p>
</li>

Plugin load error (symbol not found</code>)</strong>: Version mismatch between the sail binary
and the plugin. Run dune build --release && dune install --prefix _local_install</code>
again to rebuild both from the same source.</p>
</li>

CMake cache error about mismatched source directory</strong>: Delete build/</code> and
reconfigure: rm -rf build && cmake -S . -B build ...</code></p>
</li>
</ul>
What Gets Generated</h2>
The Sail compiler translates the entire RISC-V ISA model into Lean definitions:</p>

Instruction encodings/decodings</li>
Instruction semantics</li>
CSR definitions</li>
Memory model</li>
Exception handling</li>
Extension support (M, A, F, D, C, V, etc.)</li>
</ul>
The noncomputable version is for reasoning about the spec in Lean's type theory.
The executable version can simulate RISC-V binaries.</p>



Lost in Translation
2026-03-09T00:00:00+00:00
</p>
Lost in Translation</em> (2003), directed by Sofia Coppola. Source</a></figcaption>
The Problem</h2>
A user gives Jolt a program written in the RISCV assembly language with the IMAC extension.
Jolt in turn compiles this program to Jolt Assembly, and executes (and proves correctness for) this program written in the Jolt ISA.</p>
Jolt assembly is essentially a strict subset of RISCV instructions + some extra instructions, referred to as virtual instructions.
For example, some RISCV instructions (such as LW</code>) are replaced with a sequence of instructions written in the Jolt ISA (see below).
For Jolt to be correct, the program written in Jolt assembly must be "equivalent" to the original user program.
Otherwise, we have just executed and proven correctness of execution for some arbitrary program.
Equivalence here means that the RISC-CPU state before and after executing these sequence of instructions is identical to the RISC-CPU state before and after the execution of the RISC-V instruction.
Below are the code blocks that simulate the RISC and Jolt CPU:</p>
32</span>fn</span> exec</span>(</span>&</span>self</span>,</span> cpu</span>:</span> &</span>mut</span> Cpu</span>,</span> ram_access</span>:</span> &</span>mut</span> <</span>LW</span> as</span> RISCVInstruction</span>></span>::</span>RAMAccess</span>)</span> {</span></span>
33</span>    let</span> value</span> =</span> match</span> cpu</span></span>
34</span>        .</span>mmu</span></span>
35</span>        .</span>load_word</span>(</span>cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span>.</span>wrapping_add</span>(</span>self</span>.</span>operands</span>.</span>imm</span>)</span> as</span> u64</span>)</span></span>
36</span>    {</span></span>
37</span>        Ok</span>(</span>(</span>word</span>,</span> memory_read</span>)</span>)</span> =></span> {</span></span>
38</span>            *</span>ram_access</span> =</span> memory_read</span>;</span></span>
39</span>            word</span> as</span> i32</span> as</span> i64</span></span>
40</span>        }</span></span>
41</span>        Err</span>(</span>_</span>)</span> =></span> panic!</span>(</span>"</span>MMU load error</span>"</span>)</span>,</span></span>
42</span>    }</span>;</span></span>
43</span>    cpu</span>.</span>write_register</span>(</span>self</span>.</span>operands</span>.</span>rd </span>as</span> usize</span>,</span> value</span>)</span>;</span></span>
44</span>}</span></span></code></pre>
The inline_sequence</code> describes the equivalent Jolt CPU state transitions1</a></sup>.</p>
^{1</sup>
Notice that the Jolt CPU allows for some extra instructions known as virtual instructions which edit and change virtual registers.</p>
</div>} 90</span>fn</span> inline_sequence_64</span>(</span>&</span>self</span>,</span> allocator</span>:</span> &</span>VirtualRegisterAllocator</span>)</span> -></span> Vec</span><</span>Instruction</span>></span> {</span></span>
 91</span>    let</span> v0</span> =</span> allocator</span>.</span>allocate</span>(</span>)</span>;</span></span>
 92</span>    let</span> v1</span> =</span> allocator</span>.</span>allocate</span>(</span>)</span>;</span></span>
 93</span></span>
 94</span>    let</span> mut</span> asm</span> =</span> InstrAssembler</span>::</span>new</span>(</span>self</span>.</span>address</span>,</span> self</span>.</span>is_compressed</span>,</span> Xlen</span>::</span>Bit64</span>,</span> allocator</span>)</span>;</span></span>
 95</span></span>
 96</span>    asm</span>.</span>emit_align</span>::</span><</span>VirtualAssertWordAlignment</span>></span>(</span>self</span>.</span>operands</span>.</span>rs1</span>,</span> self</span>.</span>operands</span>.</span>imm</span>)</span>;</span></span>
 97</span>    asm</span>.</span>emit_i</span>::</span><</span>ADDI</span>></span>(</span>*</span>v0</span>,</span> self</span>.</span>operands</span>.</span>rs1</span>,</span> self</span>.</span>operands</span>.</span>imm </span>as</span> u64</span>)</span>;</span></span>
 98</span>    asm</span>.</span>emit_i</span>::</span><</span>ANDI</span>></span>(</span>*</span>v1</span>,</span> *</span>v0</span>,</span> -</span>8</span>i64</span> as</span> u64</span>)</span>;</span></span>
 99</span>    asm</span>.</span>emit_ld</span>::</span><</span>LD</span>></span>(</span>*</span>v1</span>,</span> *</span>v1</span>,</span> 0</span>)</span>;</span></span>
100</span>    asm</span>.</span>emit_i</span>::</span><</span>SLLI</span>></span>(</span>*</span>v0</span>,</span> *</span>v0</span>,</span> 3</span>)</span>;</span></span>
101</span>    asm</span>.</span>emit_r</span>::</span><</span>SRL</span>></span>(</span>*</span>v1</span>,</span> *</span>v1</span>,</span> *</span>v0</span>)</span>;</span></span>
102</span>    asm</span>.</span>emit_i</span>::</span><</span>VirtualSignExtendWord</span>></span>(</span>self</span>.</span>operands</span>.</span>rd</span>,</span> *</span>v1</span>,</span> 0</span>)</span>;</span></span>
103</span></span>
104</span>    asm</span>.</span>finalize</span>(</span>)</span></span>
105</span>}</span></span></code></pre>
Naturally, the RISC-CPU does not have virtual registers, so equivalence between the two blocks of code is measured by equivalence of RISC CPU state, whose fields are a strict subset of the Jolt CPU state.</p>
With equivalence defined, how does one prove that the two states are equivalent?
One way would be to enumerate all possible inputs for all instructions, feed them into the two blocks, and check if the states are the same.
This works but it's computationally infeasible.
Instead, we prove equivalence mathematically, formally in a theorem proving language such as Lean 4.</p>
^2</sup>In fact there are professionally maintained projects that do this for ARM. See this</a> project for symbolically simulating ARM instructions.</p>
</div>
Here is roughly how we go about such a thing.
As a first step we define a RISCV CPU State in Lean3</a></sup>.
The details of this code block are not so important.
The takeaway here is that - it is possible to model a CPU formally in Lean2</a></sup>.</p>
-- This models a general object that stores data</span></span>
-- The locations are of type α; and the values are of type β</span></span>
abbrev</span> DataStore</span> α</span> β</span> := α → β</span></span>
</span>
-- In Jolt Memory has</span></span>
-- α : BitVec </span>64</span></span>
-- β : Bitvec </span>8</span></span>
abbrev</span> Memory</span> := DataStore (BitVec </span>64</span>) (BitVec </span>8</span>)</span></span>
</span>
-- The RISC-V ISA has </span>32</span> general purpose registers</span></span>
-- α : BitVec </span>64</span></span>
-- β : Bitvec </span>8</span></span>
abbrev</span> RegFile</span> := DataStore (BitVec </span>5</span>) (BitVec </span>64</span>)</span></span>
</span>
-- CSR address space is </span>12</span>-bit </span>in</span> RISC-V (</span>4096</span> possible CSRs)</span></span>
abbrev</span> CsrFile</span> := DataStore (BitVec </span>12</span>) (BitVec </span>64</span>)</span></span>
</span>
</span>
-- This models a data store </span>where</span> the input is a bit vector and the output</span></span>
-- is a byte of data (more specifically a bit vector of size </span>8</span>).</span></span>
abbrev</span> ByteDataStore</span> addr_bits</span> := BitVec addr_bits → BitVec </span>8</span></span>
</span>
-- Given a location of type α, </span>return</span> what is stored </span>in</span> the store at the location α.</span></span>
def</span> read</span> {α β : </span>Type</span>} [DecidableEq α] (a : α) (datastore : DataStore α β) : β :=</span></span>
  datastore a</span></span>
</span>
-- takes a datastore, an address a, and a new value b (to be written at address a)</span></span>
-- returns a new datastore that returns the same values as the original datastore at</span></span>
-- all addresses except a, </span>where</span> it returns b</span></span>
def</span> write</span> {α β : </span>Type</span>} [DecidableEq α] (a : α) (b : β) (datastore : DataStore α β) : DataStore α β :=</span></span>
  fun</span> x => </span>if</span> x = a </span>then</span> b </span>else</span> (datastore x)</span></span>
</span>
-- The simplified state of a computer</span></span>
-- Memory</span></span>
-- Register</span></span>
-- Program Counter</span></span>
-- Flags</span></span>
-- Componentwise equality -> Equality Of State</span></span>
@</span>[ext]</span></span>
structure</span> State</span> where</span></span>
  mem : Memory</span></span>
  reg : RegFile</span></span>
  csr : CsrFile := </span>fun</span> _ => </span>0</span>#</span>64</span></span>
  pc  : BitVec </span>64</span> := </span>0</span>#</span>64</span></span>
  error : Bool := </span>false</span></span>
</span></code></pre>
^{3</sup>
This is a first pass definition of state. Eventually we will model virtual registers, and Jolt CPU as well.</p>
</div>}^4</sup>Eventually, we will use the SAIL RISCV library</a> written by Galois for RiscV instructions to define RISCV CPU transitions. For now we intentionally write state, and instruction definitions from scratch, to control every step of the proving pipeline.</p>
</div>
^5</sup>Separating pure computations from state-changing operations is a well-studied idea in monadic programming</a> — we won't bore you with the details, but see here</a> and here</a> if you're curious.</p>
</div>
Then we define how the RISCV instruction would change state4</a></sup>.</p>
/--</span> RISC-V LW semantics </span>-/</span></span>
def</span> lw</span> (rs1 rd : BitVec </span>5</span>) (imm : BitVec </span>12</span>) (s : State) : State :=</span></span>
  let</span> base := read rs1 s.reg</span></span>
  let</span> addr := imm.setWidth </span>64</span> + base</span></span>
  if</span> addr &&& </span>3</span>#</span>64</span> ≠ </span>0</span>#</span>64</span> then</span> { s </span>with</span> error := </span>true</span> }</span></span>
  else</span></span>
    let</span> word := read_word addr s</span></span>
    let</span> new_reg := write rd (word.signExtend </span>64</span>) s.reg</span></span>
    { s </span>with</span> reg := new_reg }</span></span></code></pre>
The Jolt sequence is also defined in Lean.</p>
/--</span> Jolt LW semantics </span>-/</span></span>
def</span> jolt_lw</span> (rs1 rd : BitVec </span>5</span>) (imm : BitVec </span>12</span>) (s : State) : State :=</span></span>
  let</span> base              := read rs1 s.reg</span></span>
  let</span> v_address         := Riscv.addi base imm</span></span>
  let</span> (v_address, s)    := Jolt.virtualAssertWordAlignment v_address s</span></span>
  if</span> s.error </span>then</span> s</span></span>
  else</span></span>
    let</span> v_dword_addr    := Riscv.andi v_address (-</span>8</span>#</span>64</span>)</span></span>
    let</span> v_dword         := read_dword v_dword_addr s</span></span>
    let</span> v_shift         := Riscv.slli v_address </span>3</span></span>
    let</span> v_word          := Riscv.srl v_dword v_shift</span></span>
    let</span> result          := Jolt.virtualSignExtendWord v_word</span></span>
    let</span> new_reg         := write rd result s.reg</span></span>
    { s </span>with</span> reg := new_reg }</span></span></code></pre>
Then, finally we prove they are equivalent by writing it as a theorem.</p>
theorem</span> lw_eq</span> (rs1 rd : BitVec </span>5</span>) (imm : BitVec </span>12</span>) (s : State)</span></span>
    (h_no_error : s.error = </span>false</span>) :</span></span>
    Riscv.lw rs1 rd imm s = jolt_lw rs1 rd imm s := </span>by</span></span></code></pre>
We actually have a full Lean proof for the above theorem, but we skip it here as it distracts from the main goal of the post.</p>
What's The Drama?</h3>
So we can take Rust code, express it meaningfully in Lean and prove theorems about it.
Great! What's the drama?
The issue here -- is that the way I came up with the above Lean code is by hand-translating Rust code into Lean.
Firstly, this is error prone, but as the code snippets are small and regular one could forgive such a manual procedure.
Secondly, and more importantly, tomorrow if someone changes the Jolt ISA spec, how do we keep the code aligned?
This manual process will not scale, and will be a nightmare to maintain.</p>

  
  What we really want is a way to automatically extract the Rust code into Lean (or any other format such as .md for documentation).</p>

</div>
The naive approach is to parse the exec</code> Rust code directly and translate it to Lean.
But this is a plan with a very slippery slope.
A general Rust-to-Lean translator would need to handle every valid way of expressing the same logic — variable shadowing, closures, method chains, trait dispatch, control flow.
This is essentially writing a Rust compiler frontend.
We do NOT</strong> want to re-write the Rust compiler.</p>
Tools like Hax</a> take a different approach.
Hax hooks into rustc</code> as a compiler plugin and extracts Rust's own THIR</a> (Typed High-level Intermediate Representation), then translates it into verification languages like F*, Coq, or Lean (see the Hax architecture docs</a> and the Lean backend</a>).
For our purposes this is certainly overkill.
Firstly, we want to model in Lean the high-level Rust function description, not a compiler IR lowering of it.
Secondly, the interface to these tools is janky.
We cannot give it a Rust function and say write this in Lean.
It needs a full crate</a> — cargo hax into lean</code> operates on an entire cargo project, not individual functions.</p>
This is not what we really want to do.
What we really want is to go through each instructions/*.rs</code> file, extract just the exec (and inline) blocks, and model them in Lean like we did earlier.
The exec</code> blocks are simple: read operands, compute, write results.

  
  If we write the instruction semantics using a small, fixed grammar instead of arbitrary Rust, then translation becomes mechanical.</p>

</div>
</p>
For example, the same LW</code> code written in a custom grammar might look like this</p>
46</span>#</span>[</span>tracer_macros</span>::</span>gen_exec</span>]</span></span>
47</span>impl</span> LW</span> {</span></span>
48</span>    fn</span> ast</span>(</span>)</span> -></span> Stmt</span> {</span></span>
49</span>        Seq</span>(</span>[</span></span>
50</span>            Load</span>(</span>"</span>v</span>"</span>,</span> W32</span>,</span> Add</span>(</span>Rs1</span>,</span> Imm</span>)</span>)</span>,</span></span>
51</span>            WriteRd</span>(</span>Cast</span> {</span> from</span>:</span> W32</span>,</span> to</span>:</span> W64</span>,</span> sign</span>:</span> Signed</span>,</span> expr</span>:</span> Var</span>(</span>"</span>v</span>"</span>)</span> }</span>)</span>,</span></span>
52</span>        ]</span>)</span></span>
53</span>    }</span></span>
54</span>}</span></span></code></pre>
But what should this grammar look like?</p>
A Custom AST</h2>
We need a grammar rich enough to express every Jolt instruction. Each instruction reads operands, computes a value, and writes the result — to a register, to memory, or to the program counter. The grammar must capture all of this.</p>
A first attempt — one enum for everything:</p>
enum</span> Node</span> {</span></span>
    //</span> Terminals — leaves of the tree</span></span>
    Rs1</span>,</span></span>
    Imm</span>,</span></span>
    //</span> Expression — computes a value from children</span></span>
    Add</span>(</span>Box</span><</span>Node</span>></span>,</span> Box</span><</span>Node</span>></span>)</span>,</span></span>
    //</span> Statement — writes to CPU state</span></span>
    WriteRd</span>(</span>Box</span><</span>Node</span>></span>)</span>,</span></span>
}</span></span></code></pre>
This lets us write WriteRd(Add(Rs1, Imm))</code>. But it also lets us write garbage like WriteRd(WriteRd(Rs1))</code> or Add(WriteRd(Rs1), Imm)</code>.</p>
The problem is that there's no distinction between nodes that change state</strong> (writing to a register) and nodes that compute intermediate values</strong> (adding two numbers). We'll call the first kind statements</strong> and the second kind expressions</strong>5</a></sup>. The single enum conflates them.</p>
To make this work with one type, we need a runtime check that classifies each variant — something the enum itself doesn't encode:</p>
fn</span> is_statement</span>(</span>node</span>:</span> &</span>Node</span>)</span> -></span> bool</span> {</span></span>
    match</span> node</span> {</span></span>
        Node</span>::</span>WriteRd</span>(</span>_</span>)</span> =></span> true</span>,</span></span>
        //</span> Every new statement variant must be added here:</span></span>
        //</span> Node::Store(..) => true,</span></span>
        //</span> Node::WritePc(_) => true,</span></span>
        //</span> Node::Branch(..) => true,</span></span>
        _</span> =></span> false</span>,</span></span>
    }</span></span>
}</span></span></code></pre>
This has to be kept in sync with the enum — every time a statement variant is added, is_statement</code> must be updated. Forget one, and garbage trees slip through silently.</p>
Now the translation function uses it to check every child:</p>
fn</span> generate</span>(</span>node</span>:</span> &</span>Node</span>)</span> -></span> TokenStream</span> {</span></span>
    match</span> node</span> {</span></span>
        //</span> Terminals</span></span>
        Node</span>::</span>Rs1</span> =></span> quote!</span> {</span> rs1</span> }</span>,</span></span>
        Node</span>::</span>Imm</span> =></span> quote!</span> {</span> imm</span> }</span>,</span></span>
        //</span> Expression — must guard against statement children</span></span>
        Node</span>::</span>Add</span>(</span>a</span>,</span> b</span>)</span> =></span> {</span></span>
            assert!</span>(</span>!</span>is_statement</span>(</span>a</span>)</span>,</span> "</span>Add cannot contain a statement</span>"</span>)</span>;</span></span>
            assert!</span>(</span>!</span>is_statement</span>(</span>b</span>)</span>,</span> "</span>Add cannot contain a statement</span>"</span>)</span>;</span></span>
            let</span> a</span> =</span> generate</span>(</span>a</span>)</span>;</span></span>
            let</span> b</span> =</span> generate</span>(</span>b</span>)</span>;</span></span>
            quote!</span> {</span> #</span>a</span> +</span> #</span>b</span> }</span></span>
        }</span></span>
        //</span> Statement — must also guard against statement children</span></span>
        Node</span>::</span>WriteRd</span>(</span>child</span>)</span> =></span> {</span></span>
            assert!</span>(</span>!</span>is_statement</span>(</span>child</span>)</span>,</span> "</span>WriteRd cannot contain a statement</span>"</span>)</span>;</span></span>
            let</span> val</span> =</span> generate</span>(</span>child</span>)</span>;</span></span>
            quote!</span> {</span> rd</span> =</span> #</span>val</span>;</span> }</span></span>
        }</span></span>
    }</span></span>
}</span></span></code></pre>
Every variant that expects a value has to guard against receiving a statement. This works, but the checks are repetitive and easy to forget.</p>
A simpler solution — split into two types:</p>
enum</span> Expr</span> {</span></span>
    //</span> Terminals</span></span>
    Rs1</span>,</span></span>
    Imm</span>,</span></span>
    //</span> Expression — children are Expr, not Stmt</span></span>
    Add</span>(</span>Box</span><</span>Expr</span>></span>,</span> Box</span><</span>Expr</span>></span>)</span>,</span></span>
}</span></span>
</span>
enum</span> Stmt</span> {</span></span>
    //</span> Statement — takes an Expr, so no statement can sneak in</span></span>
    WriteRd</span>(</span>Expr</span>)</span>,</span></span>
}</span></span></code></pre>
The garbage trees don't compile — WriteRd</code> takes an Expr</code>, not a Stmt</code>. The translation becomes:</p>
fn</span> generate_expr</span>(</span>expr</span>:</span> &</span>Expr</span>)</span> -></span> TokenStream</span> {</span></span>
    match</span> expr</span> {</span></span>
        //</span> Terminals — no recursion</span></span>
        Expr</span>::</span>Rs1</span> =></span> quote!</span> {</span> rs1</span> }</span>,</span></span>
        Expr</span>::</span>Imm</span> =></span> quote!</span> {</span> imm</span> }</span>,</span></span>
        //</span> Expression — recurse into generate_expr, guaranteed to return a value</span></span>
        Expr</span>::</span>Add</span>(</span>a</span>,</span> b</span>)</span> =></span> {</span></span>
            let</span> a</span> =</span> generate_expr</span>(</span>a</span>)</span>;</span></span>
            let</span> b</span> =</span> generate_expr</span>(</span>b</span>)</span>;</span></span>
            quote!</span> {</span> #</span>a</span> +</span> #</span>b</span> }</span></span>
        }</span></span>
    }</span></span>
}</span></span>
</span>
fn</span> generate_stmt</span>(</span>stmt</span>:</span> &</span>Stmt</span>)</span> -></span> TokenStream</span> {</span></span>
    match</span> stmt</span> {</span></span>
        //</span> Statement — generate_expr returns a value, safe to assign</span></span>
        Stmt</span>::</span>WriteRd</span>(</span>expr</span>)</span> =></span> {</span></span>
            let</span> val</span> =</span> generate_expr</span>(</span>expr</span>)</span>;</span></span>
            quote!</span> {</span> rd</span> =</span> #</span>val</span>;</span> }</span></span>
        }</span></span>
    }</span></span>
}</span></span></code></pre>
No runtime checks. generate_expr</code> always returns a value. generate_stmt</code> always returns an assignment. The compiler enforces it.</p>
The above was a minimal example. Here is the full AST used by Jolt (tracer/src/ast.rs</code>):</p>
20</span>enum</span> AstExpr</span> {</span></span>
21</span>    //</span> Terminals</span></span>
22</span>    Rs1</span>,</span> Rs2</span>,</span> Imm</span>,</span> Pc</span>,</span></span>
23</span>    Reg</span>(</span>u8</span>)</span>,</span></span>
24</span>    Lit</span>(</span>i128</span>)</span>,</span></span>
25</span>    Advice</span>,</span></span>
26</span>    MostNegative</span>,</span></span>
27</span></span>
28</span>    //</span> Arithmetic — children are AstExpr</span></span>
29</span>    Add</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
30</span>    Sub</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
31</span>    Mul</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
32</span>    MulHigh</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
33</span>    MulHighSU</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
34</span>    MulHighU</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
35</span>    Div</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
36</span>    DivU</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
37</span>    Rem</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
38</span>    RemU</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
39</span></span>
40</span>    //</span> Bitwise</span></span>
41</span>    And</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
42</span>    Or</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
43</span>    Xor</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
44</span>    Not</span>(</span>Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
45</span></span>
46</span>    //</span> Shifts</span></span>
47</span>    Sll</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
48</span>    Srl</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
49</span>    Sra</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
50</span></span>
51</span>    //</span> Comparison</span></span>
52</span>    Eq</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
53</span>    Ne</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
54</span>    Lt</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
55</span>    LtU</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
56</span>    Ge</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
57</span>    GeU</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
58</span></span>
59</span>    //</span> Type conversion</span></span>
60</span>    Cast</span> {</span> from</span>:</span> Width</span>,</span> to</span>:</span> Width</span>,</span> sign</span>:</span> SignMode</span>,</span> expr</span>:</span> Box</span><</span>AstExpr</span>></span> }</span>,</span></span>
61</span></span>
62</span>    //</span> Unary</span></span>
63</span>    TrailingZeros</span>(</span>Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
64</span></span>
65</span>    //</span> Conditional</span></span>
66</span>    If</span>(</span>Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
67</span></span>
68</span>    //</span> Xlen-dependent</span></span>
69</span>    XlenMatch</span> {</span> bit32</span>:</span> Box</span><</span>AstExpr</span>></span>,</span> bit64</span>:</span> Box</span><</span>AstExpr</span>></span> }</span>,</span></span>
70</span></span>
71</span>    //</span> Bindings</span></span>
72</span>    Let</span>(</span>String</span>,</span> Box</span><</span>AstExpr</span>></span>,</span> Box</span><</span>AstExpr</span>></span>)</span>,</span></span>
73</span>    Var</span>(</span>String</span>)</span>,</span></span>
74</span>}</span></span>
75</span></span>
76</span>enum</span> AstStmt</span> {</span></span>
77</span>    WriteRd</span>(</span>AstExpr</span>)</span>,</span></span>
78</span>    WriteReg</span>(</span>u8</span>,</span> AstExpr</span>)</span>,</span></span>
79</span>    Store</span>(</span>Width</span>,</span> AstExpr</span>,</span> AstExpr</span>)</span>,</span></span>
80</span>    WritePc</span>(</span>AstExpr</span>)</span>,</span></span>
81</span>    Branch</span>(</span>AstExpr</span>,</span> AstExpr</span>)</span>,</span></span>
82</span>    Assert</span>(</span>AstExpr</span>,</span> AstExpr</span>)</span>,</span></span>
83</span>    Load</span>(</span>String</span>,</span> Width</span>,</span> AstExpr</span>)</span>,</span></span>
84</span>    Seq</span>(</span>Vec</span><</span>AstStmt</span>></span>)</span>,</span></span>
85</span>    LetStmt</span>(</span>String</span>,</span> AstExpr</span>)</span>,</span></span>
86</span>    Nop</span>,</span></span>
87</span>}</span></span></code></pre>
What this really defines is a grammar. Each enum variant is a production rule — it says what a valid tree can look like. Written as a grammar:</p>
Expr ::=</span></span>
    | Rs1 | Rs2 | Imm | Pc | Reg(u8) | Lit(i128) | Advice | MostNegative</span></span>
    | Add(Expr, Expr) | Sub(Expr, Expr) | Mul(Expr, Expr)</span></span>
    | MulHigh(Expr, Expr) | MulHighSU(Expr, Expr) | MulHighU(Expr, Expr)</span></span>
    | Div(Expr, Expr) | DivU(Expr, Expr) | Rem(Expr, Expr) | RemU(Expr, Expr)</span></span>
    | And(Expr, Expr) | Or(Expr, Expr) | Xor(Expr, Expr) | Not(Expr)</span></span>
    | Sll(Expr, Expr) | Srl(Expr, Expr) | Sra(Expr, Expr)</span></span>
    | Eq(Expr, Expr) | Ne(Expr, Expr)</span></span>
    | Lt(Expr, Expr) | LtU(Expr, Expr) | Ge(Expr, Expr) | GeU(Expr, Expr)</span></span>
    | Cast(Width, Width, SignMode, Expr)</span></span>
    | TrailingZeros(Expr)</span></span>
    | If(Expr, Expr, Expr)</span></span>
    | XlenMatch(Expr, Expr)</span></span>
    | Let(String, Expr, Expr) | Var(String)</span></span>
</span>
Stmt ::=</span></span>
    | WriteRd(Expr) | WriteReg(u8, Expr)</span></span>
    | Store(Width, Expr, Expr) | WritePc(Expr)</span></span>
    | Branch(Expr, Expr) | Assert(Expr, Expr)</span></span>
    | Load(String, Width, Expr)</span></span>
    | Seq(Stmt*) | LetStmt(String, Expr) | Nop</span></span></code></pre>
The two-type split is visible here: Expr</code> only produces Expr</code> children. Stmt</code> takes Expr</code> children for values, and Stmt</code> children only via Seq</code>.</p>
The syn</code> Crate</h2>
Now that we have a grammar, how do we parse it? The ast</code> function is valid Rust syntax — Seq([...])</code> is a function call, Cast { from: W32, ... }</code> is a struct literal, Rs1</code> is a bare identifier. None of these names exist in Rust's standard library, but syn</code> doesn't care — it parses syntax, not semantics.</p>
syn</code> is a Rust library that parses Rust source code into a typed tree.
A proc macro receives raw tokens; syn</code> turns them into structured types
we can pattern-match on.</p>
Consider this Rust function:</p>
impl</span> Calculator</span> {</span></span>
    fn</span> compute</span>(</span>&</span>self</span>)</span> -></span> i32</span> {</span></span>
        let</span> base</span> =</span> max</span>(</span>self</span>.</span>x</span>,</span> 10</span>)</span>;</span></span>
        Point</span> {</span> x</span>:</span> base</span>,</span> y</span>:</span> -</span>1</span> }</span></span>
    }</span></span>
}</span></span></code></pre>
syn</code> parses this into a tree. Here is what each piece becomes:</p>
syn::ItemImpl                          ← impl Calculator { ... }</span></span>
└── method: compute</span></span>
    └── syn::Block                     ← { ... }</span></span>
        ├── syn::Stmt::Local           ← let base = max(self.x, 10);</span></span>
        │   └── syn::Expr::Call        ← max(self.x, 10)</span></span>
        │       ├── .func: Expr::Path  ← max</span></span>
        │       └── .args:</span></span>
        │           ├── Expr::Field    ← self.x</span></span>
        │           └── Expr::Lit      ← 10</span></span>
        └── syn::Stmt::Expr           ← Point { x: base, y: -1 }  (no semicolon = return value)</span></span>
            └── syn::Expr::Struct      ← Point { x: base, y: -1 }</span></span>
                ├── .path              ← Point</span></span>
                └── .fields:</span></span>
                    ├── x: Expr::Path  ← base</span></span>
                    └── y: Expr::Unary ← -1</span></span></code></pre>
Official docs:</strong></p>

syn::Stmt</code>: here</a>,</li>
syn::Expr</code>: here</a>.</li>
</ul>
Our LW ast</code> function produces exactly the same kinds of nodes:</p>
syn::ItemImpl                                         ← impl LW { ... }</span></span>
└── method: ast</span></span>
    └── syn::Block                                    ← { ... }</span></span>
        └── syn::Stmt::Expr(_, None)                  ← the return expression</span></span>
            └── syn::Expr::Call                        ← Seq([...])</span></span>
                ├── .func: Expr::Path                  ← "Seq"</span></span>
                └── .args[0]:</span></span>
                    syn::Expr::Array                   ← [Load(...), WriteRd(...)]</span></span>
                    ├── [0]: Expr::Call                 ← Load("v", W32, Add(Rs1, Imm))</span></span>
                    │   ├── .func: Expr::Path           ← "Load"</span></span>
                    │   └── .args:</span></span>
                    │       ├── [0]: Expr::Lit           ← "v"</span></span>
                    │       ├── [1]: Expr::Path          ← "W32"</span></span>
                    │       └── [2]: Expr::Call          ← Add(Rs1, Imm)</span></span>
                    │           ├── .func: Expr::Path    ← "Add"</span></span>
                    │           └── .args:</span></span>
                    │               ├── [0]: Expr::Path  ← "Rs1"</span></span>
                    │               └── [1]: Expr::Path  ← "Imm"</span></span>
                    └── [1]: Expr::Call                 ← WriteRd(Cast { ... })</span></span>
                        ├── .func: Expr::Path           ← "WriteRd"</span></span>
                        └── .args[0]:</span></span>
                            Expr::Struct                ← Cast { from: W32, ... }</span></span>
                            ├── .path                    ← "Cast"</span></span>
                            └── .fields:</span></span>
                                ├── from: Expr::Path     ← "W32"</span></span>
                                ├── to:   Expr::Path     ← "W64"</span></span>
                                ├── sign: Expr::Path     ← "Signed"</span></span>
                                └── expr: Expr::Call     ← Var("v")</span></span>
                                    ├── .func: Expr::Path ← "Var"</span></span>
                                    └── .args[0]: Expr::Lit ← "v"</span></span></code></pre>
Compare with the Calculator example. The structure is the same:</p>

Seq(...)</code> and WriteRd(...)</code> are function calls, just like max(...)</code></li>
Cast { from: W32, ... }</code> is a struct literal, just like Point { x: 1 }</code></li>
Rs1</code> is a bare identifier, just like base</code></li>
[Load(...), WriteRd(...)]</code> is an array literal</li>
</ul>
syn</code> doesn't assign any meaning to these names. It just builds a tree of syn::Expr</code> nodes. Our proc macro walks this tree, recognises the grammar's production rules by name, and emits code.</p>
Auto-generating Rust from the AST</h2>
So what do we gain by defining instruction semantics as an AST?
The original motivation was Lean — compile the AST into Lean definitions for formal verification. But we get much more than that.
We write the semantics once in the grammar, and backends compile it to anything — Rust for the CPU emulator, documentation, or whatever else we need tomorrow.
One definition, many outputs.</p>
To see this in action, let's compare the original hand-written exec</code> for LW with the auto-generated ast_exec</code>.
Before comparing them, there is one difference that needs explaining.</p>
Look at cpu.mmu.load_word(...)</code> in the hand-written exec</code>.
It returns two things: the loaded value (word</code>) and a record of the memory access (memory_read</code>).
The loaded value is the instruction's result — it gets sign-extended and written to rd</code>.
The memory access record is bookkeeping for Jolt's proof system — it captures what</em> was read and from where</em>, so the prover can later verify the memory access.</p>
The hand-written exec</code> stores this record with *ram_access = memory_read</code>.
The ram_access</code> parameter is passed in specifically for this — it's a mutable reference that the caller uses to collect proof data.</p>
In the AST, the author writes Load("v", W32, Add(Rs1, Imm))</code> — pure semantics, no bookkeeping.
The code generator must emit the recording automatically.
But there is a problem: the proc macro operates on tokens, not types.</p>
Each instruction declares its RAM type in declare_riscv_instr!</code>:</p>
declare_riscv_instr!</span>(</span></span>
    name</span> =</span> LW</span>,</span></span>
    ...</span></span>
    ram</span>  =</span> RAMRead</span>      //</span> ← LW's RAMAccess type is RAMRead</span></span>
)</span>;</span></span>
</span>
declare_riscv_instr!</span>(</span></span>
    name</span> =</span> ADD</span>,</span></span>
    ...</span></span>
    ram</span>  =</span> (</span>)</span>           //</span> ← ADD does not access memory</span></span>
)</span>;</span></span></code></pre>
This sets the associated type <LW as RISCVInstruction>::RAMAccess = RAMRead</code>.
But syn</code> parses syntax, not types.
When generate_ast_stmt</code> sees Load(...)</code>, it does not know whether this instruction's RAMAccess</code> is RAMRead</code>, RAMWrite</code>, or ()</code>.
So it cannot emit *ram_access = memory_read</code> — that only compiles if ram_access</code> is a RAMRead</code>.
It cannot emit nothing — that silently drops the recording.
It cannot branch on the type — it doesn't know the type.</p>
We introduced a trait to solve this (tracer/src/instruction/mod.rs:348</code>):</p>
348</span>pub</span> trait</span> RecordRead</span> {</span></span>
349</span>    fn</span> record_read</span>(</span>&</span>mut</span> self</span>,</span> read</span>:</span> RAMRead</span>)</span>;</span></span>
350</span>}</span></span></code></pre>
With an impl for each possible RAM type:</p>
352</span>impl</span> RecordRead</span> for</span> RAMRead</span> {</span></span>
353</span>    fn</span> record_read</span>(</span>&</span>mut</span> self</span>,</span> read</span>:</span> RAMRead</span>)</span> {</span></span>
354</span>        *</span>self</span> =</span> read</span>;</span></span>
355</span>        //</span> self is ram_access, read is memory_read</span></span>
356</span>        //</span> this does exactly: *ram_access = memory_read</span></span>
357</span>    }</span></span>
358</span>}</span></span>
359</span>impl</span> RecordRead</span> for</span> RAMWrite</span> {</span></span>
360</span>    fn</span> record_read</span>(</span>&</span>mut</span> self</span>,</span> _</span>:</span> RAMRead</span>)</span> {</span>}</span>  //</span> write-only: nothing to record</span></span>
361</span>}</span></span>
362</span>impl</span> RecordRead</span> for</span> (</span>)</span> {</span></span>
363</span>    fn</span> record_read</span>(</span>&</span>mut</span> self</span>,</span> _</span>:</span> RAMRead</span>)</span> {</span>}</span>  //</span> no RAM: nothing to record</span></span>
364</span>}</span></span></code></pre>
Now the code generator emits the same call for every Load</code>:</p>
let</span> (</span>v</span>,</span> _ram_read</span>)</span> =</span> cpu</span>.</span>mmu</span>.</span>load_word</span>(</span>addr</span>)</span>.</span>expect</span>(</span>"</span>MMU load error</span>"</span>)</span>;</span></span>
RecordRead</span>::</span>record_read</span>(</span>_ram_access</span>,</span> _ram_read</span>)</span>;</span></span></code></pre>
_ram_read</code> is the memory access record returned by load_word</code> — the same value as memory_read</code> in the hand-written exec</code>.
For LW, _ram_access</code> has type RAMRead</code>, so the first impl fires: *self = read</code> stores the record.
For an instruction with ram = ()</code>, the third impl fires: it does nothing.
The Rust compiler resolves the correct impl at compile time.
The proc macro never needs to know the type — it emits one line, and trait dispatch handles the rest.</p>
Compare the original exec</code> with the auto-generated ast_exec</code>:</p>








  
    fn</span> exec</span>(</span>&</span>self</span>,</span> cpu</span>:</span> &</span>mut</span> Cpu</span>,</span></span>
    ram_access</span>:</span> &</span>mut</span> <</span>LW</span> as</span></span>
        RISCVInstruction</span>></span>::</span>RAMAccess</span>)</span></span>
{</span></span>
    let</span> value</span> =</span> match</span> cpu</span>.</span>mmu</span>.</span>load_word</span>(</span></span>
        cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span></span>
            .</span>wrapping_add</span>(</span>self</span>.</span>operands</span>.</span>imm</span>)</span></span>
            as</span> u64</span>)</span></span>
    {</span></span>
        Ok</span>(</span>(</span>word</span>,</span> memory_read</span>)</span>)</span> =></span> {</span></span>
            *</span>ram_access</span> =</span> memory_read</span>;</span></span>
            word</span> as</span> i32</span> as</span> i64</span></span>
        }</span></span>
        Err</span>(</span>_</span>)</span> =></span> panic!</span>(</span>"</span>MMU load error</span>"</span>)</span>,</span></span>
    }</span>;</span></span>
    cpu</span>.</span>write_register</span>(</span></span>
        self</span>.</span>operands</span>.</span>rd </span>as</span> usize</span>,</span> value</span>)</span>;</span></span>
}</span></span></code></pre>
    Hand-written exec</figcaption>
  </figure>
  
    fn</span> ast_exec</span>(</span>&</span>self</span>,</span> cpu</span>:</span> &</span>mut</span> Cpu</span>,</span></span>
    _ram_access</span>:</span> &</span>mut</span> <</span>LW</span> as</span></span>
        RISCVInstruction</span>></span>::</span>RAMAccess</span>)</span></span>
{</span></span>
    let</span> (</span>v</span>,</span> _ram_read</span>)</span> =</span> cpu</span>.</span>mmu</span>.</span>load_word</span>(</span></span>
        cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span></span>
            .</span>wrapping_add</span>(</span>self</span>.</span>operands</span>.</span>imm</span>)</span></span>
            as</span> u64</span>)</span></span>
        .</span>expect</span>(</span>"</span>MMU load error</span>"</span>)</span>;</span></span>
    crate</span>::</span>instruction</span>::</span>RecordRead</span></span>
        ::</span>record_read</span>(</span></span>
            _ram_access</span>,</span> _ram_read</span>)</span>;</span></span>
    let</span> v</span> =</span> v</span> as</span> i64</span>;</span></span>
    let</span> _rd_val</span> =</span> (</span>v</span> as</span> i32</span> as</span> i64</span>)</span>;</span></span>
    cpu</span>.</span>write_register</span>(</span></span>
        self</span>.</span>operands</span>.</span>rd </span>as</span> usize</span>,</span> _rd_val</span>)</span>;</span></span>
}</span></span></code></pre>
    Auto-generated ast_exec</figcaption>
  </figure>
</div>

Decoding: Rust backend</h2>
Above we saw the auto-generated Rust code side by side with the hand-written version. But how do we actually get from the grammar to that Rust code?</p>
The #[tracer_macros::gen_exec]</code> attribute triggers the proc macro.
It receives the entire impl LW { ... }</code> block as a token stream, parses it with syn</code> into a syn::ItemImpl</code>, finds the method named ast</code>, and passes its body — a syn::Block</code> — to generate_exec_body</code> (tracer-macros/src/rust_backend.rs:14</code>).</p>

  
  A syn::Block</code> is a { ... }</code> containing a Vec<syn::Stmt></code>.
For LW, the body has one statement: syn::Stmt::Expr(expr, None)</code> — the return expression with no semicolon.
Here expr</code> is a syn::Expr::Call</code> for Seq(...)</code>, whose argument is a syn::Expr::Array</code> containing two elements — one for Load(...)</code> and one for WriteRd(...)</code>.</p>

</div>
generate_exec_body</code> (tracer-macros/src/rust_backend.rs:14</code>) is where parsing begins.
It receives the syn::Block</code> and iterates over its Vec<syn::Stmt></code>:</p>
14</span>pub</span> fn</span> generate_exec_body</span>(</span>block</span>:</span> &</span>syn</span>::</span>Block</span>)</span> -></span> Result</span><</span>TokenStream2</span>,</span> syn</span>::</span>Error</span>></span> {</span></span>
15</span>    let</span> stmts</span> =</span> &</span>block</span>.</span>stmts</span>;</span></span>
16</span>    if</span> stmts</span>.</span>is_empty</span>(</span>)</span> {</span></span>
17</span>        return</span> Err</span>(</span>syn</span>::</span>Error</span>::</span>new_spanned</span>(</span>block</span>,</span> "</span>ast() body is empty</span>"</span>)</span>)</span>;</span></span>
18</span>    }</span></span>
19</span></span>
20</span>    let</span> mut</span> parts</span> =</span> Vec</span>::</span>new</span>(</span>)</span>;</span></span>
21</span>    for</span> stmt</span> in</span> stmts</span> {</span></span>
22</span>        match</span> stmt</span> {</span></span>
23</span>            //</span> let addr = Add(Rs1, Imm);  →  process RHS as an expression</span></span>
24</span>            syn</span>::</span>Stmt</span>::</span>Local</span>(</span>local</span>)</span> =></span> {</span></span>
25</span>                let</span> name</span> =</span> &</span>local</span>.</span>pat</span>;</span></span>
26</span>                let</span> init</span> =</span> local</span>.</span>init</span>.</span>as_ref</span>(</span>)</span></span>
27</span>                    .</span>ok_or_else</span>(</span>|</span>|</span> syn</span>::</span>Error</span>::</span>new_spanned</span>(</span>local</span>,</span></span>
28</span>                        "</span>let binding must have an initializer</span>"</span>)</span>)</span>?</span>;</span></span>
29</span>                let</span> val</span> =</span> generate_ast_expr</span>(</span>&</span>init</span>.</span>expr</span>)</span>?</span>;</span></span>
30</span>                parts</span>.</span>push</span>(</span>quote!</span> {</span> let</span> #</span>name</span> =</span> #</span>val</span>;</span> }</span>)</span>;</span></span>
31</span>            }</span></span>
32</span>            //</span> Expression with semicolon  →  process as a statement</span></span>
33</span>            syn</span>::</span>Stmt</span>::</span>Expr</span>(</span>expr</span>,</span> Some</span>(</span>_semi</span>)</span>)</span> =></span> {</span></span>
34</span>                parts</span>.</span>push</span>(</span>generate_ast_stmt</span>(</span>expr</span>)</span>?</span>)</span>;</span></span>
35</span>            }</span></span>
36</span>            //</span> Expression without semicolon (return)  →  process as a statement</span></span>
37</span>            syn</span>::</span>Stmt</span>::</span>Expr</span>(</span>expr</span>,</span> None</span>)</span> =></span> {</span></span>
38</span>                parts</span>.</span>push</span>(</span>generate_ast_stmt</span>(</span>expr</span>)</span>?</span>)</span>;</span></span>
39</span>            }</span></span>
40</span>            _</span> =></span> return</span> Err</span>(</span>syn</span>::</span>Error</span>::</span>new_spanned</span>(</span>stmt</span>,</span></span>
41</span>                "</span>unsupported statement in ast() body</span>"</span>)</span>)</span>,</span></span>
42</span>        }</span></span>
43</span>    }</span></span>
44</span></span>
45</span>    Ok</span>(</span>quote!</span> {</span> #</span>(</span>#</span>parts</span>)</span>*</span> }</span>)</span></span>
46</span>}</span></span></code></pre>
Three cases:</p>
Case 1: syn::Stmt::Local</code> — a let</code> binding.</h3>
fn</span> ast</span>(</span>)</span> -></span> Stmt</span> {</span></span>
    let</span> addr</span> =</span> Add</span>(</span>Rs1</span>,</span> Imm</span>)</span>;</span>   //</span> ← syn::Stmt::Local</span></span>
    WriteRd</span>(</span>addr</span>)</span></span>
}</span></span></code></pre>
syn::Stmt::Local</code> has two parts we care about: local.pat</code> (the pattern — here, the identifier addr</code>) and local.init</code> (the initializer — here, Add(Rs1, Imm)</code>).
The code extracts both:</p>
syn</span>::</span>Stmt</span>::</span>Local</span>(</span>local</span>)</span> =></span> {</span></span>
    let</span> name</span> =</span> &</span>local</span>.</span>pat</span>;</span>                    //</span> LHS, e.g. `addr`</span></span>
    let</span> init</span> =</span> local</span>.</span>init</span>.</span>as_ref</span>(</span>)</span>            //</span> RHS, e.g. `Add(Rs1, Imm)`</span></span>
        .</span>ok_or_else</span>(</span>|</span>|</span> syn</span>::</span>Error</span>::</span>new_spanned</span>(</span>local</span>,</span></span>
            "</span>let binding must have an initializer</span>"</span>)</span>)</span>?</span>;</span></span>
    let</span> val</span> =</span> generate_ast_expr</span>(</span>&</span>init</span>.</span>expr</span>)</span>?</span>;</span> //</span> process RHS as an expression</span></span>
    parts</span>.</span>push</span>(</span>quote!</span> {</span> let</span> #</span>name</span> =</span> #</span>val</span>;</span> }</span>)</span>;</span> //</span> re-emit as a Rust let binding</span></span>
}</span></span></code></pre>
The right-hand side init.expr</code> goes to generate_ast_expr</code> — it computes a value.
The result is re-emitted as a Rust let</code> binding with the same name.
A let</code> without an initializer (e.g. let addr;</code>) is an error.</p>
Case 2: syn::Stmt::Expr(expr, Some(_))</code> — an expression followed by a semicolon.</h3>
Processed by generate_ast_stmt</code> (it modifies state).</p>
fn</span> ast</span>(</span>)</span> -></span> Stmt</span> {</span></span>
    Seq</span>(</span>[</span></span>
        Store</span>(</span>W32</span>,</span> Rs1</span>,</span> Rs2</span>)</span>;</span>   //</span> ← syn::Stmt::Expr(_, Some(;))</span></span>
        WriteRd</span>(</span>Rs1</span>)</span></span>
    ]</span>)</span></span>
}</span></span></code></pre>Case 3: syn::Stmt::Expr(expr, None)</code> — the final expression with no semicolon (the return value).</h3>
Also processed by generate_ast_stmt</code>.</p>
fn</span> ast</span>(</span>)</span> -></span> Stmt</span> {</span></span>
    WriteRd</span>(</span>Add</span>(</span>Rs1</span>,</span> Imm</span>)</span>)</span>      //</span> ← syn::Stmt::Expr(_, None)</span></span>
}</span></span></code></pre>
  
  Why does syn::Stmt::Local</code> go to generate_ast_expr</code>, while syn::Stmt::Expr</code> goes to generate_ast_stmt</code>?</h3>
A let</code> binding computes a value and gives it a name — its right-hand side goes to generate_ast_expr</code>.
A top-level expression in the block is the thing that actually does</em> something — it writes a register, stores to memory, branches — so it goes to generate_ast_stmt</code>.</p>
This is exactly the two-type split from Part 3: syn::Stmt::Local</code> maps to AstExpr</code> (computes a value), syn::Stmt::Expr</code> maps to AstStmt</code> (changes state).</p>
The split is enforced.
If someone writes let addr = WriteRd(Rs1);</code>, the right-hand side goes to generate_ast_expr</code>.
generate_ast_expr</code> matches the function name against its known variants — Add</code>, Lit</code>, Var</code>, Cast</code>, etc.
"WriteRd"</code> is not among them.
It hits the catch-all (tracer-macros/src/rust_backend.rs:317</code>):</p>
_</span> =></span> Err</span>(</span>syn</span>::</span>Error</span>::</span>new_spanned</span>(</span>call</span>,</span> format!</span>(</span>"</span>unknown Expr variant: </span>{</span>}</span>"</span>,</span> func_name</span>)</span>)</span>)</span>,</span></span></code></pre>
The proc macro emits a compile-time error: "unknown Expr variant: WriteRd"</strong>.
Statement names only exist in generate_ast_stmt</code>'s match table, expression names only in generate_ast_expr</code>'s.
Writing a statement where an expression is expected is a compile error, not a silent bug.</p>
For LW, there is one syn::Stmt</code>: case 3.
The expr</code> is Seq([...])</code>, which goes to generate_ast_stmt</code>.</p>

</div>
generate_ast_expr</code> (tracer-macros/src/rust_backend.rs:183</code>)</h2>
This function receives a syn::Expr</code> and returns a TokenStream2</code> that computes a value.
It never modifies CPU state.</p>
The full function is at tracer-macros/src/rust_backend.rs:183-350</code>.</p>
The outer match is on the syn::Expr</code> variant:</p>

Expr::Path(p)</code> — a bare identifier.
These are the terminals.</li>
Expr::Call(call)</code> — a function call.
These are the compound expressions.</li>
Expr::Struct(s)</code> — a struct literal.
Cast</code> and XlenMatch</code> use this form.</li>
Expr::Unary(u)</code> — prefix operator like -1</code>.
For example, -8</code> in And(Rs1, -8)</code> is parsed as syn::Expr::Unary</code> and emitted as (-8 as i64)</code>.</li>
Expr::Lit(lit)</code> — a literal like 42</code>.
For example, 3</code> in Sll(Rs1, 3)</code> is parsed as syn::Expr::Lit</code> and emitted as (3 as i64)</code>.</li>
Anything else — error.</li>
</ul>
Terminals (Expr::Path</code>)</h3>
Name</th> Emits</th></tr></thead>

Rs1</code></td> cpu.x[self.operands.rs1 as usize]</code></td></tr>
Rs2</code></td> cpu.x[self.operands.rs2 as usize]</code></td></tr>
Imm</code></td> self.operands.imm</code></td></tr>
Pc</code></td> cpu.pc as i64</code></td></tr>
Advice</code></td> self.advice as i64</code></td></tr>
MostNegative</code></td> cpu.most_negative()</code></td></tr>
anything else</td> passed through as a Rust variable reference</td></tr>
</tbody></table>
The last case is how let</code> bindings work.
If the user writes let addr = Add(Rs1, Imm); WriteRd(addr)</code>, then addr</code> in WriteRd(addr)</code> hits the catch-all and is emitted as the Rust identifier addr</code> — which refers to the let</code> binding emitted earlier by generate_exec_body</code>.</p>
Compound expressions (Expr::Call</code>)</h3>
Name</th> Args</th> Emits</th></tr></thead>

Lit</code></td> 1 literal</td> val as i64</code></td></tr>
Reg</code></td> 1 literal</td> cpu.x[idx as usize]</code></td></tr>
Add</code></td> 2 exprs</td> a.wrapping_add(b)</code></td></tr>
Sub</code></td> 2 exprs</td> a.wrapping_sub(b)</code></td></tr>
Mul</code></td> 2 exprs</td> a.wrapping_mul(b)</code></td></tr>
Div</code></td> 2 exprs</td> a.wrapping_div(b)</code></td></tr>
DivU</code></td> 2 exprs</td> (a as u64).wrapping_div(b as u64) as i64</code></td></tr>
Rem</code></td> 2 exprs</td> a.wrapping_rem(b)</code></td></tr>
RemU</code></td> 2 exprs</td> (a as u64).wrapping_rem(b as u64) as i64</code></td></tr>
And</code></td> 2 exprs</td> a & b</code></td></tr>
Or</code></td> 2 exprs</td> a | b</code></td></tr>
Xor</code></td> 2 exprs</td> a ^ b</code></td></tr>
Not</code></td> 1 expr</td> !a</code></td></tr>
Sll</code></td> 2 exprs</td> a.wrapping_shl(b as u32)</code></td></tr>
Srl</code></td> 2 exprs</td> (a as u64).wrapping_shr(b as u32) as i64</code></td></tr>
Sra</code></td> 2 exprs</td> a.wrapping_shr(b as u32)</code></td></tr>
Eq</code></td> 2 exprs</td> if a == b { 1 } else { 0 }</code></td></tr>
Ne</code></td> 2 exprs</td> if a != b { 1 } else { 0 }</code></td></tr>
Lt</code></td> 2 exprs</td> if a < b { 1 } else { 0 }</code></td></tr>
LtU</code></td> 2 exprs</td> unsigned comparison</td></tr>
Ge</code></td> 2 exprs</td> if a >= b { 1 } else { 0 }</code></td></tr>
GeU</code></td> 2 exprs</td> unsigned comparison</td></tr>
MulHigh</code></td> 2 exprs</td> upper 64 bits of signed 128-bit multiply</td></tr>
MulHighSU</code></td> 2 exprs</td> upper 64 bits of signed×unsigned multiply</td></tr>
MulHighU</code></td> 2 exprs</td> upper 64 bits of unsigned 128-bit multiply</td></tr>
TrailingZeros</code></td> 1 expr</td> (a as u64).trailing_zeros() as i64</code></td></tr>
If</code></td> 3 exprs</td> if cond != 0 { then } else { else }</code></td></tr>
Let</code></td> 3: string, expr, expr</td> { let name = val; body }</code></td></tr>
Var</code></td> 1 string</td> the named identifier</td></tr>
</tbody></table>
All binary operations go through a helper binary_op</code> (tracer-macros/src/rust_backend.rs:401</code>) which calls generate_ast_expr</code> on both arguments and combines them with the given operator.</p>
Struct expressions (Expr::Struct</code>)</h3>
Two variants use struct literal syntax:</p>
Cast { from, to, sign, expr }</code></strong> — type conversion.
Handled by generate_ast_cast</code> (tracer-macros/src/rust_backend.rs:353</code>).
Reads four named fields: from</code> (source width), to</code> (target width), sign</code> (Signed</code> or Unsigned</code>), expr</code> (the inner expression).
The (from, to, sign)</code> triple selects the Rust cast chain.</p>
AST:</p>
Cast</span> {</span> from</span>:</span> W32</span>,</span> to</span>:</span> W64</span>,</span> sign</span>:</span> Signed</span>,</span> expr</span>:</span> Var</span>(</span>"</span>v</span>"</span>)</span> }</span></span></code></pre>
Generated Rust:</p>
(</span>v</span> as</span> i32</span> as</span> i64</span>)</span></span></code></pre>
Sign-extend from 32-bit to 64-bit: cast to i32</code> (interpret as signed 32-bit), then widen to i64</code>.</p>
AST:</p>
Cast</span> {</span> from</span>:</span> W64</span>,</span> to</span>:</span> W32</span>,</span> sign</span>:</span> Unsigned</span>,</span> expr</span>:</span> Rs2</span> }</span></span></code></pre>
Generated Rust:</p>
(</span>(</span>cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs2 </span>as</span> usize</span>]</span> as</span> u32</span>)</span> as</span> i64</span>)</span></span></code></pre>
Truncate to 32-bit: cast to u32</code> (drop upper bits), then back to i64</code>.</p>
XlenMatch { bit32, bit64 }</code></strong> — runtime dispatch on the CPU's word size.</p>
AST:</p>
XlenMatch</span> {</span></span>
    bit32</span>:</span> Cast</span> {</span> from</span>:</span> W32</span>,</span> to</span>:</span> W32</span>,</span> sign</span>:</span> Unsigned</span>,</span> expr</span>:</span> Rs1</span> }</span>,</span></span>
    bit64</span>:</span> Rs1</span>,</span></span>
}</span></span></code></pre>
Generated Rust:</p>
match</span> cpu</span>.</span>xlen </span>{</span></span>
    crate</span>::</span>emulator</span>::</span>cpu</span>::</span>Xlen</span>::</span>Bit32</span> =></span> (</span>(</span>cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span> as</span> u32</span>)</span> as</span> i64</span>)</span>,</span></span>
    crate</span>::</span>emulator</span>::</span>cpu</span>::</span>Xlen</span>::</span>Bit64</span> =></span> cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span>,</span></span>
}</span></span></code></pre>
Each branch is processed by generate_ast_expr</code> independently.</p>
generate_ast_stmt</code> (tracer-macros/src/rust_backend.rs:44</code>)</h2>
This function receives a syn::Expr</code> and matches on the function name to determine which AstStmt</code> variant it is.
Every variant's arguments that represent values are processed by generate_ast_expr</code>.
The output is always a TokenStream2</code> that modifies CPU state.</p>
The outer match is on the syn::Expr</code> variant:</p>

Expr::Call(call)</code> — the common case.
Extract the function name from call.func</code>, then match on it.</li>
Expr::Path(p)</code> — a bare identifier.
Only Nop</code> is valid here.</li>
Anything else — error: "expected a Stmt variant"</code>.</li>
</ul>
The full function is at tracer-macros/src/rust_backend.rs:44-179</code>.</p>
The Expr::Call</code> match table:</p>
Name</th> Args</th> What it emits</th></tr></thead>

WriteRd</code></td> 1 expr</td> cpu.write_register(self.operands.rd, val)</code></td></tr>
WriteReg</code></td> 2 exprs (reg, value)</td> cpu.write_register(reg, val)</code></td></tr>
WritePc</code></td> 1 expr</td> cpu.pc = val as u64</code></td></tr>
Branch</code></td> 2 exprs (cond, target)</td> if cond != 0 { cpu.pc = target as u64 }</code></td></tr>
Assert</code></td> 2 exprs (lhs, rhs)</td> assert_eq!(lhs, rhs)</code></td></tr>
Store</code></td> 3: width, expr, expr</td> MMU store call (method chosen by width)</td></tr>
Load</code></td> 3: string, width, expr</td> MMU load call, binds result to named variable</td></tr>
LetStmt</code></td> 2: string, expr</td> let name = val;</code></td></tr>
Seq</code></td> 1 array</td> iterates elements, calls generate_ast_stmt</code> on each</td></tr>
Nop</code></td> 0</td> empty token stream</td></tr>
</tbody></table>
More Examples</h2>
We already saw LW above. Here are a few more instructions to show how the AST scales to different patterns — stores, atomics, and mixed read-write operations.</p>
SW (Store Word)</h3>
A store is the reverse of a load: compute an address, write a value to memory. The AST is a single line.</p>
fn</span> ast</span>(</span>)</span> -></span> Stmt</span> {</span></span>
    Store</span>(</span>W32</span>,</span> Add</span>(</span>Rs1</span>,</span> Imm</span>)</span>,</span> Rs2</span>)</span></span>
}</span></span></code></pre>







  
    fn</span> exec</span>(</span>&</span>self</span>,</span> cpu</span>:</span> &</span>mut</span> Cpu</span>,</span></span>
    ram_access</span>:</span> &</span>mut</span> <</span>SW</span> as</span></span>
        RISCVInstruction</span>></span>::</span>RAMAccess</span>)</span></span>
{</span></span>
    *</span>ram_access</span> =</span> cpu</span>.</span>mmu</span>.</span>store_word</span>(</span></span>
        cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span></span>
            .</span>wrapping_add</span>(</span>self</span>.</span>operands</span>.</span>imm</span>)</span></span>
            as</span> u64</span>,</span></span>
        cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs2 </span>as</span> usize</span>]</span></span>
            as</span> u32</span>,</span></span>
    )</span>.</span>ok</span>(</span>)</span>.</span>unwrap</span>(</span>)</span>;</span></span>
}</span></span></code></pre>
    Hand-written exec</figcaption>
  </figure>
  
    fn</span> ast_exec</span>(</span>&</span>self</span>,</span></span>
    cpu</span>:</span> &</span>mut</span> crate</span>::</span>emulator</span>::</span>cpu</span>::</span>Cpu</span>,</span></span>
    _ram_access</span>:</span> &</span>mut</span> <</span>SW</span> as</span></span>
        crate</span>::</span>instruction</span>::</span>RISCVInstruction</span>></span>::</span>RAMAccess</span>)</span></span>
{</span></span>
    crate</span>::</span>instruction</span>::</span>RecordWrite</span></span>
        ::</span>record_write</span>(</span></span>
            _ram_access</span>,</span></span>
            cpu</span>.</span>mmu</span>.</span>store_word</span>(</span></span>
                cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span></span>
                    .</span>wrapping_add</span>(</span>self</span>.</span>operands</span>.</span>imm</span>)</span></span>
                    as</span> u64</span>,</span></span>
                cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs2 </span>as</span> usize</span>]</span></span>
                    as</span> u32</span>,</span></span>
            )</span>.</span>ok</span>(</span>)</span>.</span>unwrap</span>(</span>)</span>,</span></span>
        )</span>;</span></span>
}</span></span></code></pre>
    Auto-generated ast_exec</figcaption>
  </figure>
</div>

AMOADDW (Atomic Add Word)</h3>
An atomic read-modify-write: load a word, add rs2</code> to it, store the result back, and write the original value to rd</code>. This exercises most of the grammar — Load</code>, LetStmt</code>, Store</code>, Cast</code>, and WriteRd</code> all in one Seq</code>.</p>
fn</span> ast</span>(</span>)</span> -></span> Stmt</span> {</span></span>
    Seq</span>(</span>[</span></span>
        Load</span>(</span>"</span>raw</span>"</span>,</span> W32</span>,</span> Rs1</span>)</span>,</span></span>
        LetStmt</span>(</span>"</span>orig</span>"</span>,</span> Cast</span> {</span> from</span>:</span> W32</span>,</span> to</span>:</span> W64</span>,</span> sign</span>:</span> Signed</span>,</span> expr</span>:</span> Var</span>(</span>"</span>raw</span>"</span>)</span> }</span>)</span>,</span></span>
        Store</span>(</span>W32</span>,</span> Rs1</span>,</span> Cast</span> {</span> from</span>:</span> W64</span>,</span> to</span>:</span> W32</span>,</span> sign</span>:</span> Unsigned</span>,</span> expr</span>:</span></span>
            Add</span>(</span>Var</span>(</span>"</span>orig</span>"</span>)</span>,</span> Cast</span> {</span> from</span>:</span> W64</span>,</span> to</span>:</span> W32</span>,</span> sign</span>:</span> Signed</span>,</span> expr</span>:</span> Rs2</span> }</span>)</span></span>
        }</span>)</span>,</span></span>
        WriteRd</span>(</span>Var</span>(</span>"</span>orig</span>"</span>)</span>)</span>,</span></span>
    ]</span>)</span></span>
}</span></span></code></pre>







  
    fn</span> exec</span>(</span>&</span>self</span>,</span> cpu</span>:</span> &</span>mut</span> Cpu</span>,</span></span>
    _</span>:</span> &</span>mut</span> <</span>AMOADDW</span> as</span></span>
        RISCVInstruction</span>></span>::</span>RAMAccess</span>)</span></span>
{</span></span>
    let</span> address</span> =</span></span>
        cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span></span>
            as</span> u64</span>;</span></span>
    let</span> add_value</span> =</span></span>
        cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs2 </span>as</span> usize</span>]</span></span>
            as</span> i32</span>;</span></span>
    let</span> load_result</span> =</span></span>
        cpu</span>.</span>mmu</span>.</span>load_word</span>(</span>address</span>)</span>;</span></span>
    let</span> original_value</span> =</span> match</span> load_result</span> {</span></span>
        Ok</span>(</span>(</span>word</span>,</span> _</span>)</span>)</span> =></span> word</span> as</span> i32</span> as</span> i64</span>,</span></span>
        Err</span>(</span>_</span>)</span> =></span> panic!</span>(</span>"</span>MMU load error</span>"</span>)</span>,</span></span>
    }</span>;</span></span>
    let</span> new_value</span> =</span> (</span>original_value</span> as</span> i32</span>)</span></span>
        .</span>wrapping_add</span>(</span>add_value</span>)</span> as</span> u32</span>;</span></span>
    cpu</span>.</span>mmu</span>.</span>store_word</span>(</span>address</span>,</span> new_value</span>)</span></span>
        .</span>expect</span>(</span>"</span>MMU store error</span>"</span>)</span>;</span></span>
    cpu</span>.</span>write_register</span>(</span></span>
        self</span>.</span>operands</span>.</span>rd </span>as</span> usize</span>,</span></span>
        original_value</span>)</span>;</span></span>
}</span></span></code></pre>
    Hand-written exec</figcaption>
  </figure>
  
    fn</span> ast_exec</span>(</span>&</span>self</span>,</span></span>
    cpu</span>:</span> &</span>mut</span> crate</span>::</span>emulator</span>::</span>cpu</span>::</span>Cpu</span>,</span></span>
    _ram_access</span>:</span> &</span>mut</span> <</span>AMOADDW</span> as</span></span>
        crate</span>::</span>instruction</span>::</span>RISCVInstruction</span>></span>::</span>RAMAccess</span>)</span></span>
{</span></span>
    let</span> (</span>raw</span>,</span> _ram_read</span>)</span> =</span> cpu</span>.</span>mmu</span></span>
        .</span>load_word</span>(</span></span>
            cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span></span>
                as</span> u64</span>)</span></span>
        .</span>expect</span>(</span>"</span>MMU load error</span>"</span>)</span>;</span></span>
    crate</span>::</span>instruction</span>::</span>RecordRead</span></span>
        ::</span>record_read</span>(</span></span>
            _ram_access</span>,</span> _ram_read</span>)</span>;</span></span>
    let</span> raw</span> =</span> raw</span> as</span> i64</span>;</span></span>
    let</span> orig</span> =</span> (</span>raw</span> as</span> i32</span> as</span> i64</span>)</span>;</span></span>
    crate</span>::</span>instruction</span>::</span>RecordWrite</span></span>
        ::</span>record_write</span>(</span></span>
            _ram_access</span>,</span></span>
            cpu</span>.</span>mmu</span>.</span>store_word</span>(</span></span>
            cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs1 </span>as</span> usize</span>]</span></span>
                as</span> u64</span>,</span></span>
            (</span>(</span>orig</span>.</span>wrapping_add</span>(</span></span>
                (</span>cpu</span>.</span>x</span>[</span>self</span>.</span>operands</span>.</span>rs2 </span>as</span> usize</span>]</span></span>
                    as</span> i32</span> as</span> i64</span>)</span>)</span></span>
                as</span> u32</span>)</span> as</span> i64</span>)</span> as</span> u32</span>,</span></span>
        )</span>.</span>ok</span>(</span>)</span>.</span>unwrap</span>(</span>)</span>,</span></span>
    )</span>;</span></span>
    let</span> _rd_val</span> =</span> orig</span>;</span></span>
    cpu</span>.</span>write_register</span>(</span></span>
        self</span>.</span>operands</span>.</span>rd </span>as</span> usize</span>,</span> _rd_val</span>)</span>;</span></span>
}</span></span></code></pre>
    Auto-generated ast_exec</figcaption>
  </figure>
</div>

What About Lean Code Generation?</h2>
The same AST can also be compiled to Lean. The Lean backend (tracer-macros/src/lean_backend.rs</code>) walks the same syn</code> tree and emits Lean 4 definitions instead of Rust code.</p>
Here is the hand-written Lean for LW (from earlier in the post) alongside the auto-generated version:</p>








  
    def</span> lw</span> (rs1 rd : BitVec </span>5</span>)</span></span>
    (imm : BitVec </span>12</span>)</span></span>
    (s : State) : State :=</span></span>
  let</span> base := read rs1 s.reg</span></span>
  let</span> addr := imm.setWidth </span>64</span> + base</span></span>
  if</span> addr &&& </span>3</span>#</span>64</span> ≠ </span>0</span>#</span>64</span> then</span></span>
    { s </span>with</span> error := </span>true</span> }</span></span>
  else</span></span>
    let</span> word := read_word addr s</span></span>
    let</span> new_reg :=</span></span>
      write rd (word.signExtend </span>64</span>) s.reg</span></span>
    { s </span>with</span> reg := new_reg }</span></span></code></pre>
    Hand-written Lean</figcaption>
  </figure>
  
    def</span> lw</span> (rs1 rs2 rd : BitVec </span>5</span>)</span></span>
    (imm : BitVec </span>12</span>)</span></span>
    (s : State) : State :=</span></span>
  if</span> (read rs1 s.reg + imm.signExtend </span>64</span>)</span></span>
      &&& </span>3</span>#</span>64</span> ≠ </span>0</span>#</span>64</span> then</span></span>
    { s </span>with</span> error := </span>true</span> }</span></span>
  else</span></span>
  let</span> v :=</span></span>
    read_word</span></span>
      (read rs1 s.reg + imm.signExtend </span>64</span>) s</span></span>
  let</span> new_reg :=</span></span>
    write rd</span></span>
      (((v).truncate </span>32</span>).signExtend </span>64</span>) s.reg</span></span>
  { s </span>with</span> reg := new_reg }</span></span></code></pre>
    Auto-generated Lean</figcaption>
  </figure>
</div>


  
  The Lean backend is still a work in progress — the auto-generated code may or may not compile right now. It is structurally equivalent to the hand-written version but differs in minor details — for instance, it always takes rs1 rs2 rd</code> in the signature even when rs2</code> is unused, and it inlines the address computation rather than binding intermediates.</p>

</div>


Sumchecks Bloody Sumchecks
2026-02-20T00:00:00+00:00
I think that's what Bono</a> really meant to say.
But it was the 80s, disco was alive, Ozzy Osbourne was biting heads off bats, and boys didn't cry</a>; so we must have lost it in the smoke.</p>
The cryptography team at A16z</a>, however, did not get it mixed up.
They've designed this zk-VM, Jolt</a>, that essentially reduces proving correct program execution to proving that a sequence of polynomial constraints are satisfied.</p>
Once these constraints are defined, they go on to use the sum-check algorithm to efficiently prove that the constraints are indeed satisfied.
There's a lot of drama about how to do this efficiently and correctly, and it can get quite complicated.
Each constraint takes the form</p>
$$
g(X) = f(X) \quad \forall X \in \bit^n
$$</p>
where $g, f \in \mathbb{F}[X_1, \ldots, X_n]$ are multi-linear extensions of functions over the program trace.
To show that the two polynomials are the same, we sample a random point $r \xleftarrow{$} \mathbb{F}^n$, and check if</p>
 $$$ \begin{align*} f(r) &= g(r) \\[10pt] &= \sum_{X \in \bit^n }\eq{r}{X} g(X) \end{align*} $$ </div> From the guarantees of Schwartz–Zippel lemma</a>, we are guaranteed that the constraints are satisfied with high probability if the check passes.</p> The problem we have is — if we ask you to list every constraint (or equivalently, its randomised sum-check representation, as shown above) — it is actually non-trivial to extract this information from the source code.</p> So we went ahead, read through the code, and rewrote the sum-checks as an abstract syntax tree. This lets us programmatically extract the sum-check equations, print them in any format we want, and also verify that virtual polynomial openings are reduced to real committed polynomial openings1</a></sup>.</p> Below is a brief description of what we did. Here</a> is the code.</p> Caveat:</strong> The specs currently omit Jolt's Advice</em> polynomials — auxiliary inputs the prover supplies to shortcut certain computations. They participate in some sumchecks but are not yet modelled in the AST. Consider the specs a faithful-but-incomplete picture of the full pipeline. In the coming weeks, we will integrate this into the actual Rust codebase, so we can auto-generate the sum-checks as a zero-cost abstraction. For now we live with the potential noise of translating Rust into Python and generating specs from it.</p> </blockquote> 1</sup> Typically the way a sum-check oracle is simulated in practice is by having the prover commit to the polynomial using a polynomial commitment scheme, and then open the commitment at a random point. There are 21 sum-checks in Jolt, over 50-odd polynomials. Only 7 of them are committed. In Jolt we reduce the correctness of opening the other non-committed polynomials to opening a committed polynomial.</p> </div> Each sumcheck is an abstract syntax tree</h2> As described above, every sumcheck in Jolt proves a statement of this shape:</p> $$\sum_{\text{vars}} f(\text{vars}) = \text{claimed sum}$$</p> We represent each one as a SumcheckSpec</code> with three core fields and four pieces of protocol metadata:</p> Field</th>What it is</th></tr></thead> sum_vars</code></td>The variables being summed over (list of Var</code>)</td></tr> integrand</code></td>The expression tree $f$ inside the $\sum$</td></tr> input_claim</code></td>What the sum equals — the RHS</td></tr> opening_point</code></td>The fresh random point the protocol produces</td></tr> degree</code></td>Max degree of the round polynomials</td></tr> rounds</code></td>How many rounds (e.g. log2(T)</code>)</td></tr> openings</code></td>Which polynomial openings are produced afterward</td></tr> </tbody></table> The first three are the mathematics. The rest is protocol metadata. And degree</code> is auto-checkable: we can walk the integrand tree and infer it from the MLE structure, since every polynomial in Jolt is multilinear (degree $\leq 1$ in each variable).</p> sumcheck/spec.py:76</code></p> @</span>dataclass</span></span> class</span> SumcheckSpec</span>:</span></span> name</span>:</span> str</span></span> sum_vars</span>:</span> list</span>[</span>Var</span>]</span> #</span> what we sum over</span></span> integrand</span>:</span> Expr</span> #</span> the expression tree inside the Σ</span></span> input_claim</span>:</span> Expr</span> #</span> what the sum equals (RHS)</span></span> opening_point</span>:</span>$

More Examples</h2>
We already saw LW above. Here are a few more instructions to show how the AST scales to different patterns — stores, atomics, and mixed read-write operations.</p>

Sumchecks Bloody Sumchecks

Anatomy Of A Jolt Sumcheck

Small Scalar Binding

Tracked Types

Algorithms For Montgomery Multiplication

Montgomery Multiplication: Theory Vs Practice

Benchmarking Details</h2>
We first describe our findings, and then describe how to recreate the analysis workflow.</p>

Compiling RISCV-SAIL Into Lean4 Cpuu

Lost in Translation

Compiling RISCV-SAIL Into Lean4 Cpuu

Lost in Translation

More Examples</h2> We already saw LW above. Here are a few more instructions to show how the AST scales to different patterns — stores, atomics, and mixed read-write operations.</p>

Sumchecks Bloody Sumchecks

Anatomy Of A Jolt Sumcheck

The Remaining Rounds</h2> With $\widetilde{A}$ and $\widetilde{B}$ materialised, the remaining rounds are standard. The mental picture is the following:</p> </p>

Small Scalar Binding

Tracked Types

Algorithms For Montgomery Multiplication

Repeat The Subroutine $n$ times</h3> Now we can play the subroutine again with $c^{(1)}_1$ replacing the role of $c_0$, and the updated value of $m = \mu_0c_1^{(1)}$ (NOTE</strong> the same $\mu_0$ is always used)</p>

Why Can't This Answer Be Greater Than $2p$ ?</h3> What did we actually do in the above process ? Over $n$ iterations, in each iteration, we computed $m$, added $mp$ to $c$ and divided by $r$. We denote the $m$ in iteration $i$ with $m_i$ here. More explicitly,</p>

Aside: Same Code Two Conclusions</h3> As a brief distraction, in this section, we give an example of how finicky performance benchmarking can be.</p>

Montgomery Multiplication: Theory Vs Practice

Benchmarking Details</h2> We first describe our findings, and then describe how to recreate the analysis workflow.</p>

More Examples</h2>
We already saw LW above. Here are a few more instructions to show how the AST scales to different patterns — stores, atomics, and mixed read-write operations.</p>

Benchmarking Details</h2>
We first describe our findings, and then describe how to recreate the analysis workflow.</p>