Who this book is for

audience: all

This book has three audiences, the same three the zipnet book is written for, adjusted for the scope of a full block-building lattice rather than a single organism:

• Integrators — external devs whose mosaik agent binds into a running lattice.
• Operators — teams standing up and running a lattice for a chain.
• Contributors — engineers extending the topology itself, or building a new mosaik-native organism that composes with the existing six.

Every chapter declares its audience on the first line (audience: integrators | operators | contributors | both | all) and respects that audience’s conventions. New pages must pick one.

Mixing audiences wastes readers’ time. When content genuinely serves more than one group, use both (integrators + operators, integrators

• contributors, …) or all, and structure the page so each audience gets the answer it came for in the first paragraph.

Integrators (external devs)

Who they are. External Rust developers whose mosaik agent publishes into — or reads from — a running lattice operated by somebody else. Typical roles:

• Searchers — agents that place bundle bids on offer and read the winning bid on the committed round.
• Wallets — agents that submit sealed transactions to zipnet and read refund attestations from tally.
• Rollup / sequencer teams — agents that consume candidate blocks from atelier + relay, or ship sequencer-authored transactions into zipnet.
• Analytics consumers — agents that subscribe to tally for public attribution data.

They do not run committee servers; that’s the operator’s job. They do not modify the organism crates; that’s the contributor’s job. They are integrators.

What they can assume.

• Comfortable with async Rust and the mosaik book.
• Already have a mosaik application in mind; the lattice is a dependency, not the centre of their work.
• They bring their own Arc<Network> and own its lifecycle.
• If they care about submission-layer anonymity, they have read the zipnet book.

What they do not need.

• Protocol theory for the organisms they aren’t using. A searcher integrating against offer should not be forced to read the unseal threshold-decryption spec.
• An operator’s view of keys, rotations, TDX image builds.
• A re-exposition of mosaik primitives.

What they care about.

• “Which organisms does my use case touch?”
• “What do I import? What LatticeConfig do I compile in?”
• “How do I bind to the operator’s lattice?”
• “What does the operator owe me out of band — universe, instance name, MR_TDs, the six organism Configs?”
• “What does an error actually mean when it fires?”

Tone. Code-forward and cookbook-style. Snippets are rust,ignore, self-contained, meant to be lifted. Public API surfaces are listed as tables. Common pitfalls are called out inline. Second person (“you”) throughout.

Canonical integrator page. Quickstart — submit, bid, read.

Operators

Who they are. Teams deploying and maintaining a lattice. In the common case a single operator runs every organism in a lattice; in the Phase 2 shape multiple operators co-run the atelier organism (each contributes committee members) while one operator drives the rest. The book treats both cases; page headers note when a procedure only applies to one.

What they can assume.

• Familiar with Linux ops, systemd units, cloud networking, TLS, Prometheus.
• Comfortable reading logs and dashboards.
• Not expected to read Rust source. A Rust or protocol detail that is load-bearing for an operational decision belongs in a clearly marked “dev note” aside that can be skipped.
• Familiar with the block-building vocabulary — PBS, order flow, relays, sequencers on L2, TDX, MR_TD. Not expected to have read the mosaik book; the operator pages link it when needed.

What they do not need.

• Organism internals. They care what a binary does, not which module it lives in.
• Integrator-side ergonomics. That’s the integrators’ book.
• The paper-by-paper cryptographic derivations. Link, don’t re-derive.

What they care about.

• “What do I run, on what hardware, with what env vars?”
• “How many committee members per organism? What happens if one dies?”
• “How do I know my lattice is healthy?”
• “How do I rotate secrets / retire an instance / upgrade an image?”
• “What page covers the alert that just fired?”

Tone. Calm, runbook-style. Numbered procedures, parameter tables, one-line shell snippets. Pre-empt the obvious “what if…” questions inline. Avoid “simply” and “just”. Every command should either be safe to run verbatim or clearly marked as needing adaptation.

Canonical operator page. Quickstart — stand up a lattice.

Contributors (internal devs)

Who they are. Senior Rust engineers with distributed-systems + cryptography background, extending the topology itself, implementing an organism crate, or standing up a seventh organism that composes with the existing six.

What they can assume.

• Have read the mosaik book, the zipnet book, and the zipnet CLAUDE.md conventions.
• Comfortable with async Rust, modified Raft, threshold cryptography, TDX attestation flows, and PBS-adjacent block- building vocabulary.
• Familiar with at least one existing block-building system (BuilderNet, vanilla MEV-Boost, a rollup sequencer).

What they do not need.

• Re-exposition of mosaik primitives or zipnet conventions. Link and move on.
• Integrator ergonomics unless they drive a design choice.
• Motivation for why we want decentralized block building. The Flashbots Writings cover that; we’re downstream.

What they care about.

• “Why this decomposition into six organisms and not four, or ten?”
• “What invariants must each organism hold? Where are they enforced?”
• “How does composition happen across organisms without creating cross-Group atomicity that mosaik does not support?”
• “What breaks if I change an organism’s StateMachine::signature()?”
• “Where do I extend this — which organism, which trait, which test?”
• “How does the shape generalise to an L2 sequencer? To cross-chain bundles?”

Tone. Dense, precise, design-review style. ASCII diagrams, pseudocode, rationale. rust,ignore snippets and structural comparisons without apology.

Canonical contributor page. Designing block-building topologies on mosaik.

Shared writing rules

• No emojis anywhere in the book.
• No exclamation marks outside explicit security warnings.
• Link the mosaik and zipnet books rather than re-explaining their primitives.
• Security-relevant facts are tagged with a visible admonition, not hidden inline.
• Keep the three quickstarts synchronised. When the lattice shape, an organism’s public surface, or the handshake model changes, update integrators, operators, and contributors quickstarts together, not “this one first, the others later”.
• Use the terms in Glossary consistently. Do not coin synonyms for “lattice”, “organism”, “universe”, “deployment” mid-page.