Use Hint Bridge for Constraining HintLoad

crates/vm/src/arch/testing/cpu.rs

@@ -37,16 +37,17 @@ use crate::{
         testing::{
             execution::air::ExecutionDummyAir,
             program::{air::ProgramDummyAir, ProgramTester},
-            ExecutionTester, MemoryTester, TestBuilder, TestChipHarness, EXECUTION_BUS, MEMORY_BUS,
-            MEMORY_MERKLE_BUS, POSEIDON2_DIRECT_BUS, RANGE_CHECKER_BUS, READ_INSTRUCTION_BUS,
+            ExecutionTester, MemoryTester, TestBuilder, TestChipHarness, EXECUTION_BUS, HINT_BUS,
+            MEMORY_BUS, MEMORY_MERKLE_BUS, POSEIDON2_DIRECT_BUS, RANGE_CHECKER_BUS,
+            READ_INSTRUCTION_BUS,
         },
         vm_poseidon2_config, Arena, ExecutionBridge, ExecutionBus, ExecutionState,
         MatrixRecordArena, MemoryConfig, PreflightExecutor, Streams, VmStateMut,
     },
     system::{
         memory::{
             adapter::records::arena_size_bound,
-            offline_checker::{MemoryBridge, MemoryBus},
+            offline_checker::{HintBridge, HintBus, MemoryBridge, MemoryBus},
             online::TracingMemory,
             MemoryAirInventory, MemoryController, SharedMemoryHelper, CHUNK,
         },
@@ -258,10 +259,13 @@ impl<F: PrimeField32> VmChipTestBuilder<F> {
     }
 
     pub fn system_port(&self) -> SystemPort {
+        let hint_bus = HintBus::new(HINT_BUS);
+        let hint_bridge = HintBridge::new(hint_bus);
         SystemPort {
             execution_bus: self.execution.bus,
             program_bus: self.program.bus,
             memory_bridge: self.memory_bridge(),
+            hint_bridge,
         }
     }
 

crates/vm/src/arch/testing/cuda.rs

@@ -50,7 +50,7 @@ use crate::{
             execution::{air::ExecutionDummyAir, DeviceExecutionTester},
             memory::DeviceMemoryTester,
             program::{air::ProgramDummyAir, DeviceProgramTester},
-            TestBuilder, TestChipHarness, EXECUTION_BUS, MEMORY_BUS, MEMORY_MERKLE_BUS,
+            TestBuilder, TestChipHarness, EXECUTION_BUS, HINT_BUS, MEMORY_BUS, MEMORY_MERKLE_BUS,
             POSEIDON2_DIRECT_BUS, READ_INSTRUCTION_BUS,
         },
         Arena, DenseRecordArena, ExecutionBridge, ExecutionBus, ExecutionState, MatrixRecordArena,
@@ -59,7 +59,7 @@ use crate::{
     system::{
         cuda::{poseidon2::Poseidon2PeripheryChipGPU, DIGEST_WIDTH},
         memory::{
-            offline_checker::{MemoryBridge, MemoryBus},
+            offline_checker::{HintBridge, HintBus, MemoryBridge, MemoryBus},
             MemoryAirInventory, SharedMemoryHelper,
         },
         poseidon2::air::Poseidon2PeripheryAir,
@@ -393,8 +393,14 @@ impl GpuChipTestBuilder {
             execution_bus: self.execution_bus(),
             program_bus: self.program_bus(),
             memory_bridge: self.memory_bridge(),
+            hint_bridge: self.hint_bridge(),
         }
     }
+
+    pub fn hint_bridge(&self) -> HintBridge {
+        let hint_bus = HintBus::new(HINT_BUS);
+        HintBridge::new(hint_bus)
+    }
     pub fn execution_bridge(&self) -> ExecutionBridge {
         ExecutionBridge::new(self.execution.bus(), self.program.bus())
     }

crates/vm/src/arch/testing/mod.rs

@@ -29,6 +29,7 @@ pub const BITWISE_OP_LOOKUP_BUS: BusIndex = 9;
 pub const BYTE_XOR_BUS: BusIndex = 10;
 pub const RANGE_TUPLE_CHECKER_BUS: BusIndex = 11;
 pub const MEMORY_MERKLE_BUS: BusIndex = 12;
+pub const HINT_BUS: BusIndex = 13;
 
 pub const RANGE_CHECKER_BUS: BusIndex = 4;
 

crates/vm/src/system/memory/offline_checker/bridge.rs

@@ -10,7 +10,7 @@ use openvm_stark_backend::{
     interaction::InteractionBuilder, p3_air::AirBuilder, p3_field::FieldAlgebra,
 };
 
-use super::bus::MemoryBus;
+use super::bus::{HintBus, MemoryBus};
 use crate::system::memory::{
     offline_checker::columns::{
         MemoryBaseAuxCols, MemoryReadAuxCols, MemoryReadOrImmediateAuxCols, MemoryWriteAuxCols,
@@ -326,3 +326,52 @@ impl MemoryOfflineChecker {
             .eval(builder, enabled);
     }
 }
+
+/// The [HintBridge] is used to constrain hint space lookups.
+/// Consumer chips call `lookup` to verify that values they read from hint_space
+/// match what was originally loaded via the hint bus lookup table.
+#[derive(Clone, Copy, Debug)]
+pub struct HintBridge {
+    hint_bus: HintBus,
+}
+
+impl HintBridge {
+    /// Create a new [HintBridge] with the provided hint bus.
+    pub fn new(hint_bus: HintBus) -> Self {
+        Self { hint_bus }
+    }
+
+    pub fn hint_bus(&self) -> HintBus {
+        self.hint_bus
+    }
+
+    /// Perform a lookup on the hint bus for a single element.
+    ///
+    /// Constrains that `(hint_id, offset, value)` exists in the hint lookup table.
+    /// Caller must constrain that `enabled` is boolean.
+    pub fn lookup<AB: InteractionBuilder>(
+        &self,
+        builder: &mut AB,
+        hint_id: impl Into<AB::Expr>,
+        offset: impl Into<AB::Expr>,
+        value: impl Into<AB::Expr>,
+        enabled: impl Into<AB::Expr>,
+    ) {
+        self.hint_bus.lookup(builder, hint_id, offset, value, enabled);
+    }
+
+    /// Add a key to the hint lookup table.
+    ///
+    /// Provider chips call this to register that `(hint_id, offset, value)` is available.
+    pub fn provide<AB: InteractionBuilder>(
+        &self,
+        builder: &mut AB,
+        hint_id: impl Into<AB::Expr>,
+        offset: impl Into<AB::Expr>,
+        value: impl Into<AB::Expr>,
+        num_lookups: impl Into<AB::Expr>,
+    ) {
+        self.hint_bus
+            .provide(builder, hint_id, offset, value, num_lookups);
+    }
+}

crates/vm/src/system/memory/offline_checker/bus.rs

@@ -1,7 +1,7 @@
 use std::iter;
 
 use openvm_stark_backend::{
-    interaction::{BusIndex, InteractionBuilder, PermutationCheckBus},
+    interaction::{BusIndex, InteractionBuilder, LookupBus, PermutationCheckBus},
     p3_field::FieldAlgebra,
 };
 
@@ -101,3 +101,65 @@ impl<T: FieldAlgebra> MemoryBusInteraction<T> {
         }
     }
 }
+
+/// Represents a hint bus identified by a unique bus index.
+/// Used as a lookup table to constrain values read from hint space.
+///
+/// Consumer chips (e.g. NativeSumcheck) perform lookups to verify that
+/// hint_space values match what was originally loaded.
+/// Provider chips (e.g. a hint loader) add keys to the lookup table.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct HintBus {
+    pub inner: LookupBus,
+}
+
+impl HintBus {
+    pub const fn new(index: BusIndex) -> Self {
+        Self {
+            inner: LookupBus::new(index),
+        }
+    }
+
+    #[inline(always)]
+    pub fn index(&self) -> BusIndex {
+        self.inner.index
+    }
+
+    /// Performs a lookup on the hint bus.
+    ///
+    /// Asserts that `(hint_id, offset, value)` is present in the hint lookup table.
+    /// Caller must constrain that `enabled` is boolean.
+    pub fn lookup<AB: InteractionBuilder>(
+        &self,
+        builder: &mut AB,
+        hint_id: impl Into<AB::Expr>,
+        offset: impl Into<AB::Expr>,
+        value: impl Into<AB::Expr>,
+        enabled: impl Into<AB::Expr>,
+    ) {
+        self.inner.lookup_key(
+            builder,
+            [hint_id.into(), offset.into(), value.into()],
+            enabled,
+        );
+    }
+
+    /// Adds a key to the hint lookup table.
+    ///
+    /// The `num_lookups` parameter should equal the number of enabled lookups performed
+    /// for this key.
+    pub fn provide<AB: InteractionBuilder>(
+        &self,
+        builder: &mut AB,
+        hint_id: impl Into<AB::Expr>,
+        offset: impl Into<AB::Expr>,
+        value: impl Into<AB::Expr>,
+        num_lookups: impl Into<AB::Expr>,
+    ) {
+        self.inner.add_key_with_lookups(
+            builder,
+            [hint_id.into(), offset.into(), value.into()],
+            num_lookups,
+        );
+    }
+}

crates/vm/src/system/memory/offline_checker/columns.rs

@@ -123,3 +123,48 @@ impl<T> AsMut<MemoryBaseAuxCols<T>> for MemoryReadOrImmediateAuxCols<T> {
         &mut self.base
     }
 }
+/// The auxiliary columns for a hint read operation.
+/// Stores the previous timestamp to enable permutation checking through the hint bus.
+#[repr(C)]
+#[derive(Clone, Copy, Debug, AlignedBorrow)]
+pub struct HintReadAuxCols<T> {
+    /// The previous timestamp when this hint location was accessed
+    pub prev_timestamp: T,
+}
+
+impl<F: PrimeField32> HintReadAuxCols<F> {
+    pub fn new(prev_timestamp: F) -> Self {
+        Self { prev_timestamp }
+    }
+
+    #[inline(always)]
+    pub fn set_prev(&mut self, timestamp: F) {
+        self.prev_timestamp = timestamp;
+    }
+}
+
+/// The auxiliary columns for a hint write operation.
+/// Stores the previous timestamp and previous value to enable permutation checking through the hint bus.
+#[repr(C)]
+#[derive(Clone, Copy, Debug, AlignedBorrow)]
+pub struct HintWriteAuxCols<T> {
+    /// The previous timestamp when this hint location was accessed
+    pub prev_timestamp: T,
+    /// The previous value at this hint location
+    pub prev_value: T,
+}
+
+impl<F: PrimeField32> HintWriteAuxCols<F> {
+    pub fn new(prev_timestamp: F, prev_value: F) -> Self {
+        Self {
+            prev_timestamp,
+            prev_value,
+        }
+    }
+
+    #[inline(always)]
+    pub fn set_prev(&mut self, timestamp: F, value: F) {
+        self.prev_timestamp = timestamp;
+        self.prev_value = value;
+    }
+}

crates/vm/src/system/mod.rs

@@ -36,7 +36,7 @@ use crate::{
         connector::VmConnectorChip,
         memory::{
             interface::MemoryInterfaceAirs,
-            offline_checker::{MemoryBridge, MemoryBus},
+            offline_checker::{HintBridge, HintBus, MemoryBridge, MemoryBus},
             online::GuestMemory,
             MemoryAirInventory, MemoryController, TimestampedEquipartition, CHUNK,
         },
@@ -149,13 +149,15 @@ pub struct SystemPort {
     pub execution_bus: ExecutionBus,
     pub program_bus: ProgramBus,
     pub memory_bridge: MemoryBridge,
+    pub hint_bridge: HintBridge,
 }
 
 #[derive(Clone)]
 pub struct SystemAirInventory<SC: StarkGenericConfig> {
     pub program: ProgramAir,
     pub connector: VmConnectorAir,
     pub memory: MemoryAirInventory<SC>,
+    pub hint_bridge: HintBridge,
     /// Public values AIR exists if and only if continuations is disabled and `num_public_values`
     /// is greater than 0.
     pub public_values: Option<PublicValuesAir>,
@@ -171,6 +173,7 @@ impl<SC: StarkGenericConfig> SystemAirInventory<SC> {
             execution_bus,
             program_bus,
             memory_bridge,
+            hint_bridge,
         } = port;
         let range_bus = memory_bridge.range_bus();
         let program = ProgramAir::new(program_bus);
@@ -212,6 +215,7 @@ impl<SC: StarkGenericConfig> SystemAirInventory<SC> {
             program,
             connector,
             memory,
+            hint_bridge,
             public_values,
         }
     }
@@ -221,6 +225,7 @@ impl<SC: StarkGenericConfig> SystemAirInventory<SC> {
             memory_bridge: self.memory.bridge,
             program_bus: self.program.bus,
             execution_bus: self.connector.execution_bus,
+            hint_bridge: self.hint_bridge,
         }
     }
 
@@ -300,10 +305,13 @@ impl<SC: StarkGenericConfig> VmCircuitConfig<SC> for SystemConfig {
         };
         let memory_bridge =
             MemoryBridge::new(memory_bus, self.memory_config.timestamp_max_bits, range_bus);
+        let hint_bus = HintBus::new(bus_idx_mgr.new_bus_idx());
+        let hint_bridge = HintBridge::new(hint_bus);
         let system_port = SystemPort {
             execution_bus,
             program_bus,
             memory_bridge,
+            hint_bridge,
         };
         let system = SystemAirInventory::new(self, system_port, merkle_compression_buses);
 

extensions/algebra/circuit/src/extension/fp2.rs

@@ -175,6 +175,7 @@ impl<SC: StarkGenericConfig> VmCircuitExtension<SC> for Fp2Extension {
             execution_bus,
             program_bus,
             memory_bridge,
+            hint_bridge: _,
         } = inventory.system().port();
 
         let exec_bridge = ExecutionBridge::new(execution_bus, program_bus);

extensions/algebra/circuit/src/extension/modular.rs

@@ -231,6 +231,7 @@ impl<SC: StarkGenericConfig> VmCircuitExtension<SC> for ModularExtension {
             execution_bus,
             program_bus,
             memory_bridge,
+            hint_bridge: _,
         } = inventory.system().port();
 
         let exec_bridge = ExecutionBridge::new(execution_bus, program_bus);

extensions/bigint/circuit/src/extension/mod.rs

@@ -143,6 +143,7 @@ impl<SC: StarkGenericConfig> VmCircuitExtension<SC> for Int256 {
             execution_bus,
             program_bus,
             memory_bridge,
+            hint_bridge: _,
         } = inventory.system().port();
 
         let exec_bridge = ExecutionBridge::new(execution_bus, program_bus);

extensions/ecc/circuit/src/extension/weierstrass.rs

@@ -200,6 +200,7 @@ impl<SC: StarkGenericConfig> VmCircuitExtension<SC> for WeierstrassExtension {
             execution_bus,
             program_bus,
             memory_bridge,
+            hint_bridge: _,
         } = inventory.system().port();
 
         let exec_bridge = ExecutionBridge::new(execution_bus, program_bus);

extensions/keccak256/circuit/src/extension/mod.rs

@@ -148,6 +148,7 @@ impl<SC: StarkGenericConfig> VmCircuitExtension<SC> for Keccak256 {
             execution_bus,
             program_bus,
             memory_bridge,
+            hint_bridge: _,
         } = inventory.system().port();
 
         let exec_bridge = ExecutionBridge::new(execution_bus, program_bus);