feat(jolt-trace): add jolt-trace crate by markosg04 · Pull Request #1369 · a16z/jolt

markosg04 · 2026-03-25T19:05:39Z

Summary

Changes

Testing

Ran tests for modified crates
cargo clippy and cargo fmt pass

Security Considerations

Breaking Changes

None

markosg04 · 2026-03-25T19:06:11Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

feat(jolt-trace): add jolt-trace crate #1369 👈 (View in Graphite)
feat: add jolt-crypto crate #1368
feat: add jolt-poly crate #1367
feat: add jolt-instructions crate #1366
feat: add jolt-transcript crate #1365
feat: add jolt-profiling crate #1364
feat: add jolt-field crate #1363
chore: workspace scaffolding for modular crates #1362
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

markosg04 · 2026-03-25T19:09:00Z

this crate might need a better name, but it is the standard interface between tracing and provers. We might want to generalize this to support recursion "tracing" too

github-actions · 2026-04-15T17:17:20Z

Warning

This PR has more than 500 changed lines and does not include a spec.

Large features and architectural changes benefit from a spec-driven workflow.
See CONTRIBUTING.md for details on how to create a spec.

If this PR is a bug fix, refactor, or doesn't warrant a spec, feel free to ignore this message.

github-actions · 2026-04-15T17:25:46Z

Benchmark comparison (crates)

group                           main_run                               pr_run
-----                           --------                               ------
EqPolynomial::evaluations/14    1.50   756.6±11.91µs        ? ?/sec    1.00    504.0±9.17µs        ? ?/sec

graphite-app · 2026-04-15T17:50:03Z

+    pub fn build_with_features(&mut self, target_dir: &str, extra_features: &[&str]) {
+        if self.elf.is_some() {
+            return;
+        }


The early return logic is incorrect and prevents building the compute_advice variant after building the regular variant. The code only checks self.elf.is_some() but doesn't account for which variant is being built.

What breaks: If a user first calls build() (which sets self.elf), then later calls build_with_features(target_dir, &["compute_advice"]), the method returns early without building the compute_advice variant, even though self.elf_compute_advice is still None.

Fix:

let is_compute_advice = extra_features.contains(&"compute_advice"); if is_compute_advice { if self.elf_compute_advice.is_some() { return; } } else { if self.elf.is_some() { return; } }

Move the is_compute_advice determination before the early return check, and check the appropriate field based on which variant is being built.

Suggested change

pub fn build_with_features(&mut self, target_dir: &str, extra_features: &[&str]) {

if self.elf.is_some() {

return;

}

pub fn build_with_features(&mut self, target_dir: &str, extra_features: &[&str]) {

let is_compute_advice = extra_features.contains(&"compute_advice");

if is_compute_advice {

if self.elf_compute_advice.is_some() {

return;

}

} else {

if self.elf.is_some() {

return;

}

}

Spotted by Graphite

Is this helpful? React 👍 or 👎 to let us know.

0xAndoroid · 2026-04-15T18:02:43Z

🔍 Starting automated code review process. I'll analyze the changes for semantic consistency, bugs, tech debt, and security concerns. Results will be posted shortly.

Generated by Claude Code

0xAndoroid

Code Review: `jolt-trace` crate extraction

Good architectural direction — extracting the host-side tracing into a standalone crate with the CycleRow trait abstraction cleanly decouples the tracer from the proving system. The Program builder, flag dispatch tables, and test coverage are solid.

Issues found

Bugs (2):

lookup_output() returns incorrect values for branch instructions (cycle_row_impl.rs:145-155). The doc comment promises comparison results (0 or 1) for branches, but the implementation returns 0. In jolt-core, branches like BEQ/BGE compute actual comparisons via LookupQuery::to_lookup_output(). This will produce incorrect witnesses when CycleRow replaces the existing path.
build_with_features() early-return skips compute_advice builds (program.rs:137). Also flagged by Graphite — the self.elf.is_some() check doesn't distinguish between regular and compute_advice variants.

Missing data (1):

decode() drops e_entry (program.rs:384-395). jolt-core returns 4 values including the ELF entry point, which is required by JoltSharedPreprocessing::new(). The new function returns only 3, silently discarding e_entry from tracer::decode().

Minor observations

_ => unreachable!() in flag dispatch is correct for the current instruction set (tracer expands others) but fragile. A comment or explicit INLINE(_) match would help.
Dropping _advice_tape in trace() matches jolt-core's existing pattern — consistent.
trace_to_file taking &Path instead of &PathBuf is a nice improvement over jolt-core.
Removing the unused F: JoltField generic from trace_analyze is correct.

Generated by Claude Code

0xAndoroid · 2026-04-15T18:09:42Z

+    fn lookup_output(&self) -> u64 {
+        let cflags = self.circuit_flags();
+        if cflags[CircuitFlags::WriteLookupOutputToRD] {
+            self.rd_write().map_or(0, |(_, _, post)| post)
+        } else if cflags[CircuitFlags::Jump] {
+            self.rd_write().map_or(0, |(_, _, post)| post)
+        } else {
+            0
+        }
+    }
+}


Bug: lookup_output() implementation doesn't match its doc comment contract.

The doc says "For branches: the comparison result (0 or 1)" but the implementation returns 0 for all branch instructions (BEQ, BGE, BGEU, BLT, BLTU, BNE). Branch instructions don't set WriteLookupOutputToRD or Jump flags, so they fall through to the else { 0 } arm.

In jolt-core, to_lookup_output() for branches actually computes the comparison. For example, BGE computes ((x as i64) >= (y as i64)) as u64 (see jolt-core/src/zkvm/instruction/bge.rs:53-62). This value is used in the R1CS witness as should_branch_lookup_output (see jolt-core/src/zkvm/r1cs/inputs.rs:503).

Since CycleRow is not consumed by jolt-core yet, this is latent — but it will cause incorrect witness generation when this trait replaces the existing LookupQuery::to_lookup_output() path. You'd need to either:

Evaluate the lookup table here (requires access to the table materializer), or

Re-derive the comparison from operands using the instruction flags (similar to how lookup_index derives its value from flags).

Generated by Claude Code

0xAndoroid · 2026-04-15T18:09:48Z

+        Instruction::VirtualXORROTW8(_) => Flags::circuit_flags(&xor_rotate::VirtualXorRotW8),
+        Instruction::VirtualXORROTW7(_) => Flags::circuit_flags(&xor_rotate::VirtualXorRotW7),
+        Instruction::NoOp => CircuitFlagSet::default().set(CircuitFlags::DoNotUpdateUnexpandedPC),
+        _ => unreachable!(),


Nit: The instruction coverage here matches jolt-core's define_rv32im_trait_impls! set exactly, which is correct — the tracer expands unsupported base instructions (SLL, LB, LW, atomics, etc.) into virtual sequences during emulation.

However, unreachable!() is fragile: if a new un-expanded instruction is added to the tracer, this panics at runtime with no compile-time warning. Consider either:

Adding a comment explaining why this is safe (the tracer expands all other instructions), or

Matching Instruction::INLINE(_) explicitly (like lookup_table_kind_for_instruction does at line 472) instead of relying on _.

Generated by Claude Code

0xAndoroid · 2026-04-15T18:09:54Z

+pub fn decode(elf: &[u8]) -> (Vec<Instruction>, Vec<(u64, u8)>, u64) {
+    let (mut instructions, raw_bytes, program_end, _, xlen) = tracer::decode(elf);
+    let program_size = program_end - RAM_START_ADDRESS;
+    let allocator = VirtualRegisterAllocator::default();
+
+    instructions = instructions
+        .into_iter()
+        .flat_map(|instr: Instruction| instr.inline_sequence(&allocator, xlen))
+        .collect();
+
+    (instructions, raw_bytes, program_size)
+}


Missing return value: jolt-core's guest::program::decode() returns 4 values (Vec<Instruction>, Vec<(u64, u8)>, u64, u64) — the 4th being e_entry (ELF entry point address). This function only returns 3.

e_entry is required by JoltSharedPreprocessing::new() and is used extensively in the prover pipeline (see every call site in jolt-core/src/zkvm/prover.rs). When jolt-trace eventually replaces the host decode path, callers won't have access to e_entry.

The underlying tracer::decode() does return e_entry — it's just being discarded on line 385. Consider returning it as the 4th tuple element to match jolt-core's interface.

Generated by Claude Code

0xAndoroid · 2026-04-15T18:10:00Z

+    pub fn build_with_features(&mut self, target_dir: &str, extra_features: &[&str]) {
+        if self.elf.is_some() {
+            return;
+        }


Bug (also flagged by Graphite): The early-return check on line 137 only checks self.elf.is_some() but doesn't account for the compute_advice variant. If build() was already called (setting self.elf), a subsequent build_with_features(dir, &["compute_advice"]) silently returns without building the compute-advice ELF.

The is_compute_advice check should be moved before the early return:

let is_compute_advice = extra_features.contains(&"compute_advice"); if is_compute_advice { if self.elf_compute_advice.is_some() { return; } } else { if self.elf.is_some() { return; } }

Generated by Claude Code

0xAndoroid · 2026-04-15T18:10:05Z

+    fn rs1_read(&self) -> Option<(u8, u64)> {
+        self.rs1_read()
+    }
+


Nit: This calls self.rs1_read() which for a Cycle ends up calling Cycle::rs1_read() (the inherent method), not CycleRow::rs1_read(). This works because the inherent method has the same signature, but it's a subtle dispatch — the trait method delegates to the inherent method of the same name. Might be worth a comment to clarify this is intentional (or use Cycle::rs1_read(self) explicitly to make the delegation visible).

Generated by Claude Code

- Adapt to jolt-riscv + jolt-lookup-tables (replacing jolt-instructions) - CycleRow trait returns CircuitFlagSet/InstructionFlagSet (packed bitfields) - with_isa_struct! macro uses jolt_riscv::rv/virt modules - lookup_table() via InstructionLookupTable extension trait - Add bytecode.rs, ram.rs, tracer_cycle.rs (renamed from cycle_row_impl) - Remove stale PLAN.md, README.md, REVIEW.md - All 26 tests pass, clippy clean

Rename crate directory and package name to match PR convention.

This was referenced Mar 25, 2026

chore: workspace scaffolding for modular crates #1362

Merged

feat: add jolt-profiling crate #1364

Merged

feat: add jolt-transcript crate #1365

Merged

feat: add jolt-field crate #1363

Merged

feat: add jolt-instructions crate #1366

Merged

This was referenced Mar 25, 2026

feat: add jolt-poly crate #1367

Merged

feat: add jolt-crypto crate #1368

Open

markosg04 marked this pull request as ready for review April 7, 2026 19:02

markosg04 requested review from 0xAndoroid and moodlezoup as code owners April 7, 2026 19:02

github-actions bot added the no-spec PR has no spec file label Apr 7, 2026

0xAndoroid force-pushed the jolt-v2/jolt-crypto branch from d2289fa to 97b7260 Compare April 14, 2026 22:09

0xAndoroid requested a review from sagar-a16z as a code owner April 14, 2026 22:09

0xAndoroid force-pushed the jolt-v2/jolt-crypto branch from 97b7260 to d42bade Compare April 14, 2026 22:11

0xAndoroid changed the base branch from jolt-v2/jolt-crypto to main April 15, 2026 16:55

0xAndoroid force-pushed the jolt-v2/jolt-host branch from cd0c688 to d26ecff Compare April 15, 2026 17:17

0xAndoroid force-pushed the jolt-v2/jolt-host branch from d26ecff to 7047bbb Compare April 15, 2026 17:20

graphite-app bot reviewed Apr 15, 2026

View reviewed changes

0xAndoroid added the claude-review-request Request a review from Claude Code label Apr 15, 2026

0xAndoroid changed the title ~~feat: add jolt-host crate~~ feat(jolt-trace): add jolt-trace crate Apr 15, 2026

0xAndoroid requested changes Apr 15, 2026

View reviewed changes

0xAndoroid removed the claude-review-request Request a review from Claude Code label Apr 15, 2026 — with Claude

markosg04 added 3 commits April 15, 2026 15:39

feat: add jolt-host crate

88487b0

rename jolt-host → jolt-trace

580e6ea

Rename crate directory and package name to match PR convention.

markosg04 force-pushed the jolt-v2/jolt-host branch from 2401151 to 580e6ea Compare April 15, 2026 19:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(jolt-trace): add jolt-trace crate#1369

feat(jolt-trace): add jolt-trace crate#1369
markosg04 wants to merge 3 commits intomainfrom
jolt-v2/jolt-host

markosg04 commented Mar 25, 2026

Uh oh!

markosg04 commented Mar 25, 2026 •

edited

Loading

Uh oh!

markosg04 commented Mar 25, 2026

Uh oh!

github-actions bot commented Apr 15, 2026

Uh oh!

github-actions bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

graphite-app bot Apr 15, 2026

Uh oh!

0xAndoroid commented Apr 15, 2026

Uh oh!

0xAndoroid left a comment

Uh oh!

0xAndoroid Apr 15, 2026

Uh oh!

0xAndoroid Apr 15, 2026

Uh oh!

0xAndoroid Apr 15, 2026

Uh oh!

0xAndoroid Apr 15, 2026

Uh oh!

0xAndoroid Apr 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

markosg04 commented Mar 25, 2026

Summary

Changes

Testing

Security Considerations

Breaking Changes

Uh oh!

markosg04 commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markosg04 commented Mar 25, 2026

Uh oh!

github-actions bot commented Apr 15, 2026

Uh oh!

github-actions bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmark comparison (crates)

Uh oh!

graphite-app bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

0xAndoroid commented Apr 15, 2026

Uh oh!

0xAndoroid left a comment

Choose a reason for hiding this comment

Code Review: jolt-trace crate extraction

Issues found

Minor observations

Uh oh!

0xAndoroid Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

0xAndoroid Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

0xAndoroid Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

0xAndoroid Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

0xAndoroid Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

markosg04 commented Mar 25, 2026 •

edited

Loading

github-actions bot commented Apr 15, 2026 •

edited

Loading

Code Review: `jolt-trace` crate extraction