# Overview
Mosaik is a Rust runtime for building self-organizing, leaderless distributed systems. It targets **trusted, permissioned networks** — environments where all participating nodes are controlled by the same organization and assumed to be honest.
## Key Features
| **Self-organizing** | Nodes discover each other via gossip and form the correct topology automatically |
| **Typed pub/sub** | Stream any serializable Rust type between nodes with backpressure and filtering |
| **Raft consensus** | Form consensus groups with leader election and replicated state machines |
| **Replicated collections** | Distributed `Map`, `Vec`, `Set`, `Cell`, `Once`, and `PriorityQueue` with strong consistency |
| **QUIC transport** | Built on [iroh](https://github.com/n0-computer/iroh) for modern, encrypted P2P networking |
| **Relay support** | Nodes behind NAT can communicate via relay servers with automatic hole-punching |
| **TEE support** | First-class Intel TDX support for hardware-attested identity and access control |
## Module Map
Mosaik is organized into five composable subsystems:
```text
┌──────────────────────────────────────────────────────┐
│ Network │
│ Entry point. QUIC endpoint, identity, routing. │
├─────────────┬─────────────┬─────────────┬────────────┤
│ Discovery │ Streams │ Groups │Collections │
│ Gossip & │ Typed │ Raft │ Replicated │
│ peer │ pub/sub │ consensus │ Map, Vec, │
│ catalog │ channels │ groups │ Set, Reg, │
│ │ │ │ Once, DEPQ │
└─────────────┴─────────────┴─────────────┴────────────┘
```
### Network
The entry point to the SDK. Creates the QUIC endpoint, manages node identity (derived from a secret key), and composes all subsystems via ALPN-based protocol multiplexing.
### Discovery
Gossip-based peer discovery. Maintains a **catalog** — a synchronized view of all known peers, their capabilities (tags), and their available streams and groups. Uses two complementary protocols: real-time gossip announcements and full catalog synchronization for catch-up.
### Streams
Typed, async pub/sub data channels. Any Rust type implementing `Serialize + DeserializeOwned + Send + 'static` can be streamed. Producers publish data; consumers subscribe. Discovery automatically connects matching producers and consumers across the network.
### Groups
Consensus groups coordinated by a modified Raft consensus protocol. Nodes sharing a group key form a cluster, elect a leader, and replicate commands through a shared log. Custom state machines define application logic that runs deterministically on all group members.
### Collections
Higher-level replicated data structures built on Groups. Each collection (`Map`, `Vec`, `Set`, `Cell`, `Once`, `PriorityQueue`) creates its own Raft group with a specialized state machine.
### TEE
Provides first-class support for Trusted Execution Environments. Nodes running inside a TEE (currently Intel TDX) can generate hardware-signed attestation tickets that prove their software identity. Other nodes validate these attestations before accepting connections — enabling cryptographic access control without out-of-band coordination.
## Design Decisions
### Trusted Network Assumption
Mosaik is **not** Byzantine fault tolerant. All nodes are assumed to be honest and correctly implementing the protocol. This assumption enables:
- Simpler consensus (no need for 2/3 supermajority)
- Higher throughput (fewer message rounds)
- Simplified state sync (no fraud proofs needed)
For stronger integrity guarantees, groups can optionally require hardware attestations via `TicketValidator`s. When combined with TEE enclaves such as Intel TDX, this provides cryptographic proof that every group member is running the expected software, hardening the trust model against compromised or tampered nodes.
This makes mosaik ideal for infrastructure controlled by a single organization, such as L2 chains, internal microservices, or distributed compute clusters.
### Built on iroh
Mosaik uses [iroh](https://github.com/n0-computer/iroh) for its networking layer, which provides:
- **QUIC transport** — multiplexed, encrypted connections
- **Relay servers** — NAT traversal for nodes behind firewalls
- **mDNS** — optional local network discovery
- **Endpoint identity** — public keys as node identifiers