chore(deps): patch cowprotocol to bleu/cow-rs main (post-alpha.3)

.gitignore

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

Cargo.toml

@@ -10,6 +10,18 @@ edition = "2024"
 license = "AGPL-3.0"
 repository = "https://github.com/nullisLabs/shepherd"
 
+# `cowprotocol` v1.0.0-alpha.3 (the crates.io release the engine
+# depends on) was cut from `cowdao-grants/cow-rs` PR #5 at commit
+# `1742ffa`. `bleu/cow-rs` main has 18 commits since, including the
+# `composable::Proof` width fix (relevant to the TWAP poll path),
+# `OrderCreation` zero-from-address fast-fail (closes a MEDIUM
+# review finding from PR #5), and the `order_book` / `composable`
+# submodule splits. Patching to that commit picks them up without
+# waiting for an alpha.4 publish. Drop once `cowprotocol >= 1.0.0-alpha.4`
+# ships.
+[patch.crates-io]
+cowprotocol = { git = "https://github.com/bleu/cow-rs", rev = "c012404ffefc411bff543d2290e19ba7fbef2516" }
+
 [profile.dev]
 panic = "abort"
 

crates/nexum-engine/Cargo.toml

@@ -6,10 +6,56 @@ 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-rpc-types-eth = { version = "1.5", default-features = false, features = ["std"] }
+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"] }
+futures             = "0.3"
+
+# `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,119 @@
+//! 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>,
+    /// Modules the supervisor should boot. Each entry resolves a
+    /// `(component.wasm, nexum.toml)` pair on the local filesystem
+    /// for 0.2 — content-addressed resolution (Swarm / OCI /
+    /// `[[content.sources]]`) lands in 0.3 per
+    /// `docs/03-module-discovery.md`.
+    #[serde(default)]
+    pub modules: Vec<ModuleEntry>,
+}
+
+/// One `[[modules]]` table from `engine.toml`.
+///
+/// Both fields are filesystem paths in 0.2. `manifest` defaults to
+/// `nexum.toml` next to `path` if omitted, matching the bundle layout
+/// in `docs/02-modules-events-packaging.md`.
+#[derive(Debug, Deserialize)]
+pub struct ModuleEntry {
+    /// Path to the compiled `.wasm` component.
+    pub path: std::path::PathBuf,
+    /// Path to the module's `nexum.toml`. Defaults to `<path-parent>/nexum.toml`.
+    #[serde(default)]
+    pub manifest: Option<std::path::PathBuf>,
+}
+
+#[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)
+}