runtime: implement cow-api, chain, local-store host backends

.gitignore

@@ -21,3 +21,4 @@ Thumbs.db
 # Environment
 .env
 .env.*
+data/

crates/nexum-engine/Cargo.toml

@@ -6,10 +6,54 @@ 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`. Pinned to the
+# crates.io release Shepherd is shipping 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.5", default-features = false, features = ["ws", "ipc", "pubsub", "reqwest"] }
+alloy-rpc-client    = { version = "1.5", default-features = false }
+alloy-transport     = { version = "1.5", default-features = false }
+alloy-transport-ws  = { version = "1.5", default-features = false }
+alloy-primitives    = { version = "1.5", 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"

crates/nexum-engine/src/engine_config.rs

@@ -0,0 +1,98 @@
+//! Engine-side runtime configuration.
+//!
+//! Distinct from `nexum.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 <path>` 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<u64, ChainConfig>,
+}
+
+#[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,
+}
+
+impl Default for EngineSection {
+    fn default() -> Self {
+        Self {
+            state_dir: default_state_dir(),
+            log_level: default_log_level(),
+        }
+    }
+}
+
+#[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<EngineConfig> {
+    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)
+}