Who this book is for

audience: all

The zipnet book has three audiences. Every chapter declares its audience on the first line (audience: users | operators | contributors | both | all) and respects that audience’s conventions. This page is the authoritative description of each audience and the tone we hold ourselves to. New pages must pick one.

Mixing audiences wastes readers’ time and erodes trust. When content genuinely serves more than one group, use both (users + operators, users + contributors, …) or all, and structure the page so each audience gets the answer it came for in the first paragraph.

Users

Who they are. External Rust developers building their own mosaik agents that publish into — or read from — a running zipnet instance. They do not run committee servers or the aggregator; that is the operator’s job. They are integrators, not protocol implementers.

What they can assume.

• Comfortable with async Rust and the mosaik book.
• Already have a mosaik application in mind; zipnet is a dependency, not the centre of their work.
• They bring their own Arc<Network> and own its lifecycle.

What they do not need.

• Protocol theory. A user who wants it can follow the link to the contributor pages.
• An explanation of mosaik primitives. Link the mosaik book instead.
• A committee operator’s view of keys, rotations, or monitoring.

What they care about.

• “What do I import?”
• “How do I bind to the operator’s instance?”
• “What does the operator owe me out of band — universe, instance name, MR_TD?”
• “What does an error actually mean when it fires?”

Tone. Code-forward and cookbook-style. Snippets are rust,ignore, self-contained, and meant to be lifted into the reader’s workspace. Public API surfaces are listed as tables. Common pitfalls are called out inline so the reader does not have to infer them from silence. Second person (“you”) throughout.

Canonical user page. Quickstart — publish and read.

Operators

Who they are. Devops staff deploying and maintaining zipnet instances. They run the committee, the aggregator, and the TDX images. They are the ones the users rely on.

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.

What they do not need.

• The paper. Link it when a term is inherited; do not re-derive.
• Internal crate layering. The operator cares what a binary does, not which crate it lives in.
• Client-side ergonomics. That is the users’ book.

What they care about.

• “What do I run, on what hardware, with what env vars?”
• “How do I know it 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 an instance.

Contributors

Who they are. Senior Rust engineers with distributed-systems and cryptography background, extending the protocol or the code, or standing up a new service on mosaik that reuses zipnet’s deployment pattern.

What they can assume.

• Have read the ZIPNet paper (eprint 2024/1227).
• Have read the mosaik book and are comfortable with Stream, Group, Collection, TicketValidator, the when() DSL, declare! macros.
• Comfortable with async Rust, Raft, DC nets.

What they do not need.

• Re-exposition of the paper. Cite section numbers (e.g. “§3.2”) and move on.
• Primitives covered in the mosaik book. Link it.
• User-level ergonomics unless they drive a design choice.

What they care about.

• “Why is it this shape and not Shape A / B / C / D?”
• “What invariants must hold? Where are they enforced?”
• “What breaks when I bump StateMachine::signature()?”
• “Where do I extend this — which module, which trait, which test?”

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

Canonical contributor page. Designing coexisting systems on mosaik.

Shared writing rules

• No emojis anywhere in the book or the code.
• No exclamation marks outside explicit security warnings.
• Link the paper by section number when inheriting its terminology (e.g. “§3.2 scheduling”), not by paraphrase.
• Link the mosaik book rather than re-explaining mosaik primitives. Our readers can follow a link.
• Security-relevant facts are tagged with a visible admonition, not hidden inline.
• Keep the three quickstarts synchronised. When the public SDK shape, the deployment model, or the naming convention changes, update the users, operators, and contributors quickstarts together, not “this one first, the others later”.