nexum-runtime

Nexum is a WASM Component Model host runtime for web3 modules. It supervises guest components built against the nexum:host WIT world, giving each module a capability-gated view of the host: chain access over JSON-RPC, an allowlisted wasi:http outbound gate, a local key-value store, clocks, and structured logging, with fuel and memory limits enforced per module.

This repository is the leaf of the Nullis runtime stack: it carries no cross-repo dependencies. Downstream repositories (videre, shepherd) build on the SDK and runtime published here.

Layout

• crates/nexum-runtime - the engine host: wasmtime embedding, supervisor, capability providers, metrics.
• crates/nexum-cli - the bare nexum engine binary.
• crates/nexum-launch - shared launch surface (config loading, logging, presets).
• crates/nexum-sdk - the guest-side SDK modules build against.
• crates/nexum-sdk-test - SDK acceptance-test harness.
• crates/nexum-module-macros - proc-macros for module entrypoints.
• crates/nexum-tasks - task lifecycle and graceful shutdown.
• crates/nexum-world - single-source capability and fault-label vocabularies.
• modules/example - minimal reference module.
• modules/examples/ - example modules (balance-tracker, http-probe, price-alert).
• modules/fixtures/ - adversarial test fixtures (clock-reader, env-reader, flaky-bomb, fuel-bomb, memory-bomb, panic-bomb, slow-host, topic-parity).
• wit/nexum-host - the nexum:host WIT package.

Development

The repository pins its toolchain via a Nix flake (Rust 1.94.0, matching CI):

nix develop        # or `direnv allow` once
just build         # engine + all guest wasms
just test          # host engine unit tests
just ci            # full CI series locally (fmt, clippy, doc, wasms, nextest, doctests)

Without Nix, any Rust 1.94+ toolchain with the wasm32-wasip2 target, cargo-nextest, and just works.

Running a module

just run           # builds the example module and runs the engine with it

The engine takes a component wasm and its component.toml (dependencies + config). The manifest is mandatory: pass its path, or ship a component.toml next to the wasm. Every manifest must declare a [dependencies] table; an empty one grants nothing. Every manifest must also declare a [component].name that is not blank. The engine uses the name as the state namespace, and it refuses a missing, empty, or whitespace-only name.

cargo run -p nexum-cli -- target/wasm32-wasip2/release/example.wasm modules/example/component.toml

A module that declares a block or event trigger needs its chain declared in engine.toml, or the engine refuses to boot. The smallest working stanza is:

[chains.11155111]
rpc_url = "http://localhost:8545"

http(s):// URLs are not dialled at boot; ws(s):// URLs are. The example module declares no triggers, so just run needs no engine.toml; the modules under modules/examples/ and modules/fixtures/ do.

Component integrity

A manifest may pin its artifact with digest = "sha256:<64 hex chars>" in [component] (one sha256sum of the .wasm). A present pin is strictly verified against the loaded bytes before compilation; a mismatch or a malformed pin refuses the boot. An absent pin loads with a warning that logs the computed digest; set require_component_digest = true under [engine] in engine.toml to make an absent pin a boot error. An operator may pin the same artifact independently with digest on its [[modules]] entry in engine.toml; both pins are verified against the loaded bytes, and the warning is silent when the operator pin covers the artifact. The default sibling component.toml lives in the same trust domain as the artifact, so an author-side pin closes accidental drift only. Against a compromised artifact store, set [[modules]].digest, which lives in trusted config; an operator-owned manifest outside the artifact directory via the manifest key on [[modules]] combined with require_component_digest = true closes the same gap.

Licence

AGPL-3.0-or-later. See LICENSE.