M2 epic: TWAP + EthFlow modules + module.toml manifests

.gitignore

@@ -21,3 +21,11 @@ Thumbs.db
 # Environment
 .env
 .env.*
+
+# Agent skills / AI tooling — installed locally, never committed.
+.agents/
+.claude/
+skills-lock.json
+
+# Engine runtime state (default state_dir from engine.toml).
+data/

Cargo.toml

@@ -10,6 +10,20 @@ 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 diverged since with: the
+# `composable::Proof` width fix (relevant to the TWAP poll path),
+# `OrderCreation` zero-from-address fast-fail, the `order_book` /
+# `composable` submodule splits, `OrderPostErrorKind` + `retry_hint()`
+# (BLEU-822, the protocol-level retry contract M2 modules dispatch
+# on), and `OrderBookApi::with_base_url(chain, base_url)` for barn /
+# staging routing (BLEU-823). Patching to that commit picks the lot
+# 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 = "57f5f553ab28c9fff54089daf2d39b4282f3e4dd" }
+
 [profile.dev]
 panic = "abort"
 

README.md

@@ -46,10 +46,71 @@ just build
 
 # Run the runtime against the example module
 just run
+
+# Run unit tests
+just test
 ```
 
 Without Nix, you need: Rust (edition 2024, see `rust-toolchain.toml` if present), the `wasm32-wasip2` target, and `wasm-tools`.
 
+## Running
+
+### Single-module (development)
+
+```sh
+nexum-engine <path-to-component.wasm> [<module.toml>]
+```
+
+The `module.toml` is optional; without it the engine prints a deprecation warning and loads the module with empty capabilities and config (0.1 fallback).
+
+### Multi-module (production)
+
+```sh
+nexum-engine --engine-config engine.toml
+```
+
+`engine.toml` declares RPC endpoints, the state directory, and a `[[modules]]` list:
+
+```toml
+[engine]
+state_dir = "/var/lib/shepherd"
+log_level  = "info"
+
+[chains.1]
+rpc_url = "wss://mainnet.infura.io/ws/v3/..."
+
+[[modules]]
+path     = "modules/twap-monitor/twap-monitor.wasm"
+manifest = "modules/twap-monitor/module.toml"
+
+[[modules]]
+path = "modules/ethflow-watcher/ethflow-watcher.wasm"
+```
+
+### Module manifest (`module.toml`)
+
+```toml
+[module]
+name    = "twap-monitor"
+version = "0.1.0"
+
+[capabilities]
+required = ["chain", "local-store", "cow-api"]
+optional = ["http"]
+
+[capabilities.http]
+allow = ["api.cow.fi"]
+
+[[subscription]]
+kind     = "log"
+chain_id = 1
+address  = "0xC92E8bdf79f0507f65a392b0ab4667716BFE0110"  # ComposableCoW
+
+[[subscription]]
+kind     = "block"
+chain_id = 1
+```
+
 ## Documentation
 
 The `docs/` directory contains the design corpus:

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/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 },
+});

crates/nexum-engine/src/cli.rs

@@ -0,0 +1,46 @@
+//! Manual CLI parser. Kept hand-rolled (instead of pulling clap) because
+//! the surface is small and unlikely to grow in 0.2.
+
+use std::path::PathBuf;
+
+/// Parsed CLI surface.
+///
+/// `nexum-engine [<wasm-path> [<manifest-path>]] [--engine-config <path>]`
+///
+/// Positional `<wasm-path>` is a backwards-compat shortcut that
+/// synthesises a one-module engine config. Production deployments pass
+/// `--engine-config` and declare modules in TOML.
+#[derive(Debug, Default)]
+pub struct Cli {
+    pub wasm: Option<PathBuf>,
+    pub manifest: Option<PathBuf>,
+    pub engine_config: Option<PathBuf>,
+}
+
+impl Cli {
+    pub fn parse() -> Self {
+        let mut args = std::env::args().skip(1);
+        let mut cli = Self::default();
+        let mut positional = Vec::new();
+        while let Some(arg) = args.next() {
+            match arg.as_str() {
+                "--engine-config" => cli.engine_config = args.next().map(PathBuf::from),
+                "-h" | "--help" => {
+                    eprintln!(
+                        "usage: nexum-engine [<wasm-path> [<manifest-path>]] \
+                         [--engine-config <path>]"
+                    );
+                    std::process::exit(0);
+                }
+                _ => positional.push(arg),
+            }
+        }
+        if let Some(p) = positional.first() {
+            cli.wasm = Some(PathBuf::from(p));
+        }
+        if let Some(p) = positional.get(1) {
+            cli.manifest = Some(PathBuf::from(p));
+        }
+        cli
+    }
+}

crates/nexum-engine/src/engine_config.rs

@@ -0,0 +1,119 @@
+//! 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 <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, module.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
+/// `module.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 `module.toml`. Defaults to `<path-parent>/module.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)
+}