Introduction

audience: all

Zipnet is an anonymous broadcast channel for bounded sets of authenticated participants. A group of clients publish messages onto a shared log; nobody — not even the operators of the infrastructure, acting individually — can tell which client authored which message.

This book documents a working prototype of ZIPNet built as a mosaik-native application. The protocol follows Rosenberg, Shih, Zhao, Wang, Miers, and Zhang (2024) with a small, grep-able set of v1 simplifications tracked in Roadmap to v2. The motivation for running this shape in Flashbots’ infrastructure is laid out in Network-anonymized mempools — zipnet is one concrete realisation of the direction sketched there.

The source tree lives at github.com/flashbots/zipnet; this book is rendered from book/src/ in the same repo.

What zipnet is for

The canonical motivating case is an encrypted mempool: TEE-attested wallets seal transactions and publish them through zipnet; builders read an ordered log of sealed transactions; no party — not even a compromised builder — can link a transaction back to its author until on-chain execution reveals whatever the transaction itself reveals. The encryption layer (threshold decryption, TEE unsealing, plaintext-if-you-want) sits on top; zipnet supplies the anonymous, ordered, sybil-resistant publish channel underneath.

Other deployments in the same shape:

Permissioned order-flow auctions. Whitelisted searchers publish intents; builders bid without knowing which searcher sent what.
Anonymous governance signalling. Token-holder wallets cast signals a delegate can tally without learning which wallet sent any given one.
Private sealed-bid auctions. Bidders publish; outcomes are public; bid-to-bidder linkage is cryptographic.

What zipnet uniquely provides across these:

Sender anonymity within an attested set. A compromised reader cannot tie a message back to its author unless every committee operator colludes (any-trust).
Shared ordered view. Every subscriber sees the same log in the same order.
Sybil resistance. Only TEE-attested clients can publish.
Censorship resistance at the publish layer. Readers cannot drop messages from specific authors because authorship is unlinkable.

The deployment model in one paragraph

Zipnet runs as one mosaik-native organism among many on a shared mosaik universe — a single NetworkId (zipnet::UNIVERSE) that hosts zipnet alongside signers, storage, oracles, and anything else that composes the same way. An operator stands up a deployment by pinning a zipnet::Config — a short namespaced name (e.g. acme.mainnet) plus a shuffle window and a 32-byte init salt — and publishing it alongside the datum schema. Multiple deployments coexist on the same universe, each with its own committee, ACL, and round parameters. Consumers open typed handles against a deployment with three one-liners: Zipnet::<D>::submit(&network, &ACME_MAINNET), Zipnet::<D>::receipts(&network, &ACME_MAINNET), and Zipnet::<D>::read(&network, &ACME_MAINNET). There is no on-network registry; the operator publishes the Config (and, if TDX-gated, the committee MR_TD) via release notes or docs, and consumers compile it in.

The full rationale is in Designing coexisting systems on mosaik.

Three audiences, three entry points

This book is written for three distinct readers. Every page declares its audience on the first line and respects that audience’s tone. Pick the one that matches you:

Developers — external devs whose Rust agent publishes into, or reads from, a zipnet deployment somebody else operates. Start at Quickstart — publish and read.
Operators — devops staff deploying and maintaining deployments. Not expected to read Rust. Start at Deployment overview then Quickstart — stand up an instance.
Contributors — internal devs (senior Rust engineers with distsys and crypto background) extending the prototype itself. Start at Designing coexisting systems on mosaik then Architecture.

See Who this book is for for the tone conventions each audience is held to.

What this prototype is

A permissioned, any-trust broadcast system: anonymity is preserved as long as at least one committee server is honest; liveness requires every committee server to be honest (in v1).
Real cryptography — X25519 Diffie–Hellman, HKDF-SHA256, AES-128-CTR pad generation, blake3 falsification tags, ed25519 peer signatures (via iroh).
Real consensus — the committee runs a modified Raft through mosaik’s Group<CommitteeMachine>.
Real networking — the aggregator and the committee communicate through mosaik typed streams; discovery is gossip + pkarr + mDNS; transport is iroh / QUIC.

What this prototype is not

A production anonymous broadcast system. Ratcheting, footprint scheduling, cover traffic, multi-tier aggregators, and TDX-only builds tracked in the Roadmap to v2 are all deferred.
Byzantine fault tolerant. Mosaik is explicit about this; zipnet inherits the assumption. See Threat model for the precise statement.

Layout of the source tree

crates/zipnet/
  Cargo.toml
  build.rs          optional TDX image builder (feature-gated)
  src/
    lib.rs          SDK facade — Zipnet::<D>::{submit,receipts,read},
                     Config, UNIVERSE, ShuffleDatum, errors.
    main.rs         operator binary — `zipnet {server|aggregator|client}`
                     (+ optional `ingest` subcommand under --features ingest)
    proto/          pure wire types + crypto primitives (no async, no I/O)
    shuffler/       Algorithms 1/2/3 as pure functions
    node/           mosaik integration — declare! items, committee state
                     machine, ticket validator, role event loops
    ingest.rs       optional REST gateway role (feature-gated)
  tests/
    e2e.rs          node-level integration test
    sdk_e2e.rs      SDK-level integration test
book/               this book

See Crate map for the dependency graph and purity boundaries.

Keyboard shortcuts