Merge pull request #3238 from ProvableHQ/mohammadfawaz/query_functions

feat: read-only `query` functions

Author: vicsn

.circleci/config.yml

@@ -905,8 +905,10 @@ jobs:
     steps:
       - run_test:
           workspace_member: snarkvm-synthesizer
+          # `history` enables the per-key historical update map that the `query` evaluation path
+          # depends on; gating it here ensures the v15 query tests are exercised in CI.
           flags: >
-            --lib --bins --features test
+            --lib --bins --features test,history
             --partition count:1/2
             -- --test-threads 8
           cache_key_suffix: -test1
@@ -919,7 +921,7 @@ jobs:
       - run_test:
           workspace_member: snarkvm-synthesizer
           flags: >
-            --lib --bins --features test
+            --lib --bins --features test,history
             --partition count:2/2
             -- --test-threads 8
           cache_key_suffix: -test2
@@ -933,7 +935,7 @@ jobs:
           timeout: 30m # test_vm_execute_and_finalize can take over 10 minutes in the current setup
           no_output_timeout: 20m
           workspace_member: snarkvm-synthesizer
-          flags: --test '*' --features test,dev-print -- --test-threads=4
+          flags: --test '*' --features test,dev-print,history -- --test-threads=4
           cache_key_suffix: -integration
 
   synthesizer-process:
@@ -942,6 +944,8 @@ jobs:
     steps:
       - run_test:
           workspace_member: snarkvm-synthesizer-process
+          # See `synthesizer-test-partition1` for why `history` is enabled.
+          flags: --features history
 
   synthesizer-process-with-rocksdb:
     executor: rust-docker

console/network/src/lib.rs

@@ -226,6 +226,8 @@ pub trait Network:
     const MAX_RECORDS: usize = 10 * Self::MAX_FUNCTIONS;
     /// The maximum number of closures in a program.
     const MAX_CLOSURES: usize = 2 * Self::MAX_FUNCTIONS;
+    /// The maximum number of query functions in a program.
+    const MAX_QUERIES: usize = 2 * Self::MAX_FUNCTIONS;
     /// The maximum number of operands in an instruction.
     const MAX_OPERANDS: usize = Self::MAX_INPUTS;
     /// The maximum number of instructions in a closure or function.

synthesizer/Cargo.toml

@@ -33,7 +33,7 @@ locktick = [
 ]
 async = [ "snarkvm-ledger-query/async", "snarkvm-synthesizer-process/async" ]
 cuda = [ "snarkvm-algorithms/cuda" ]
-history = [ "snarkvm-ledger-store/history" ]
+history = [ "snarkvm-ledger-store/history", "snarkvm-synthesizer-process/history" ]
 history-staking-rewards = [ "snarkvm-ledger-store/history-staking-rewards" ]
 slipstream-plugins = [ "snarkvm-ledger-store/slipstream-plugins" ]
 rocks = [ "snarkvm-ledger-store/rocks" ]

synthesizer/process/Cargo.toml

@@ -44,6 +44,7 @@ wasm = [
   "snarkvm-synthesizer-snark/wasm"
 ]
 test = [ "snarkvm-console/test", "snarkvm-circuit/test" ]
+history = [ "snarkvm-ledger-store/history" ]
 timer = [ "aleo-std/timer" ]
 dev-print = [ "snarkvm-utilities/dev-print" ]
 dev_skip_checks = [ ]

synthesizer/process/src/cost.rs

@@ -259,6 +259,20 @@ pub fn deployment_cost_v2<N: Network>(
         );
     }
 
+    // Bound each query function's worst-case compute. Queries are off-consensus and have no
+    // dedicated fee component beyond what is already counted in `storage_cost` (their bytes
+    // contribute to `size_in_bytes`). The bound below is purely a deploy-time sanity check
+    // to keep pathological queries from being accepted.
+    for query in deployment.program().queries().values() {
+        let query_cost = query_cost_for_single_query(&stack, query.name(), ConsensusFeeVersion::V3)?;
+        ensure!(
+            query_cost <= N::TRANSACTION_SPEND_LIMIT[1].1,
+            "Query '{}' has a cost '{query_cost}' which exceeds the transaction spend limit '{}'",
+            query.name(),
+            N::TRANSACTION_SPEND_LIMIT[1].1
+        );
+    }
+
     // Compute the namespace cost in microcredits: 10^(10 - num_characters) * 1e6
     let namespace_cost = 10u64
         .checked_pow(10u32.saturating_sub(num_characters))
@@ -1000,6 +1014,30 @@ fn finalize_cost_for_single_function_raw<N: Network>(
     Ok(finalize_cost)
 }
 
+/// Returns the maximum compute cost (in microcredits) of a single query function's body.
+///
+/// Queries do not run as part of consensus, so this cost is not paid by anyone — it is only
+/// used as a deploy-time sanity bound (mirrors the per-function `TRANSACTION_SPEND_LIMIT`
+/// check) to prevent deploying queries whose worst-case compute is unreasonable.
+fn query_cost_for_single_query<N: Network>(
+    stack: &Stack<N>,
+    query_name: &Identifier<N>,
+    consensus_fee_version: ConsensusFeeVersion,
+) -> Result<u64> {
+    let query = stack.program().get_query_ref(query_name)?;
+
+    // Query types are not cached on the stack today; recompute them here for the cost walk.
+    let query_types = FinalizeTypes::from_query(stack, query)?;
+
+    let mut query_cost = 0u64;
+    for command in query.commands() {
+        query_cost = query_cost
+            .checked_add(cost_per_command(stack, &query_types, command, consensus_fee_version)?)
+            .ok_or(anyhow!("Query cost overflowed"))?;
+    }
+    Ok(query_cost)
+}
+
 /// Returns the total finalize cost for an execution by iterating over all concrete transitions.
 /// This gives an exact cost calculation because we know which functions were actually called.
 /// The complexity is O(MAX_TRANSITIONS * MAX_COMMANDS_PER_FINALIZE) which is bounded.

synthesizer/process/src/finalize.rs

@@ -15,7 +15,7 @@
 
 use super::*;
 use console::program::{FinalizeType, Future, Register};
-use snarkvm_synthesizer_program::{Await, FinalizeRegistersState, Operand, RegistersTrait};
+use snarkvm_synthesizer_program::{Await, FinalizeRegistersState, FinalizeStoreTrait, Operand, RegistersTrait};
 use snarkvm_utilities::try_vm_runtime;
 
 use std::collections::HashSet;
@@ -332,7 +332,8 @@ fn finalize_constructor<N: Network, P: FinalizeStorage<N>>(
     let constructor_types = stack.get_constructor_types()?.clone();
 
     // Initialize the finalize registers.
-    let mut registers = FinalizeRegisters::new(state, transition_id, *program_id.name(), constructor_types, nonce);
+    let mut registers =
+        FinalizeRegisters::new(state, Some(transition_id), *program_id.name(), constructor_types, Some(nonce));
 
     // Determine the scope name.
     let scope_name = Identifier::<N>::from_str("constructor")?;
@@ -447,8 +448,13 @@ fn finalize_transition<N: Network, P: FinalizeStorage<N>>(
                     // Otherwise, query the call graph for the child transition ID corresponding to the future that is being awaited.
                     let consensus_version = N::CONSENSUS_VERSION(state.block_height())?;
                     let transition_id = if (ConsensusVersion::V1..=ConsensusVersion::V2).contains(&consensus_version) {
-                        // Get the current transition ID.
-                        let transition_id = registers.transition_id();
+                        // Get the current transition ID. The finalize path always initializes
+                        // registers with `Some(transition_id)`; only the query path uses `None`,
+                        // and `await` is forbidden on the query path, so this is unreachable
+                        // there. Treat `None` as a logic error.
+                        let transition_id = registers
+                            .transition_id()
+                            .ok_or_else(|| anyhow!("Cannot resolve a child transition ID without a transition ID"))?;
                         // Get the child transition ID.
                         match call_graph.get(transition_id) {
                             Some(transitions) => match transitions.get(call_counter) {
@@ -570,10 +576,10 @@ fn initialize_finalize_state<N: Network>(
     // Initialize the registers.
     let mut registers = FinalizeRegisters::new(
         state,
-        transition_id,
+        Some(transition_id),
         *future.function_name(),
         stack.get_finalize_types(future.function_name())?.clone(),
-        nonce,
+        Some(nonce),
     );
 
     // Store the inputs. The argument count is guaranteed to match the finalize's declared inputs
@@ -589,9 +595,12 @@ fn initialize_finalize_state<N: Network>(
 }
 
 // A helper function to finalize all commands except `await`, updating the finalize operations and the counter.
+//
+// Generic over the store so the query evaluator (which passes either the canonical
+// `FinalizeStore` or a read-only historic adapter) can reuse this dispatch.
 #[inline]
-fn finalize_command_except_await<N: Network>(
-    store: &FinalizeStore<N, impl FinalizeStorage<N>>,
+pub(crate) fn finalize_command_except_await<N: Network>(
+    store: &impl FinalizeStoreTrait<N>,
     stack: &impl StackTrait<N>,
     registers: &mut FinalizeRegisters<N>,
     positions: &HashMap<Identifier<N>, usize>,

synthesizer/process/src/lib.rs

@@ -36,6 +36,10 @@ mod deploy;
 mod evaluate;
 mod execute;
 mod finalize;
+#[cfg(feature = "history")]
+mod query;
+#[cfg(feature = "history")]
+pub use query::evaluate_query_at_height;
 mod verify_deployment;
 mod verify_execution;
 mod verify_fee;