Random Walks

Jolt System Mismatch

2026-06-19T00:00:00+00:00

Jolt Implementation Of CSRRW#</a> </h2>

Jolt supports the writing of 6 control status registers, namely, mstatus, mtvec, mepc, mtval, mscratch, mcause</code>; and it treats the writing to each of these registers uniformly.

The assembly signature is csrrw rd, csr, rs1</code> and the pseudocode of semantics in the Jolt expansion is roughly:

if rd = x0 then </span></span>
    [vreg_csr] <- [rs1] + 0 -- implemented via ADDI</span></span>
if rd = rs1 then </span></span>
    tmp <- [rs1] + 0</span></span>
    [rd] <- [vreg_csr] + 0 </span></span>
    [v_reg_csr] <- tmp + 0</span></span>
else </span></span>
    [rd] <- [vreg_csr]</span></span>
    [v_reg_csr] <- [rs1]</span></span></code></pre>
This can be verified against the Jolt source code</a>.</p>


  
  Problem</div>
  
  The issue</strong> is that the RISC-V specification does not treat writes to control status registers uniformly.
Depending on the status register being written to, the logic differs.</p>
For mscratch, mcause, mtval</code>, the above logic agrees with the RISC-V specification.
For the remaining three, the spec asks that we first legalize the value in rs1</code> before writing it to the control status register.</p>
More details below.</p>

</aside>

mtvec#</a>
</h2>
As per the Sail spec, which we checked to be correct1</a></sup>, the value written to the contents of mtvec</code> control status register is given by</p>
writeReg mtvec (← (legalize_tvec (← readReg mtvec) value))</span></span></code></pre>
which in simple speak is saying first apply the legalize_tvec</code> function with inputs the old_mtvec</code> value and rs1_value</code> and then write the control status register.
The legalize_tvec</code> function is given by</p>
def</span> legalize_tvec</span> (o : (BitVec </span>64</span>)) (v : (BitVec </span>64</span>)) : SailM (BitVec </span>64</span>) := </span>do</span></span>
  let</span> v := (Mk_Mtvec v) -- identity function.</span></span>
  match</span> (trapVectorMode_of_bits (_get_Mtvec_Mode v)) </span>with</span></span>
  | TV_Direct => (pure v) -- we </span>have</span> to prove that we are </span>in</span> TV_Direct</span></span>
  | TV_Vector => (pure v) -- or TV_Vector </span></span>
  | _ =></span></span>
    (</span>do</span></span>
      match</span> xtvec_mode_reserved_behavior </span>with</span></span>
      | Xtvec_Fatal =></span></span>
        (reserved_behavior</span></span>
          (HAppend.hAppend </span>"Tried to write a reserved value ("</span></span>
            (HAppend.hAppend (Int.repr (BitVec.toNatInt (_get_Mtvec_Mode v)))</span></span>
              ") to the MODE field of xtvec."</span>)))</span></span>
      | Xtvec_Ignore => (pure (_update_Mtvec_Mode v (_get_Mtvec_Mode o))))</span></span></code></pre>
Given the functional-language nature of Lean, the above might seem hard to parse, but all that’s going on is the following:</p>
The match statement is saying: get the lowest two bits of rs1_val</code>.
If that value is 00</code> or 01</code>, then [vreg_csr] <- [rs1_val]</code>, as in Jolt.
Otherwise, grab the two least-significant bits of mtvec</code>, overwrite rs1_val</code>’s lowest two bits with them, and then write this updated value into mtvec</code>.</p>
</p>
Now for the Jolt code to be correct, we must prove</em> that the lowest two bits of rs1_val</code> are always either 00</code> or 01</code>.
But Jolt does not</strong> promise this.</p>
mepc#</a>
</h2>
The first step is to read the old mepc</code> value.</p>
if</span> ((bne access_type CSRWrite) : Bool)</span></span>
            then</span> (read_CSR csr) -- read csr (we take this branch)</span></span>
            else</span> (pure (zeros (n := </span>64</span>))) ) : SailM xlenbits )</span></span></code></pre>
which for mepc</code> — whose 12-bit address is 0x341</code> — results in the call</p>
  | </span>0x341</span> => (get_xepc Machine)</span></span></code></pre>
which in turn returns</p>
(align_pc (← readReg mepc))</span></span></code></pre>
So in simple speak: we read the current value in the mepc</code> register, and then align it first:</p>
def</span> align_pc</span> (addr : (BitVec </span>64</span>)) : SailM (BitVec </span>64</span>) := </span>do</span></span>
  if</span> ((← (currentlyEnabled Ext_Zca)) : Bool)</span></span>
  then</span> (pure (BitVec.update addr </span>0 0</span>#</span>1</span>))</span></span>
  else</span> (pure (Sail.BitVec.updateSubrange addr </span>1 0</span> (zeros (n := (</span>1</span> -i (</span>0</span> -i </span>1</span>))))))</span></span></code></pre>
So the old value read from mepc</code> is not the value before update (as Jolt assumes), but that value with its low bit cleared.
Note that because this hart enables Ext_Zca</code> (hartSupports Ext_Zca => true</code>), the active</em> branch is BitVec.update addr 0 0#1</code>, which clears bit 0 only</strong>; the else</code> branch clearing bits [1:0]</code> is reached only when Zca</code> is disabled.2</a></sup></p>
Similarly, before writing to mepc</code>, we compute:</p>
let</span> target := (legalize_xepc rs1_value)</span></span></code></pre>
where</p>
def</span> legalize_xepc</span> (v : (BitVec </span>64</span>)) : (BitVec </span>64</span>) :=</span></span>
  if</span> ((hartSupports Ext_Zca) : Bool)</span></span>
  then</span> (BitVec.update v </span>0 0</span>#</span>1</span>)</span></span>
  else</span> (Sail.BitVec.updateSubrange v </span>1 0</span> (zeros (n := (</span>1</span> -i (</span>0</span> -i </span>1</span>)))))</span></span></code></pre>
So both the read (align_pc</code>) and the write (legalize_xepc</code>) clear mepc</code>’s low bits, whereas Jolt copies rs1_val</code> into the virtual register verbatim ([vreg_csr] <- [rs1] + 0</code>, via ADDI</code>) and later reads it back verbatim.</p>
Now for the Jolt code to be correct, we must prove</em> that every value written to mepc</code> is already aligned — i.e. bit 0 of rs1_val</code> is always 0</code> (or bits [1:0]</code> are 00</code> when Zca</code> is disabled).
But this guard does not exist in Jolt.</p>
mstatus#</a>
</h2>
This is also a bug, but the write is more complex, in that I have to parse the following Lean code to give you the clean algorithm.
I’ll do this in a couple of days.</p>
-- v = [rs1]</span></span>
-- o = [mstatus]</span></span>
def</span> legalize_mstatus</span> (o : (BitVec </span>64</span>)) (v : (BitVec </span>64</span>)) : SailM (BitVec </span>64</span>) := </span>do</span></span>
  let</span> v := (Mk_Mstatus v) -- overwrite v </span></span>
  let</span> o ← </span>do</span></span>
    (pure (_update_Mstatus_SIE</span></span>
        (_update_Mstatus_MIE</span></span>
          (_update_Mstatus_SPIE</span></span>
            (_update_Mstatus_MPIE</span></span>
              (_update_Mstatus_VS</span></span>
                (_update_Mstatus_SPP</span></span>
                  (_update_Mstatus_MPP</span></span>
                    (_update_Mstatus_FS</span></span>
                      (_update_Mstatus_XS</span></span>
                        (_update_Mstatus_MPRV</span></span>
                          (_update_Mstatus_SUM</span></span>
                            (_update_Mstatus_MXR</span></span>
                              (_update_Mstatus_TVM</span></span>
                                (_update_Mstatus_TW</span></span>
                                  (_update_Mstatus_TSR</span></span>
                                    (_update_Mstatus_SPELP</span></span>
                                      (_update_Mstatus_MPELP o</span></span>
                                        (</span>if</span> ((hartSupports Ext_Zicfilp) : Bool)</span></span>
                                        then</span> (_get_Mstatus_MPELP v)</span></span>
                                        else</span> 0</span>#</span>1</span>))</span></span>
                                      (</span>if</span> ((hartSupports Ext_Zicfilp) : Bool)</span></span>
                                      then</span> (_get_Mstatus_SPELP v)</span></span>
                                      else</span> 0</span>#</span>1</span>))</span></span>
                                    (← </span>do</span></span>
                                      if</span> ((← (currentlyEnabled Ext_S)) : Bool)</span></span>
                                      then</span> (pure (_get_Mstatus_TSR v))</span></span>
                                      else</span> (pure </span>0</span>#</span>1</span>)))</span></span>
                                  (← </span>do</span></span>
                                    if</span> ((← (currentlyEnabled Ext_U)) : Bool)</span></span>
                                    then</span> (pure (_get_Mstatus_TW v))</span></span>
                                    else</span> (pure </span>0</span>#</span>1</span>)))</span></span>
                                (← </span>do</span></span>
                                  if</span> ((← (currentlyEnabled Ext_S)) : Bool)</span></span>
                                  then</span> (pure (_get_Mstatus_TVM v))</span></span>
                                  else</span> (pure </span>0</span>#</span>1</span>)))</span></span>
                              (← </span>do</span></span>
                                if</span> ((← (currentlyEnabled Ext_S)) : Bool)</span></span>
                                then</span> (pure (_get_Mstatus_MXR v))</span></span>
                                else</span> (pure </span>0</span>#</span>1</span>)))</span></span>
                            (← </span>do</span></span>
                              if</span> ((← (virtual_memory_supported ())) : Bool)</span></span>
                              then</span> (pure (_get_Mstatus_SUM v))</span></span>
                              else</span> (pure </span>0</span>#</span>1</span>)))</span></span>
                          (← </span>do</span></span>
                            if</span> ((← (currentlyEnabled Ext_U)) : Bool)</span></span>
                            then</span> (pure (_get_Mstatus_MPRV v))</span></span>
                            else</span> (pure </span>0</span>#</span>1</span>))) (extStatus_to_bits Off))</span></span>
                      (</span>if</span> ((hartSupports Ext_Zfinx) : Bool)</span></span>
                      then</span> (extStatus_to_bits Off)</span></span>
                      else</span> (_get_Mstatus_FS v)))</span></span>
                    (← </span>do</span></span>
                      if</span> ((← (have_nominal_privLevel (_get_Mstatus_MPP v))) : Bool)</span></span>
                      then</span> (pure (_get_Mstatus_MPP v))</span></span>
                      else</span> (pure (privLevel_to_bits (← (lowest_supported_privLevel ()))))))</span></span>
                  (← </span>do</span></span>
                    if</span> ((← (currentlyEnabled Ext_S)) : Bool)</span></span>
                    then</span> (pure (_get_Mstatus_SPP v))</span></span>
                    else</span> (pure </span>0</span>#</span>1</span>)))</span></span>
                (</span>if</span> ((hartSupports Ext_Zve32x) : Bool)</span></span>
                then</span> (_get_Mstatus_VS v)</span></span>
                else</span> 0b00#</span>2</span>)) (_get_Mstatus_MPIE v))</span></span>
            (← </span>do</span></span>
              if</span> ((← (currentlyEnabled Ext_S)) : Bool)</span></span>
              then</span> (pure (_get_Mstatus_SPIE v))</span></span>
              else</span> (pure </span>0</span>#</span>1</span>))) (_get_Mstatus_MIE v))</span></span>
        (← </span>do</span></span>
          if</span> ((← (currentlyEnabled Ext_S)) : Bool)</span></span>
          then</span> (pure (_get_Mstatus_SIE v))</span></span>
          else</span> (pure </span>0</span>#</span>1</span>))))</span></span>
  let</span> dirty :=</span></span>
    (((extStatus_of_bits (_get_Mstatus_FS o)) == Dirty) || (((extStatus_of_bits (_get_Mstatus_XS o)) == Dirty) || ((extStatus_of_bits</span></span>
            (_get_Mstatus_VS o)) == Dirty)))</span></span>
  (pure (_update_Mstatus_SD o (bool_to_bit dirty)))</span></span></code></pre>MRET Issue#</a>
</h2>
Sail’s MRET handler does not merely produce a target PC. It first mutates mstatus and cur_privilege, then reads mepc through prepare_xret_target
Machine, then execute_MRET writes nextPC..</p>
</span>
Before MRET</span></span>
</span>
Jolt:</span></span>
  pc              = current pc</span></span>
  nextPC          = old nextPC</span></span>
  cur_privilege   = Machine</span></span>
  mepc            = return target</span></span>
  mstatus.MPP     = Machine</span></span>
  mstatus.MIE     = old MIE</span></span>
  mstatus.MPIE    = old MPIE</span></span>
  mstatus.MPRV    = old MPRV</span></span>
</span>
Sail:</span></span>
  PC              = current pc</span></span>
  nextPC          = old nextPC</span></span>
  cur_privilege   = Machine</span></span>
  mepc            = return target</span></span>
  mstatus.MPP     = Machine</span></span>
  mstatus.MIE     = old MIE</span></span>
  mstatus.MPIE    = old MPIE</span></span>
  mstatus.MPRV    = old MPRV</span></span>
</span>
After MRET</span></span>
</span>
Jolt:</span></span>
  pc / nextPC      = mepc</span></span>
  cur_privilege    = Machine</span></span>
  mepc             = unchanged</span></span>
  mstatus.MPP      = Machine      <-- unchanged</span></span>
  mstatus.MIE      = old MIE      <-- unchanged</span></span>
  mstatus.MPIE     = old MPIE     <-- unchanged</span></span>
  mstatus.MPRV     = old MPRV     <-- unchanged</span></span>
</span>
Sail:</span></span>
  nextPC           = mepc</span></span>
  cur_privilege    = Machine      <-- old mstatus.MPP</span></span>
  mepc             = unchanged</span></span>
  mstatus.MPP      = User         <-- mismatch (No way to get this to align)</span></span>
  mstatus.MIE      = old MPIE     <-- mismatch unless old MIE = old MPIE</span></span>
  mstatus.MPIE     = 1            <-- mismatch unless old MPIE = 1</span></span>
  mstatus.MPRV     = old MPRV     <-- unchanged because cur_privilege remains Machine</span></span>
</span></code></pre>
The problem here is there is NO</strong> way to tell sail that that privilege level will not be lowered to user, as Jolt says by writing 1 to bit 20 of the misa that user mode is enabled.
So if that is the case, the sail spec says we MUST</strong> reduce privilege when returning from a trap.
Unfortunately, jolt is always</strong> in Machine mode.</p>
</span>
writeReg mstatus (Sail.BitVec.updateSubrange (← readReg mstatus) </span>12 11</span></span>
  (privLevel_to_bits</span></span>
    (← </span>do</span></span>
      if</span> ((← (currentlyEnabled Ext_U)) : Bool)</span></span>
      then</span> (pure User)</span></span>
      else</span> (pure Machine))))</span></span></code></pre>References#</a>
</h2>
All claims above can also be checked against the official RISC-V ISA docs</p>

mtvec</a></li>
mepc</a></li>
</ul>



Checked against the official RISC-V privileged ISA, which defines mtvec</code></a> as a WARL</strong> register whose MODE</code> field has only the Direct</code> (0b00</code>) and Vectored</code> (0b01</code>) encodings. ↩</a></p>
</li>

Zca</code> enables 16-bit (compressed) instructions. See the official Zc* specification</a>. ↩</a></p>
</li>
</ol>
</section>

Equivalence Statements And Assumptions 2026-05-22T00:00:00+00:00 The Jolt-qed project verifies, in Lean, that each Jolt bytecode expansion has the same effect as the RISC-V instruction it replaces. These equivalence theorems are not unconditional: they rely on explicit hypotheses about the RISC-V/Jolt state, plus a small number of trusted edits to the generated RISC-V model so that it matches the Jolt CPU. This post records those proof assumptions and trusted-code changes. Changes to the Trusted RISC-V Model#</a> </h2> The Lean RISC-V model lives in LeanRV64D/</code>, with the top-level entry point in LeanRV64D.lean</code>. It was generated by automatically transpiling the Sail specification of a RISC-V CPU to Lean1</a>. The Sail-to-Lean post</a> explains how we obtained this generated code. We treat that generated model as trusted throughout the project, except for the two changes below. We say that the RISC-V CPU should not support misaligned memory addressing. We do this because Jolt does not support misaligned addressing, and it would be impossible to prove equivalence otherwise. The Ethereum zkVM Standards v0</a> recommend that zk-VMs use RV64IM+Zicclsm</code> as the target baseline, where Zicclsm</code> is included to support misaligned loads and stores. We highlight this drawback off the bat.</li> </ol> -- WARNING: CHANGE IN TRANSPILED CODE def plat_enable_misaligned_access : Bool := false</code></pre> Jolt does not support the Zicfiss and Zicfilp extensions. Leaving them on makes it impossible to prove equivalences about writing to control status registers.</li> </ol> -- WARNING: (change to sail, Jolt does not support Zicfilp extension). | Ext_Zicfilp => false -- WARNING: (change to sail, Jolt does not support Zicfiss extension). | Ext_Zicfiss => false</code></pre> These are the only changes we make to the generated RISC-V model. Equivalence Statement Structure#</a> </h2> Shown below is the equivalence statement for the sra</code> instruction. It says that running the Jolt instruction sraProgram</code> with arguments rd rs2 rs1</code> on the current Jolt state js</code>, and then projecting down to the RISC-V state, is identical to running sra rd rs2 rs1</code> on the RISC-V state of the current Jolt CPU. In simple words, we could either run the original RISC-V instruction or run the Jolt expansion on the same starting state, and the effect is the same. If we showed this for all RISC-V instructions, then we would show that Jolt faithfully simulates RISC-V. Now to prove this theorem, we use an assumption bundle. The goal of this post is to explain what an assumption bundle is. 1/-- Main program-level equivalence for `SRA`. -/ 2def sraProgramEqSailStatement 3 (rs2 : regidx) 4 (rs1 : regidx) 5 (rd : regidx) 6 (js : SailJoltState) 7 (_h : BinarySourceReadWithLinkedCSRs rs2 rs1 js) -- <--- Assumption bundle 8 : Prop := 9 System.systemProjectResult 10 ((JoltISA.execProgram (JoltISA.sraProgram rs2 rs1 rd)).run js) = 11 (execute_RTYPE rs2 rs1 rd rop.SRA).run js.sail</code></pre> Assumption bundles are conjunctions of assumptions defined in JoltBytecode/Assumptions.lean</code> and collected in JoltBytecode/Bundles.lean</code>. Each equivalence statement in Jolt-qed uses an assumption bundle. Bundles describe exactly which assumptions were used to prove equivalence for a given instruction. An assumption bundle is always made up of a list of assumptions2</a>. This specific assumption bundle is made up of the two groups of assumptions shown below. abbrev BinarySourceReadAssumptions (rs2 rs1 : regidx) (js : SailJoltState) := Assumptions.BinarySourceReadAssumptions rs2 rs1 js.sail private structure LinkedCSRRegisterAssumptions (js : SailJoltState) where mstatus_matches : Assumptions.MstatusVRegMatchesSail js mtvec_matches : Assumptions.MtvecVRegMatchesSail js mscratch_matches : Assumptions.MscratchVRegMatchesSail js mepc_matches : Assumptions.MepcVRegMatchesSail js mcause_matches : Assumptions.McauseVRegMatchesSail js mtval_matches : Assumptions.MtvalVRegMatchesSail js</code></pre> We will explain what these mean below, but the takeaway message is that every equivalence theorem uses an assumption bundle. Any assumption bundle can only be made up of core assumptions listed in Assumptions.lean</code>. Assumptions#</a> </h2> For the rest of the document, we list every assumption used in Jolt. If any assumption that is not listed here, or in Assumptions.lean</code>, is used in a proof bundle, then that should be remedied immediately, and we should check whether the assumption is justified. Privilege Is Always Machine#</a> </h3> structure CurPrivilegeMachine (s : SailState) : Prop where value : s.regs.get? Register.cur_privilege = some (Privilege.Machine : RegisterType Register.cur_privilege)</code></pre> In simple English, the value in current_privilege</code> indicates that the Jolt CPU runs in machine mode all the time. According to the Jolt Rust code base</a>, Jolt always runs in machine mode. The above Lean code simply states that the value in the cur_privilege</code> register is Privilege.Machine</code>. MPP Bit Set To Machine#</a> </h3> structure MstatusMppMachine (js : SailJoltState) : Prop where value_eq : _get_Mstatus_MPP (js.vregs JoltISA.mstatusVReg) = privLevel_to_bits Privilege.Machine</code></pre> Jolt uses virtual register 39 to model the mstatus</code> control status register of the Jolt CPU. Based on the Jolt source code</a>, Jolt always runs in machine mode, and the MPP bit of the status register is always set to Machine</code>. MISA User Enabled#</a> </h3> structure MisaUserEnabled (s : SailState) : Prop where exists_value : ∃ misa : BitVec 64, s.regs.get? Register.misa = some (misa : RegisterType Register.misa) ∧ _get_Misa_U misa = 1#1</code></pre> Jolt initialises misa</code> to 0x800000008014312f</code> based on jolt/tracer/src/emulator/cpu.rs:399</code>. The function _get_Misa_U</code> reads bit 20 of the misa</code> CSR, which, based on the written value, is 1. According to the RISC-V ISA</a>, having bit 20 set to 1 implies user mode is enabled. MPRV Bit#</a> </h3> structure MstatusMprvZero (s : SailState) : Prop where value : ∃ mval : RegisterType Register.mstatus, s.regs.get? Register.mstatus = some mval ∧ _get_Mstatus_MPRV mval = 0#1</code></pre> According to Jolt</a>, the MPRV</code> bit of the mstatus</code> register is set to 0 in Jolt. As a direct consequence of this, we get bare translation: virtual addresses are the same as physical addresses, which is also true in the Jolt code base. In Lean, this is captured by the following three bare-translation theorems for loads, stores, and atomics. We only show the theorem statements here; the proofs are in JoltBytecode/InstructionEquivalence/ProofSupport/BundleLemmas.lean</code>. theorem translateAddr_load_data_of_machine_mprv_zero (addr : BitVec 64) (s : SailState) (hpriv : Assumptions.CurPrivilegeMachine s) (hmprv : Assumptions.MstatusMprvZero s) : translateAddr (Virtaddr addr) (Load Data) s = .ok (Ok (physaddr.Physaddr addr, init_ext_ptw)) s</code></pre>theorem translateAddr_store_data_of_machine_mprv_zero (addr : BitVec 64) (s : SailState) (hpriv : Assumptions.CurPrivilegeMachine s) (hmprv : Assumptions.MstatusMprvZero s) : translateAddr (Virtaddr addr) (Store Data) s = .ok (Ok (physaddr.Physaddr addr, init_ext_ptw)) s</code></pre>theorem translateAddr_atomic_data_of_machine_mprv_zero (op : amoop) (addr : BitVec 64) (s : SailState) (hpriv : Assumptions.CurPrivilegeMachine s) (hmprv : Assumptions.MstatusMprvZero s) : translateAddr (Virtaddr addr) (Atomic (op, Data, Data)) s = .ok (Ok (physaddr.Physaddr addr, init_ext_ptw)) s</code></pre>Zicfilp Extension#</a> </h3> structure ZicfilpDisabled (s : SailState) : Prop where value : currentlyEnabled extension.Ext_Zicfilp s = .ok false s</code></pre> Jolt does not support the Zicfilp extension</a>. Mtvec#</a> </h3> structure MtvecWriteDirectMode (value : BitVec 64) : Prop where mode_eq : _get_Mtvec_Mode value = 0b00#2</code></pre> The RISC-V ISA requires that we legalise values before writing to control and status registers. See this blog</a> for more details. When writing the contents of rs1</code> into the mtvec</code> control and status register, if the value in rs1</code> has the two least significant bits set to 00</code>, then we write rs1</code>’s contents directly into mtvec</code>. Otherwise, we need to legalise the value. The above assumption says the value in rs1</code> will always have the lower two bits set to 00</code>. The ZeroOS/Jolt boot path writes _trap_handler</code> to mtvec</code> with csrw mtvec, t0</code> ZeroOS defines _trap_handler</code> under .align 2</code>, which gives 4-byte alignment, so the lower two bits are 00</code>. Evidence from ZeroOS source code is given below. The ZeroOS boot code writes</a> to mtvec</code>, and the trap handler definition is aligned</a>. Warning</div> This assumption holds when we use the write to mtvec</code> operation as it is meant to be used in Jolt. If a malicious program were to write a different value to Jolt mtvec</code>, Jolt does not have any mechanism to legalise the value. In that case, Jolt would not be following the RISC-V spec. We will rely on the proof mechanism to catch this. </aside> Align PC#</a> </h3> Jolt supports compressed instructions (+c</code> / RV64IMAC), as seen here</a>, so we can only guarantee that the least significant bit of PC is 0. The relevant assumption is that mepc[0] = 0</code>. Thus, the legalisation operation according to the specification is a no-op because the lowest bit is already cleared. structure MepcReadAligned (value : BitVec 64) (s : SailState) : Prop where value_eq : align_pc value s = .ok value s</code></pre> This is the write-side counterpart of MepcReadAligned</code>: CSRRW writes the new rs1</code> value, so the assumption must be about that source value rather than only the old stored mepc</code>. structure MepcWriteLegalized (value : BitVec 64) : Prop where value_eq : legalize_xepc value = value</code></pre>Legalise MStatus#</a> </h3> structure MstatusWriteLegalized (old value : BitVec 64) (s : SailState) : Prop where value_eq : legalize_mstatus old value s = .ok value s</code></pre> Jolt does not legalise before writing to mstatus</code>. The evidence is in the Jolt CSR expansions: CSRRW</code> writes rs1</code> directly into the CSR virtual register, and CSRRS</code> writes the OR of the old CSR value and rs1</code>. See csrrw.rs</code></a> and csrrs.rs</code></a>. Virtual Register Modelling#</a> </h3> Here we are saying that certain virtual registers in Jolt correspond to the control status registers in the Sail state. We could have written directly to the Sail registers in our Jolt semantics, but to be faithful to the Jolt expansion, we write the virtual registers and record that correspondence as an assumption. The Jolt code</a> confirms this. /-- Sail `mstatus` agrees with Jolt's persistent `mstatus` virtual register. -/ structure MstatusVRegMatchesSail (js : SailJoltState) : Prop where value_eq : js.sail.regs.get? Register.mstatus = some (js.vregs JoltISA.mstatusVReg) /-- Sail `mtvec` agrees with Jolt's persistent trap-handler virtual register. -/ structure MtvecVRegMatchesSail (js : SailJoltState) : Prop where value_eq : js.sail.regs.get? Register.mtvec = some (js.vregs JoltISA.trapHandlerVReg) /-- Sail `mscratch` agrees with Jolt's persistent `mscratch` virtual register. -/ structure MscratchVRegMatchesSail (js : SailJoltState) : Prop where value_eq : js.sail.regs.get? Register.mscratch = some (js.vregs JoltISA.mscratchVReg) /-- Sail `mepc` agrees with Jolt's persistent `mepc` virtual register. -/ structure MepcVRegMatchesSail (js : SailJoltState) : Prop where value_eq : js.sail.regs.get? Register.mepc = some (js.vregs JoltISA.mepcVReg) /-- Sail `mcause` agrees with Jolt's persistent `mcause` virtual register. -/ structure McauseVRegMatchesSail (js : SailJoltState) : Prop where value_eq : js.sail.regs.get? Register.mcause = some (js.vregs JoltISA.mcauseVReg) /-- Sail `mtval` agrees with Jolt's persistent `mtval` virtual register. -/ structure MtvalVRegMatchesSail (js : SailJoltState) : Prop where value_eq : js.sail.regs.get? Register.mtval = some (js.vregs JoltISA.mtvalVReg)</code></pre>Memory Assumptions#</a> </h3> structure DwordPresent (addr : BitVec 64) (s : SailState) : Prop where bytes : ∃ bytes : Fin 8 → BitVec 8, ∀ k : Fin 8, s.mem.get? (addr.toNat + k.val) = some (bytes k)</code></pre> Lean models memory as a hash map from natural numbers to 8-bit bitstrings. The natural numbers are countably infinite, while the address space of any CPU is not. Additionally, because memory is modelled as a hash map, Lean needs a hypothesis that the key already exists before it can retrieve the value. This is a proof-engineering issue: the generated model represents memory as a partial map, so we must state that the relevant bytes are present. Thus, the following assumption says that addresses can be read from memory and that they return valid bytes across the entire doubleword window. abbrev LoadPmpOk (addr : BitVec 64) (width : Nat) (s : SailState) : Prop := phys_access_check (Load Data) Privilege.Machine (physaddr.Physaddr addr) width false s = .ok none s /-- Machine-mode PMP accepts every explicit sub-load inside a memory window. -/ structure LoadPmpOkWindow (base : BitVec 64) (width : Nat) (s : SailState) : Prop where ok : ∀ offset accessWidth : Nat, offset + accessWidth ≤ width → LoadPmpOk (base + BitVec.ofNat 64 offset) accessWidth s abbrev StorePmpOk (addr : BitVec 64) (width : Nat) (s : SailState) : Prop := phys_access_check (Store Data) Privilege.Machine (physaddr.Physaddr addr) width false s = .ok none s /-- Machine-mode PMP accepts every explicit sub-store inside a memory window. -/ structure StorePmpOkWindow (base : BitVec 64) (width : Nat) (s : SailState) : Prop where ok : ∀ offset accessWidth : Nat, offset + accessWidth ≤ width → StorePmpOk (base + BitVec.ofNat 64 offset) accessWidth s abbrev AtomicPmpOk (op : amoop) (addr : BitVec 64) (width : Nat) (s : SailState) : Prop := phys_access_check (Atomic (op, Data, Data)) Privilege.Machine (physaddr.Physaddr addr) width true s = .ok none s /-- Machine-mode PMP accepts every explicit sub-AMO inside a memory window. -/ structure AtomicPmpOkWindow (op : amoop) (base : BitVec 64) (width : Nat) (s : SailState) : Prop where ok : ∀ offset accessWidth : Nat, offset + accessWidth ≤ width → AtomicPmpOk op (base + BitVec.ofNat 64 offset) accessWidth s </code></pre> Jolt’s Rust MMU explicitly says memory protection is not implemented. These predicates constrain the generated RISC-V model to the corresponding no-PMP-fault path. Rust source: https://github.com/abiswas3/jolt/blob/main/tracer/src/emulator/mmu.rs#L17</code>. The above assumption says the entire doubleword block read by LD</code> at physical address addr</code> is not protected and can be read. The same applies to writing to memory. To prove equivalence, we need to tell the generated RISC-V model that the address is safe to read from or write to. The generated RISC-V model uses different checks for LD</code>, SD</code>, and atomic operations, so we need three sets of assumptions that say the same thing. abbrev NotReadableMmio (addr : BitVec 64) (width : Nat) (s : SailState) : Prop := within_mmio_readable (physaddr.Physaddr addr) width s = .ok false s structure NotReadableMmioWindow (base : BitVec 64) (width : Nat) (s : SailState) : Prop where ok : ∀ offset accessWidth : Nat, offset + accessWidth ≤ width → NotReadableMmio (base + BitVec.ofNat 64 offset) accessWidth s abbrev NotWritableMmio (addr : BitVec 64) (width : Nat) (s : SailState) : Prop := within_mmio_writable (physaddr.Physaddr addr) width s = .ok false s /-- Every explicit sub-store inside a memory window avoids writable MMIO. -/ structure NotWritableMmioWindow (base : BitVec 64) (width : Nat) (s : SailState) : Prop where ok : ∀ offset accessWidth : Nat, offset + accessWidth ≤ width → NotWritableMmio (base + BitVec.ofNat 64 offset) accessWidth s </code></pre> Rust source: tracer/src/emulator/mmu.rs:139-213</code>. Jolt splits VM memory into reserved low-memory regions for advice, inputs, outputs, panic, and termination, followed by ordinary RAM. These regions share one VM address space and are mapped into the memory witness layout. Ordinary RAM is backed by the emulator memory map, while advice/input/output are modelled by JoltDevice</code>. Jolt does not support device MMIO such as UART, CLINT, PLIC, or disk; accesses to those ranges panic in the tracer. On the generated RISC-V side, memory operations can branch on memory-mapped device addresses, so the proof needs assumptions such as NotReadableMmio</code> and NotWritableMmio</code> to keep execution on the ordinary/Jolt-supported memory path. Register Assumptions#</a> </h3> structure XRegReadable (r : regidx) (s : SailState) : Prop where exists_value : ∃ value : BitVec 64, rX_bits r s = .ok value s structure SailRegReadable (r : Register) (s : SailState) : Prop where exists_value : ∃ value : RegisterType r, s.regs.get? r = some value /-- Assumptions for an instruction that reads one architectural source register. -/ structure UnarySourceReadAssumptions (rs1 : regidx) (s : SailState) where rs1_val : BitVec 64 rs1_read : rX_bits rs1 s = .ok rs1_val s /-- Assumptions for an instruction that reads two architectural source registers. -/ structure BinarySourceReadAssumptions (rs2 rs1 : regidx) (s : SailState) where rs1_val : BitVec 64 rs1_read : rX_bits rs1 s = .ok rs1_val s rs2_val : BitVec 64 rs2_read : rX_bits rs2 s = .ok rs2_val s </code></pre> These assumptions say that the Sail register file is readable. This translation was done by Galois and researchers at Cambridge University. See the Sail-to-Lean post for further details. ↩</a> </li> We could not figure out a way to get the Lean kernel to enforce this in a clean manner without completely redoing the project. So we do this manually by enforcing that each field uses something from the Assumptions</code> namespace. If you, the reader, know a better way to do this, please reach out with a pull request. ↩</a> </li> </ol> </section> Jolt: Introduction 2026-05-22T00:00:00+00:00 Jolt - a Birds Eye View#</a> </h2> A user supplies a guest program1</a> (a RISC-V elf) to Jolt. Jolt runs this program, and writes any outputs on the output tape, along with a proof. A proof is simply another program that the user runs to get output 0 or 1. If the output of the proof is 1, then the user agrees Trace to Polynomials#</a> </h2> Technically this statement is not strictly true. The input also allows some custom instructions that are not native RISC-V instructions. ↩</a> </li> </ol> </section> How to Model a CPU in Lean 2026-05-22T00:00:00+00:00 To prove equivalence with a RISC-V CPU, we first need a RISC-V CPU modeled in Lean. Luckily for us, the teams at Galois</a> and Cambridge University</a> have done the hard work for us. Given a Sail specification of a RISC-V CPU, they translated the Sail specification into non-executable Lean code suitable for theorem proving. The details of how to get this code can be found here</a>. Our starting point will be to understand this transpilation. At its core, a CPU is just a state machine whose state is described by the register file, memory, program counter, control/status registers, and so on1</a>. Instructions describe the ways the machine can transition between states. Of course, there are also the mechanics of how a state transition physically works. For example, on a silicon chip, the CPU emits an address on a bus, and the memory decoder reads this address, selects the matching memory cell, and drives its stored bits back onto the data bus where the CPU latches them into a register. We will not focus on the mechanics of how state transitions happen on a physical chip or in software emulation. Our concern is what happens before and after a state transition. From here on, we refer to the trusted Sail-to-Lean transpilation as Sail code. State#</a> </h2> The RISC-V state, abbreviated as SailState</code>, is given by: 25abbrev SailState := SequentialState RegisterType trivialChoiceSource</code></pre> Here, SequentialState</code> describes the full machine state from the Sail model. It is parameterized2</a> by the function RegisterType : Register → Type</code> and a ChoiceSource</code>. The register file and memory are fields of the structure with details described below. 467structure SequentialState (RegisterType : Register → Type) (c : ChoiceSource) where 468 regs : Std.ExtDHashMap Register RegisterType 469 choiceState : c.α 470 mem : Std.ExtHashMap Nat (BitVec 8) 471 tags : Unit 472 cycleCount : Nat 473 sailOutput : Array String</code></pre> regs</code> (line 468) models the register file with Std.ExtDHashMap Register RegisterType</code> — a hash map where the keys are of type Register</code> and the value type of the register depends on the key. That is, if the key is k : Register</code>, the corresponding value has type RegisterType k</code>. This is what makes it a dependent hash map rather than an ordinary one, and also why the state is declared with parameters RegisterType</code> and ChoiceSource</code>. Register</code> is an inductive with ~180 variants — one for every named register in the RISC-V spec: 1526inductive Register : Type where 1527 | hart_state 1528 | satp 1529 | PC 1530 | nextPC 1531 | x1 | x2 | x3 | ... | x31 -- general-purpose registers 1532 -- ... CSRs, vector registers, debug state, ~180 variants total ...</code></pre> RegisterType</code> is the exact function3</a> that tells the hash map what the type of the value is for each key: 1708abbrev RegisterType : Register → Type 1709 | .hart_state => HartState 1710 | .mhpmcounter => (Vector (BitVec 64) 32) 1711 | .tlb => (Vector (Option TLB_Entry) (2 ^ 6)) 1712 | .PC => (BitVec 64) 1713 | .x1 => (BitVec 64) -- all x1–x31 map to BitVec 64 1714 | .x2 => (BitVec 64) 1715 -- ...</code></pre> So regs[.PC]</code> has type RegisterType .PC = BitVec 64</code>, while regs[.tlb]</code> has type RegisterType .tlb = Vector (Option TLB_Entry) (2 ^ 6)</code>. Each register gets exactly the type it needs. The general-purpose registers x1-x31</code> are of type BitVec 64</code>. The mem</code> field models byte-addressable memory as a hash map from Nat</code> addresses to BitVec 8</code> bytes. The second parameter c</code> has type ChoiceSource</code>, a structure that provides a way to pick default values for primitive types. 291structure ChoiceSource where 292 (α : Type) 293 (nextState : Primitive → α → α) 294 (choose : ∀ p : Primitive, α → p.reflect)</code></pre> To define SailState</code>, we use trivialChoiceSource</code>, which is defined as: 296def trivialChoiceSource : ChoiceSource where 297 α := Unit 298 nextState _ _ := () 299 choose p _ := 300 match p with 301 | .bool => false 302 | .bit => 0 303 | .int => 0 304 | .nat => 0 305 | .string => "" 306 | .fin _ => 0 307 | .bitvector _ => 0</code></pre> More simply, this says that all default values are the expected ones. Next, we describe how one steps the CPU or performs a state transition. The Sail Monad#</a> </h2> Step transitions are modeled using Lean’s built-in error-state monad (EStateM ε σ α</code>), with the error</a> and state</a> types. Under the hood EStateM ε σ α</code> is just a function σ → Result ε σ α</code> that takes a state and returns either .ok v newState</code> or .error e newState</code>, where v : α</code> and e : ε</code>. See the official EStateM</code> documentation</a> for further details. The Sail library defines a generic version called PreSailM</code>, leaving the register types, choice source, and user-exception type as parameters: 479abbrev PreSailM (RegisterType : Register → Type) (c : ChoiceSource) (ue : Type) := 480 EStateM (Error ue) (SequentialState RegisterType c)</code></pre> SailM</code> is just PreSailM</code> instantiated with the user-exception type ue</code> as exception</code> (so the error type ε</code> becomes Error exception</code>) and the state σ</code> as SailState</code> defined above. 1928abbrev SailM := PreSailM RegisterType trivialChoiceSource exception</code></pre> Notice that SailM</code> fixes the error type ε</code> and state type σ</code>, but says nothing about the result type α</code>. That is deliberate: EStateM ε σ α</code> takes three type arguments, and here we have only supplied the first two. SailM</code> is therefore a function Type → Type</code>. The remaining α</code> is filled in at each use site, giving a different “step computation that yields an α</code>”: SailM ExecutionResult -- a full instruction step, yielding its execution result SailM (BitVec 64) -- a step that reads a register, yielding a 64-bit word SailM Unit -- a step run only for its effect on state</code></pre> So SailM</code> is the “RISC-V step computation” constructor, and SailM α</code> is “a step computation that produces an α</code>”. This is the same currying you already use when you write List</code> (a Type → Type</code>) and only later List Nat</code>. Errors#</a> </h3> These variants model all the ways the execution part of the fetch-decode-execute cycle can go wrong. Error</code> is from the Sail library: 351inductive Error (ue : Type) where 352 | Exit 353 | Unreachable 354 | OutOfMemoryRange (n : Nat) 355 | Assertion (s : String) 356 | User (e : ue)</code></pre> The User</code> constructor wraps a user-exception type ue</code>, which is instantiated with exception</code> from the RISC-V model: 87inductive exception where 88 | Error_not_implemented (_ : String) 89 | Error_internal_error (_ : String) 90 | Error_reserved_behavior (_ : String)</code></pre>Executing Instructions#</a> </h2> With SailM</code> defined above, to execute instructions we must provide two things: The type for $\alpha$. For RISC-V instructions, $\alpha$ will invariably be ExecutionResult</code>. This is the final output after execution.</li> Once $\alpha$ is defined, a full description of the state transition.</li> </ol> Execution Results: The Return Type After Execution#</a> </h3> 1464inductive ExecutionResult where 1465 | Retire_Success (_ : Unit) 1466 | ExecuteAs (_ : instruction) 1467 | Enter_Wait (_ : WaitReason) 1468 | Illegal_Instruction (_ : Unit) 1469 | Virtual_Instruction (_ : Unit) 1470 | Trap (_ : (Privilege × ctl_result × xlenbits)) 1471 | Memory_Exception (_ : (virtaddr × ExceptionType)) 1472 | Ext_CSR_Check_Failure (_ : Unit) 1473 | Ext_ControlAddr_Check_Failure (_ : ext_control_addr_error) 1474 | Ext_DataAddr_Check_Failure (_ : ext_data_addr_error) 1475 | Ext_XRET_Priv_Failure (_ : Unit)</code></pre> In the happy path, instructions return RETIRE_SUCCESS</code> (which is Retire_Success ()</code>). To make this idea more concrete, we look at the actual execution of a native RISC-V instruction, ADDIW</code>. The opcode signature is ADDIW rd, rs1, imm</code>. In pseudocode, it computes: # ADDIW rd, rs1, imm (RV64I) tmp = rs1 + sext(imm) # 64-bit wrapping add of the sign-extended 12-bit imm rd = sext( tmp[31:0] ) # keep the low 32 bits, sign-extend back to 64</code></pre> That is, the add is done in 64 bits but only the low 32 bits are kept and then sign-extended back to 64. Below is the trusted Sail implementation of the pseudocode above. 71658def execute_ADDIW (imm : (BitVec 12)) (rs1 : regidx) (rd : regidx) : SailM ExecutionResult := do 71659 let result ← do (pure ((← (rX_bits rs1)) + (sign_extend (m := 64) imm))) -- m1 71660 (wX_bits rd (sign_extend (m := 64) (Sail.BitVec.extractLsb result 31 0))) -- m2 71661 (pure RETIRE_SUCCESS) -- m3</code></pre> Next we try and parse the above code. It might look simple, but under the hood a lot is going, and understanding it is key for understanding our proof tactics later on. Remark</div> We will not always discuss do notation in such detail, but we choose to do so here because all CPU implementations are written in do notation. Thus, it’s important to get used to mentally translating do notation into function composition. </aside> Function Signature#</a> </h4> The function signature says the inputs are a 12-bit immediate value imm</code> and general-purpose source and destination registers rs1</code> and rd</code>, which are of type4</a> regidx</code>. 31inductive regidx where 32 | Regidx (_ : (BitVec (if ( false : Bool) then 4 else 5)))</code></pre> To parse the body, we need a little do notation</a>. Lean is a functional language, but CPU execution is inherently stateful, so do</code> notation lets us write imperative-looking code that the Lean elaborator desugars back into ordinary functional code. The mental model is that each line of the block is a SailM α</code> computation — and recall these are just functions: feed one the current state and it either returns .ok</code> with a new value and state, or .error</code> with an error value and state. If a line errors, the computation short-circuits and the whole block returns that error; on success, the returned value is passed along to the next line. Applying this to the whole body, the three do</code> lines desugar into one nested >>=</code> chain: Parsing The Body#</a> </h4> We rewrite the outer do</code> block as do result ← m1 m2 m3</code></pre> Here m1</code>, m2</code>, and m3</code> are the monadic expressions marked in the code above. m1 := do (pure ((← (rX_bits rs1)) + (sign_extend (m := 64) imm))) m2 := wX_bits rd (sign_extend (m := 64) (Sail.BitVec.extractLsb result 31 0)) m3 := pure RETIRE_SUCCESS</code></pre> Following the guide on how to desugar do notation</a>, the first desugaring step gives: m1 >>= (fun result => do m2 m3 )</code></pre> A reminder that, a function m : Type → Type</code> can be used as a monad only when Lean has a Monad m</code> instance5</a> for it, which provides pure</code> and bind</code>. The notation a >>= f</code> is notation for bind a f</code>, where a : m α</code> and f : α → m β</code>. For EStateM</code>, read bind</code> as: run a</code>; if it succeeds, pass its returned value to f</code> to produce the next monadic computation. The next desugaring step is as follows: m1 >>= (fun result => m2 >>= (fun _ => do m3 ) )</code></pre> The next step is: m1 >>= (fun result => m2 >>= (fun _ => m3 ) )</code></pre> We expand only m2</code> and m3</code> first. As m1</code> is itself a do</code> block, we do expand that next individually, and then give you the combined version. m1 >>= (fun result => -- m2 expanded (wX_bits rd (sign_extend (m := 64) (Sail.BitVec.extractLsb result 31 0))) >>= (fun _ => -- m3 expanded pure RETIRE_SUCCESS ) )</code></pre> Now parsing m1</code> do (pure ((← (rX_bits rs1)) + (sign_extend (m := 64) imm)))</code></pre> as m1</code> is a single statement it desugars to (pure ((← (rX_bits rs1)) + (sign_extend (m := 64) imm)))</code></pre> The next desugaring step hoists the nested ←</code> out of the argument to pure</code>: (rX_bits rs1) >>= (fun rs1_value => pure (rs1_value + sign_extend (m := 64) imm) )</code></pre> Putting the desugared m1</code> back into the outer chain gives: ((rX_bits rs1) >>= (fun x => pure (x + sign_extend (m := 64) imm) )) >>= (fun result => (wX_bits rd (sign_extend (m := 64) (Sail.BitVec.extractLsb result 31 0))) >>= (fun _ => pure RETIRE_SUCCESS ) )</code></pre> rX_bits</code> is a monadic computation: given the current state, it returns a 64-bit value (the contents of register rs1</code>)^{6</a> and threads the state unchanged. So the output is really SailM (BitVec 64)</code>. </li>} sign_extend</code> just sign-extends the immediate value and returns a 64-bit value. </li> The next line, wX_bits ...</code>, runs only if the first line succeeds all the way through. It is itself another bind: if we successfully write the sign-extended low 32 bits of result</code> (that is, sext(result[31:0])</code>) into the rd</code> key of the register hash map, and that write succeeds </li> the final pure RETIRE_SUCCESS</code> returns RETIRE_SUCCESS</code> without changing the state further. </li> </ol> Thus, wX_bits ...</code> is the only monadic computation that changes state. We refer the reader to the Read and Write Chain</a> appendix for the full code blocks. Jolt CPU#</a> </h2> The Jolt CPU as modeled in Rust is shown below. Most fields have an equivalent copy in the Sail state, so the Jolt state can and should be built on top of SailState</code> with some extra fields. For the purposes of proving expansion equivalence, this is enough7</a>. What we really need to model is the virtual registers and the virtual register allocation. Jolt adds virtual registers and extra instructions. 203 #[derive(Clone, Debug)] 204 pub struct Cpu { 205 clock: u64, 206 207 pub(crate) privilege_mode: PrivilegeMode, 208 wfi: bool, 209 pub x: [i64; REGISTER_COUNT as usize], // Missing in Sail 210 #[allow(dead_code)] 211 f: [f64; 32], 212 pub(crate) pc: u64, 213 csr: [u64; CSR_CAPACITY], 214 pub mmu: Mmu, 215 reservation: u64, 216 is_reservation_set: bool, 217 reservation_width: ReservationWidth, 218 _dump_flag: bool, 219 unsigned_data_mask: u64, 220 // pub trace: Vec<Cycle>, 221 pub trace_len: usize, // Missing in Sail 222 executed_instrs: u64, // "real" RV64IMAC cycles 223 active_markers: FnvHashMap<u32, ActiveMarker>, 224 pub vr_allocator: VirtualRegisterAllocator, // Missing in Sail 225 /// Call stack tracking (circular buffer) 226 call_stack: VecDeque<CallFrame>, 227 /// Advice tape for runtime advice system 228 pub advice_tape: AdviceTape, // Not modeled in Lean 229 #[cfg(feature = "field-inline")] 230 pub field_registers: FieldRegisterFile, 231 }</code></pre> This gives us the following definition of Jolt state in Lean. We do not model the virtual registers as a hash map; instead, we model them as a function from BitVec 7 -> BitVec 64</code>. 27structure SailJoltState where 28 sail : SailState 29 vregs : BitVec 7 → BitVec 64 := fun _ => 0</code></pre> Note that we have duplication here. The sail</code> field already has the regidx</code> for the general-purpose registers, and the first 32 slots of vregs</code> are also the same. To make proofs easier to manage, we directly use the Sail registers when writing to general-purpose registers, and block off writing to the first 32 registers. 31-- The general-purpose registers are in the Sail hash map already, 32-- so we should never write to vr 0-31. 33def WritableVReg (vr : BitVec 7) : Prop := 34 ¬ vr.toNat < 32 35 36-- We cannot write to the first 32 registers, as we use xreg for them. 37def writeVReg (vr : BitVec 7) (val : BitVec 64) : JoltMonad Unit := 38 if vr.toNat < 32 then 39 throw (Error.Assertion "writeVReg: architectural xreg address") 40 else 41 modify fun js => { js with vregs := fun r => if r = vr then val else js.vregs r }</code></pre>Virtual Registers#</a> </h3> Not all virtual registers are the same. The figure below shows the classification of the different registers. Virtual register allocation is modeled directly in the expansion. The logic used in Jolt is as follows: Before an instruction executes, all registers from 40 to 47 are marked free.</li> When Jolt asks for a scratch virtual register, we return the lowest-indexed register marked free. For example, at the start, with all scratch registers marked free, the first free register is 40. Once this is returned, 40 is marked used until it is explicitly marked free again. The next free register is then 41, and so on.</li> </ul> We explicitly model this in JoltBytecode/JoltISA/VirtualRegisters.lean</code>, with proof-side facts in JoltBytecode/InstructionEquivalence/ProofSupport/VirtualRegisters.lean</code>, so that expansion proofs can check that the allocator neither runs out of scratch virtual registers nor reuses one that is still live. Two sets of control/status registers</div> It might seem confusing that some virtual registers represent control/status registers, while there is also a separate field for CSRs. This is because the Jolt CPU emulator is a fork of a RISC-V emulator. This means that the emulator is able to emulate non-expanded vanilla RISC-V programs. However, when reading a Jolt CPU program, control/status register reads and writes are done via the virtual register file. ECALL</code>, EBREAK</code>, MRET</code>, CSRRW</code>, CSRRS</code>, and CSRRC</code> are all expanded (as we show later). </aside> Jolt Monad (Stepping the CPU)#</a> </h2> We step the Jolt CPU using the same EStateM</code> infrastructure. The only difference between this and the RISC-V CPU is that we use SailJoltState</code> instead of SailState</code>. abbrev JoltMonad (α : Type) := EStateM (Error exception) SailJoltState α</code></pre> Next, we define the instructions natively supported by the Jolt CPU: a subset of RISC-V instructions, plus a few new virtual instructions. The source of truth is the Rust instruction definition in tracer/src/instruction/mod.rs</a>. These are modeled in Lean as the inductive type JoltISA.Instr</code>. 30inductive Instr where 31 | NoOp 32 | ADDI (dst : Dst) (src : Src) (imm : BitVec 12) 33 | ANDI (dst : Dst) (src : Src) (imm : BitVec 12) 34 | ORI (dst : Dst) (src : Src) (imm : BitVec 12) 35 | XORI (dst : Dst) (src : Src) (imm : BitVec 12) 36 | LUI (dst : Dst) (imm : BitVec 64) 37 | JAL (dst : Dst) (imm : BitVec 21) 38 | BEQ (lhs rhs : Src) (imm : BitVec 13) 39 | ADD (dst : Dst) (lhs rhs : Src) 40 | SUB (dst : Dst) (lhs rhs : Src) 41 | MUL (dst : Dst) (lhs rhs : Src) 42 | VirtualMULI (dst : Dst) (src : Src) (imm : BitVec 64) 43 -- ... ~55 more opcodes, including the Virtual* family ... 44 | VirtualAssertMulUNoOverflow (lhs rhs : Src) 45 | VirtualAssertLTE (lhs rhs : Src) 46 deriving Repr</code></pre> Note that unlike the RISC-V Cpu, these instructions can read/write to both risc-v registers and virtual registers. /-- An instruction source operand: either a virtual register or an architectural Sail register. -/ inductive Src where | vreg : VReg → Src | xreg : regidx → Src deriving Repr /-- An instruction destination operand: either a virtual register or an architectural Sail register. -/ inductive Dst where | vreg : VReg → Dst | xreg : regidx → Dst deriving Repr</code></pre> The inductive type above only lists the different instructions supported by the Jolt ISA. It does not describe how the Jolt state changes when these instructions are executed. We do that next. Executing Jolt Instructions#</a> </h3> In JoltBytecode/JoltISA/Semantics.lean</code> we define execInstr</code>, a function that maps a JoltISA.Instr</code> to a JoltMonad ExecutionResult</code>. That is, for each native or virtual Jolt instruction, it defines the state update function. Remember, JoltMonad</code> is just a function. To execute the instruction, we have to “run” the function with a current state. 30def execInstr : Instr → JoltMonad ExecutionResult 31 | .NoOp => 32 pure RETIRE_SUCCESS 33 | .ADDI dst src imm => do 34 let x ← readSrc src 35 writeDst dst (x + sign_extend (m := 64) imm) 36 pure RETIRE_SUCCESS 37 | .ANDI dst src imm => do 38 let x ← readSrc src 39 writeDst dst (x &&& sign_extend (m := 64) imm) 40 pure RETIRE_SUCCESS 41 | .ORI dst src imm => do 42 let x ← readSrc src 43 writeDst dst (x ||| sign_extend (m := 64) imm) 44 pure RETIRE_SUCCESS 45 -- ... remaining native and virtual instruction cases ... 46 | .VirtualAssertLTE lhs rhs => do 47 let x ← readSrc lhs 48 let y ← readSrc rhs 49 if x.toNat ≤ y.toNat then 50 pure RETIRE_SUCCESS 51 else 52 throw (Error.Assertion "VirtualAssertLTE")</code></pre> You might ask: where did this execution logic come from? For now, it is hand-translated from the Rust source code. For each instruction, the process is as follows: Find the corresponding exec</code> block and model the Rust code in Lean. For example, here are the Lean semantics and Rust semantics side by side for ADDI</code>. | .ADDI dst src imm => do let x ← readSrc src writeDst dst (x + sign_extend (m := 64) imm) pure RETIRE_SUCCESS</code></pre> This eyeballing of Rust and Lean code is prone to bugs. As a temporary solution, we always have an AI agent double-check the two code blocks. In the coming weeks, we will have an auto-translator from Rust to Lean for instruction execution semantics. </aside> 19 fn exec(&self, cpu: &mut Cpu, _: &mut <ADDI as RISCVInstruction>::RAMAccess) { 20 cpu.write_register( 21 self.operands.rd as usize, 22 cpu.sign_extend( 23 cpu.x[self.operands.rs1 as usize].wrapping_add(normalize_imm(self.operands.imm)), 24 ), 25 ); 26 }</code></pre> As a result of the translation above, some natively supported instructions, such as ADDI</code>, have both a Jolt execution and a trusted Sail execution. We want them to agree on how they change Sail state. This gives us an equivalence theorem for every Jolt instruction that is natively supported on a RISC-V CPU. Continuing with the ADDI</code> example, it looks like the following: 69/-- Main native `ADDI` equivalence statement. -/ 70def addiInstrEqSailStatement 71 (imm : BitVec 12) 72 (rs1 rd : regidx) 73 (js : SailJoltState) 74 (_h : UnarySourceReadWithLinkedCSRs rs1 js) : Prop := 75 System.systemProjectResult 76 ((JoltISA.execInstr (.ADDI (.xreg rd) (.xreg rs1) imm)).run js) = 77 ((execute_ITYPE imm rs1 rd iop.ADDI).run js.sail)</code></pre> The statement above translates to the following mathematical statement. — ADDI Equivalence Statement</div> Given a 12-bit immediate value imm</code>, a readable source register rs1</code>, a writable destination register rd</code>, assumptions h</code>, and an initial Jolt state js</code>, running Jolt’s ADDI</code> and projecting down to the Sail state gives the same state as running the trusted Sail ADDI</code> on the input state js.sail</code>. </aside> The exact assumption bundle used for ADDI</code> is UnarySourceReadWithLinkedCSRs rs1 js</code>, which bundles two sets of assumptions together. The structure UnarySourceReadAssumptions</code> just says we can read rs1</code>. As the register file is a hash map, this is a Lean implementation detail: we have to say that the key exists in the hash map. The other structure is LinkedCSRRegisterAssumptions</code>. 29/-- Assumptions for an instruction that reads one architectural source register. -/ 30structure UnarySourceReadAssumptions (rs1 : regidx) (js : SailJoltState) where 31 rs1_val : BitVec 64 32 rs1_read : rX_bits rs1 js.sail = .ok rs1_val js.sail 33 34/-- Persistent CSR virtual registers agree with Sail's architectural CSR state. -/ 35private structure LinkedCSRRegisterAssumptions (js : SailJoltState) where 36 mstatus_matches : Assumptions.MstatusVRegMatchesSail js 37 mtvec_matches : Assumptions.MtvecVRegMatchesSail js 38 mscratch_matches : Assumptions.MscratchVRegMatchesSail js 39 mepc_matches : Assumptions.MepcVRegMatchesSail js 40 mcause_matches : Assumptions.McauseVRegMatchesSail js 41 mtval_matches : Assumptions.MtvalVRegMatchesSail js 42 43/-- One source-register read plus persistent CSR virtual-register agreement. -/ 44structure UnarySourceReadWithLinkedCSRs 45 (rs1 : regidx) (js : SailJoltState) 46 extends UnarySourceReadAssumptions rs1 js, 47 LinkedCSRRegisterAssumptions js</code></pre> It simply says that the virtual registers are equal to the Sail registers for the corresponding control/status registers. The only thing left to explain is systemProjectResult</code>. systemProjectResult</code> removes the Jolt-specific state and keeps only the sail</code> state, which can be compared with the RISC-V CPU. Before we do that, we must map the virtual registers that represent control/status registers in Jolt to the Sail control/status registers. Without this step, a program could arbitrarily write to these registers, and dropping vregs</code> would make the Sail states appear to agree. We need to tell Lean that those virtual registers represent the same values as the Sail registers. 65/-- Overlay Jolt's persistent virtual CSR registers onto the generated Sail CSR 66register keys. 67 68This is only a proof projection: the Rust-faithful Jolt programs still write 69Jolt virtual registers, and the Sail specification still reads/writes generated 70Sail registers. -/ 71def systemProject (js : SailJoltState) : SailState := 72 { js.sail with 73 regs := 74 ((((((js.sail.regs 75 |>.insert Register.mtvec (js.vregs JoltISA.trapHandlerVReg)) 76 |>.insert Register.mscratch (js.vregs JoltISA.mscratchVReg)) 77 |>.insert Register.mepc (js.vregs JoltISA.mepcVReg)) 78 |>.insert Register.mcause (js.vregs JoltISA.mcauseVReg)) 79 |>.insert Register.mtval (js.vregs JoltISA.mtvalVReg)) 80 |>.insert Register.mstatus (js.vregs JoltISA.mstatusVReg)) } 81 82/-- Project a Jolt run result through `systemProject`, preserving the result 83value and error shape while materializing virtual CSRs in the Sail state. -/ 84def systemProjectResult 85 (r : EStateM.Result (Error exception) SailJoltState α) : 86 EStateM.Result (Error exception) SailState α := 87 match r with 88 | .ok a js' => .ok a (systemProject js') 89 | .error e js' => .error e (systemProject js')</code></pre> And that’s it: for every natively supported instruction, we have to prove that this statement is true. Expansions#</a> </h3> We’ve handled natively supported RISC-V instructions. What about instructions like LW</code>, where the RISC-V instruction is handled as a sequence of Jolt instructions rather than as one native execInstr</code> step? These instructions are modeled by expansion programs. An expansion program is a value of the inductive type Program</code>, made from composing Jolt instructions, as defined below. 192/-- Structured Jolt bytecode programs. 193 194`instr i next` means: execute `i`; if it retires successfully, continue with 195`next`; otherwise return the non-retire result immediately. -/ 196inductive Program where 197 | done (result : ExecutionResult) 198 | instr (instr : Instr) (next : Program) 199 deriving Repr</code></pre> So a program is either finished, with a final ExecutionResult</code>, or it is one instruction followed by the rest of the program. In plain English, a program is just the composition of instruction steps: run this instruction, then run the next instruction, and so on until the program ends. For example, a tiny program with two instructions looks like this: def tinyProgram (rd rs1 : regidx) : Program := .instr (.ADDI (.xreg rd) (.xreg rs1) 1) <| .instr (.ANDI (.xreg rd) (.xreg rd) 255) <| .done RETIRE_SUCCESS</code></pre> The <|</code> symbol is just Lean sugar that lets us write this composition without a pile of parentheses. Without <|</code>, the same program is: def tinyProgram (rd rs1 : regidx) : Program := .instr (.ADDI (.xreg rd) (.xreg rs1) 1) (.instr (.ANDI (.xreg rd) (.xreg rd) 255) (.done RETIRE_SUCCESS))</code></pre> This represents the expansion: ADDI x[rd], x[rs1], 1 ANDI x[rd], x[rd], 255</code></pre> For LW</code>, the Lean model of the Jolt expansion lives in JoltBytecode/JoltISA/Expansions/Load.lean</code> as JoltISA.lwProgram</code>: 116/-- Rust's RV64 `LW::inline_sequence`. -/ 117def lwProgram (imm : BitVec 12) (rs1 rd : regidx) : Program := 118 let v0 := loadV0For rd 119 let v1 := loadV1For rd 120 let tmp := loadInlineTmpFor rd 121 let dst := loadDstFor rd 122 .instr (.VirtualAssertWordAlignment rs1 imm (ExceptionType.E_Load_Addr_Align ())) <| 123 .instr (.ADDI (.vreg v0) (.xreg rs1) imm) <| 124 .instr (.ANDI (.vreg v1) (.vreg v0) (-8 : BitVec 12)) <| 125 .instr (.LD .normal (.vreg v1) (.vreg v1) 0) <| 126 slliBlock (.vreg v0) (.vreg v0) (3 : BitVec 6) <| 127 srlBlock (.vreg v1) (.vreg v1) (.vreg v0) tmp <| 128 .instr (.VirtualSignExtendWord dst (.vreg v1)) <| 129 .done RETIRE_SUCCESS</code></pre> We make use of some helper functions like loadV0For</code> to model virtual register allocation. 36/-- Rust source `rd = x0` rewrite destination for side-effecting load 37expansions. -/ 38def loadDstFor (rd : regidx) : Dst := 39 sideEffectingRdZeroDst rd 40 41/-- Rust load `v0`, shifted when `rd = x0` consumes the first temporary. -/ 42def loadV0For (rd : regidx) : VReg := 43 if isX0 rd then inlineTmp1 else loadV0 44 45/-- Rust load `v1`, shifted when `rd = x0` consumes the first temporary. -/ 46def loadV1For (rd : regidx) : VReg := 47 if isX0 rd then inlineTmp2 else loadV1 48 49/-- Recursive load scratch, shifted when `rd = x0` consumes the first 50temporary. -/ 51def loadInlineTmpFor (rd : regidx) : VReg := 52 if isX0 rd then inlineTmp3 else loadInlineTmp</code></pre> The reason they look somewhat complex is that we also need to model the side effect of the case where rd=x0</code>. In that case Jolt swaps rd</code> for the first free virtual register, and this means the downstream virtual register allocation changes by an offset of 1. These helpers help represent that in a clean manner. So far, this only says how to build a program. We still need to say how to run one. What are these blocks?</div> One might notice that we said a program is built by composing instructions. However, the two lines slliBlock</code> and srlBlock</code> are not themselves instructions. This is because Jolt does not support SLLI</code> and SRL</code> natively either, so they are expanded too. 71/-- Rust `SLLI::inline_sequence`: multiply by the immediate power of two. -/ 72def slliBlock (dst : Dst) (src : Src) (shamt : BitVec 6) (tail : Program) : Program := 73 .instr (.VirtualMULI dst src (slliMultiplier shamt)) tail 74 75/-- Rust `SRL::inline_sequence`: compute the right-shift bitmask in a scratch 76virtual register, then run `VirtualSRL` with that bitmask. -/ 77def srlBlock (dst : Dst) (value shift : Src) (scratch : VReg) 78 (tail : Program) : Program := 79 .instr (.VirtualShiftRightBitmask (.vreg scratch) shift) <| 80 .instr (.VirtualSRL dst value (.vreg scratch)) tail</code></pre> With the block notation, we just write the programs cleanly. </aside> The Rust expansion is given below, and we can see that it lines up with the Lean lwProgram</code>. 7pub(in crate::expand) fn expand_lw( 8 instruction: &SourceInstructionRow, 9) -> Result<ExpandedInstructionSequence, ExpansionError> { 10 let mut asm = ExpansionBuilder::new(*instruction); 11 let v0 = asm.allocate()?; 12 let v1 = asm.allocate()?; 13 14 // RAM is accessed at doubleword granularity here. The word alignment 15 // assertion is still required by the source `LW` semantics. 16 asm.expand_address( 17 SourceInstructionKind::VirtualAssertWordAlignment, 18 reg(rs1(instruction)?), 19 instruction.operands.imm, 20 ); 21 asm.expand_i( 22 SourceInstructionKind::ADDI, 23 v0.operand(), 24 reg(rs1(instruction)?), 25 format_i_imm(instruction.operands.imm), 26 ); 27 // v1 = containing doubleword address, v0 = byte offset within it. 28 asm.expand_i( 29 SourceInstructionKind::ANDI, 30 v1.operand(), 31 v0.operand(), 32 format_i_imm(-8), 33 ); 34 asm.expand_i(SourceInstructionKind::LD, v1.operand(), v1.operand(), 0); 35 asm.expand_i(SourceInstructionKind::SLLI, v0.operand(), v0.operand(), 3); 36 asm.expand_r( 37 SourceInstructionKind::SRL, 38 v1.operand(), 39 v1.operand(), 40 v0.operand(), 41 ); 42 asm.expand_i( 43 SourceInstructionKind::VirtualSignExtendWord( 44 jolt_riscv::instructions::VirtualSignExtendWord(()), 45 ), 46 reg(rd(instruction)?), 47 v1.operand(), 48 0, 49 ); 50 asm.release(v0); 51 asm.release(v1); 52 53 asm.finalize() 54}</code></pre>Executing Expanded Programs#</a> </h2> Execution of a program is much like the execution of a single Jolt instruction. Given a program, instead of a single Jolt instruction, we return a state transition function. If the program is already complete, then execution just returns the result. Otherwise, it takes the instruction and the rest of the program, steps the current Jolt instruction, and on successful execution, executes the rest. 413def execProgram : Program → JoltMonad ExecutionResult 414 | .done result => pure result 415 | .instr instr rest => do 416 match ← execInstr instr with 417 | .Retire_Success () => execProgram rest 418 -- If any instruction does not complete successfully, 419 -- return Result.ok result s' and do not run the rest of the program. 420 | result => pure result</code></pre> If the instruction traps, errors, or otherwise returns a non-retire result, execution stops and that result is returned. We will also prove that this program leaves the Sail state exactly as it would be after running the trusted Sail LW</code>. 398def lwProgramEqSailStatement (imm : BitVec 12) 399 (rs1 rd : regidx) 400 (js : SailJoltState) 401 (_h : LoadProgramEqSailAssumptions imm rs1 js) : Prop := 402 System.systemProjectResult 403 ((JoltISA.execProgram (JoltISA.lwProgram imm rs1 rd)).run js) = 404 (execute_LOAD imm rs1 rd false 4).run js.sail</code></pre> The statement above translates to the following mathematical statement. — LW Equivalence Statement</div> Given a 12-bit immediate value imm</code>, a readable source register rs1</code>, a writable destination register rd</code>, assumptions h</code>, and an initial Jolt state js</code>, running Jolt’s expanded LW</code> program and projecting down to the Sail state gives the same state as running the trusted Sail LW</code> on the input state js.sail</code>. </aside> In upcoming posts, we will dive into the details of assumptions in theorem statements and how to go about proving these statements. Appendices#</a> </h2> Read and Write Chain#</a> </h3> 696def rX_bits (app_0 : regidx) : SailM (BitVec 64) := do 697 let .Regidx i := app_0 698 (rX (Regno (BitVec.toNatInt i))) 699 700def wX_bits (typ_0 : regidx) (data : (BitVec 64)) : SailM Unit := do 701 let .Regidx i : regidx := typ_0 702 (wX (Regno (BitVec.toNatInt i)) data)</code></pre>618def rX (app_0 : regno) : SailM (BitVec 64) := do 619 let .Regno r := app_0 620 let v ← (( do 621 match r with 622 | 0 => (pure zero_reg) 623 | 1 => readReg x1 624 | 2 => readReg x2 625 -- ... x3 through x30 ... 626 | _ => readReg x31 ) : SailM regtype ) 627 (pure (regval_from_reg v))</code></pre>656def wX (typ_0 : regno) (in_v : (BitVec 64)) : SailM Unit := do 657 let .Regno r : regno := typ_0 658 let v := (regval_into_reg in_v) 659 match r with 660 | 0 => (pure ()) 661 | 1 => writeReg x1 v 662 | 2 => writeReg x2 v 663 -- ... x3 through x30 ... 664 | _ => writeReg x31 v 665 if ((r != 0) : Bool) 666 then (xreg_write_callback (Regidx (to_bits (l := 5) r)) in_v) 667 else (pure ())</code></pre>530def writeReg (r : Register) (v : RegisterType r) : PreSailM RegisterType c ue PUnit := 531 modify fun s => { s with regs := s.regs.insert r v }</code></pre>534def readReg (r : Register) : PreSailM RegisterType c ue (RegisterType r) := do 535 let .some s := (← get).regs.get? r 536 | throw .Unreachable 537 pure s</code></pre>CSR Assumptions#</a> </h3> 107structure MstatusVRegMatchesSail (js : SailJoltState) : Prop where 108 value_eq : 109 js.sail.regs.get? Register.mstatus = 110 some (js.vregs JoltISA.mstatusVReg) 111 112structure MtvecVRegMatchesSail (js : SailJoltState) : Prop where 113 value_eq : 114 js.sail.regs.get? Register.mtvec = 115 some (js.vregs JoltISA.trapHandlerVReg) 116 117structure MscratchVRegMatchesSail (js : SailJoltState) : Prop where 118 value_eq : 119 js.sail.regs.get? Register.mscratch = 120 some (js.vregs JoltISA.mscratchVReg) 121 122structure MepcVRegMatchesSail (js : SailJoltState) : Prop where 123 value_eq : 124 js.sail.regs.get? Register.mepc = 125 some (js.vregs JoltISA.mepcVReg) 126 127structure McauseVRegMatchesSail (js : SailJoltState) : Prop where 128 value_eq : 129 js.sail.regs.get? Register.mcause = 130 some (js.vregs JoltISA.mcauseVReg) 131 132structure MtvalVRegMatchesSail (js : SailJoltState) : Prop where 133 value_eq : 134 js.sail.regs.get? Register.mtval = 135 some (js.vregs JoltISA.mtvalVReg)</code></pre> See the RISC-V ISA for a detailed description of state. ↩</a> </li> More formally, the state is defined as a dependent inductive type with one constructor. So to fully define the state, one must specify a term of the function type RegisterType</code> and a term of ChoiceSource</code>. ↩</a> </li> Or, in Lean terms, the term of type Register → Type</code>. ↩</a> </li> For our purposes, regidx</code> behaves just like a BitVec 5</code>, but is given its own name to record that this particular 5-bit vector is a general-purpose register index. Here the condition is false</code>, so the if</code> reduces through the else</code> branch to 5</code>, and regidx</code> is just Regidx (BitVec 5)</code>. This aligns with the RISC-V spec that there are $2^5 = 32$ general-purpose registers. ↩</a> </li> In simple terms, this means pure</code> and bind</code> have been implemented for m</code>. ↩</a> </li> As the register file is a hash map, Lean requires a proof that the key already exists in the hash map. Without this proof, we are unable to get the bits inside the hash map, and the computation errors as shown in the appendices. Of course, in a real physical CPU, the register file is not a hash map and we do not have to say that general-purpose register x</code> exists. So although not shown here, to prove theorems we will have a general assumption that the general-purpose registers can be read. ↩</a> </li> This state may change as we model other parts of Jolt and decide whether to include the remaining Rust fields. ↩</a> </li> </ol> </section> Sail RISC-V Into Lean 2026-03-22T00:00:00+00:00 Caution</div> 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. </aside> Tested on: macOS (Apple Silicon)</li> Intel CPU Arch Linux (TODO:)</li> </ul> Step 0: Clone Both Repos#</a> </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. git clone git@github.com:abiswas3/sail-riscv.git git clone git@github.com:abiswas3/sail.git</code></pre>parent/ ├── sail/ # Sail compiler (transpiler) -- clone from github.com/rems-project/sail └── sail-riscv/ # This repo -- RISC-V ISA model written in Sail</code></pre>Step 1: Install System Dependencies#</a> </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. </aside> macOS (Homebrew)#</a> </h3> xcode-select --install # if not already done brew install opam gmp z3 pkgconf cmake</code></pre>Arch Linux#</a> </h3> sudo pacman -S opam # OCaml package manager -- needed to fetch and install Sail's OCaml dependencies sudo pacman -S gmp # GNU Multiple Precision arithmetic library -- Sail uses it internally for big integer arithmetic sudo pacman -S z3 # SMT solver from Microsoft Research -- Sail calls Z3 during type-checking to prove # arithmetic constraints on dependent types (e.g. that bitvector widths are correct) sudo pacman -S cmake # build system generator -- sail-riscv uses CMake to orchestrate the Sail-to-Lean code generation sudo pacman -S base-devel # C compiler, make, binutils, etc. -- OCaml's runtime is written in C and some opam # packages have C bindings (e.g. GMP). Also provides C++ compiler which sail-riscv's # CMake build needs for the emulator harness, even if you only want Lean output. sudo pacman -S pkgconf # pkg-config implementation -- CMake uses it to locate system libraries like GMP</code></pre>Both Platforms: Initialize opam (one-time)#</a> </h3> Run the following code from anywhere – opam stores its state in ~/.opam/</code>. TODO: ocaml crash course opam init # follow prompts, say yes to shell setup eval $(opam env) # or restart your shell</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>). Step 2: Build and Install the Sail Compiler Locally#</a> </h2> You should be in the parent/</code> directory (the one containing both sail/</code> and sail-riscv/</code>). 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 loaded at startup. 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: 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. </aside> dune 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: cd sail</code></pre>2a. Install OCaml dependencies#</a> </h3> opam install . --deps-only</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. 2b. Build the compiler and plugins#</a> </h3> dune build --release</code></pre> Compiles everything in the sail repo. Produces build artifacts under _build/</code>, including: _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. 2c. Install into a local prefix#</a> </h3> dune install --prefix _local_install</code></pre> Copies the binary, plugins, and standard library files into a structured directory: _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. cd ..</code></pre>Verify the Lean backend is loaded#</a> </h3> SAIL_DIR=sail/_local_install/share/sail sail/_local_install/bin/sail --help | grep lean</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>. Step 3: Configure the sail-riscv Build#</a> </h2> From the parent directory (or from sail-riscv/</code>): cd sail-riscv SAIL_DIR=$(realpath ../sail/_local_install/share/sail) \ cmake -S . -B build \ -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DSAIL_BIN=$(realpath ../sail/_local_install/bin/sail)</code></pre> Key variables: 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: Both paths must be absolute. 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. Step 4: Generate Lean Code#</a> </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). Warning</div> I also do not understand any of the Z3 stuff right now. </aside> Noncomputable (for theorem proving)#</a> </h3> SAIL_DIR=$(realpath ../sail/_local_install/share/sail) \ cmake --build build --target generated_lean_rv64d</code></pre> Output: build/model/Lean_RV64D/</code> (~155 .lean</code> files) This version uses noncomputable</code> sections, suitable for interactive proof in Lean. Executable (for running + theorem provin + theorem provingg)#</a> </h3> SAIL_DIR=$(realpath ../sail/_local_install/share/sail) \ cmake --build build --target generated_lean_executable_rv64d</code></pre> Output: build/model/Lean_RV64D_executable/</code> (~155 .lean</code> files) This version generates computable code that can be built and executed with lake build</code>. RV32 Variants#</a> </h3> Replace rv64d</code> with rv32d</code> in the target names for 32-bit: generated_lean_rv32d</code></li> generated_lean_executable_rv32d</code></li> </ul> Step 5: Build the Generated Lean Code (Optional)#</a> </h2> Each output directory contains a lakefile.toml</code> and lean-toolchain</code>. To compile: cd build/model/Lean_RV64D/ # or Lean_RV64D_executable/ lake update lake build</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>). Rebuilding After Sail Compiler Changes#</a> </h2> Since you’re running from source, after modifying the Sail compiler: # 1. Rebuild and reinstall the compiler cd ../sail dune build --release dune install --prefix _local_install # 2. Clean stale outputs and re-generate Lean (from sail-riscv) cd ../sail-riscv rm -rf build/model/Lean_RV64D build/model/Lean_RV64D_executable SAIL_DIR=$(realpath ../sail/_local_install/share/sail) \ cmake --build build --target generated_lean_rv64d SAIL_DIR=$(realpath ../sail/_local_install/share/sail) \ cmake --build build --target generated_lean_executable_rv64d</code></pre>Troubleshooting#</a> </h2> Cannot find source file: ../sail/_local_install/share/sail/lib/elf.c</code>: 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. </li> --lean</code> flag not found: 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>). </li> sail: command not found</code> during cmake: You need to pass -DSAIL_BIN=</code> pointing to your local install, and set SAIL_DIR</code> as an environment variable. </li> Plugin load error (symbol not found</code>): 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. </li> CMake cache error about mismatched source directory: Delete build/</code> and reconfigure: rm -rf build && cmake -S . -B build ...</code> </li> </ul> What Gets Generated#</a> </h2> The Sail compiler translates the entire RISC-V ISA model into Lean definitions: 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. Anatomy Of A Jolt Sumcheck 2025-12-01T00:00:00+00:00 (Update) 2026-08-14</div> Jolt has changed so much since writing this post was written, the code is no longer in main. Still the post remains valid if one were to understand how to implement streaming sum-checks. </aside> This write-up talks about this PR</a> which introduces a generalised sum-check API, adapted to accommodate an implementation of Jolt that uses $O(1)$ memory1</a>. The Trace#</a> </h2> Before we describe the API, it will be useful to briefly re-cap how Jolt works. At the heart of the Jolt prover is the sumcheck algorithm. Given some polynomial $g$ and a set $S$ with sufficient structure2</a>, the sum-check algorithm enables a prover to convince a verifier that it computed $\sum_{x \in S} g(x)$ honestly. The end goal of the Jolt prover is to convince an honest verifier that it ran some guest program3</a> correctly. It does so via many sum-check algorithms. Therefore for the whole setup to work, the polynomials involved in these sumchecks must be in some way related to the execution of said program. As such honest proving begins with emulation of the given RISC-V program – which we refer to as the trace. This is a fancy way of saying that the prover runs the program, and stores succinctly as a list the machine state before and after each instruction. This list is what we refer to as the trace. And it is this trace from which we will construct the sum-check polynomials in Jolt. See the emulation post for a fully worked out description of the emulation from an actual albeit useless program written in Rust. For example, consider the following program with just two instructions. 00001117 auipc sp,0x1 # sp = PC + (0x1 << 12) = 0x80000000 + 0x1000 = 0x80001000 12010113 addi sp,sp,288 # sp = 0x80001000 + 288 = 0x80001120</code></pre> After doing some initial setup of all the values of registers and memory, the emulation looks like the following: Cycle 0: AUIPC( address: 2147483648, // = 0x80000000 operands: FormatU { rd: 2, // x2 = sp (stack pointer) imm: 4096, // = 0x1000 }, register_state: { rd: (0, 2147487744) // sp: 0 → 0x80001000 } ) Cycle 1: ADDI( RISCVCycle { instruction: ADDI { address: 2147483652, // = 0x80000004 (Program counter) operands: FormatI { rd: 2, // sp (based on mapping above) rs1: 2, // sp imm: 288, // = 0x120 }, virtual_sequence_remaining: None, is_first_in_sequence: false, is_compressed: false, }, register_state: RegisterStateFormatI { rd: ( 2147487744, // new value in rd 2147488032, // old value in rd ), rs1: 2147487744, // value in rs1 }, ram_access: (), // no ram access }, ) </code></pre> For the purposes of this post, this is the mental model we will have when referring to the trace. It is a giant vector of length $T$, and location $t \in [T]$ stores the machine state before and after the $t$’th instruction. A Lie In Service Of The Truth</div> Throughout this post we will assume that we can store the entire trace in memory, and iterating through the trace is free. This is clearly not true, and we will fix this at a later date. But for the purposes of this post, this assumption allows us to abstract away important implementation details that currently remain unimplemented, and prove that we can indeed implement any Jolt sumcheck with $O(1)$ memory. </aside> Correctness As Constraint Satisfaction#</a> </h2> Now with the trace/emulation in hand, we ask - what does it mean for a program to be executed correctly? One way to define correctness would be to say at every cycle, the machine state is consistent with the program specification. As a concrete example, consider loading and storing to memory. In RISC-V assembly loads/store instructions look like the following: lb rd, offset(rs1) # Load byte (sign-extended) lh rd, offset(rs1) # Load halfword (sign-extended) lw rd, offset(rs1) # Load word (sign-extended) ld rd, offset(rs1) # Load doubleword (RV64) lbu rd, offset(rs1) # Load byte unsigned lhu rd, offset(rs1) # Load halfword unsigned lwu rd, offset(rs1) # Load word unsigned (RV64) sb rs2, offset(rs1) # Store byte sh rs2, offset(rs1) # Store halfword sw rs2, offset(rs1) # Store word sd rs2, offset(rs1) # Store doubleword (RV64)</code></pre> So if the instruction has the Load</code> flag set to 1 or Store</code> flag set to 1, then the address from which we read/write must be equal to value in rs1 + offset</code>. Using propositional logic we write: if { Instruct has Load OR Store } then ( RamAddress ) == ( Rs1Value + Imm )</code></pre> The same thing expressed as algebraic constraints: (Load + Store) * (RamAddress - (Rs1Value + Imm)) = 0</code></pre> For a program to be correctly executed, for every time step $t \in \lbrace 0,1 \rbrace^{\log T}$, the above constraint must be satisfied. Of course for a program to be correct, it is not sufficient to just satisfy the above constraint. There are many more constraints. In the OuterSpartan</code> sumcheck we write down 20 such constraints, express these constraints as the evaluations of two polynomials $\widetilde{A}$ and $\widetilde{B}$, and represent constraint satisfaction as a sumcheck. More details follow. The Outer Spartan Polynomials#</a> </h2> There are 20 constraints for each time step $t \in \lbrace 0,1\rbrace^{\log T}$. Each constraint will be of form Term 1 * Term 2 = 0</code>. Here Term 1</code> will be represented by $A$ and Term 2</code> will be represented by $B$. Indexing: We divide the 20 constraints into 2 groups. We refer to each constraint using two digits4</a> $(b,y)$ where $b \in \lbrace 0,1\rbrace$ is the selector index, and $y\in \lbrace -4, \ldots, 5\rbrace$ refers to one of the 10 constraints in group $b$. For example, $(0,-4)$ refers to constraint 1, </li> $(0, -3)$ refers to constraint 2, </li> … </li> $(1, 5)$ refers to the 20th constraint and so on. </li> </ul> Example : Constraint 1#</a> </h3> Let $z_t[\text{LOAD}], z_t[\text{STORE}] \in \lbrace 0,1\rbrace$ denote boolean flags that denote whether the $t$’th instruction contains a LOAD or a STORE instruction. For a given time step $t \in \lbrace 0,1\rbrace^{\log T}$, using information from the trace, we write a table of evaluations with the following indexing logic: $A(t, 0 , -4) = z_t[\text{LOAD}] + z_t[\text{STORE}]$ </li> $B(t, 0, -4) = (\text{RamAddress} - (\text{Rs1Value} + \text{Imm}))$ </li> </ul> That is satisfying constraint 1 for time step $t$ is equivalent to checking if $A(t, 0, -4) \times B(t, 0, -4) = 0$. The remaining 19 constraints give us evaluations $A(X_t, X_b, Y)$ and $B(X_t, X_b, Y)$ for $Y \in \lbrace -4, \ldots, 5\rbrace, X_b \in \lbrace 0,1\rbrace, X_t \in \lbrace 0,1\rbrace^{\log T}$. The picture you have in mind is the following Satisfying all constraints is just saying the following:

Random Walks

Jolt System Mismatch

Equivalence Statements And Assumptions

Jolt: Introduction

How to Model a CPU in Lean

Sail RISC-V Into Lean

Step 4: Generate Lean Code#</a> </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> Warning</div> I also do not understand any of the Z3 stuff right now.</p> </aside>

Anatomy Of A Jolt Sumcheck