Skip to main content

spacedb_query/
runtime.rs

1//! The deterministic, sandboxed WASM runtime that runs a function next to the data.
2//!
3//! Two rules make a result corroboratable:
4//!
5//! 1. **No ambient nondeterminism.** The module gets **no WASI** — no clock,
6//!    randomness, network, or filesystem. Its only input is the bytes we hand it;
7//!    its only output is the bytes it returns. So `f(input)` is pure: same module
8//!    + input ⇒ same output, fuel, and peak memory on any host.
9//! 2. **Bounded by fuel + memory, never by the wall clock.** Fuel is a
10//!    deterministic instruction count, so every honest host either completes
11//!    within the same budget or traps at the same point. A wall-clock timeout
12//!    would make *completion itself* device-dependent and break corroboration.
13//!
14//! ## The function ABI (host ⇄ guest)
15//!
16//! A function module exports:
17//! - `memory` — its linear memory,
18//! - `alloc(len: i32) -> i32` — a guest allocator returning a writable offset,
19//! - `run(in_ptr: i32, in_len: i32) -> i64` — the entry point; the `i64` packs the
20//!   output slice as `(out_ptr as u32) << 32 | (out_len as u32)`.
21//!
22//! No host imports are required — which is exactly what keeps a function
23//! deterministic and safe to run on a volunteer device.
24
25use std::collections::HashMap;
26use std::sync::Mutex;
27
28use wasmtime::{
29    Config, Engine, Instance, Linker, Module, Store, StoreLimits, StoreLimitsBuilder, TypedFunc,
30};
31
32use crate::corroborate::FunctionRun;
33use crate::error::{QueryError, QueryResult};
34use crate::functions::CtxHostState;
35
36/// Per-invocation bounds. Both are **deterministic** — fuel is an instruction
37/// count; the memory cap is in whole MB — so they bound execution identically on
38/// every host.
39#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40pub struct RunLimits {
41    pub max_fuel: u64,
42    pub max_mem_mb: u32,
43}
44
45impl Default for RunLimits {
46    fn default() -> Self {
47        Self {
48            max_fuel: 100_000_000,
49            max_mem_mb: 64,
50        }
51    }
52}
53
54/// One execution: the answer the function produced, and the attestation proving it.
55#[derive(Clone, Debug)]
56pub struct Execution {
57    /// The output bytes — the answer that travels back.
58    pub output: Vec<u8>,
59    /// The deterministic, content-addressed attestation.
60    pub run: FunctionRun,
61}
62
63/// Store data — holds the memory limiter the engine consults on every
64/// `memory.grow`.
65struct HostState {
66    limits: StoreLimits,
67}
68
69/// How many compiled modules a runtime keeps. A query touches two (map and
70/// reduce) and a node serves a handful of deployed functions; past this the
71/// cache is simply cleared, so it can never grow without bound.
72const MODULE_CACHE_CAP: usize = 64;
73
74/// A reusable compute-to-data engine. Construct once per host; [`run`](Self::run)
75/// is stateless apart from a compile cache keyed by the workload hash.
76pub struct FunctionRuntime {
77    engine: Engine,
78    /// Compiled modules by BLAKE3 of their bytes — the workload identity every
79    /// run already computes. A map-reduce runs the same two modules once per
80    /// shard and once per reduce step; compiling them each time was the whole
81    /// cost of the query (cranelift dwarfs the guest's work). `Module` is a
82    /// cheap `Arc` handle, and compilation is a pure function of the bytes and
83    /// the engine config, so a cached module is indistinguishable from a fresh one.
84    modules: Mutex<HashMap<[u8; 32], Module>>,
85    /// The Database-Function linker (`spacedb::host_call`), built once: it
86    /// depends only on the engine, and a run instantiates from it.
87    ctx_linker: Linker<CtxHostState>,
88}
89
90impl FunctionRuntime {
91    /// The shared wasmtime engine (fuel-metered, backtrace-free) — reused by the
92    /// Database-Function path in [`crate::functions`].
93    pub(crate) fn engine(&self) -> &Engine {
94        &self.engine
95    }
96
97    /// Construct the runtime. Fails as [`QueryError::Engine`] if wasmtime rejects
98    /// the configuration on this host — a consumer gets an error to handle, not a
99    /// panic.
100    pub fn new() -> QueryResult<Self> {
101        let mut config = Config::new();
102        config.consume_fuel(true);
103        // We only need traps as recoverable errors, not stack traces. Capturing a
104        // wasm backtrace on trap walks native frames, which aborts on Windows with
105        // this slim feature set — and a determinism-bound runtime has no use for it.
106        config.wasm_backtrace(false);
107        let engine = Engine::new(&config).map_err(|e| QueryError::Engine(e.to_string()))?;
108        let ctx_linker = crate::functions::ctx_linker(&engine)?;
109        Ok(Self {
110            engine,
111            modules: Mutex::new(HashMap::new()),
112            ctx_linker,
113        })
114    }
115
116    /// The linker every Database Function instantiates from.
117    pub(crate) fn ctx_linker(&self) -> &Linker<CtxHostState> {
118        &self.ctx_linker
119    }
120
121    /// The compiled module for `module_wasm`, whose hash is `workload_hash`.
122    pub(crate) fn module(
123        &self,
124        workload_hash: &[u8; 32],
125        module_wasm: &[u8],
126    ) -> QueryResult<Module> {
127        let mut modules = self.modules.lock().unwrap_or_else(|p| p.into_inner());
128        if let Some(module) = modules.get(workload_hash) {
129            return Ok(module.clone());
130        }
131        let module = Module::new(&self.engine, module_wasm)
132            .map_err(|e| QueryError::Compile(e.to_string()))?;
133        if modules.len() >= MODULE_CACHE_CAP {
134            modules.clear();
135        }
136        modules.insert(*workload_hash, module.clone());
137        Ok(module)
138    }
139
140    /// Run `module_wasm`'s `run` entry over `input` under `limits`, returning the
141    /// output and its verifiable [`FunctionRun`]. `module_wasm` is the deployed
142    /// `.wasm` (hashed as the workload identity).
143    pub fn run(
144        &self,
145        module_wasm: &[u8],
146        input: &[u8],
147        limits: &RunLimits,
148    ) -> QueryResult<Execution> {
149        self.run_prehashed(&hash(module_wasm), module_wasm, input, None, limits)
150    }
151
152    /// [`run`](Self::run) with the module's hash already known (a planner hashes
153    /// each module once per query, not once per shard) and, when the caller has
154    /// it, the input's digest too (a pinned snapshot carries its own). The
155    /// attestation is identical: these are the same values `run` computes.
156    pub fn run_prehashed(
157        &self,
158        workload_hash: &[u8; 32],
159        module_wasm: &[u8],
160        input: &[u8],
161        input_digest: Option<[u8; 32]>,
162        limits: &RunLimits,
163    ) -> QueryResult<Execution> {
164        let workload_hash = *workload_hash;
165        let input_digest = input_digest.unwrap_or_else(|| hash(input));
166
167        let module = self.module(&workload_hash, module_wasm)?;
168
169        let max_bytes = limits.max_mem_mb as usize * 1024 * 1024;
170        let mut store = Store::new(
171            &self.engine,
172            HostState {
173                limits: StoreLimitsBuilder::new().memory_size(max_bytes).build(),
174            },
175        );
176        store.limiter(|h| &mut h.limits);
177        store
178            .set_fuel(limits.max_fuel)
179            .map_err(|e| QueryError::Fuel(e.to_string()))?;
180
181        let instance = Instance::new(&mut store, &module, &[])
182            .map_err(|e| QueryError::Instantiate(e.to_string()))?;
183
184        let memory = instance
185            .get_memory(&mut store, "memory")
186            .ok_or(QueryError::MissingExport("memory"))?;
187        let alloc: TypedFunc<i32, i32> = instance
188            .get_typed_func(&mut store, "alloc")
189            .map_err(|_| QueryError::MissingExport("alloc"))?;
190        let run: TypedFunc<(i32, i32), i64> = instance
191            .get_typed_func(&mut store, "run")
192            .map_err(|_| QueryError::MissingExport("run"))?;
193
194        // alloc + write the input
195        let in_len =
196            i32::try_from(input.len()).map_err(|_| QueryError::Abi("input too large".into()))?;
197        let in_ptr = alloc
198            .call(&mut store, in_len)
199            .map_err(|e| QueryError::Trap(e.to_string()))?;
200        memory
201            .write(&mut store, in_ptr as usize, input)
202            .map_err(|e| QueryError::Abi(format!("input write: {e}")))?;
203
204        // run, then read the returned (out_ptr, out_len) slice
205        let packed = run
206            .call(&mut store, (in_ptr, in_len))
207            .map_err(|e| QueryError::Trap(e.to_string()))?;
208        let packed = packed as u64;
209        let out_ptr = (packed >> 32) as usize;
210        let out_len = (packed & 0xFFFF_FFFF) as usize;
211        let output = crate::functions::read_output(memory.data(&store), out_ptr, out_len)?;
212        let output_digest = hash(&output);
213
214        // fuel consumed = budget − remaining; peak ≈ final size (functions don't
215        // shrink memory within a single run)
216        let remaining = store.get_fuel().map_err(|e| QueryError::Fuel(e.to_string()))?;
217        let fuel_used = limits.max_fuel.saturating_sub(remaining);
218        let mem_peak_mb = (memory.data_size(&store) / (1024 * 1024)) as u32;
219
220        Ok(Execution {
221            output,
222            run: FunctionRun {
223                workload_hash,
224                input_digest,
225                output_digest,
226                fuel_used,
227                mem_peak_mb,
228            },
229        })
230    }
231}
232
233fn hash(bytes: &[u8]) -> [u8; 32] {
234    *blake3::hash(bytes).as_bytes()
235}