pkg mosaik · lang rust ≥ 1.89 · net quic · iroh · mdns · dht · stage stage 1 / primitives

mosaik

A Rust runtime for building self-organizing, leaderless distributed systems. Drop binaries on arbitrary machines — they find each other, infer the data-flow graph, and converge.

Read the docs → View source $ cargo add mosaik

No central coordinator. No manual topology. No orchestration glue.
Give a node a NetworkId — it will find the rest.

from the mosaik manifesto

I · The problem

Modern infrastructure is stitched together by orchestration.

Manifests, sidecars, service meshes, schedulers, operators, templates, and the quiet tax of DevOps glue holding it all in place. Distributed systems inherit not only the machinery but the assumption that a central plane must arrange them.

Mosaik rejects that assumption for the case where it was never necessary: permissioned networks of honest nodes — for example, L2 infrastructure operated by a single organization, where participants are trusted but the system is still distributed.

What mosaik removes

Orchestrators. Topology templates. Service-mesh sidecars. Leader election scripts. Static peer lists. Configuration bundles that drift. The operational weight of coordinating who-talks-to-whom.

What mosaik provides

Peer discovery via Mainline DHT and mDNS. Typed pub/sub streams over QUIC. Raft consensus tuned for trusted members. Replicated data structures. Hardware-attested identity via TDX. All composable from a single Network handle.

◇ ◇ ◇

II · Four primitives

Composable subsystems, accessed from a single Network.

Each primitive is independently useful and composes cleanly with the others. Applications pick the surface they need: gossip alone, pub/sub over gossip, consensus groups on top of pub/sub, or replicated collections on top of groups.

01 — Discovery

Gossip, catalog, tags.

Every node broadcasts its presence, capabilities, and the streams/groups/stores it offers. Two protocols compose: signed real-time announcements via iroh-gossip, and bidirectional catalog sync for initial catch-up. Transparent by default; tunable via NetworkBuilder.

let network = Network::new(network_id).await?; // the node is now online and discoverable

02 — Streams

Typed async pub/sub.

Producers and consumers connected across the swarm by Rust type. Predicates, limits, online conditions, per-subscription stats, backpressure.

let p = network.streams().produce::<Block>(); let c = network.streams().consume::<Block>();

03 — Groups

Raft, retuned for trust.

Bonded mesh, non-voting followers, dynamic quorum, parallel log catch-up.

let g = network.groups() .with_state_machine(sm) .join().await?;

04 — Collections

Replicated data structures on top of Groups.

Map, Vec, Set, Cell, Once, PriorityQueue. Each has a writer and any number of readers; every mutation returns a Version readers can await via when().reaches(v).

let map = collections::Map::<String, u64>::new(&network, store_id); map.insert("alice".into(), 100).await?; // readers on other nodes converge automatically

III · A minimal node

Six lines to join a swarm and start streaming.

A node needs only a NetworkId to participate. A secret key is generated on each run, giving the node a unique identity. Peer discovery is automatic via Mainline DHT; an optional bootstrap peer speeds up initial discovery.

examples/hello.rs

use mosaik::*;
use futures::SinkExt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let network_id: NetworkId = "my-app".into();
    let network = Network::new(network_id).await?;

    // the node is now online and discoverable
    println!("node {} is online", network.local().id());

    // create a typed producer — any serializable type works
    let producer = network.streams().produce::<String>();

    // wait for at least one consumer to connect
    producer.when().online().await;

    // send data
    producer.send("hello, world".into()).await?;
    Ok(())
}

◇ ◇ ◇

IV · Design philosophy

Five commitments the system holds to.

i

Not Byzantine fault tolerant.

All members are assumed honest. This simplifies the protocol stack and unlocks higher throughput than BFT equivalents. For stronger integrity, groups can require hardware attestations to cryptographically prove every member runs the expected software.
ii

Self-organizing — no central coordinator.

Nodes discover each other, infer the data-flow topology, elect leaders where needed, and converge to a stable operational state. A NetworkId is the only required input.
iii

Built on modern networking.

QUIC peer-to-peer transport via iroh, with relay support and hole-punching. Mainline DHT plus mDNS for discovery; gossip for catalog convergence.
iv

Composable primitives.

Four subsystems — Discovery, Streams, Groups, Collections — accessible from a single Network handle. Each is independently useful; together they cover a wide range of distributed application patterns.
v

First-class TEE support.

Hardware-attested identity via Intel TDX (AMD SEV-SNP and ARM CCA planned). Access control based on cryptographic proof of the software running on each node, not on operator-held keys.

V · Roadmap

Three stages, widening concentric circles of trust.

Current · Stage 1

Primitives

Core primitives for building self-organized systems in trusted, permissioned networks.

Discovery · gossip, catalog, tags
Streams · producers, consumers, predicates
Groups · Raft consensus, failover
Collections · replicated data stores
Preferences · latency, geo-proximity ranking
Diagnostics · introspection, metrics

Next · Stage 2

Trust & Privacy

Authorization on stream subscriptions, attested sandbox runtimes, cryptographically scoped trust corridors between groups.

Later · Stage 3

Decentralization & Permissionlessness

Extending beyond trusted single-operator environments — into networks where membership is open and accountability is cryptographic rather than organizational.

VI · Start

Add the crate. Write six lines. Watch the swarm form.

Cargo.toml

# via cargo
cargo add mosaik

# or in Cargo.toml
[dependencies]
mosaik = "0.2"

Requires Rust ≥ 1.89. Developed on macOS, tested on Linux. Read through the integration tests for runnable examples of every primitive.

docs docs.mosaik.world → src github.com/flashbots/mosaik → pkg crates.io/crates/mosaik → test scenario tests → demo orderbook example → bug report an issue →