Introduction

audience: all

This book specifies a composition layer above mosaik’s existing rungs: a shape for naming an operator-selected slice of the mosaik universe and presenting it to integrators through one handshake token, along with four specified basic services that operator coalitions recur to.

A government (abbreviated gov) denotes the composition unit. The term is used in a narrow, service- offering sense — a gov offers services, it does not compel. It does not tax, does not admit or exclude citizens, does not override operators. The non-authority stance is load-bearing for the trust composition and is restated wherever the word’s ordinary connotation of compulsion could mislead.

A gov is identified by one GovConfig fingerprint and composes three kinds of citizen:

• Lattices — operator-scoped mid-rung compositions of organisms. Builder specifies the first class of lattice: six organisms under one LatticeConfig for one EVM chain’s block-building pipeline. Other classes may follow their own proposals; nothing here assumes a lattice is a block-building lattice.
• Standalone organisms — mosaik-native services with a narrow public surface living directly on the shared universe: oracles, attestation fabrics, identity substrates, data-availability shards, reputation organisms, coordination markets, messaging fabrics, analytics pipelines, and further classes as they are proposed.
• Confluences — cross-citizen organisms introduced by this rung. A confluence’s Config fingerprint folds two or more citizen fingerprints (lattices, organisms, or both), and its public surface coordinates across them.

Govs do not own what they reference; they name a set of citizens under one handshake token so integrators, operators, and confluences can address the composition as a unit. Every citizen and every gov lives on the same mosaik universe.

Basic services

The blueprint specifies four basic services a gov may ship. Each is a shape, not a requirement: a gov ships zero, one, or all four, and whichever it ships has the shape defined here so that a service named “Atlas” in one gov provides the same interface and guarantees as “Atlas” in another.

• Atlas — a directory of citizens with operator metadata.
• Almanac — a shared clock and sequence beacon for confluences that need cross-citizen timing.
• Chronicle — a tamper-evident audit log of gov actions: publications, rotations, retirements.
• Passport — optional citizenship tokens a citizen may accept. Never required for a citizen to operate.

Full specifications are in Basic services.

Domain scope

Block-building is the first fully-specified domain for the mosaik runtime (builder). It is not the only one. The universe is an open surface; any service built from mosaik’s primitives (Stream, Group, Collection, TicketValidator) can live on it. Plausible additional categories, each realised as one or more organisms:

• Attestation fabrics aggregating TEE quotes or running cross-vendor attestation transcripts.
• Signal and oracle grids publishing attested price or event feeds.
• Data-availability shards serving commitments and retrieval proofs under their own committee admission.
• Identity and PKI substrates issuing, rotating, or revoking identities under ticket-gated roots.
• Reputation and credit organisms.
• Coordination markets — prediction, allocation, and non-block auction-like organisms.
• Messaging and pub-sub fabrics with attested delivery.
• Analytics and indexing pipelines publishing derived views across citizens.
• Non-EVM settlement lattices following builder’s pattern but rebuilt against other domain constraints.

The list is illustrative. The blueprint does not bless a fixed catalog; each category arrives with its own proposal.

Fixed shapes, open catalogs

The central discipline: fix the shapes, leave the catalogs open.

Specified:

• The GovConfig struct and its derivation rules.
• The four basic-service shapes: their Config signatures, public surfaces, and derivation under GOV_ROOT.
• Citizenship-by-reference — citizens are referenced, not re-derived; a citizen belongs to many govs without churning its identity.
• The non-authority rules — a gov does not gate citizens’ ACLs, does not issue tickets on their behalf, does not override their operators.

Left open:

• Whether any given gov ships any basic services. A gov with zero services is valid.
• The catalog of confluences beyond the four basic services. Each commissioned confluence arrives when a cross-citizen problem forces it.
• The catalog of standalone-organism categories and lattice classes. New categories arrive with their own books.
• Heavy-gov primitives — laws, taxation, judiciary, enforceable policies over citizens. Explicitly deferred. Any future heavy-gov proposal must restate the non-authority rules and rebuild the trust composition; the current blueprint neither anticipates nor precludes one.
• Inter-gov coordination, governance-of-the-gov, federation contracts — all out of band.

This repository ships a specification, not a runtime. Code samples are specifications, not library calls cargo add resolves today. The discipline is what the blueprint fixes; counts and catalogs are not.

Motivating pressures

Five pressures, none specific to block-building:

• Composition of heterogeneous citizens. As more organisms live on the shared universe, operators need a way to publish “these are the services I run together” without inventing a new handshake per coalition.
• Cross-citizen coordination. Some commits depend on inputs from more than one citizen — an attestation aggregator reading every lattice’s tally, an oracle grid ingesting feeds from both a non-EVM settlement lattice and a cross-chain analytics organism, a prediction market consuming outcomes from two chains. Confluences are the shape for such commits.
• Shared civic services. Operator coalitions repeatedly reinvent the same four services — member directory, shared clock, audit log, optional citizenship token. Specifying the shapes once bounds drift across deployments.
• One handshake token. An integrator binding across three lattices, an attestation organism, a confluence, and the gov’s Atlas compiles one GovConfig and obtains typed handles on all of them — rather than five independent handshakes and five independent trust decisions.
• Operator federation. Teams coordinating a set of citizens (every chain in a superchain stack, every oracle feed in a region, every organism in an ecosystem) need a naming unit for that coordination without that name becoming a supra-citizen authority.

None of these requires re-deriving what a lattice or organism is. The gov layer leaves every referenced citizen unchanged and composes them.

Gov identity in one paragraph

A gov is identified by a GovConfig that folds every root input into one deterministic fingerprint: the gov’s instance name, an ordered set of LatticeConfig fingerprints, an ordered set of standalone-organism references, and an ordered set of ConfluenceConfig fingerprints (including any basic-service confluences). Govs live on the shared mosaik universe. Integrators compile in a GovConfig and obtain handles on any citizen or confluence from one Arc<Network>; operators publish the GovConfig together with the set of MR_TDs or other attestation pins. A gov has no state of its own — it is a naming and composition unit, not a Group, Stream, or Collection.

Full rationale is in Designing governments on mosaik.

What this blueprint provides

• A single handshake token for a multi-citizen composition. One GovConfig yields compile-time bindings to every lattice, standalone organism, and confluence the gov composes.
• A discipline for commissioning a new confluence. Fixed shape (content + intent addressed Config, narrow public surface, ticket-gated ACL); open catalog.
• A discipline for composing standalone organisms. Any organism with a Config fingerprint is referenced in a gov’s organisms slice without identity change.
• Four basic-service shapes. Each specified, each optional for any given gov.
• Stable composition semantics. A citizen referenced by several govs retains one canonical identity; its operators do not re-issue tickets, and integrators bonded directly to it need not know which govs include it.
• An explicit atomicity boundary. The gov layer inherits mosaik’s no-cross-Group-atomicity constraint end-to-end.

What this blueprint does not provide

• Heavy-gov primitives. No laws, taxation, judiciary, or enforceable policies over citizens.
• A fixed catalog for any open-ended category. No count of confluences beyond the four basic services, no list of organism categories, no blessed set of lattice classes.
• Cross-gov atomicity. Govs coexist on the shared universe; they do not participate in cross-gov consensus.
• A supra-citizen authority. A gov does not issue tickets on behalf of its citizens, does not override their operators, and cannot unilaterally retire a citizen.
• A canonical implementation. The blueprint specifies shapes; implementations land as follow-on proposals when commissioned.

Three audiences, three entry points

Every page declares its audience on the first line and respects that audience’s conventions:

• Integrators — agents binding across citizens or into a confluence or basic service. Start at Quickstart — bind many citizens from one agent.
• Operators — teams running a confluence, standalone organism, basic service, or a federated multi-citizen composition. Start at Gov overview and Quickstart — stand up a gov.
• Contributors — engineers commissioning a new confluence, a new class of mid-rung composition, a new basic service, or extending the gov-level composition model. Start at Designing governments on mosaik and Anatomy of a gov.

See Who this book is for for audience conventions.

Vocabulary ladder

  mosaik primitives            Stream, Group, Collection, TicketValidator
  composed into
    organisms                  one Config fingerprint, narrow public surface
  composed into
    (optional) lattices        a fully-specified mid-rung composition
                               (block-building, per builder; other classes
                                may follow)
  composed into
    governments                N lattices + M organisms + K confluences
                               (including any basic services) under one
                               GovConfig

Each rung:

• Reuses the rung below verbatim — no re-derivation, no shadow identifiers, no alternative ACL model.
• Adds one compositional idea: narrow public surface (organisms), within-lattice derivation (lattices), heterogeneous citizen composition plus basic services (govs).
• Is operator-scoped. Discovery is compile-time fingerprint reference at every rung; no on-network registry is load-bearing.

The universe (the mosaik NetworkId) is the only mandatory bottom rung. Each upper rung is optional composition; an integrator who needs only one organism does not compile in a LatticeConfig or GovConfig. The lattice rung is optional: a gov may contain zero lattices and compose purely standalone organisms and confluences, or zero organisms and only lattices. Both shapes are valid.

Layout of this book

book/src/
  introduction.md              this page
  audiences.md                 audience conventions
  integrators/                 for agents binding across citizens and confluences
  operators/                   for teams running a gov
  contributors/                for engineers designing or extending govs
  appendix/                    glossary