diff --git a/.gitignore b/.gitignore index 357bddc..e43a15c 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,4 @@ Thumbs.db # Environment .env .env.* +data/ diff --git a/crates/nexum-engine/Cargo.toml b/crates/nexum-engine/Cargo.toml index 65768c3..f8f0914 100644 --- a/crates/nexum-engine/Cargo.toml +++ b/crates/nexum-engine/Cargo.toml @@ -6,10 +6,59 @@ license.workspace = true repository.workspace = true [dependencies] +# WASM Component Model runtime. wasmtime = { version = "45", features = ["component-model"] } wasmtime-wasi = "45" + +# Async + error plumbing. anyhow = "1" +thiserror = "2" tokio = { version = "1", features = ["full"] } -getrandom = "0.4" + +# Manifest parsing. serde = { version = "1", features = ["derive"] } toml = "1" +serde_json = "1" + +# Observability. `tracing` replaces the prior `eprintln!` debug log +# so the engine can drop into a structured log pipeline in production. +tracing = "0.1" +tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "env-filter", "ansi"] } + +# `cow-api` backend. cowprotocol pulls `OrderBookApi`, `OrderCreation`, +# `OrderUid`, the orderbook base URL table per `Chain`, and the typed +# error surface the host re-projects into `HostError`. +# +# This is the canonical `cowprotocol` crate from `cowdao-grants/cow-rs` +# (homepage / repository fields on crates.io point there). The workspace +# `[patch.crates-io]` redirects it to the head of cow-rs PR #5 per +# ADR-0004; see the comment there for the bump policy. Pinned to the +# 1.0.0-alpha line — the published release Shepherd ships against. +cowprotocol = "1.0.0-alpha" +# REST passthrough for `cow_api::request`. cowprotocol pulls reqwest +# transitively for its own client; we depend on it directly so the +# import is explicit and survives any future cowprotocol feature +# rearrangement. +reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] } + +# `chain` backend. Each configured chain owns a `DynProvider` built +# from a `WsConnect`/`Http` transport so the host's `request` / +# `request-batch` impls can hand a raw `(method, params)` pair to +# alloy's JSON-RPC layer without reimplementing the codec. +alloy-provider = { version = "1.8", default-features = false, features = ["ws", "ipc", "pubsub", "reqwest"] } +alloy-rpc-client = { version = "1.8", default-features = false } +alloy-transport = { version = "1.8", default-features = false } +alloy-transport-ws = { version = "1.8", default-features = false } +alloy-primitives = { version = "1.6", default-features = false, features = ["std", "serde"] } + +# `local-store` backend. Per-module namespacing is enforced +# host-side via a `[len:u8][module_name][raw_key]` prefix. +redb = "2" + +# Misc. +getrandom = "0.4" +url = "2" + +[dev-dependencies] +tempfile = "3" +wiremock = "0.6" diff --git a/crates/nexum-engine/src/bindings.rs b/crates/nexum-engine/src/bindings.rs new file mode 100644 index 0000000..d0f57dd --- /dev/null +++ b/crates/nexum-engine/src/bindings.rs @@ -0,0 +1,16 @@ +//! WIT bindings generated by `wasmtime::component::bindgen!`. +//! +//! Both `wit/nexum-host` and `wit/shepherd-cow` packages are listed +//! explicitly so wit-parser can resolve the cross-package reference +//! natively - no vendored `deps/` tree needed. The world name is fully +//! qualified. +//! +//! Every `Host` trait impl in [`crate::host::impls`] consumes types +//! generated here. + +wasmtime::component::bindgen!({ + path: ["../../wit/nexum-host", "../../wit/shepherd-cow"], + world: "shepherd:cow/shepherd", + imports: { default: async }, + exports: { default: async }, +}); diff --git a/crates/nexum-engine/src/engine_config.rs b/crates/nexum-engine/src/engine_config.rs new file mode 100644 index 0000000..7629af4 --- /dev/null +++ b/crates/nexum-engine/src/engine_config.rs @@ -0,0 +1,155 @@ +//! Engine-side runtime configuration. +//! +//! Distinct from `module.toml` (module manifest): this file describes +//! the *engine*'s I/O wiring - chain RPC endpoints and the on-disk +//! location of the `local-store` database. Both are required for the +//! 0.2 reference engine to do anything other than print stubs. +//! +//! Lookup order: +//! +//! 1. `--engine-config ` CLI flag (future), or third positional +//! argument today; +//! 2. `engine.toml` in the current working directory; +//! 3. defaults - no chains configured, `state_dir = ./data`. +//! +//! A missing config is OK for the example module (it only logs); for +//! the cow-api / chain backends it surfaces as `HostError { +//! kind: unsupported }` so guests learn early. + +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; + +use serde::Deserialize; +use tracing::{info, warn}; + +/// Engine-side configuration loaded from `engine.toml`. +#[derive(Debug, Default, Deserialize)] +pub struct EngineConfig { + #[serde(default)] + pub engine: EngineSection, + /// Per-chain RPC URLs keyed by EVM chain id (decimal in TOML). + /// Used by the `chain::request` host call and as the alloy provider + /// pool seed. + #[serde(default)] + pub chains: BTreeMap, +} + +#[derive(Debug, Deserialize)] +pub struct EngineSection { + #[serde(default = "default_state_dir")] + pub state_dir: PathBuf, + /// `tracing_subscriber::EnvFilter`-compatible directive. Defaults to + /// `info` when absent; `RUST_LOG` overrides at process start. + #[serde(default = "default_log_level")] + pub log_level: String, + /// Resource caps applied to every module store at instantiation. + /// `wasmtime` traps a module that overruns either; the operator + /// tunes the budget based on their hardware and the modules they + /// load. + #[serde(default)] + pub limits: ModuleLimits, +} + +impl Default for EngineSection { + fn default() -> Self { + Self { + state_dir: default_state_dir(), + log_level: default_log_level(), + limits: ModuleLimits::default(), + } + } +} + +/// Per-module resource caps the supervisor applies to each store. +/// +/// `wasmtime` exposes two complementary knobs: +/// +/// - **Fuel** is decremented per executed instruction (`Config::consume_fuel +/// (true)`). When the store runs out, the module traps with `OutOfFuel`. +/// The budget is reset before every `on_event` invocation so a single +/// greedy event cannot starve the next one. +/// - **Memory size** caps the module's linear memory growth, applied via +/// `StoreLimitsBuilder::memory_size`. A module that requests more linear +/// memory than this gets a `MemoryOutOfBounds`-class trap from +/// `memory.grow`. +/// +/// Both are `Option` so an unset value falls through to the engine's +/// built-in defaults; operators only need to write the keys they actually +/// want to override. `main.rs` reads these at instantiation; the multi- +/// module supervisor (BLEU-818) consumes the same accessors per module +/// store. +#[derive(Clone, Copy, Debug, Default, Deserialize)] +pub struct ModuleLimits { + /// Fuel granted before every `on_event` call. `None` -> engine default. + #[serde(default)] + pub fuel_per_event: Option, + /// Linear-memory ceiling per module (bytes). `None` -> engine default. + #[serde(default)] + pub memory_bytes: Option, +} + +impl ModuleLimits { + /// Default fuel granted per `on_event` invocation (≈ 1 billion WASM + /// instructions). Modules that exceed this budget trap with + /// `OutOfFuel`. + pub const DEFAULT_FUEL_PER_EVENT: u64 = 1_000_000_000; + + /// Default linear-memory cap per module (64 MiB). Prevents a single + /// runaway module from exhausting process memory. + pub const DEFAULT_MEMORY_BYTES: u64 = 64 * 1024 * 1024; + + /// Resolved fuel budget (config override, falling back to the default). + pub fn fuel(&self) -> u64 { + self.fuel_per_event.unwrap_or(Self::DEFAULT_FUEL_PER_EVENT) + } + + /// Resolved memory cap in bytes (config override, falling back to the + /// default). + pub fn memory(&self) -> u64 { + self.memory_bytes.unwrap_or(Self::DEFAULT_MEMORY_BYTES) + } +} + +#[derive(Debug, Deserialize)] +pub struct ChainConfig { + /// JSON-RPC endpoint. `ws://` and `wss://` engage alloy's pubsub + /// transport (required for `eth_subscribe`); `http://` and `https://` + /// engage the HTTP transport (request/response only). + pub rpc_url: String, +} + +fn default_state_dir() -> PathBuf { + PathBuf::from("./data") +} + +fn default_log_level() -> String { + "info".to_owned() +} + +/// Read an engine config from disk, returning defaults if the file is +/// missing. Parse errors propagate. +pub fn load_or_default(path: Option<&Path>) -> anyhow::Result { + let path = match path { + Some(p) => p.to_path_buf(), + None => PathBuf::from("engine.toml"), + }; + + if !path.exists() { + warn!( + path = %path.display(), + "engine.toml not found - running with defaults (no chain RPC endpoints; \ + chain::request and cow_api::submit_order will return Unsupported)" + ); + return Ok(EngineConfig::default()); + } + + let raw = std::fs::read_to_string(&path)?; + let cfg: EngineConfig = toml::from_str(&raw)?; + info!( + path = %path.display(), + chains = cfg.chains.len(), + state_dir = %cfg.engine.state_dir.display(), + "engine config loaded", + ); + Ok(cfg) +} diff --git a/crates/nexum-engine/src/host/cow_orderbook.rs b/crates/nexum-engine/src/host/cow_orderbook.rs new file mode 100644 index 0000000..49c1945 --- /dev/null +++ b/crates/nexum-engine/src/host/cow_orderbook.rs @@ -0,0 +1,141 @@ +//! `shepherd:cow/cow-api` backend. +//! +//! Two responsibilities: +//! +//! 1. `request` - generic REST passthrough. Module gives the HTTP +//! method, path (relative to the chain's orderbook base URL), and +//! optional JSON body. We dispatch via `reqwest`, return the +//! response body verbatim. +//! 2. `submit_order` - typed submission. Module gives a JSON-encoded +//! `cowprotocol::OrderCreation`; we parse, dispatch via +//! `cowprotocol::OrderBookApi::post_order`, return the assigned +//! `OrderUid` as a `0x`-prefixed hex string. +//! +//! Per-chain `OrderBookApi` instances are constructed once at engine +//! boot from the discriminated chain set in `cowprotocol::Chain`. +//! Chains the SDK does not know about return `Unsupported` at the +//! host call boundary. + +use std::collections::BTreeMap; + +use cowprotocol::{Chain, OrderBookApi, OrderCreation, OrderUid}; +use thiserror::Error; + +/// Process-wide pool of `OrderBookApi` clients keyed by EVM chain id. +#[derive(Debug, Clone)] +pub struct OrderBookPool { + clients: BTreeMap, + http: reqwest::Client, +} + +impl Default for OrderBookPool { + /// Build a pool covering every `cowprotocol::Chain` variant. Each entry + /// uses the canonical `api.cow.fi/{slug}/api/v1` base URL from the SDK. + /// Override individual entries via `OrderBookApi::new_with_base_url` for + /// barn or staging targets. + fn default() -> Self { + let http = reqwest::Client::new(); + let chains = [ + Chain::Mainnet, + Chain::Gnosis, + Chain::Sepolia, + Chain::ArbitrumOne, + Chain::Base, + ]; + let clients = chains + .iter() + .map(|c| (c.id(), OrderBookApi::new(*c))) + .collect(); + Self { clients, http } + } +} + +impl OrderBookPool { + /// Look up the client for a chain. + pub fn get(&self, chain_id: u64) -> Result<&OrderBookApi, CowApiError> { + self.clients + .get(&chain_id) + .ok_or(CowApiError::UnknownChain(chain_id)) + } + + /// REST passthrough. The base URL is whichever URL the pool's + /// `OrderBookApi` client carries - overrides set via + /// `OrderBookApi::new_with_base_url` (staging, wiremock) flow + /// through here too, which keeps the passthrough and the typed + /// `submit_order_json` path aimed at the same orderbook. + pub async fn request( + &self, + chain_id: u64, + method: &str, + path: &str, + body: Option<&str>, + ) -> Result { + let api = self.get(chain_id)?; + let base = api.base_url().clone(); + // `path` may or may not lead with a slash; `Url::join` handles + // both, but we strip a single leading `/` so consumers can + // write either `/orders/...` or `orders/...` interchangeably. + let trimmed = path.strip_prefix('/').unwrap_or(path); + let url = base + .join(trimmed) + .map_err(|e| CowApiError::BadPath(format!("{path:?}: {e}")))?; + + let request = match method.to_ascii_uppercase().as_str() { + "GET" => self.http.get(url), + "POST" => self.http.post(url), + "PUT" => self.http.put(url), + "DELETE" => self.http.delete(url), + other => return Err(CowApiError::BadMethod(other.to_owned())), + }; + let request = if let Some(body) = body { + request + .header(reqwest::header::CONTENT_TYPE, "application/json") + .body(body.to_owned()) + } else { + request + }; + + let response = request.send().await.map_err(CowApiError::Network)?; + // Surface the orderbook's structured 4xx / 5xx bodies verbatim + // so the guest can decode `{"errorType": "...", "description": + // "..."}` - projecting them into HostError here loses the + // detail the guest needs to recover. + let text = response.text().await.map_err(CowApiError::Network)?; + Ok(text) + } + + /// Typed submission. `body` is the JSON encoding of + /// `cowprotocol::OrderCreation`. The chain's orderbook validates + /// `from`, the EIP-712 hash, and (if `Eip1271`) the contract + /// signature; we return whatever UID it assigns. + pub async fn submit_order_json( + &self, + chain_id: u64, + body: &[u8], + ) -> Result { + let creation: OrderCreation = serde_json::from_slice(body).map_err(CowApiError::Decode)?; + let api = self.get(chain_id)?; + let uid = api.post_order(&creation).await?; + Ok(uid) + } +} + +#[derive(Debug, Error)] +pub enum CowApiError { + #[error("unknown chain {0} (no cowprotocol::Chain variant)")] + UnknownChain(u64), + #[error("bad HTTP method `{0}` (expected GET/POST/PUT/DELETE)")] + BadMethod(String), + #[error("invalid path: {0}")] + BadPath(String), + #[error("network: {0}")] + Network(#[from] reqwest::Error), + #[error("decode OrderCreation JSON: {0}")] + Decode(#[from] serde_json::Error), + #[error("orderbook: {0}")] + Orderbook(#[from] cowprotocol::Error), +} + + +#[cfg(test)] +mod tests; diff --git a/crates/nexum-engine/src/host/cow_orderbook/tests.rs b/crates/nexum-engine/src/host/cow_orderbook/tests.rs new file mode 100644 index 0000000..214e709 --- /dev/null +++ b/crates/nexum-engine/src/host/cow_orderbook/tests.rs @@ -0,0 +1,152 @@ +use super::*; +use wiremock::matchers::{method, path}; +use wiremock::{Mock, MockServer, ResponseTemplate}; + +#[test] +fn pool_indexes_default_chains() { + let pool = OrderBookPool::default(); + assert!(pool.get(1).is_ok(), "mainnet present"); + assert!(pool.get(100).is_ok(), "gnosis present"); + assert!(pool.get(11_155_111).is_ok(), "sepolia present"); + assert!(pool.get(42_161).is_ok(), "arbitrum present"); + assert!(pool.get(8_453).is_ok(), "base present"); +} + +#[test] +fn unknown_chain_surfaces_typed_error() { + let pool = OrderBookPool::default(); + assert!(matches!( + pool.get(99_999), + Err(CowApiError::UnknownChain(99_999)) + )); +} + +/// Build a pool whose Mainnet entry points at `mock.uri()`. +/// `OrderBookApi::new_with_base_url` ships in cowprotocol; we +/// rely on it so wiremock-driven tests can exercise the full +/// request path without re-implementing the HTTP client. +fn pool_with_mainnet_at(mock: &MockServer) -> OrderBookPool { + let mut clients = std::collections::BTreeMap::new(); + clients.insert( + Chain::Mainnet.id(), + OrderBookApi::new_with_base_url(mock.uri().parse().expect("mock uri parses")), + ); + OrderBookPool { + clients, + http: reqwest::Client::new(), + } +} + +#[tokio::test] +async fn request_passes_get_path_through() { + let mock = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/api/v1/version")) + .respond_with(ResponseTemplate::new(200).set_body_string(r#"{"version":"x.y.z"}"#)) + .expect(1) + .mount(&mock) + .await; + + let pool = pool_with_mainnet_at(&mock); + let body = pool + .request(Chain::Mainnet.id(), "GET", "/api/v1/version", None) + .await + .expect("request succeeds"); + assert_eq!(body, r#"{"version":"x.y.z"}"#); +} + +#[tokio::test] +async fn request_relative_path_works() { + // Module passes a path without a leading slash. The + // passthrough should still resolve against the orderbook + // base URL. + let mock = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/api/v1/native_price/0xabc")) + .respond_with(ResponseTemplate::new(200).set_body_string("1.23")) + .expect(1) + .mount(&mock) + .await; + + let pool = pool_with_mainnet_at(&mock); + let body = pool + .request( + Chain::Mainnet.id(), + "GET", + "api/v1/native_price/0xabc", + None, + ) + .await + .expect("relative path resolves"); + assert_eq!(body, "1.23"); +} + +#[tokio::test] +async fn request_rejects_unknown_method() { + let pool = OrderBookPool::default(); + let err = pool + .request(Chain::Mainnet.id(), "PATCH", "/x", None) + .await + .unwrap_err(); + assert!(matches!(err, CowApiError::BadMethod(_))); +} + +#[tokio::test] +async fn submit_order_propagates_orderbook_response() { + let mock = MockServer::start().await; + let body_json = sample_order_json(); + // cowprotocol POST /api/v1/orders returns the order UID + // (56-byte hex) as a JSON string body. + let returned_uid = format!("\"0x{}\"", "ab".repeat(56)); + Mock::given(method("POST")) + .and(path("/api/v1/orders")) + .respond_with(ResponseTemplate::new(201).set_body_string(returned_uid.clone())) + .expect(1) + .mount(&mock) + .await; + + let pool = pool_with_mainnet_at(&mock); + let uid = pool + .submit_order_json(Chain::Mainnet.id(), body_json.as_bytes()) + .await + .expect("submit succeeds"); + assert_eq!(uid.as_slice().len(), 56); + assert_eq!(uid.as_slice(), &[0xab; 56]); +} + +/// A minimal but accepted-by-cowprotocol OrderCreation JSON. We +/// generate it inside the test so the JSON shape stays in lockstep +/// with the published `cowprotocol` version. +fn sample_order_json() -> String { + use alloy_primitives::{Address, U256}; + use cowprotocol::OrderCreation; + use cowprotocol::app_data::{EMPTY_APP_DATA_HASH, EMPTY_APP_DATA_JSON}; + use cowprotocol::order::{BuyTokenDestination, OrderData, OrderKind, SellTokenSource}; + use cowprotocol::signature::Signature; + use cowprotocol::signing_scheme::SigningScheme; + + let order_data = OrderData { + sell_token: Address::from([0x01; 20]), + buy_token: Address::from([0x02; 20]), + receiver: None, + sell_amount: U256::from(100u64), + buy_amount: U256::from(99u64), + valid_to: u32::MAX, + app_data: EMPTY_APP_DATA_HASH, + fee_amount: U256::ZERO, + kind: OrderKind::Sell, + partially_fillable: false, + sell_token_balance: SellTokenSource::Erc20, + buy_token_balance: BuyTokenDestination::Erc20, + }; + let signature = Signature::from_bytes(SigningScheme::PreSign, &[]).expect("presign empty"); + let creation = OrderCreation::from_signed_order_data( + &order_data, + signature, + Address::from([0x03; 20]), + EMPTY_APP_DATA_JSON.to_owned(), + None, + ) + .expect("valid OrderCreation"); + serde_json::to_string(&creation).expect("serialise OrderCreation") +} diff --git a/crates/nexum-engine/src/host/error.rs b/crates/nexum-engine/src/host/error.rs new file mode 100644 index 0000000..a11c7c4 --- /dev/null +++ b/crates/nexum-engine/src/host/error.rs @@ -0,0 +1,36 @@ +//! Small constructors that wrap the WIT `HostError` shape, used by +//! every `Host` trait impl, plus the lowercase hex encoder shared by +//! the `cow-api` submission path. + +use crate::bindings::HostError; +use crate::bindings::nexum::host::types::HostErrorKind; + +/// `Unsupported` (HTTP 501-style) error for capabilities the engine +/// reference build does not implement yet. +pub(crate) fn unimplemented(domain: &str, detail: impl Into) -> HostError { + HostError { + domain: domain.into(), + kind: HostErrorKind::Unsupported, + code: 501, + message: detail.into(), + data: None, + } +} + +/// `Internal` (HTTP 500-style) error for unexpected backend failures. +pub(crate) fn internal_error(domain: &str, detail: impl Into) -> HostError { + HostError { + domain: domain.into(), + kind: HostErrorKind::Internal, + code: 0, + message: detail.into(), + data: None, + } +} + +/// Lowercase hex encoder. Re-exports `alloy_primitives::hex::encode` +/// (already in the workspace dep graph for the chain backend) so the +/// engine does not roll its own per-byte `write!` loop. +pub(crate) fn hex_encode(bytes: &[u8]) -> String { + alloy_primitives::hex::encode(bytes) +} diff --git a/crates/nexum-engine/src/host/impls/chain.rs b/crates/nexum-engine/src/host/impls/chain.rs new file mode 100644 index 0000000..e0e30db --- /dev/null +++ b/crates/nexum-engine/src/host/impls/chain.rs @@ -0,0 +1,67 @@ +//! `nexum:host/chain`: raw JSON-RPC dispatch over alloy. + +use std::time::Instant; + +use crate::bindings::HostError; +use crate::bindings::nexum; +use crate::bindings::nexum::host::types::HostErrorKind; +use crate::host::error::internal_error; +use crate::host::provider_pool::ProviderError; +use crate::host::state::HostState; + +impl nexum::host::chain::Host for HostState { + async fn request( + &mut self, + chain_id: u64, + method: String, + params: String, + ) -> Result { + let start = Instant::now(); + tracing::debug!(chain_id, %method, "chain::request"); + let result = match self.chain.request(chain_id, method, params).await { + Ok(body) => Ok(body), + Err(ProviderError::UnknownChain(id)) => Err(HostError { + domain: "chain".into(), + kind: HostErrorKind::Unsupported, + code: 0, + message: format!("chain {id} has no engine.toml RPC entry"), + data: None, + }), + Err(ProviderError::InvalidParams { detail, .. }) => Err(HostError { + domain: "chain".into(), + kind: HostErrorKind::InvalidInput, + code: -32602, + message: detail, + data: None, + }), + Err(ProviderError::Rpc { detail, .. }) => Err(HostError { + domain: "chain".into(), + kind: HostErrorKind::Internal, + code: -32603, + message: detail, + data: None, + }), + Err(err) => Err(internal_error("chain", err.to_string())), + }; + tracing::trace!(elapsed_ms = ?start.elapsed(), "chain::request done"); + result + } + + async fn request_batch( + &mut self, + chain_id: u64, + requests: Vec, + ) -> Result, HostError> { + let start = Instant::now(); + tracing::debug!(chain_id, count = requests.len(), "chain::request-batch"); + let mut out = Vec::with_capacity(requests.len()); + for req in requests { + match nexum::host::chain::Host::request(self, chain_id, req.method, req.params).await { + Ok(s) => out.push(nexum::host::chain::RpcResult::Ok(s)), + Err(e) => out.push(nexum::host::chain::RpcResult::Err(e)), + } + } + tracing::trace!(elapsed_ms = ?start.elapsed(), "chain::request-batch done"); + Ok(out) + } +} diff --git a/crates/nexum-engine/src/host/impls/clock.rs b/crates/nexum-engine/src/host/impls/clock.rs new file mode 100644 index 0000000..f65b674 --- /dev/null +++ b/crates/nexum-engine/src/host/impls/clock.rs @@ -0,0 +1,19 @@ +//! `nexum:host/clock`: wall-clock + monotonic time. + +use std::time::{SystemTime, UNIX_EPOCH}; + +use crate::bindings::nexum; +use crate::host::state::HostState; + +impl nexum::host::clock::Host for HostState { + async fn now_ms(&mut self) -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_millis() as u64) + .unwrap_or(0) + } + + async fn monotonic_ns(&mut self) -> u64 { + self.monotonic_baseline.elapsed().as_nanos() as u64 + } +} diff --git a/crates/nexum-engine/src/host/impls/cow_api.rs b/crates/nexum-engine/src/host/impls/cow_api.rs new file mode 100644 index 0000000..b3b51d5 --- /dev/null +++ b/crates/nexum-engine/src/host/impls/cow_api.rs @@ -0,0 +1,85 @@ +//! `shepherd:cow/cow-api`: REST passthrough + typed `submit_order`. +//! Backend logic lives in [`crate::host::cow_orderbook`]; this is the +//! WIT-side error mapping. + +use std::time::Instant; + +use crate::bindings::nexum::host::types::HostErrorKind; +use crate::bindings::{HostError, shepherd}; +use crate::host::cow_orderbook::CowApiError; +use crate::host::error::{hex_encode, internal_error, unimplemented}; +use crate::host::state::HostState; + +impl shepherd::cow::cow_api::Host for HostState { + async fn request( + &mut self, + chain_id: u64, + method: String, + path: String, + body: Option, + ) -> Result { + let start = Instant::now(); + tracing::debug!(chain_id, %method, %path, "cow-api::request"); + let result = match self + .cow + .request(chain_id, &method, &path, body.as_deref()) + .await + { + Ok(body) => Ok(body), + Err(CowApiError::UnknownChain(id)) => Err(unimplemented( + "cow-api", + format!("chain {id} not in cowprotocol"), + )), + Err(CowApiError::BadMethod(m)) => Err(HostError { + domain: "cow-api".into(), + kind: HostErrorKind::InvalidInput, + code: 0, + message: format!("unsupported HTTP method: {m}"), + data: None, + }), + Err(CowApiError::BadPath(msg)) => Err(HostError { + domain: "cow-api".into(), + kind: HostErrorKind::InvalidInput, + code: 0, + message: msg, + data: None, + }), + Err(err) => Err(internal_error("cow-api", err.to_string())), + }; + tracing::trace!(elapsed_ms = ?start.elapsed(), "cow-api::request done"); + result + } + + async fn submit_order( + &mut self, + chain_id: u64, + order_data: Vec, + ) -> Result { + let start = Instant::now(); + tracing::debug!(chain_id, bytes = order_data.len(), "cow-api::submit-order"); + let result = match self.cow.submit_order_json(chain_id, &order_data).await { + Ok(uid) => Ok(format!("0x{}", hex_encode(uid.as_slice()))), + Err(CowApiError::UnknownChain(id)) => Err(unimplemented( + "cow-api", + format!("chain {id} not in cowprotocol"), + )), + Err(CowApiError::Decode(err)) => Err(HostError { + domain: "cow-api".into(), + kind: HostErrorKind::InvalidInput, + code: 0, + message: format!("invalid OrderCreation JSON: {err}"), + data: None, + }), + Err(CowApiError::Orderbook(err)) => Err(HostError { + domain: "cow-api".into(), + kind: HostErrorKind::Denied, + code: 0, + message: err.to_string(), + data: None, + }), + Err(err) => Err(internal_error("cow-api", err.to_string())), + }; + tracing::trace!(elapsed_ms = ?start.elapsed(), "cow-api::submit-order done"); + result + } +} diff --git a/crates/nexum-engine/src/host/impls/http.rs b/crates/nexum-engine/src/host/impls/http.rs new file mode 100644 index 0000000..2900d4d --- /dev/null +++ b/crates/nexum-engine/src/host/impls/http.rs @@ -0,0 +1,51 @@ +//! `nexum:host/http`: manifest allowlist check, then `Unsupported`. +//! +//! Real `fetch` lands in 0.3. The allowlist is enforced now so a +//! module that ships with an empty (or no) `[capabilities.http].allow` +//! gets denied loudly, matching the "no implicit network" stance. + +use tracing::warn; + +use crate::bindings::HostError; +use crate::bindings::nexum; +use crate::bindings::nexum::host::types::HostErrorKind; +use crate::host::error::unimplemented; +use crate::host::state::HostState; +use crate::manifest::{extract_host, host_allowed}; + +impl nexum::host::http::Host for HostState { + async fn fetch( + &mut self, + req: nexum::host::http::Request, + ) -> Result { + let host = match extract_host(&req.url) { + Some(h) => h, + None => { + return Err(HostError { + domain: "http".into(), + kind: HostErrorKind::InvalidInput, + code: 0, + message: format!("not an http(s) URL: {}", req.url), + data: None, + }); + } + }; + if !host_allowed(host, &self.http_allowlist) { + warn!(host, "[http] denied by allowlist"); + return Err(HostError { + domain: "http".into(), + kind: HostErrorKind::Denied, + code: 0, + message: format!( + "host {host} not in [capabilities.http].allow; \ + add it to module.toml to permit" + ), + data: None, + }); + } + Err(unimplemented( + "http", + "fetch not implemented in 0.2 reference runtime (allowlist passed)", + )) + } +} diff --git a/crates/nexum-engine/src/host/impls/identity.rs b/crates/nexum-engine/src/host/impls/identity.rs new file mode 100644 index 0000000..6a4a050 --- /dev/null +++ b/crates/nexum-engine/src/host/impls/identity.rs @@ -0,0 +1,29 @@ +//! `nexum:host/identity`: deferred to 0.3 (keystore / KMS backend). +//! `accounts()` returns an empty roster so guests can probe-then-skip; +//! signing returns `Unsupported`. + +use crate::bindings::HostError; +use crate::bindings::nexum; +use crate::host::error::unimplemented; +use crate::host::state::HostState; + +impl nexum::host::identity::Host for HostState { + async fn accounts(&mut self) -> Result>, HostError> { + Ok(vec![]) + } + + async fn sign(&mut self, _account: Vec, _message: Vec) -> Result, HostError> { + Err(unimplemented("identity", "sign requires a keystore (0.3)")) + } + + async fn sign_typed_data( + &mut self, + _account: Vec, + _typed_data: String, + ) -> Result, HostError> { + Err(unimplemented( + "identity", + "sign-typed-data requires a keystore (0.3)", + )) + } +} diff --git a/crates/nexum-engine/src/host/impls/local_store.rs b/crates/nexum-engine/src/host/impls/local_store.rs new file mode 100644 index 0000000..3bf74fe --- /dev/null +++ b/crates/nexum-engine/src/host/impls/local_store.rs @@ -0,0 +1,38 @@ +//! `nexum:host/local-store`: redb backend with host-side namespacing. +//! +//! The store handle in [`HostState`] is a [`ModuleStore`] — already +//! scoped to this module's keccak prefix. The impls below are +//! single-line forwards onto that handle. +//! +//! [`ModuleStore`]: crate::host::local_store_redb::ModuleStore + +use crate::bindings::HostError; +use crate::bindings::nexum; +use crate::host::error::internal_error; +use crate::host::state::HostState; + +impl nexum::host::local_store::Host for HostState { + async fn get(&mut self, key: String) -> Result>, HostError> { + self.store + .get(&key) + .map_err(|err| internal_error("local-store", err.to_string())) + } + + async fn set(&mut self, key: String, value: Vec) -> Result<(), HostError> { + self.store + .set(&key, &value) + .map_err(|err| internal_error("local-store", err.to_string())) + } + + async fn delete(&mut self, key: String) -> Result<(), HostError> { + self.store + .delete(&key) + .map_err(|err| internal_error("local-store", err.to_string())) + } + + async fn list_keys(&mut self, prefix: String) -> Result, HostError> { + self.store + .list_keys(&prefix) + .map_err(|err| internal_error("local-store", err.to_string())) + } +} diff --git a/crates/nexum-engine/src/host/impls/logging.rs b/crates/nexum-engine/src/host/impls/logging.rs new file mode 100644 index 0000000..b3a2a02 --- /dev/null +++ b/crates/nexum-engine/src/host/impls/logging.rs @@ -0,0 +1,18 @@ +//! `nexum:host/logging`: routes guest log lines through the host's +//! `tracing` subscriber, tagged with the module namespace. + +use crate::bindings::nexum; +use crate::host::state::HostState; + +impl nexum::host::logging::Host for HostState { + async fn log(&mut self, level: nexum::host::logging::Level, message: String) { + let module = self.module_namespace.as_str(); + match level { + nexum::host::logging::Level::Trace => tracing::trace!(module, "{}", message), + nexum::host::logging::Level::Debug => tracing::debug!(module, "{}", message), + nexum::host::logging::Level::Info => tracing::info!(module, "{}", message), + nexum::host::logging::Level::Warn => tracing::warn!(module, "{}", message), + nexum::host::logging::Level::Error => tracing::error!(module, "{}", message), + } + } +} diff --git a/crates/nexum-engine/src/host/impls/messaging.rs b/crates/nexum-engine/src/host/impls/messaging.rs new file mode 100644 index 0000000..5582b00 --- /dev/null +++ b/crates/nexum-engine/src/host/impls/messaging.rs @@ -0,0 +1,27 @@ +//! `nexum:host/messaging`: deferred to 0.3 (Waku backend). `query` +//! returns an empty result, same posture as `identity::accounts`. + +use crate::bindings::HostError; +use crate::bindings::nexum; +use crate::host::error::unimplemented; +use crate::host::state::HostState; + +impl nexum::host::messaging::Host for HostState { + async fn publish( + &mut self, + _content_topic: String, + _payload: Vec, + ) -> Result<(), HostError> { + Err(unimplemented("messaging", "Waku backend deferred to 0.3")) + } + + async fn query( + &mut self, + _content_topic: String, + _start_time: Option, + _end_time: Option, + _limit: Option, + ) -> Result, HostError> { + Ok(vec![]) + } +} diff --git a/crates/nexum-engine/src/host/impls/mod.rs b/crates/nexum-engine/src/host/impls/mod.rs new file mode 100644 index 0000000..8256af9 --- /dev/null +++ b/crates/nexum-engine/src/host/impls/mod.rs @@ -0,0 +1,19 @@ +//! `Host` trait impls for [`crate::host::state::HostState`], one +//! file per WIT interface. +//! +//! The interfaces themselves (and their generated trait shapes) live +//! in [`crate::bindings`]; this module only contains the dispatch +//! glue between the WIT signature and the corresponding backend in +//! [`crate::host`]. + +mod chain; +mod clock; +mod cow_api; +mod http; +mod identity; +mod local_store; +mod logging; +mod messaging; +mod random; +mod remote_store; +mod types; diff --git a/crates/nexum-engine/src/host/impls/random.rs b/crates/nexum-engine/src/host/impls/random.rs new file mode 100644 index 0000000..88e2f8c --- /dev/null +++ b/crates/nexum-engine/src/host/impls/random.rs @@ -0,0 +1,16 @@ +//! `nexum:host/random`: fills `len` bytes from the OS CSPRNG. +//! Getrandom 0.4 failures are exceptionally rare on supported +//! platforms; on failure we return zero-filled bytes - guests that +//! need a strong-failure signal should use identity or chain primitives +//! instead. + +use crate::bindings::nexum; +use crate::host::state::HostState; + +impl nexum::host::random::Host for HostState { + async fn fill(&mut self, len: u32) -> Vec { + let mut buf = vec![0u8; len as usize]; + let _ = getrandom::fill(&mut buf); + buf + } +} diff --git a/crates/nexum-engine/src/host/impls/remote_store.rs b/crates/nexum-engine/src/host/impls/remote_store.rs new file mode 100644 index 0000000..9001d1f --- /dev/null +++ b/crates/nexum-engine/src/host/impls/remote_store.rs @@ -0,0 +1,40 @@ +//! `nexum:host/remote-store`: deferred to 0.3 (Swarm backend). + +use crate::bindings::HostError; +use crate::bindings::nexum; +use crate::host::error::unimplemented; +use crate::host::state::HostState; + +impl nexum::host::remote_store::Host for HostState { + async fn upload(&mut self, _data: Vec) -> Result, HostError> { + Err(unimplemented( + "remote-store", + "Swarm backend deferred to 0.3", + )) + } + + async fn download(&mut self, _reference: Vec) -> Result, HostError> { + Err(unimplemented( + "remote-store", + "Swarm backend deferred to 0.3", + )) + } + + async fn read_feed( + &mut self, + _owner: Vec, + _topic: Vec, + ) -> Result>, HostError> { + Err(unimplemented( + "remote-store", + "Swarm backend deferred to 0.3", + )) + } + + async fn write_feed(&mut self, _topic: Vec, _data: Vec) -> Result, HostError> { + Err(unimplemented( + "remote-store", + "Swarm backend deferred to 0.3", + )) + } +} diff --git a/crates/nexum-engine/src/host/impls/types.rs b/crates/nexum-engine/src/host/impls/types.rs new file mode 100644 index 0000000..c4a93e1 --- /dev/null +++ b/crates/nexum-engine/src/host/impls/types.rs @@ -0,0 +1,7 @@ +//! `nexum:host/types` is a type-only interface (no functions). The +//! generated trait is empty; we just provide the marker impl. + +use crate::bindings::nexum; +use crate::host::state::HostState; + +impl nexum::host::types::Host for HostState {} diff --git a/crates/nexum-engine/src/host/local_store_redb.rs b/crates/nexum-engine/src/host/local_store_redb.rs new file mode 100644 index 0000000..de272cb --- /dev/null +++ b/crates/nexum-engine/src/host/local_store_redb.rs @@ -0,0 +1,185 @@ +//! `nexum:host/local-store` backend. +//! +//! Single redb file under `EngineConfig.engine.state_dir`. Per-module +//! namespacing is enforced host-side via a fixed-length 32-byte prefix: +//! `keccak256(module_name) ++ raw_key`. Two modules using the same key +//! string see disjoint data regardless of how similar their names are. +//! +//! The 32-byte hash prefix has two properties that the old +//! `[len:u8][name][key]` scheme lacked: +//! +//! - **Fixed width** - no length field to forge; a module cannot craft a +//! key that bleeds into another module's prefix range. +//! - **ENS-compatible** - keccak256 is the same hash used by ENS node +//! derivation, so module identities can be derived from ENS names +//! without extra hashing in the future (ADR-0003). +//! +//! ## Per-module handle +//! +//! [`LocalStore`] is the process-wide handle (one redb file shared across +//! every module). [`ModuleStore`] is the per-module view: it carries the +//! pre-computed namespace prefix once, so every get / set / delete / +//! list-keys call concatenates `prefix ++ key` without re-hashing the +//! module name. The supervisor builds one `ModuleStore` per module at +//! instantiation via [`LocalStore::module`]. + +#![allow(clippy::result_large_err)] + +use std::path::Path; +use std::sync::Arc; + +use alloy_primitives::keccak256; +use redb::{Database, TableDefinition}; +use thiserror::Error; + +const TABLE: TableDefinition<'static, &[u8], &[u8]> = TableDefinition::new("nexum:local-store"); +const PREFIX_LEN: usize = 32; + +/// Process-wide handle to the local-store redb database. Cheap to clone; +/// per-module access is created via [`LocalStore::module`]. +#[derive(Debug, Clone)] +pub struct LocalStore { + db: Arc, +} + +impl LocalStore { + /// Open (or create) the redb file at `path`. Materialises the shared + /// table so subsequent read transactions never hit `TableDoesNotExist`. + pub fn open(path: impl AsRef) -> Result { + let db = Database::create(path).map_err(StorageError::Open)?; + { + let txn = db.begin_write().map_err(StorageError::Txn)?; + txn.open_table(TABLE).map_err(StorageError::Table)?; + txn.commit().map_err(StorageError::Commit)?; + } + Ok(Self { db: Arc::new(db) }) + } + + /// Build a per-module view with the namespace prefix computed once. + /// + /// Returns [`StorageError::InvalidNamespace`] for the empty string so + /// callers can rely on a non-trivial prefix. The returned + /// [`ModuleStore`] shares the same `Arc` as `self`; cloning + /// it is cheap (Arc bump + 32 bytes). + pub fn module(&self, namespace: &str) -> Result { + if namespace.is_empty() { + return Err(StorageError::InvalidNamespace( + "module namespace must not be empty".into(), + )); + } + let prefix = keccak256(namespace.as_bytes()).0; + Ok(ModuleStore { + db: Arc::clone(&self.db), + prefix, + }) + } +} + +/// Per-module view of the local store. Carries the precomputed +/// `keccak256(module_name)` prefix so every operation concatenates +/// `prefix ++ key` without re-hashing the name. Cheap to clone (Arc +/// bump + 32 bytes). +#[derive(Debug, Clone)] +pub struct ModuleStore { + db: Arc, + prefix: [u8; PREFIX_LEN], +} + +impl ModuleStore { + /// Fetch a value for `key`. Returns `Ok(None)` when no entry exists; + /// the module never observes the prefix. + pub fn get(&self, key: &str) -> Result>, StorageError> { + let full = self.build_key(key); + let txn = self.db.begin_read().map_err(StorageError::Txn)?; + let table = txn.open_table(TABLE).map_err(StorageError::Table)?; + let value = table + .get(full.as_slice()) + .map_err(StorageError::Storage)? + .map(|v| v.value().to_vec()); + Ok(value) + } + + /// Insert or overwrite. + pub fn set(&self, key: &str, value: &[u8]) -> Result<(), StorageError> { + let full = self.build_key(key); + let txn = self.db.begin_write().map_err(StorageError::Txn)?; + { + let mut table = txn.open_table(TABLE).map_err(StorageError::Table)?; + table + .insert(full.as_slice(), value) + .map_err(StorageError::Storage)?; + } + txn.commit().map_err(StorageError::Commit)?; + Ok(()) + } + + /// Delete. Idempotent - deleting a missing key is a no-op. + pub fn delete(&self, key: &str) -> Result<(), StorageError> { + let full = self.build_key(key); + let txn = self.db.begin_write().map_err(StorageError::Txn)?; + { + let mut table = txn.open_table(TABLE).map_err(StorageError::Table)?; + table + .remove(full.as_slice()) + .map_err(StorageError::Storage)?; + } + txn.commit().map_err(StorageError::Commit)?; + Ok(()) + } + + /// Enumerate keys whose raw key (post-prefix) starts with `prefix`. + /// Returns only the module-visible key strings - the host strips + /// the namespace prefix. + pub fn list_keys(&self, prefix: &str) -> Result, StorageError> { + let full_prefix = self.build_key(prefix); + let txn = self.db.begin_read().map_err(StorageError::Txn)?; + let table = txn.open_table(TABLE).map_err(StorageError::Table)?; + let mut out = Vec::new(); + // redb's B-tree iterates keys in sorted order, so a range + // starting at `full_prefix` only touches matching entries (and + // the first key past the prefix range). Breaking on the first + // non-matching key keeps this O(matching entries) instead of + // the O(total DB entries) `table.iter()` would do. + for entry in table + .range(full_prefix.as_slice()..) + .map_err(StorageError::Storage)? + { + let (k, _v) = entry.map_err(StorageError::Storage)?; + let key_bytes = k.value(); + if !key_bytes.starts_with(&full_prefix) { + break; + } + if let Ok(s) = std::str::from_utf8(&key_bytes[PREFIX_LEN..]) { + out.push(s.to_owned()); + } + } + Ok(out) + } + + fn build_key(&self, key: &str) -> Vec { + let mut out = Vec::with_capacity(PREFIX_LEN + key.len()); + out.extend_from_slice(&self.prefix); + out.extend_from_slice(key.as_bytes()); + out + } +} + +/// Errors surfaced by [`LocalStore`] / [`ModuleStore`]. +#[derive(Debug, Error)] +pub enum StorageError { + #[error("open redb: {0}")] + Open(#[source] redb::DatabaseError), + #[error("redb txn: {0}")] + Txn(#[source] redb::TransactionError), + #[error("redb table: {0}")] + Table(#[source] redb::TableError), + #[error("redb storage: {0}")] + Storage(#[source] redb::StorageError), + #[error("redb commit: {0}")] + Commit(#[source] redb::CommitError), + #[error("invalid namespace: {0}")] + InvalidNamespace(String), +} + +#[cfg(test)] +mod tests; diff --git a/crates/nexum-engine/src/host/local_store_redb/tests.rs b/crates/nexum-engine/src/host/local_store_redb/tests.rs new file mode 100644 index 0000000..b80d653 --- /dev/null +++ b/crates/nexum-engine/src/host/local_store_redb/tests.rs @@ -0,0 +1,93 @@ +use super::*; + +fn fresh() -> (tempfile::TempDir, LocalStore) { + let dir = tempfile::tempdir().expect("tempdir"); + let store = LocalStore::open(dir.path().join("ls.redb")).expect("open"); + (dir, store) +} + +#[test] +fn set_get_roundtrip() { + let (_dir, store) = fresh(); + let twap = store.module("twap").unwrap(); + twap.set("k", b"v").unwrap(); + assert_eq!(twap.get("k").unwrap().as_deref(), Some(&b"v"[..])); +} + +#[test] +fn namespaces_isolate_modules() { + let (_dir, store) = fresh(); + let a = store.module("a").unwrap(); + let b = store.module("b").unwrap(); + a.set("k", b"from-a").unwrap(); + b.set("k", b"from-b").unwrap(); + assert_eq!(a.get("k").unwrap().as_deref(), Some(&b"from-a"[..])); + assert_eq!(b.get("k").unwrap().as_deref(), Some(&b"from-b"[..])); +} + +#[test] +fn delete_then_get_is_none() { + let (_dir, store) = fresh(); + let twap = store.module("twap").unwrap(); + twap.set("k", b"v").unwrap(); + twap.delete("k").unwrap(); + assert!(twap.get("k").unwrap().is_none()); +} + +#[test] +fn list_keys_strips_namespace_prefix() { + let (_dir, store) = fresh(); + let twap = store.module("twap").unwrap(); + twap.set("posted:1", b"x").unwrap(); + twap.set("posted:2", b"y").unwrap(); + twap.set("other", b"z").unwrap(); + let keys = twap.list_keys("posted:").unwrap(); + assert_eq!(keys.len(), 2); + assert!(keys.iter().all(|k| k.starts_with("posted:"))); +} + +#[test] +fn rejects_empty_namespace() { + let (_dir, store) = fresh(); + let err = store.module("").unwrap_err(); + assert!(matches!(err, StorageError::InvalidNamespace(_))); +} + +#[test] +fn prefix_is_fixed_32_bytes() { + let (_dir, store) = fresh(); + let short = store.module("a").unwrap(); + let long = store.module(&"a".repeat(300)).unwrap(); + assert_eq!(short.prefix.len(), PREFIX_LEN); + assert_eq!(long.prefix.len(), PREFIX_LEN); + // Different inputs produce different prefixes. + assert_ne!(short.prefix, long.prefix); +} + +#[test] +fn prefix_is_deterministic() { + let (_dir, store) = fresh(); + let m1 = store.module("twap-monitor").unwrap(); + let m2 = store.module("twap-monitor").unwrap(); + assert_eq!(m1.prefix, m2.prefix); +} + +#[test] +fn similar_names_differ() { + // Verify that names that share a common prefix don't collide. + let (_dir, store) = fresh(); + let pa = store.module("module-a").unwrap(); + let pb = store.module("module-b").unwrap(); + assert_ne!(pa.prefix, pb.prefix); +} + +#[test] +fn module_handles_share_underlying_data() { + // Two `ModuleStore` handles for the same name see the same data — + // confirms cloning is just an Arc bump, not a fresh DB view. + let (_dir, store) = fresh(); + let m1 = store.module("twap").unwrap(); + let m2 = store.module("twap").unwrap(); + m1.set("k", b"v").unwrap(); + assert_eq!(m2.get("k").unwrap().as_deref(), Some(&b"v"[..])); +} diff --git a/crates/nexum-engine/src/host/mod.rs b/crates/nexum-engine/src/host/mod.rs new file mode 100644 index 0000000..20f2ec2 --- /dev/null +++ b/crates/nexum-engine/src/host/mod.rs @@ -0,0 +1,21 @@ +//! Host-side backends for the `nexum:host` / `shepherd:cow` interfaces, +//! plus the per-module `HostState` and the WIT `Host` trait impls. +//! +//! Layout: +//! - [`state`]: `HostState` struct + `WasiView` impl, the receiver +//! every WIT `Host` trait is implemented for. +//! - [`error`]: small constructors that build the WIT `HostError` +//! shape (`unimplemented`, `internal_error`) plus the lowercase +//! `hex_encode` shared by the `cow-api` submission path. +//! - [`cow_orderbook`], [`provider_pool`], [`local_store_redb`]: +//! capability backends. Pure code with no bindgen types, so each +//! can be unit-tested without spinning up a wasmtime store. +//! - [`impls`] (private): the bindgen-side trait impls, one file per +//! WIT interface, that dispatch to the backends above. + +pub mod cow_orderbook; +pub mod error; +mod impls; +pub mod local_store_redb; +pub mod provider_pool; +pub mod state; diff --git a/crates/nexum-engine/src/host/provider_pool.rs b/crates/nexum-engine/src/host/provider_pool.rs new file mode 100644 index 0000000..19f55f9 --- /dev/null +++ b/crates/nexum-engine/src/host/provider_pool.rs @@ -0,0 +1,156 @@ +//! `nexum:host/chain` backend. +//! +//! Per-chain alloy provider, opened from the engine config at boot. +//! `request` is a raw JSON-RPC dispatch: the host hands `(method, +//! params)` straight to alloy's transport and returns the result body +//! verbatim. No method allowlist, no re-encoding of params - the +//! contract is "give us a JSON-RPC pair, we'll return what the node +//! returns". +//! +//! Transports: +//! - `ws://` / `wss://` - `WsConnect`; required for `eth_subscribe`. +//! - `http://` / `https://` - alloy's HTTP transport; request/response only. + +use std::collections::BTreeMap; +use std::sync::Arc; + +use alloy_provider::{DynProvider, Provider, ProviderBuilder, WsConnect}; +use serde_json::value::RawValue; +use thiserror::Error; +use tracing::info; + +use crate::engine_config::EngineConfig; + +/// Pool of alloy providers keyed by chain id. +#[derive(Debug, Clone)] +pub struct ProviderPool { + providers: Arc>, +} + +impl ProviderPool { + /// Open one provider per chain in `cfg.chains`. WebSocket URLs + /// engage alloy's pubsub transport; HTTP URLs use the HTTP + /// transport. Connection failures propagate to the caller; the + /// engine treats them as fatal at boot. + pub async fn from_config(cfg: &EngineConfig) -> Result { + let mut providers: BTreeMap = BTreeMap::new(); + for (chain_id, chain_cfg) in &cfg.chains { + let url = chain_cfg.rpc_url.as_str(); + info!(chain_id, url, "opening chain RPC provider"); + let provider = if url.starts_with("ws://") || url.starts_with("wss://") { + ProviderBuilder::new() + .connect_ws(WsConnect::new(url)) + .await + .map_err(|e| ProviderError::Connect { + chain_id: *chain_id, + detail: e.to_string(), + })? + .erased() + } else { + let parsed: url::Url = + url.parse() + .map_err(|e: url::ParseError| ProviderError::Connect { + chain_id: *chain_id, + detail: e.to_string(), + })?; + ProviderBuilder::new().connect_http(parsed).erased() + }; + providers.insert(*chain_id, provider); + } + Ok(Self { + providers: Arc::new(providers), + }) + } + + /// Empty pool used by tests. Every `request` call returns + /// `UnknownChain`. Gated behind `#[cfg(test)]` so the non-test + /// build does not link an unused constructor. + #[cfg(test)] + pub fn empty() -> Self { + Self { + providers: Arc::new(BTreeMap::new()), + } + } + + /// Raw JSON-RPC dispatch. `params_json` must be the JSON encoding + /// of the params array (e.g. `"[\"0x...\",\"latest\"]"`), as + /// produced by the SDK's `chain::request` glue. + pub async fn request( + &self, + chain_id: u64, + method: String, + params_json: String, + ) -> Result { + let provider = self + .providers + .get(&chain_id) + .ok_or(ProviderError::UnknownChain(chain_id))?; + // Pass the params through as a raw JSON value so alloy does + // not re-encode them on the way to the node. + let params: Box = + RawValue::from_string(params_json).map_err(|e| ProviderError::InvalidParams { + method: method.clone(), + detail: e.to_string(), + })?; + // `raw_request` consumes the method name; clone once for the + // error branch so the success path moves the original string + // straight into alloy without an extra allocation. + let method_for_err = method.clone(); + let result: Box = + provider + .raw_request(method.into(), params) + .await + .map_err(|e| ProviderError::Rpc { + method: method_for_err, + detail: e.to_string(), + })?; + Ok(result.get().to_owned()) + } +} + +/// Errors surfaced by [`ProviderPool`]. +#[derive(Debug, Error)] +pub enum ProviderError { + /// Chain id absent from the engine config. + #[error("unknown chain {0} (no engine.toml entry)")] + UnknownChain(u64), + /// Could not open the underlying transport. + #[error("connect chain {chain_id}: {detail}")] + Connect { + /// Chain id we failed to dial. + chain_id: u64, + /// Transport-side error string. + detail: String, + }, + /// The guest-supplied JSON params did not parse. + #[error("invalid params JSON for `{method}`: {detail}")] + InvalidParams { + /// RPC method name. + method: String, + /// JSON-parser detail. + detail: String, + }, + /// The node returned an error for the dispatched call. + #[error("rpc `{method}` failed: {detail}")] + Rpc { + /// RPC method name. + method: String, + /// Transport-side error string. + detail: String, + }, +} + +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn empty_pool_rejects_lookups() { + let pool = ProviderPool::empty(); + let err = pool + .request(1, "eth_blockNumber".into(), "[]".into()) + .await + .unwrap_err(); + assert!(matches!(err, ProviderError::UnknownChain(1))); + } +} diff --git a/crates/nexum-engine/src/host/state.rs b/crates/nexum-engine/src/host/state.rs new file mode 100644 index 0000000..5a6a167 --- /dev/null +++ b/crates/nexum-engine/src/host/state.rs @@ -0,0 +1,53 @@ +//! Per-instance host state and its WASI view. +//! +//! One [`HostState`] is created per module, lives inside the wasmtime +//! `Store`, and is the receiver every `Host` trait impl in +//! [`super::impls`] is implemented for. + +use std::time::Instant; + +use wasmtime::component::ResourceTable; +use wasmtime_wasi::{WasiCtx, WasiCtxView, WasiView}; + +use super::cow_orderbook::OrderBookPool; +use super::local_store_redb::ModuleStore; +use super::provider_pool::ProviderPool; + +pub(crate) struct HostState { + pub wasi: WasiCtx, + pub table: ResourceTable, + /// Wasmtime memory / table / instance caps applied to this store. + /// Wired in via `store.limiter(|state| &mut state.limits)` right + /// after construction; the operator-tunable budget comes from + /// `engine.toml`'s `[engine.limits]` table. + pub limits: wasmtime::StoreLimits, + /// Origin for `clock::monotonic-ns`. Differences between successive + /// readings are the only meaningful values. + pub monotonic_baseline: Instant, + /// Per-module `[capabilities.http].allow` allowlist (from module.toml). + /// Consulted by `http::fetch` before any outbound call. + pub http_allowlist: Vec, + /// Human-readable module name carried by every log line emitted via + /// the `logging` host. The local-store handle below already encodes + /// the same identity as its keccak prefix; this field exists purely + /// for log tagging. + pub module_namespace: String, + /// `cow-api` backend - per-chain `OrderBookApi` clients + reqwest. + pub cow: OrderBookPool, + /// `chain` backend - per-chain alloy `DynProvider` pool. + pub chain: ProviderPool, + /// Per-module local-store handle with the `keccak256(name)` prefix + /// computed once at instantiation. Every get / set / delete / + /// list-keys hop is just `prefix ++ key` concat — no per-call + /// hashing. + pub store: ModuleStore, +} + +impl WasiView for HostState { + fn ctx(&mut self) -> WasiCtxView<'_> { + WasiCtxView { + ctx: &mut self.wasi, + table: &mut self.table, + } + } +} diff --git a/crates/nexum-engine/src/main.rs b/crates/nexum-engine/src/main.rs index f013f22..c314006 100644 --- a/crates/nexum-engine/src/main.rs +++ b/crates/nexum-engine/src/main.rs @@ -1,376 +1,127 @@ +#![cfg_attr(not(test), warn(unused_crate_dependencies))] + +// alloy split its API across multiple crates; we depend on the +// transports directly so cargo resolves the right feature set, but +// the runtime code only names them through the `alloy_provider` +// re-exports. Silence `unused_crate_dependencies` with `as _`. +use alloy_rpc_client as _; +use alloy_transport as _; +use alloy_transport_ws as _; + +mod bindings; +mod engine_config; +mod host; mod manifest; use std::path::PathBuf; -use std::time::{Instant, SystemTime, UNIX_EPOCH}; +use std::time::Instant; + +use tracing::{info, warn}; +use tracing_subscriber::EnvFilter; use wasmtime::component::{Component, Linker, ResourceTable}; use wasmtime::error::Context as _; use wasmtime::{Engine, Store}; -use wasmtime_wasi::{WasiCtx, WasiCtxBuilder, WasiCtxView, WasiView}; - -// Both packages are listed explicitly so wit-parser can resolve the -// cross-package reference natively — no vendored deps/ tree needed. -// World name is fully qualified. -wasmtime::component::bindgen!({ - path: ["../../wit/nexum-host", "../../wit/shepherd-cow"], - world: "shepherd:cow/shepherd", - imports: { default: async }, - exports: { default: async }, -}); - -use nexum::host::types::HostErrorKind; - -struct HostState { - wasi: WasiCtx, - table: ResourceTable, - /// Origin for `clock::monotonic-ns`. Differences between successive - /// readings are the only meaningful values. - monotonic_baseline: Instant, - /// Per-module `[capabilities.http].allow` allowlist (from nexum.toml). - /// Consulted by `http::fetch` before any outbound call. - http_allowlist: Vec, -} - -impl WasiView for HostState { - fn ctx(&mut self) -> WasiCtxView<'_> { - WasiCtxView { - ctx: &mut self.wasi, - table: &mut self.table, - } - } -} - -fn unimplemented(domain: &str, detail: impl Into) -> HostError { - HostError { - domain: domain.into(), - kind: HostErrorKind::Unsupported, - code: 501, - message: detail.into(), - data: None, - } -} - -// -- Stub implementations for host interfaces -- - -impl nexum::host::types::Host for HostState {} - -impl shepherd::cow::cow_api::Host for HostState { - async fn request( - &mut self, - _chain_id: u64, - method: String, - path: String, - _body: Option, - ) -> Result { - let start = Instant::now(); - eprintln!("[cow-api] {method} {path}"); - let result = Err(unimplemented( - "cow-api", - format!("not implemented: {method} {path}"), - )); - eprintln!("[timing] cow-api::request: {:?}", start.elapsed()); - result - } - - async fn submit_order( - &mut self, - _chain_id: u64, - _order_data: Vec, - ) -> Result { - let start = Instant::now(); - eprintln!("[cow-api] submit-order"); - let result = Err(unimplemented("cow-api", "submit-order not implemented")); - eprintln!("[timing] cow-api::submit-order: {:?}", start.elapsed()); - result - } -} - -impl nexum::host::chain::Host for HostState { - async fn request( - &mut self, - _chain_id: u64, - method: String, - _params: String, - ) -> Result { - let start = Instant::now(); - eprintln!("[chain] request: {method}"); - let result = Err(HostError { - domain: "chain".into(), - kind: HostErrorKind::Unsupported, - code: -32601, - message: format!("method not implemented: {method}"), - data: None, - }); - eprintln!("[timing] chain::request: {:?}", start.elapsed()); - result - } - - async fn request_batch( - &mut self, - chain_id: u64, - requests: Vec, - ) -> Result, HostError> { - let start = Instant::now(); - eprintln!("[chain] request-batch: {} calls", requests.len()); - let mut out = Vec::with_capacity(requests.len()); - for req in requests { - match self.request(chain_id, req.method, req.params).await { - Ok(s) => out.push(nexum::host::chain::RpcResult::Ok(s)), - Err(e) => out.push(nexum::host::chain::RpcResult::Err(e)), - } - } - eprintln!("[timing] chain::request-batch: {:?}", start.elapsed()); - Ok(out) - } -} - -impl nexum::host::identity::Host for HostState { - async fn accounts(&mut self) -> Result>, HostError> { - let start = Instant::now(); - eprintln!("[identity] accounts"); - let result = Ok(vec![]); - eprintln!("[timing] identity::accounts: {:?}", start.elapsed()); - result - } - - async fn sign(&mut self, _account: Vec, _message: Vec) -> Result, HostError> { - let start = Instant::now(); - eprintln!("[identity] sign"); - let result = Err(unimplemented("identity", "sign not implemented")); - eprintln!("[timing] identity::sign: {:?}", start.elapsed()); - result - } - - async fn sign_typed_data( - &mut self, - _account: Vec, - _typed_data: String, - ) -> Result, HostError> { - let start = Instant::now(); - eprintln!("[identity] sign-typed-data"); - let result = Err(unimplemented("identity", "sign-typed-data not implemented")); - eprintln!("[timing] identity::sign-typed-data: {:?}", start.elapsed()); - result - } -} - -impl nexum::host::local_store::Host for HostState { - async fn get(&mut self, key: String) -> Result>, HostError> { - let start = Instant::now(); - eprintln!("[local-store] get: {key}"); - let result = Ok(None); - eprintln!("[timing] local-store::get: {:?}", start.elapsed()); - result - } - - async fn set(&mut self, key: String, _value: Vec) -> Result<(), HostError> { - let start = Instant::now(); - eprintln!("[local-store] set: {key}"); - let result = Ok(()); - eprintln!("[timing] local-store::set: {:?}", start.elapsed()); - result - } - - async fn delete(&mut self, key: String) -> Result<(), HostError> { - let start = Instant::now(); - eprintln!("[local-store] delete: {key}"); - let result = Ok(()); - eprintln!("[timing] local-store::delete: {:?}", start.elapsed()); - result - } - - async fn list_keys(&mut self, prefix: String) -> Result, HostError> { - let start = Instant::now(); - eprintln!("[local-store] list-keys: {prefix}"); - let result = Ok(vec![]); - eprintln!("[timing] local-store::list-keys: {:?}", start.elapsed()); - result - } -} - -impl nexum::host::remote_store::Host for HostState { - async fn upload(&mut self, _data: Vec) -> Result, HostError> { - let start = Instant::now(); - let result = Err(unimplemented("remote-store", "upload not implemented")); - eprintln!("[timing] remote-store::upload: {:?}", start.elapsed()); - result - } - - async fn download(&mut self, _reference: Vec) -> Result, HostError> { - let start = Instant::now(); - let result = Err(unimplemented("remote-store", "download not implemented")); - eprintln!("[timing] remote-store::download: {:?}", start.elapsed()); - result - } - - async fn read_feed( - &mut self, - _owner: Vec, - _topic: Vec, - ) -> Result>, HostError> { - let start = Instant::now(); - let result = Err(unimplemented("remote-store", "read-feed not implemented")); - eprintln!("[timing] remote-store::read-feed: {:?}", start.elapsed()); - result - } - - async fn write_feed(&mut self, _topic: Vec, _data: Vec) -> Result, HostError> { - let start = Instant::now(); - let result = Err(unimplemented("remote-store", "write-feed not implemented")); - eprintln!("[timing] remote-store::write-feed: {:?}", start.elapsed()); - result - } -} - -impl nexum::host::messaging::Host for HostState { - async fn publish(&mut self, content_topic: String, _payload: Vec) -> Result<(), HostError> { - let start = Instant::now(); - eprintln!("[messaging] publish: {content_topic}"); - let result = Err(unimplemented("messaging", "publish not implemented")); - eprintln!("[timing] messaging::publish: {:?}", start.elapsed()); - result - } - - async fn query( - &mut self, - content_topic: String, - _start_time: Option, - _end_time: Option, - _limit: Option, - ) -> Result, HostError> { - let start = Instant::now(); - eprintln!("[messaging] query: {content_topic}"); - let result = Ok(vec![]); - eprintln!("[timing] messaging::query: {:?}", start.elapsed()); - result - } -} - -impl nexum::host::logging::Host for HostState { - async fn log(&mut self, level: nexum::host::logging::Level, message: String) { - let start = Instant::now(); - let level_str = match level { - nexum::host::logging::Level::Trace => "TRACE", - nexum::host::logging::Level::Debug => "DEBUG", - nexum::host::logging::Level::Info => "INFO", - nexum::host::logging::Level::Warn => "WARN", - nexum::host::logging::Level::Error => "ERROR", - }; - eprintln!("[{level_str}] {message}"); - eprintln!("[timing] logging::log: {:?}", start.elapsed()); - } -} - -// -- Additive 0.2 capabilities -- - -impl nexum::host::clock::Host for HostState { - async fn now_ms(&mut self) -> u64 { - SystemTime::now() - .duration_since(UNIX_EPOCH) - .map(|d| d.as_millis() as u64) - .unwrap_or(0) - } - - async fn monotonic_ns(&mut self) -> u64 { - self.monotonic_baseline.elapsed().as_nanos() as u64 - } -} - -impl nexum::host::random::Host for HostState { - async fn fill(&mut self, len: u32) -> Vec { - let mut buf = vec![0u8; len as usize]; - // getrandom 0.4: fill() returns Result<(), Error>. CSPRNG failures - // are exceptionally rare on supported platforms; on failure we - // return zero-filled bytes — guests that need a strong-failure - // signal should use identity or chain primitives instead. - let _ = getrandom::fill(&mut buf); - buf - } -} - -impl nexum::host::http::Host for HostState { - async fn fetch( - &mut self, - req: nexum::host::http::Request, - ) -> Result { - let start = Instant::now(); - eprintln!("[http] {} {}", req.method, req.url); +use wasmtime_wasi::WasiCtxBuilder; - // Manifest allowlist enforcement runs before any I/O. Hosts that - // never link a manifest leave `http_allowlist` empty, which denies - // every request — matching the "no implicit network" stance. - let host = match manifest::extract_host(&req.url) { - Some(h) => h, - None => { - eprintln!("[timing] http::fetch: {:?}", start.elapsed()); - return Err(HostError { - domain: "http".into(), - kind: HostErrorKind::InvalidInput, - code: 0, - message: format!("not an http(s) URL: {}", req.url), - data: None, - }); - } - }; - if !manifest::host_allowed(host, &self.http_allowlist) { - eprintln!("[http] denied by allowlist: {host}"); - eprintln!("[timing] http::fetch: {:?}", start.elapsed()); - return Err(HostError { - domain: "http".into(), - kind: HostErrorKind::Denied, - code: 0, - message: format!( - "host {host} not in [capabilities.http].allow; \ - add it to nexum.toml to permit" - ), - data: None, - }); - } - - // 0.2: allowlist passed, but the reference runtime does not perform - // real HTTP yet. Real fetch lands in 0.3. - let result = Err(unimplemented( - "http", - "fetch not implemented in 0.2 reference runtime (allowlist passed)", - )); - eprintln!("[timing] http::fetch: {:?}", start.elapsed()); - result - } -} +use crate::bindings::{Config, Shepherd, nexum}; +use crate::host::state::HostState; #[tokio::main] async fn main() -> anyhow::Result<()> { let mut args = std::env::args().skip(1); let wasm_path = args.next().ok_or_else(|| { - anyhow::anyhow!("usage: nexum-engine []") + anyhow::anyhow!( + "usage: nexum-engine [] []" + ) })?; let explicit_manifest = args.next().map(PathBuf::from); - - println!("nexum-engine: loading component from {wasm_path}"); - - // Load the manifest from the explicit path if given, otherwise from - // `nexum.toml` next to the component file. Missing → fallback (with - // deprecation warning). + let explicit_engine_config = args.next().map(PathBuf::from); + + // -- 1. Load engine config (optional). -- + let engine_cfg = engine_config::load_or_default(explicit_engine_config.as_deref())?; + + // -- 2. Install tracing subscriber. -- + let env_filter = EnvFilter::try_from_default_env() + .or_else(|_| EnvFilter::try_new(&engine_cfg.engine.log_level)) + .unwrap_or_else(|_| EnvFilter::new("info")); + tracing_subscriber::fmt() + .with_env_filter(env_filter) + .with_target(true) + .init(); + + info!("nexum-engine starting"); + info!(wasm = %wasm_path, "loading component"); + + // -- 3. Load the module manifest. -- + // Canonical name is module.toml (ADR-0001). nexum.toml is accepted with a + // deprecation warning during the 0.1->0.2 transition; removed in 0.3. let manifest_path = explicit_manifest.or_else(|| { - PathBuf::from(&wasm_path) - .parent() - .map(|p| p.join("nexum.toml")) + let dir = PathBuf::from(&wasm_path).parent()?.to_owned(); + let canonical = dir.join("module.toml"); + if canonical.exists() { + return Some(canonical); + } + let legacy = dir.join("nexum.toml"); + if legacy.exists() { + eprintln!( + "[deprecation] nexum.toml is deprecated; rename to module.toml (ADR-0001). \ + Support will be removed in 0.3." + ); + return Some(legacy); + } + None }); let loaded = match manifest_path.as_deref() { - Some(p) if p.exists() => { - println!("nexum-engine: loading manifest from {}", p.display()); + Some(p) => { + info!(manifest = %p.display(), "loading module manifest"); manifest::load(p)? } - _ => manifest::fallback_manifest(), + None => manifest::fallback_manifest(), }; + // -- 4. Bring up the host backends. -- + std::fs::create_dir_all(&engine_cfg.engine.state_dir).with_context(|| { + format!( + "create state directory {}", + engine_cfg.engine.state_dir.display() + ) + })?; + let store_path = engine_cfg.engine.state_dir.join("local-store.redb"); + let local_store = host::local_store_redb::LocalStore::open(&store_path) + .with_context(|| format!("open local-store at {}", store_path.display()))?; + let cow_pool = host::cow_orderbook::OrderBookPool::default(); + let provider_pool = host::provider_pool::ProviderPool::from_config(&engine_cfg) + .await + .context("open chain providers")?; + + // -- 5. Build the wasmtime engine + component. -- let mut config = wasmtime::Config::new(); config.wasm_component_model(true); + // Fuel metering is always on so the operator's per-event budget + // (`engine.toml::[engine.limits].fuel_per_event`) can trap a runaway + // module before it starves the host. `Store::set_fuel` below seeds + // the actual budget per instance. + config.consume_fuel(true); + // `async_support` was deprecated in wasmtime 45 - the engine + // resolves async on its own. Keeping the call out of the Config + // chain silences the `deprecated` warning under + // `RUSTFLAGS=-D warnings`. let engine = Engine::new(&config)?; - let start = Instant::now(); + let load_start = Instant::now(); let component = Component::from_file(&engine, &wasm_path).context("failed to load component")?; - eprintln!("[timing] component load: {:?}", start.elapsed()); + tracing::debug!(elapsed_ms = ?load_start.elapsed(), "component load"); + + // Enforce capability declarations before spending time on instantiation. + manifest::enforce_capabilities( + &loaded, + component + .component_type() + .imports(&engine) + .map(|(name, _)| name), + ) + .map_err(|e| anyhow::anyhow!("{e}"))?; let mut linker = Linker::::new(&engine); Shepherd::add_to_linker::>( @@ -380,44 +131,78 @@ async fn main() -> anyhow::Result<()> { wasmtime_wasi::p2::add_to_linker_async(&mut linker)?; let wasi = WasiCtxBuilder::new().inherit_stdio().build(); + let module_namespace = if loaded.manifest.module.name.is_empty() { + "module".to_owned() + } else { + loaded.manifest.module.name.clone() + }; + let module_store = local_store + .module(&module_namespace) + .with_context(|| format!("open local-store view for module {module_namespace:?}"))?; + + let limits_cfg = engine_cfg.engine.limits; + let memory_cap = usize::try_from(limits_cfg.memory()).unwrap_or(usize::MAX); + let limits = wasmtime::StoreLimitsBuilder::new() + .memory_size(memory_cap) + .build(); let mut store = Store::new( &engine, HostState { wasi, table: ResourceTable::new(), + limits, monotonic_baseline: Instant::now(), http_allowlist: loaded.http_allowlist, + module_namespace: module_namespace.clone(), + cow: cow_pool, + chain: provider_pool, + store: module_store, }, ); + store.limiter(|state| &mut state.limits); + store + .set_fuel(limits_cfg.fuel()) + .context("seed module fuel budget")?; + info!( + fuel = limits_cfg.fuel(), + memory_bytes = limits_cfg.memory(), + "applied module resource limits", + ); - let start = Instant::now(); + let inst_start = Instant::now(); let bindings = Shepherd::instantiate_async(&mut store, &component, &linker) .await .context("failed to instantiate component")?; - eprintln!("[timing] component instantiate: {:?}", start.elapsed()); + tracing::debug!(elapsed_ms = ?inst_start.elapsed(), "component instantiate"); - println!("nexum-engine: calling init..."); - // 0.2: [config] is stringly-typed (typed variant deferred to 0.3). - // Fall back to a single ("name", "") pair if the manifest has - // no [config] section so the example module still has something to log. + info!("calling init"); let config_entries: Config = if loaded.config.is_empty() { vec![("name".into(), loaded.manifest.module.name.clone())] } else { loaded.config }; - let start = Instant::now(); + let init_start = Instant::now(); match bindings.call_init(&mut store, &config_entries).await? { - Ok(()) => println!("nexum-engine: init succeeded"), - Err(e) => println!( - "nexum-engine: init failed: {}::{:?} {} ({})", - e.domain, e.kind, e.message, e.code + Ok(()) => info!(elapsed_ms = ?init_start.elapsed(), "init succeeded"), + Err(e) => warn!( + domain = %e.domain, + kind = ?e.kind, + code = e.code, + message = %e.message, + "init failed", ), } - eprintln!("[timing] call_init: {:?}", start.elapsed()); + + // Refuel before on_event so each event runs against a full budget, + // independent of how much instantiation + init consumed. The + // supervisor (BLEU-818) does the same per delivered event. + store + .set_fuel(limits_cfg.fuel()) + .context("refuel for on_event")?; // Dispatch a test block event (timestamps are ms since Unix epoch, UTC). - println!("nexum-engine: dispatching test block event..."); + info!("dispatching test block event"); let block = nexum::host::types::Block { chain_id: 1, number: 19_000_000, @@ -425,16 +210,18 @@ async fn main() -> anyhow::Result<()> { timestamp: 1_700_000_000_000, }; let event = nexum::host::types::Event::Block(block); - let start = Instant::now(); + let evt_start = Instant::now(); match bindings.call_on_event(&mut store, &event).await? { - Ok(()) => println!("nexum-engine: on-event succeeded"), - Err(e) => println!( - "nexum-engine: on-event failed: {}::{:?} {} ({})", - e.domain, e.kind, e.message, e.code + Ok(()) => info!(elapsed_ms = ?evt_start.elapsed(), "on-event succeeded"), + Err(e) => warn!( + domain = %e.domain, + kind = ?e.kind, + code = e.code, + message = %e.message, + "on-event failed", ), } - eprintln!("[timing] call_on_event: {:?}", start.elapsed()); - println!("nexum-engine: done"); + info!("done"); Ok(()) } diff --git a/crates/nexum-engine/src/manifest/capabilities.rs b/crates/nexum-engine/src/manifest/capabilities.rs new file mode 100644 index 0000000..fddb788 --- /dev/null +++ b/crates/nexum-engine/src/manifest/capabilities.rs @@ -0,0 +1,162 @@ +//! Capability enforcement: cross-checks the component's WIT imports +//! against the `[capabilities]` block declared in `module.toml`. + +use std::collections::HashSet; + +use super::error::CapabilityViolation; +use super::types::{KNOWN_CAPABILITIES, LoadedManifest}; + +/// Check that every capability-bearing WIT import of the component is covered +/// by the module's manifest declarations. Call this after loading the +/// component but before instantiation. +/// +/// When `[capabilities]` is absent the manifest is in 0.1-fallback mode and +/// all imports are allowed; the caller is expected to have already emitted +/// a deprecation warning. +/// +/// `component_imports` should be the iterator returned by +/// `component.component_type().imports(&engine)` - pass the **name** part +/// (`&str`) of each `(&str, ComponentItem)` tuple. +pub fn enforce_capabilities<'a>( + loaded: &LoadedManifest, + component_imports: impl Iterator, +) -> Result<(), CapabilityViolation> { + let caps = match loaded.manifest.capabilities.as_ref() { + None => return Ok(()), // 0.1-fallback: no enforcement + Some(c) => c, + }; + + let declared: HashSet<&str> = caps + .required + .iter() + .chain(caps.optional.iter()) + .map(String::as_str) + .collect(); + + for import_name in component_imports { + if let Some(cap) = wit_import_to_cap(import_name) + && !declared.contains(cap) + { + return Err(CapabilityViolation { + capability: cap.to_owned(), + wit_import: import_name.to_owned(), + }); + } + } + Ok(()) +} + +/// Map a WIT import name to a capability name, or `None` for non-capability +/// imports. +/// +/// Returns `Some(iface)` only for interfaces in [`KNOWN_CAPABILITIES`]; +/// type-only packages like `nexum:host/types` and unrelated namespaces +/// (`wasi:*`) fall through to `None` so they do not need a manifest +/// declaration. +/// +/// Examples: +/// - `"nexum:host/chain@0.2.0"` -> `Some("chain")` +/// - `"shepherd:cow/cow-api@0.2.0"` -> `Some("cow-api")` +/// - `"nexum:host/types@0.2.0"` -> `None` (type-only, not a capability) +/// - `"wasi:io/streams@0.2.0"` -> `None` +pub(super) fn wit_import_to_cap(import_name: &str) -> Option<&str> { + let without_version = import_name.split('@').next().unwrap_or(import_name); + let iface = without_version + .strip_prefix("nexum:host/") + .or_else(|| without_version.strip_prefix("shepherd:cow/"))?; + if KNOWN_CAPABILITIES.contains(&iface) { + Some(iface) + } else { + None + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::manifest::types::{CapabilitiesSection, Manifest}; + + #[test] + fn wit_import_to_cap_nexum_host() { + assert_eq!(wit_import_to_cap("nexum:host/chain@0.2.0"), Some("chain")); + assert_eq!( + wit_import_to_cap("nexum:host/local-store@0.2.0"), + Some("local-store") + ); + assert_eq!(wit_import_to_cap("nexum:host/http@0.2.0"), Some("http")); + } + + #[test] + fn wit_import_to_cap_shepherd_cow() { + assert_eq!( + wit_import_to_cap("shepherd:cow/cow-api@0.2.0"), + Some("cow-api") + ); + } + + #[test] + fn wit_import_to_cap_wasi_is_none() { + assert_eq!(wit_import_to_cap("wasi:io/streams@0.2.0"), None); + assert_eq!(wit_import_to_cap("wasi:cli/stdin@0.2.0"), None); + assert_eq!(wit_import_to_cap("wasi:sockets/tcp@0.2.0"), None); + } + + fn manifest_with_caps(required: &[&str], optional: &[&str]) -> LoadedManifest { + LoadedManifest { + manifest: Manifest { + capabilities: Some(CapabilitiesSection { + required: required.iter().map(|s| s.to_string()).collect(), + optional: optional.iter().map(|s| s.to_string()).collect(), + http: None, + }), + ..Default::default() + }, + http_allowlist: vec![], + config: vec![], + } + } + + fn manifest_no_caps() -> LoadedManifest { + LoadedManifest { + manifest: Manifest::default(), + http_allowlist: vec![], + config: vec![], + } + } + + #[test] + fn enforce_passes_when_caps_absent() { + // 0.1-fallback: no capabilities section -> all imports allowed + let loaded = manifest_no_caps(); + let imports = ["nexum:host/chain@0.2.0", "nexum:host/remote-store@0.2.0"]; + assert!(enforce_capabilities(&loaded, imports.into_iter()).is_ok()); + } + + #[test] + fn enforce_passes_when_all_imports_declared() { + let loaded = manifest_with_caps(&["chain", "cow-api"], &["http"]); + let imports = [ + "nexum:host/chain@0.2.0", + "shepherd:cow/cow-api@0.2.0", + "nexum:host/http@0.2.0", + "wasi:io/streams@0.2.0", // wasi is always skipped + ]; + assert!(enforce_capabilities(&loaded, imports.into_iter()).is_ok()); + } + + #[test] + fn enforce_rejects_undeclared_import() { + let loaded = manifest_with_caps(&["chain"], &[]); + // module imports remote-store but didn't declare it + let imports = ["nexum:host/chain@0.2.0", "nexum:host/remote-store@0.2.0"]; + let err = enforce_capabilities(&loaded, imports.into_iter()).unwrap_err(); + assert_eq!(err.capability, "remote-store"); + } + + #[test] + fn enforce_optional_caps_are_also_allowed() { + let loaded = manifest_with_caps(&["chain"], &["remote-store"]); + let imports = ["nexum:host/chain@0.2.0", "nexum:host/remote-store@0.2.0"]; + assert!(enforce_capabilities(&loaded, imports.into_iter()).is_ok()); + } +} diff --git a/crates/nexum-engine/src/manifest/error.rs b/crates/nexum-engine/src/manifest/error.rs new file mode 100644 index 0000000..9b667b3 --- /dev/null +++ b/crates/nexum-engine/src/manifest/error.rs @@ -0,0 +1,41 @@ +//! Error types for manifest parsing and capability enforcement. + +use thiserror::Error; + +use super::types::KNOWN_CAPABILITIES; + +/// Errors returned while loading or validating a manifest. +#[derive(Debug, Error)] +pub enum ParseError { + /// Could not read the manifest file from disk. + #[error("manifest: i/o: {0}")] + Io(#[from] std::io::Error), + /// The on-disk bytes did not parse as TOML. + #[error("manifest: parse: {0}")] + Toml(#[from] toml::de::Error), + /// `[capabilities].required` named an interface the engine does + /// not know how to provision. The display impl lists the known + /// set so a typo surfaces with the corrected name in reach. + #[error( + "manifest: unknown capability {name:?} in [capabilities].required (known: {})", + KNOWN_CAPABILITIES.join(", "), + )] + UnknownCapability { + /// The unknown capability name as it appeared in the manifest. + name: String, + }, +} + +/// Error returned when a component's WIT imports exceed its declared capabilities. +#[derive(Debug, Error)] +#[error( + "component imports `{capability}` ({wit_import}) but it is not listed in \ + [capabilities].required or [capabilities].optional" +)] +pub struct CapabilityViolation { + /// Capability name (e.g. `"remote-store"`). + pub capability: String, + /// Full WIT import name as it appeared in the component (e.g. + /// `"nexum:host/remote-store@0.2.0"`). + pub wit_import: String, +} diff --git a/crates/nexum-engine/src/manifest.rs b/crates/nexum-engine/src/manifest/load.rs similarity index 51% rename from crates/nexum-engine/src/manifest.rs rename to crates/nexum-engine/src/manifest/load.rs index 522e168..560112f 100644 --- a/crates/nexum-engine/src/manifest.rs +++ b/crates/nexum-engine/src/manifest/load.rs @@ -1,132 +1,28 @@ -//! Minimal `nexum.toml` parser and capability-enforcement helpers (0.2 scope). +//! Parse `module.toml` from disk, validate, and emit operator-visible +//! warnings. //! -//! 0.2 intentionally ships a slim subset of the manifest spec described in -//! the migration guide §3: -//! -//! - `[capabilities].required` is parsed and validated (names must be in -//! the known capability set; the 0.2 reference engine always provides -//! all of them, so this is a sanity check + future-proofing). -//! - `[capabilities].optional` is parsed and logged; trap-stub fallback -//! for absent optionals is deferred to 0.3. -//! - `[capabilities.http].allow` is parsed and consulted by the `http` -//! host impl before any outbound call. -//! - `[config]` is flattened to `Vec<(String, String)>` and passed to the -//! module's `init`. Typed `config-value` variant is deferred to 0.3. -//! -//! When the manifest file is missing or has no `[capabilities]` section, -//! a deprecation warning is emitted on stderr and the engine falls back -//! to 0.1 behaviour (treat every linked capability as required). This -//! fallback will be removed in 0.3. +//! Also exposes the small URL/host helpers the `http` host backend +//! uses to enforce the manifest's `[capabilities.http].allow` list at +//! request time. use std::collections::HashSet; use std::path::Path; -use serde::Deserialize; - -/// Capability names recognised by the 0.2 reference engine. Matches the -/// interfaces the `shepherd` world links into the linker. -pub const KNOWN_CAPABILITIES: &[&str] = &[ - "chain", - "identity", - "local-store", - "remote-store", - "messaging", - "logging", - "clock", - "random", - "http", - // Domain-extension caps (provided by the shepherd world only): - "cow-api", -]; - -#[derive(Debug, Deserialize, Default)] -pub struct Manifest { - #[serde(default)] - pub module: ModuleSection, - #[serde(default)] - pub capabilities: Option, - #[serde(default)] - pub config: toml::Table, -} - -#[derive(Debug, Deserialize, Default)] -#[allow(dead_code)] // version + component parsed for future 0.3 hash-verification. -pub struct ModuleSection { - #[serde(default)] - pub name: String, - #[serde(default)] - pub version: String, - #[serde(default)] - pub component: String, -} - -#[derive(Debug, Deserialize, Default)] -pub struct CapabilitiesSection { - #[serde(default)] - pub required: Vec, - #[serde(default)] - pub optional: Vec, - #[serde(default)] - pub http: Option, -} - -#[derive(Debug, Deserialize, Default)] -pub struct HttpSection { - #[serde(default)] - pub allow: Vec, -} - -/// Errors returned while loading or validating a manifest. -#[derive(Debug)] -pub enum ParseError { - Io(std::io::Error), - Toml(toml::de::Error), - UnknownCapability(String), -} - -impl std::fmt::Display for ParseError { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - match self { - Self::Io(e) => write!(f, "manifest: i/o: {e}"), - Self::Toml(e) => write!(f, "manifest: parse: {e}"), - Self::UnknownCapability(name) => write!( - f, - "manifest: unknown capability {:?} in [capabilities].required (known: {})", - name, - KNOWN_CAPABILITIES.join(", ") - ), - } - } -} - -impl std::error::Error for ParseError {} - -/// Loaded + validated manifest, plus its source path for diagnostics. -pub struct LoadedManifest { - pub manifest: Manifest, - /// Hosts to allow for `http::fetch`. Each entry is either an exact - /// hostname or a `*.suffix` wildcard. - pub http_allowlist: Vec, - /// `[config]` flattened to `(key, stringified-value)` pairs ready to - /// hand to a module's `init`. TOML scalars (string, integer, float, - /// boolean) become their text form. Arrays and tables are rendered as - /// their TOML representation. - pub config: Vec<(String, String)>, -} +use super::error::ParseError; +use super::types::{KNOWN_CAPABILITIES, LoadedManifest, Manifest}; -/// Read `nexum.toml` from `path`, parse, validate, and emit a deprecation +/// Read `module.toml` from `path`, parse, validate, and emit a deprecation /// warning if `[capabilities]` is absent (0.1-compat fallback). pub fn load(path: &Path) -> Result { - let raw = std::fs::read_to_string(path).map_err(ParseError::Io)?; - let manifest: Manifest = toml::from_str(&raw).map_err(ParseError::Toml)?; + let raw = std::fs::read_to_string(path)?; + let manifest: Manifest = toml::from_str(&raw)?; let caps = manifest.capabilities.as_ref(); if caps.is_none() { eprintln!( - "[deprecation] no [capabilities] section in nexum.toml — \ + "[deprecation] no [capabilities] section in module.toml - \ defaulting to all-required (0.1 behaviour). This default \ - will be removed in 0.3; add an explicit [capabilities] block \ - now." + will be removed in 0.3; add an explicit [capabilities] block." ); } @@ -134,7 +30,7 @@ pub fn load(path: &Path) -> Result { let known: HashSet<&str> = KNOWN_CAPABILITIES.iter().copied().collect(); for name in c.required.iter().chain(c.optional.iter()) { if !known.contains(name.as_str()) { - return Err(ParseError::UnknownCapability(name.clone())); + return Err(ParseError::UnknownCapability { name: name.clone() }); } } if !c.required.is_empty() { @@ -173,13 +69,13 @@ pub fn load(path: &Path) -> Result { }) } -/// Synthesise a "0.1 fallback" manifest for when no `nexum.toml` is found. +/// Synthesise a "0.1 fallback" manifest for when no `module.toml` is found. /// Emits the same deprecation warning as a missing-section manifest. pub fn fallback_manifest() -> LoadedManifest { eprintln!( - "[deprecation] no nexum.toml found — defaulting to all-required \ + "[deprecation] no module.toml found - defaulting to all-required \ (0.1 behaviour). This default will be removed in 0.3; ship a \ - nexum.toml alongside your component." + module.toml alongside your component." ); LoadedManifest { manifest: Manifest::default(), @@ -204,7 +100,7 @@ pub fn host_allowed(host: &str, allowlist: &[String]) -> bool { } /// Extract the host component from a URL. Returns `None` for non-http(s) -/// schemes or malformed input. Intentionally simple — adds no `url` +/// schemes or malformed input. Intentionally simple - adds no `url` /// crate dependency. pub fn extract_host(url: &str) -> Option<&str> { let after_scheme = url diff --git a/crates/nexum-engine/src/manifest/mod.rs b/crates/nexum-engine/src/manifest/mod.rs new file mode 100644 index 0000000..95c6665 --- /dev/null +++ b/crates/nexum-engine/src/manifest/mod.rs @@ -0,0 +1,39 @@ +//! `module.toml` parser and capability-enforcement helpers (0.2 scope). +//! +//! 0.2 intentionally ships a slim subset of the manifest spec: +//! +//! - `[capabilities].required` is parsed and validated (names must be in +//! the known capability set; the 0.2 reference engine always provides +//! all of them, so this is a sanity check + future-proofing). +//! - `[capabilities].optional` is parsed and logged; trap-stub fallback +//! for absent optionals is deferred to 0.3. +//! - `[capabilities.http].allow` is parsed and consulted by the `http` +//! host impl before any outbound call. +//! - `[config]` is flattened to `Vec<(String, String)>` and passed to the +//! module's `init`. Typed `config-value` variant is deferred to 0.3. +//! +//! When the manifest file is missing or has no `[capabilities]` section, +//! a deprecation warning is emitted and the engine falls back to 0.1 +//! behaviour (treat every linked capability as required). This fallback +//! will be removed in 0.3. +//! +//! ## Layout +//! +//! - [`types`]: the serde `Manifest` shape + `LoadedManifest` the engine +//! actually consumes, plus the `KNOWN_CAPABILITIES` registry. +//! - [`load`]: `module.toml` -> `LoadedManifest`, plus the host/URL +//! helpers the `http` backend uses at request time. +//! - [`capabilities`]: WIT-import vs declared-capabilities cross-check. +//! - [`error`]: `ParseError`, `CapabilityViolation`. + +mod capabilities; +mod error; +mod load; +mod types; + +pub use capabilities::enforce_capabilities; +pub use load::{extract_host, fallback_manifest, host_allowed, load}; +// CapabilityViolation, ParseError, LoadedManifest, and the section +// structs are reachable through these functions' return / argument +// types; consumers that need to name them directly do so via +// `crate::manifest::error::*` or `::types::*`. diff --git a/crates/nexum-engine/src/manifest/types.rs b/crates/nexum-engine/src/manifest/types.rs new file mode 100644 index 0000000..70799c2 --- /dev/null +++ b/crates/nexum-engine/src/manifest/types.rs @@ -0,0 +1,74 @@ +//! Data structures: `Manifest`, sections, and `LoadedManifest`. +//! +//! Plain serde shapes plus the `KNOWN_CAPABILITIES` registry. The parsing +//! and validation logic lives in [`super::load`]; capability enforcement +//! in [`super::capabilities`]. + +use serde::Deserialize; + +/// Capability names recognised by the 0.2 reference engine. Matches the +/// interfaces the `shepherd` world links into the linker. +pub const KNOWN_CAPABILITIES: &[&str] = &[ + "chain", + "identity", + "local-store", + "remote-store", + "messaging", + "logging", + "clock", + "random", + "http", + // Domain-extension caps (provided by the shepherd world only): + "cow-api", +]; + +#[derive(Debug, Deserialize, Default)] +pub struct Manifest { + #[serde(default)] + pub module: ModuleSection, + #[serde(default)] + pub capabilities: Option, + #[serde(default)] + pub config: toml::Table, +} + +#[derive(Debug, Deserialize, Default)] +#[allow(dead_code)] // version + component parsed for future 0.3 hash-verification. +pub struct ModuleSection { + #[serde(default)] + pub name: String, + #[serde(default)] + pub version: String, + #[serde(default)] + pub component: String, +} + +#[derive(Debug, Deserialize, Default)] +pub struct CapabilitiesSection { + #[serde(default)] + pub required: Vec, + #[serde(default)] + pub optional: Vec, + #[serde(default)] + pub http: Option, +} + +#[derive(Debug, Deserialize, Default)] +pub struct HttpSection { + #[serde(default)] + pub allow: Vec, +} + +/// Loaded + validated manifest, plus the data the engine needs to +/// instantiate a module. +pub struct LoadedManifest { + pub manifest: Manifest, + /// Hosts to allow for `http::fetch`. Each entry is either an exact + /// hostname or a `*.suffix` wildcard. + pub http_allowlist: Vec, + /// `[config]` flattened to `(key, stringified-value)` pairs ready to + /// hand to a module's `init`. TOML scalars (string, integer, float, + /// boolean) become their text form. Arrays and tables are rendered as + /// their TOML representation. + pub config: Vec<(String, String)>, +} diff --git a/engine.example.toml b/engine.example.toml new file mode 100644 index 0000000..74769ae --- /dev/null +++ b/engine.example.toml @@ -0,0 +1,48 @@ +# Engine-side runtime configuration for `nexum-engine`. +# +# Distinct from `nexum.toml` (per-module manifest): this file +# describes the *engine*'s I/O wiring. Copy to `engine.toml` next to +# the binary, or pass the path as the third positional argument. + +[engine] +# Directory the local-store redb file (and future engine artefacts) +# will be created under. Created automatically at boot. +state_dir = "./data" + +# `tracing_subscriber::EnvFilter`-compatible directive. `RUST_LOG` +# overrides at process start. +log_level = "info" + +# Resource caps applied to every module store. wasmtime traps a module +# that overruns either limit; the supervisor then logs and continues on +# the next event. Both keys are optional — omitting one falls back to +# the engine's compiled-in default. Tune up for compute-heavy modules +# (eth_call orchestration, signature recovery loops), tune down on +# shared hosts where one greedy module must not starve the others. +[engine.limits] +# Fuel budget granted before every `on_event` invocation. 1 unit ~= +# 1 wasm instruction. 1 billion ~= ~1 second of pure compute on a +# modern CPU. +fuel_per_event = 1_000_000_000 +# Linear-memory ceiling per module, in bytes. Default 64 MiB. +memory_bytes = 67_108_864 + +# One [chains.] table per chain the engine should be able to talk +# to. Chain ids are EVM decimal. `ws://` and `wss://` URLs engage +# alloy's pubsub transport (needed for `eth_subscribe`); `http://` and +# `https://` use the HTTP transport. + +[chains.1] +rpc_url = "https://ethereum-rpc.publicnode.com" + +[chains.100] +rpc_url = "https://rpc.gnosischain.com" + +[chains.11155111] +rpc_url = "wss://ethereum-sepolia-rpc.publicnode.com" + +[chains.42161] +rpc_url = "https://arb1.arbitrum.io/rpc" + +[chains.8453] +rpc_url = "https://mainnet.base.org"