Implement support for optional fuel metering

crates/core/src/trap.rs

@@ -277,6 +277,13 @@ pub enum TrapCode {
     /// with an index that points to a function with signature different of what is
     /// expected by this indirect call, this trap is raised.
     BadSignature,
+
+    /// This trap is raised when a WebAssembly execution ran out of fuel.
+    ///
+    /// The `wasmi` execution engine can be configured to instrument its
+    /// internal bytecode so that fuel is consumed for each executed instruction.
+    /// This is useful to deterministically halt or yield a WebAssembly execution.
+    OutOfFuel,
 }
 
 impl TrapCode {
@@ -297,6 +304,7 @@ impl TrapCode {
             Self::BadConversionToInteger => "invalid conversion to integer",
             Self::StackOverflow => "call stack exhausted",
             Self::BadSignature => "indirect call type mismatch",
+            Self::OutOfFuel => "all fuel consumed by WebAssembly",
         }
     }
 }

crates/wasi/src/snapshots/preview_1.rs

@@ -43,7 +43,7 @@ macro_rules! impl_add_to_linker_for_funcs {
             fn $fname:ident ($( $arg:ident : $typ:ty ),* $(,)? ) -> $ret:tt
         );+ $(;)?
     ) => {
-        fn add_wasi_snapshot_to_wasmi_linker<'a, T, U>(
+        fn add_wasi_snapshot_to_wasmi_linker<T, U>(
             linker: &mut Linker<T>,
             mut store_ctx: impl AsContextMut<UserState = T>,
             wasi_ctx: impl Fn(&mut T) -> &mut U + Send + Sync + Copy + 'static)

crates/wasmi/src/engine/bytecode/mod.rs

@@ -48,6 +48,9 @@ pub enum Instruction {
         len_targets: usize,
     },
     Unreachable,
+    ConsumeFuel {
+        amount: u64,
+    },
     Return(DropKeep),
     ReturnIfNez(DropKeep),
     Call(FuncIdx),
@@ -279,4 +282,28 @@ impl Instruction {
             local_depth: LocalDepth::from(local_depth),
         }
     }
+
+    /// Convenience method to create a new `ConsumeFuel` instruction.
+    pub fn consume_fuel(amount: u64) -> Self {
+        Self::ConsumeFuel { amount }
+    }
+
+    /// Increases the fuel consumption of the [`ConsumeFuel`] instruction by `delta`.
+    ///
+    /// # Panics
+    ///
+    /// - If `self` is not a [`ConsumeFuel`] instruction.
+    /// - If the new fuel consumption overflows the internal `u64` value.
+    ///
+    /// [`ConsumeFuel`]: Instruction::ConsumeFuel
+    pub fn bump_fuel_consumption(&mut self, delta: u64) {
+        match self {
+            Self::ConsumeFuel { amount } => {
+                *amount = amount.checked_add(delta).unwrap_or_else(|| {
+                    panic!("overflowed fuel consumption. current = {amount}, delta = {delta}",)
+                })
+            }
+            instr => panic!("expected Instruction::ConsumeFuel but found: {instr:?}"),
+        }
+    }
 }

crates/wasmi/src/engine/bytecode/utils.rs

@@ -1,4 +1,4 @@
-use crate::engine::Instr;
+use crate::engine::{config::FuelCosts, Instr};
 use core::fmt::Display;
 
 /// Defines how many stack values are going to be dropped and kept after branching.
@@ -62,6 +62,15 @@ impl DropKeep {
     pub fn keep(self) -> usize {
         self.keep as usize
     }
+
+    /// Returns the fuel consumption required for this [`DropKeep`].
+    pub fn fuel_consumption(self, costs: &FuelCosts) -> u64 {
+        if self.drop == 0 {
+            // If nothing is dropped no copy is required.
+            return 0;
+        }
+        u64::from(self.keep) * costs.branch_per_kept
+    }
 }
 
 /// A function index.

crates/wasmi/src/engine/cache.rs

@@ -1,3 +1,4 @@
+use super::bytecode::{DataSegmentIdx, ElementSegmentIdx, TableIdx};
 use crate::{
     instance::InstanceEntity,
     memory::DataSegment,
@@ -14,8 +15,6 @@ use crate::{
 use core::ptr::NonNull;
 use wasmi_core::UntypedValue;
 
-use super::bytecode::{DataSegmentIdx, ElementSegmentIdx, TableIdx};
-
 /// A cache for frequently used entities of an [`Instance`].
 #[derive(Debug)]
 pub struct InstanceCache {

crates/wasmi/src/engine/config.rs

@@ -27,6 +27,60 @@ pub struct Config {
     reference_types: bool,
     /// Is `true` if Wasm instructions on `f32` and `f64` types are allowed.
     floats: bool,
+    /// Is `true` if `wasmi` executions shall consume fuel.
+    consume_fuel: bool,
+    /// The configured fuel costs of all `wasmi` bytecode instructions.
+    fuel_costs: FuelCosts,
+}
+
+/// Type storing all kinds of fuel costs of instructions.
+#[derive(Debug, Copy, Clone)]
+pub struct FuelCosts {
+    /// The base fuel costs for all instructions.
+    pub base: u64,
+    /// The fuel cost for instruction operating on Wasm entities.
+    ///
+    /// # Note
+    ///
+    /// A Wasm entitiy is one of `func`, `global`, `memory` or `table`.
+    /// Those instructions are usually a bit more costly since they need
+    /// multiplie indirect accesses through the Wasm instance and store.
+    pub entity: u64,
+    /// The fuel cost offset for `memory.load` instructions.
+    pub load: u64,
+    /// The fuel cost offset for `memory.store` instructions.
+    pub store: u64,
+    /// The fuel cost offset for `call` and `call_indirect` instructions.
+    pub call: u64,
+    /// The fuel cost offset per local variable for `call` and `call_indirect` instruction.
+    ///
+    /// # Note
+    ///
+    /// This is also applied to all function parameters since
+    /// they are translated to local variable slots.
+    pub call_per_local: u64,
+    /// The fuel cost offset per kept value for branches that need to copy values on the stack.
+    pub branch_per_kept: u64,
+    /// The fuel cost offset per byte for `bulk-memory` instructions.
+    pub memory_per_byte: u64,
+    /// The fuel cost offset per element for `bulk-table` instructions.
+    pub table_per_element: u64,
+}
+
+impl Default for FuelCosts {
+    fn default() -> Self {
+        Self {
+            base: 100,
+            entity: 500,
+            load: 650,
+            store: 450,
+            call: 1500,
+            call_per_local: 10,
+            branch_per_kept: 10,
+            memory_per_byte: 2,
+            table_per_element: 10,
+        }
+    }
 }
 
 impl Default for Config {
@@ -41,6 +95,8 @@ impl Default for Config {
             bulk_memory: true,
             reference_types: true,
             floats: true,
+            consume_fuel: false,
+            fuel_costs: FuelCosts::default(),
         }
     }
 }
@@ -158,6 +214,40 @@ impl Config {
         self
     }
 
+    /// Configures whether `wasmi` will consume fuel during execution to either halt execution as desired.
+    ///
+    /// # Note
+    ///
+    /// This configuration can be used to make `wasmi` instrument its internal bytecode
+    /// so that it consumes fuel as it executes. Once an execution runs out of fuel
+    /// a [`TrapCode::OutOfFuel`](crate::core::TrapCode::OutOfFuel) trap is raised.
+    /// This way users can deterministically halt or yield the execution of WebAssembly code.
+    ///
+    /// - Use [`Store::add_fuel`](crate::Store::add_fuel) to pour some fuel into the [`Store`] before
+    ///   executing some code as the [`Store`] start with no fuel.
+    /// - Use [`Caller::consume_fuel`](crate::Caller::consume_fuel) to charge costs for executed host functions.
+    ///
+    /// Disabled by default.
+    ///
+    /// [`Store`]: crate::Store
+    /// [`Engine`]: crate::Engine
+    pub fn consume_fuel(&mut self, enable: bool) -> &mut Self {
+        self.consume_fuel = enable;
+        self
+    }
+
+    /// Returns `true` if the [`Config`] enables fuel consumption by the [`Engine`].
+    ///
+    /// [`Engine`]: crate::Engine
+    pub(crate) fn get_consume_fuel(&self) -> bool {
+        self.consume_fuel
+    }
+
+    /// Returns the configured [`FuelCosts`].
+    pub(crate) fn fuel_costs(&self) -> &FuelCosts {
+        &self.fuel_costs
+    }
+
     /// Returns the [`WasmFeatures`] represented by the [`Config`].
     pub fn wasm_features(&self) -> WasmFeatures {
         WasmFeatures {