Skip to content

feat: add jolt-instructions crate#1366

Open
markosg04 wants to merge 16 commits intomainfrom
jolt-v2/jolt-instructions
Open

feat: add jolt-instructions crate#1366
markosg04 wants to merge 16 commits intomainfrom
jolt-v2/jolt-instructions

Conversation

@markosg04
Copy link
Copy Markdown
Collaborator

@markosg04 markosg04 commented Mar 25, 2026

Summary

Changes

Testing

  • Ran tests for modified crates
  • cargo clippy and cargo fmt pass

Security Considerations

Breaking Changes

None

This was referenced Mar 25, 2026
Merged
Merged
Merged
Merged
@markosg04 Graphite App
Copy link
Copy Markdown
Collaborator Author

markosg04 commented Mar 25, 2026 •
edited
Loading

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

This was referenced Mar 25, 2026
Open
Open
Open
@markosg04 markosg04 marked this pull request as ready for review April 2, 2026 15:33
@0xAndoroid 0xAndoroid force-pushed the jolt-v2/jolt-transcript branch from f089b0c to 9d859ae Compare April 6, 2026 18:25
@0xAndoroid 0xAndoroid requested a review from sagar-a16z as a code owner April 6, 2026 18:25
@0xAndoroid 0xAndoroid force-pushed the jolt-v2/jolt-transcript branch from 9d859ae to 141bc87 Compare April 6, 2026 18:26
@0xAndoroid 0xAndoroid changed the base branch from jolt-v2/jolt-transcript to graphite-base/1366 April 7, 2026 16:19
@0xAndoroid 0xAndoroid changed the base branch from graphite-base/1366 to main April 7, 2026 16:42
@0xAndoroid 0xAndoroid force-pushed the jolt-v2/jolt-instructions branch from 011fa4f to 2a63a07 Compare April 7, 2026 17:01
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

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 github-actions bot added the no-spec PR has no spec file label Apr 7, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

10 similar comments
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 8, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@0xAndoroid 0xAndoroid force-pushed the jolt-v2/jolt-instructions branch from 66a8432 to 6ae5520 Compare April 8, 2026 21:34
markosg04 and others added 11 commits April 8, 2026 17:34
@markosg04 @0xAndoroid
feat: add jolt-instructions crate
4701ed8
@0xAndoroid
fix(jolt-instructions): execute/table consistency, compile-time asser…
3c24629 
…tions, and suffixes allocation

- Fix W-suffix execute()/table sign-extension mismatch: VirtualXorRotW{16,12,8,7}
  and VirtualRotriw were sign-extending results but their tables zero-extend.
  Aligned execute() to match tables.
- Fix VirtualChangeDivisorW execute() to explicitly sign-extend, matching table.
- Add compile-time const assertions for NUM_SUFFIXES, NUM_CIRCUIT_FLAGS,
  and NUM_INSTRUCTION_FLAGS (matching existing LookupTableKind::COUNT pattern).
- Change PrefixSuffixDecomposition::suffixes() to return &'static [Suffixes]
  instead of Vec<Suffixes>, avoiding heap allocation in prover hot path.
- Add debug_assert to LookupBits::pop_msb for empty bitvector.
- Remove unnecessary #![allow(unused_results)] from lookup_table_tests.
- Add WHY comments for shift/W-suffix instructions with flag/table mismatches.
@0xAndoroid
refactor(jolt-instructions): remove opcodes module
2a7fcf0 
Remove the `opcodes` module and `fn opcode()` from the `Instruction` trait.
The opcode is now purely the registration index in `JoltInstructionSet::new()`,
eliminating a manually-synced constants file (105 constants) and simplifying
the instruction definition macro.

Integration tests now use instruction structs directly instead of
opcode-based registry lookups.
@0xAndoroid
refactor(jolt-instructions): rename virtual_ module to virt
7601969 
`virtual` is a reserved keyword; `virt` is the standard abbreviation.
@0xAndoroid
refactor: split jolt-instructions into jolt-lookup-tables + jolt-riscv
332abcd 
jolt-lookup-tables: 41 lookup tables, MLE evaluation, prefix/suffix
decomposition, LookupBits, ChallengeOps, bit interleaving.

jolt-riscv: 105 RISC-V instruction definitions, flags, macro, registry.
Depends on jolt-lookup-tables and re-exports all its types for downstream
convenience and macro compatibility.
@0xAndoroid
refactor(jolt-lookup-tables): eliminate dispatch macros, inline tests…
0293f43 
…, remove XLEN generic

- Eliminate `LookupTables<XLEN>` enum, `dispatch_table!` macro, and
  `kind_table_identity!` macro. All dispatch methods now live as explicit
  match arms on `LookupTableKind`.
- Move all lookup table tests from centralized `lookup_table_tests.rs`
  into `#[cfg(test)] mod tests` blocks in each table file.
- Replace `<const XLEN: usize>` generic with `pub const XLEN: usize = 64`.
  Delete all XLEN=8 code paths, `mle_full_hypercube_test`, and the
  `materialize()` default method.
@0xAndoroid
refactor(jolt-riscv): pack flags into bitfield structs
9e0e216 
Replace `[bool; NUM_CIRCUIT_FLAGS]` and `[bool; NUM_INSTRUCTION_FLAGS]`
with `CircuitFlagSet(u16)` and `InstructionFlagSet(u8)` packed bitfields.

Builder-pattern `.set()` for construction, `Index` impl for ergonomic
access. 21 bytes → 3 bytes per instruction flag set.
@0xAndoroid
refactor: invert jolt-riscv / jolt-lookup-tables dependency
78788bb 
jolt-riscv is now a leaf crate (jolt-field + serde only). Removed
fn lookup_table() from Instruction trait and table: clause from
define_instruction! macro.

jolt-lookup-tables depends on jolt-riscv and defines InstructionLookupTable
extension trait mapping all 105 instructions to their lookup tables.
@0xAndoroid
refactor(jolt-riscv): replace crate:: qualified paths with imports in…
0e45778 
… arithmetic files

Add `use crate::{...}` imports at the top of arithmetic.rs and
arithmetic_w.rs, replacing all fully-qualified crate:: paths in
manual trait implementations.
@0xAndoroid
fix(jolt-riscv): align instruction flags with jolt-core
70a5390 
15 flag mismatches found by cross-referencing against jolt-core:

- Add missing AddOperands to: AssertWordAlignment, AssertHalfwordAlignment,
  VirtualRev8W, VirtualSignExtendWord, VirtualZeroExtendWord,
  VirtualShiftRightBitmask, VirtualShiftRightBitmaskI
- Add missing MultiplyOperands to AssertMulUNoOverflow
- Add missing RightOperandIsImm to: AssertWordAlignment,
  AssertHalfwordAlignment, VirtualShiftRightBitmask
- Remove incorrect LeftOperandIsRs1Value from: Pow2I, Pow2IW,
  VirtualShiftRightBitmaskI
- Remove incorrect RightOperandIsImm from Pow2W
- Remove unused jolt-field dependency from jolt-riscv
@0xAndoroid
fix(jolt-riscv): restore extracted instruction contracts
406ce72 
Align the extracted instruction semantics with the existing tracer and jolt-core contracts for virtual shifts, assertions, pow2 helpers, and LISC-V LUI handling.

Clarify that advice and host I/O opcodes remain runtime-managed and only expose placeholder execute semantics through the registry API.

Constraint: Keep extracted crate behavior aligned with existing tracer/jolt-core operand contracts

Rejected: Make advice instructions emulate runtime state | trait API has no access to emulator context

Confidence: high

Scope-risk: narrow
@0xAndoroid 0xAndoroid force-pushed the jolt-v2/jolt-instructions branch from 6ae5520 to 406ce72 Compare April 8, 2026 21:34
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 8, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@0xAndoroid
refactor(jolt-riscv): replace define_instruction! macro with #[derive…
af33cf1 
…(Flags)]

Add jolt-riscv-derive proc macro crate that generates Flags trait impls
from #[circuit(...)] and #[instruction(...)] attributes on structs.
All 105 instructions now use normal struct + impl Instruction + derive
instead of the declarative macro. Remove macros.rs entirely.
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 9, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

@0xAndoroid
refactor: derive enum variant counts with strum::EnumCount
ab9bcd6 
Replace hardcoded NUM_CIRCUIT_FLAGS, NUM_INSTRUCTION_FLAGS,
NUM_PREFIXES, NUM_SUFFIXES, and LookupTableKind::COUNT with
strum::EnumCount derives. Remove manual const assert checks.
@0xAndoroid
refactor(jolt-riscv): remove JoltInstructionSet registry
6147bd2 
No external consumers — only used in its own tests. Instruction structs
are ZSTs usable directly. Opcode-indexed dispatch belongs at the
tracer/jolt-core integration point, not here.
@0xAndoroid
chore: remove placeholder authors field from new crates
ef9ab09
@0xAndoroid
refactor(jolt-lookup-tables): derive ALL_PREFIXES with strum::Variant…
2792b96 
…Array
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 10, 2026

Benchmark comparison (crates)

No baseline found — skipping comparison.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@moodlezoup moodlezoup Awaiting requested review from moodlezoup moodlezoup is a code owner

@0xAndoroid 0xAndoroid Awaiting requested review from 0xAndoroid 0xAndoroid is a code owner

@sagar-a16z sagar-a16z Awaiting requested review from sagar-a16z

Assignees

No one assigned

Labels

no-spec PR has no spec file

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@markosg04 @0xAndoroid