Skip to content

runtime: multi-module supervisor + block/log event loop#9

Draft
brunota20 wants to merge 3 commits into
nullislabs:mainfrom
bleu:feat/supervisor-event-loop
Draft

runtime: multi-module supervisor + block/log event loop#9
brunota20 wants to merge 3 commits into
nullislabs:mainfrom
bleu:feat/supervisor-event-loop

Conversation

@brunota20
Copy link
Copy Markdown

Draft, stacked on top of #8 — the diff includes that PR's commits until #8 lands.

This is the next layer: turns `main` from a single-module bootstrap that fires one test event into a multi-module supervisor that drives the engine off live `eth_subscribe` streams.

Schema additions

`engine.toml` grows `[[modules]]` entries:

```toml
[[modules]]
path = "./modules/twap/twap.wasm"
manifest = "./modules/twap/nexum.toml" # optional; defaults to sibling
```

`nexum.toml` grows `[[subscription]]` entries (tagged enum, matches the schema in `docs/02-modules-events-packaging.md`):

```toml
[[subscription]]
kind = "block"
chain_id = 11155111

[[subscription]]
kind = "log"
chain_id = 11155111
address = "0xfdaFc9d1902f4e0b84f65F49f244b32b31013b74"
event_signature = "0x..."

[[subscription]]
kind = "cron"
schedule = "*/5 * * * *" # parsed + warned; dispatch lands in 0.3
```

Unknown `kind` values surface at load time so a typo does not silently disable an event source. Cron is parsed and logged with a "declared but inert in 0.2" warning per the docs/02 lifecycle.

Multi-module loading

`supervisor::Supervisor::boot` iterates `engine_cfg.modules`, compiles each `.wasm` into its own wasmtime `Store`, runs `_init` with the manifest's `[config]`, and surfaces the subscriptions the event loop will wire. One `Engine` + `Linker` is shared across modules; `cow_pool` / `provider_pool` / `local_store` are cloned into each `HostState`; the per-module namespace comes from `manifest.module.name`.

A positional CLI `` still works for the single-module `just run` path — the supervisor synthesises a one-module config in that case, so backwards compat is preserved.

Event loop

`ProviderPool` gains `subscribe_blocks` + `subscribe_logs` returning boxed alloy streams typed `Result<Header, ProviderError>` and `Result<Log, ProviderError>`.

`main` opens:

  • one shared block subscription per chain id any module asked for, then
  • one log subscription per `(module, filter)` pair,

tags each stream with `chain_id` / `module_name`, and merges via `select_all`. Block events go to every subscribed module; log events go only to the owning module. `on_event` failures surface as `tracing::warn!` (host-error returned by guest) or `tracing::error!` (wasm trap).

SIGINT / SIGTERM (Unix) or ctrl-c (else) exits the loop cleanly.

Out of scope (deliberate, per the 0.3 roadmap)

  • Restart + poison-pill bookkeeping. Failing `_on_event` is logged but the module continues to receive subsequent events. The full Resolve→Load→Init→Run→Restart→Dead lifecycle from `docs/02` lands alongside the `[module.restart]` schema in 0.3.
  • Cron dispatch. Parsed + warned today; tokio-time-driven scheduler in 0.3.
  • Content-addressed resolution. Module `path` is a local filesystem entry in 0.2 — Swarm / OCI / ENS / `[[content.sources]]` from `docs/03` lands in 0.3.

Test surface

`cargo test -p nexum-engine --bins`: 15 passed (one new — empty supervisor returns empty subscription sets). Existing `cow_orderbook` + `provider_pool` + `local_store` tests untouched.

```
cargo fmt --all --check # clean
RUSTFLAGS=-D warnings cargo clippy --all-targets # clean
just run # example.wasm boots through the supervisor,
# exits cleanly with "no [[subscription]]"
```

Open questions

  1. CLI surface. I went with `--engine-config ` + positional ` ` for backwards-compat. If you'd rather drop the positional shortcut and require `engine.toml` in production, easy to strip.

  2. Block dispatch chains-per-stream. Today one block subscription per chain serves every module subscribed to that chain (shared subscription, per the docs/01 "shared subscriptions" line). If you'd rather one subscription per (module, chain) for clearer attribution, the structure carries through — `open_block_streams` is the only change.

  3. Log filter granularity. `[[subscription]] kind="log"` currently accepts `address` (single) + `event_signature` (topic-0). Schema could grow `addresses` (list) and `topics` (full topic-0..3 array) — I kept it small to match the example in docs/02. Happy to extend.

  4. Boundary between supervisor and main. Event-loop logic is in main.rs today (`open_block_streams` / `open_log_streams` / `run_event_loop`). It would fit in `supervisor.rs` for symmetry; left in main to keep the supervisor module focused on per-module concerns. Easy to move.

brunota20 added 3 commits June 1, 2026 14:19
Adds the dependencies the 0.2 host backends need:

- cowprotocol (1.0.0-alpha) for the cow-api submission path
  (OrderBookApi, OrderCreation, OrderUid, Chain).
- alloy-provider / -rpc-client / -transport-ws / -primitives (1.5)
  for the chain JSON-RPC dispatch. The reqwest feature on
  alloy-provider engages connect_http; the pubsub/ws features back
  eth_subscribe-class methods.
- redb (2) for local-store. Same crate cowprotocol's own watch-tower
  picked, so the dep tree does not bifurcate when both are used in
  the same workspace.
- reqwest (0.12, rustls-tls) — direct, so the import survives any
  future cowprotocol feature rearrangement.
- tracing + tracing-subscriber (env-filter + fmt) — replaces the 0.1
  eprintln! debug log so the engine can drop into a structured log
  pipeline without re-instrumenting every host call.
- thiserror (2) — typed error enums in each backend.
- tempfile + wiremock as dev-deps for the host backend tests.

Adds engine.example.toml documenting the [engine] state_dir + per-
chain RPC URLs the chain backend reads at boot; data/ is now
ignored so a local run does not leave the redb file in tree.
Replaces the 0.2 Unsupported stubs with working backends. Each
capability lives in its own host submodule so the trait impls in
main.rs stay thin (dispatch + project the backend's typed error
onto HostError).

cow_api::submit_order
  - Parses the guest's bytes as JSON cowprotocol::OrderCreation.
  - Dispatches via cowprotocol::OrderBookApi::post_order.
  - Returns the assigned OrderUid as a 0x-prefixed hex string.

cow_api::request
  - REST passthrough. The base URL is whichever URL the pool's
    OrderBookApi client carries — so OrderBookApi::new_with_base_url
    overrides (staging, wiremock) flow through transparently.
  - Method/path validated host-side; orderbook 4xx/5xx bodies are
    surfaced verbatim so the guest can decode {errorType,description}.

chain::request
  - Raw JSON-RPC dispatch over an alloy DynProvider opened from
    engine.toml at boot. WebSocket URLs engage pubsub (eth_subscribe);
    HTTP URLs use the HTTP transport. Params are passed as
    serde_json::RawValue so alloy does not re-encode.
  - request-batch falls back to per-call dispatch (same shape as the
    earlier stub but now backed by real RPC).

local_store
  - redb file under engine_config.engine.state_dir.
  - Single shared table. Per-module namespacing is enforced
    host-side via [len:u8][module_name][raw_key] prefix on every
    key. list_keys strips the prefix before returning to the guest.

logging
  - Routes through tracing::event! tagged with module=<namespace>.
  - Engine boot installs an EnvFilter-based subscriber; RUST_LOG
    overrides the engine.toml log_level.

identity / remote-store / messaging / http stay at Unsupported per
the 0.2 roadmap (keystore / Swarm / Waku land in 0.3).

Tests (14, all green):
  - cow_orderbook: pool default chains, unknown-chain typing, REST
    GET passthrough, relative-path resolution, unknown-method
    rejection, submit_order round-trip — last three under wiremock
    so the full HTTP path is exercised without hitting api.cow.fi.
  - provider_pool: empty pool surfaces UnknownChain.
  - local_store: roundtrip, namespace isolation, delete, list_keys
    prefix-stripping, empty-namespace rejection.

End-to-end against modules/example: example.wasm loads under the
new wiring, logs init + on_event through the tracing pipeline.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant