Architecture
Nunchi SDK supplies reusable Rust modules between Commonware's distributed-systems primitives and your application. The modules define chain and market mechanics. Your team chooses the rules and builds the product around them.
Three layers
| Layer | Responsibility |
|---|---|
| Commonware | Consensus, peer networking, authenticated storage, asynchronous runtime, and cryptographic primitives |
| Nunchi SDK | Asset and account models, authority, data modules, market matching, runtime composition, and example chains |
| Your application | Product rules, market parameters, risk limits, interfaces, governance, deployment, and operations |
The SDK layer is a policy engine: its modules implement financial and network rules in software.
Who operates the network
Your organization configures and publishes the chain software. Network participants run nodes under your chosen validator and governance model. Nunchi supplies the SDK. The Authority module provides a starting point for proof-of-authority configuration.
Compose an application
The Coins example pairs CoinsRuntime with ClobExtension through nunchi_chain::Application. The runtime connects module operations and state; the extension adds order-book matching to consensus.
Your application connects matching to settlement and product-specific risk rules. Oracle records need application rules for publisher trust and data interpretation. See module boundaries before extending the example.
The Examples guide also covers a bridge chain and a custom module's transaction, ledger, state, and RPC components.
Commonware foundation
The SDK uses Commonware 2026.7.0. These versioned references cover the main primitives:
| Crate | Purpose |
|---|---|
commonware-actor | Message-passing between concurrent components |
commonware-runtime | Asynchronous execution and deterministic testing |
commonware-p2p | Peer networking |
commonware-consensus | Consensus constructions, including Simplex |
commonware-storage | Authenticated storage structures |
commonware-glue | Integrations between lower-level primitives |
runtime::tokio provides asynchronous execution; runtime::deterministic provides repeatable scheduling for tests and simulations. Use the deterministic runtime to reproduce concurrent behavior and exercise failure scenarios.
For upgrades, consult the release-specific compatibility notes, including peer-version and state-sync constraints.