Designing governments on mosaik

audience: contributors

This chapter extends the design intros of zipnet and builder from one organism → one lattice → one government: a named composition of coexisting mosaik citizens — block-building lattices, standalone organisms (oracles, attestation fabrics, identity substrates, analytics pipelines, …), cross- citizen organisms (confluences), and up to four basic services (Atlas, Almanac, Chronicle, Passport).

The reader is assumed familiar with the mosaik book, the zipnet book, the builder book, and the two design intros cited above. This chapter does not re-derive content + intent addressing, the narrow-public-surface discipline, the shared-universe model, or within-lattice derivation; it uses them.

Stance

The word government is loaded. This blueprint uses it narrowly: a gov offers services; it does not compel. It does not tax, admit or exclude citizens, issue tickets on their behalf, or override their operators. The non- authority stance is load-bearing for the trust composition and is restated wherever prose could read as compulsion; the rule collapses to:

A gov offers services; it does not compel.

Every design choice in this chapter follows from it.

The problem, at N citizens

Builder composes six organisms under one LatticeConfig for one EVM chain, solving “one end-to-end pipeline for one chain” cleanly. It does not solve:

Cross-citizen coordination at scale. An agent operating across ten block-building lattices holds ten LatticeConfigs; one additionally correlating across an oracle and an attestation organism holds twelve handshakes. Driver code pairs facts across citizens, reconciles partial observations, and recovers outcome correlators. The same correlator is re-implemented per agent. The builder book’s Shape 1 is correct for two or three lattices and an unbounded implementation burden at ten-plus heterogeneous citizens.
Shared attribution. MEV captured on a block of lattice A originating from a searcher bundle submitted on lattice B — or a trade attributed by an analytics organism also reported by an oracle organism — is invisible to each service without explicit wiring. Ad hoc repetition is the same burden, one level deeper, across more boundary kinds.
Consistent cross-citizen observability. Operators running five citizens want one dashboard; analytics integrators want one API. Both want a named composition with a fingerprint that moves in lockstep with what they subscribe to. The Atlas basic service addresses this.
Operator federation. Teams coordinating a set of citizens — every chain in a superchain stack, every oracle feed in a region, every ecosystem’s bonded organisms — need a naming unit for that coordination without the unit becoming a supra-citizen authority.
Durable provenance. Decisions outlive any one GovConfig. An operator coalition needs a tamper- evident record of its own publications, rotations, and retirements — the Chronicle basic service addresses this.

Promoting “a set of citizens” to an in-consensus group collapses every citizen’s trust boundary into one committee. Builder rejected that shape at the organism level; promoting it one rung higher inherits the same objection at higher cost, and violates the non-authority stance.

The correct rung is a fingerprint above the citizens that names them for discovery, basic services, and confluence derivation — without consensus, state, or admission authority. That fingerprint is a gov.

Two axes of choice

Same two axes zipnet picked and builder reaffirmed. Each rung of the ladder inherits the zipnet conclusion; the gov rung does too.

Network topology. Does a gov live on its own NetworkId, or share a universe with every other mosaik service?
Composition. How do citizens and confluences reference each other without creating cross-Group atomicity mosaik does not support — and, now, without creating cross-gov atomicity either?

The blueprint chooses shared universe + citizenship-by- reference + no cross-Group, cross-citizen, or cross-gov atomicity. The three choices are independent; each has a narrow rationale.

Shared universe (unchanged)

builder::UNIVERSE = unique_id!("mosaik.universe") — the same constant zipnet and builder use. Every gov, lattice, standalone organism, confluence, and basic service lives on it. Different govs coexist as overlays of Groups, Streams, and Collections distinguished by their content + intent addressed IDs. An integrator caring about three govs holds one Network handle and three GovConfigs. Because govs reference citizens rather than re-deriving them, an integrator already bonded to some of the included citizens observes no duplicate identity.

The alternative — one NetworkId per gov, mirrored all the way up — is rejected on the same grounds the zipnet book rejects Shape A: operators already pay for one mosaik endpoint, services compose, and one additional endpoint per gov would turn the gov into a routing device, which is not the rung’s function.

Citizenship-by-reference

A GovConfig is a parent struct. Unlike a LatticeConfig (which nests six organism Configs and hashes them together), a GovConfig references existing citizen fingerprints without re-deriving the citizens’ organism IDs. This is the key decision of the gov rung:

  GOV             = blake3("gov|" || gov_name)
  GOV_LATTICES    = ordered set of LatticeConfig fingerprints
  GOV_ORGANISMS   = ordered set of OrganismRef fingerprints
  GOV_CONFS       = ordered set of ConfluenceConfig fingerprints
                    (basic services + commissioned confluences)
  GOV_ROOT        = blake3(
                      GOV
                      || GOV_LATTICES
                      || GOV_ORGANISMS
                      || GOV_CONFS
                    )

Here GOV_LATTICES[i] is the fingerprint builder already defines for lattice i — not a re-derivation. Likewise GOV_ORGANISMS[j] is the fingerprint the standalone organism j publishes in its own handshake. Builder’s lattice identity is:

  LATTICE(i) = blake3("builder|" || instance_name || "|chain=" || chain_id)
  + every organism's Config fingerprint inside that lattice

A gov neither modifies LATTICE(i) nor the organism roots under it, nor the Config of any standalone organism it references. A citizen referenced by three govs is one citizen; its operators issue tickets once, its integrators compile it in once, and its GroupIds are stable across gov memberships.

Rationale for by-reference over by-containment:

Citizens predate govs. The first production organism and first production lattice ship before the first gov. An integrator already bonded to a specific citizen must not have to re-bond when an operator composes that citizen into a new gov.
Citizens outlive govs. Gov membership is a composition choice and changes; citizen identity is an operator-level commitment. Govs must not force churn.
Citizens belong to multiple govs. The shared- universe choice implies a citizen may be referenced from several govs simultaneously — one per operator coalition, one per analytics vendor, one per ecosystem grouping. Re-derivation would force a cartesian product of IDs.
Govs must not become admission authorities. If a gov derived citizen IDs, joining a gov would force re- issuing tickets; the gov would own every referenced citizen’s ACL. That is heavy-gov by the back door and the blueprint refuses it.

Confluences — where govs do derive

Confluences and basic services are the places a gov derives new IDs. Each is an organism whose public surface serves readers and writers across citizen boundaries; each state machine commits facts depending on inputs from more than one citizen (or, for Atlas, metadata about the citizens).

A confluence’s identity derives like any other organism, with one addition: its content fingerprint folds in the ordered set of citizen fingerprints it spans.

  CONFLUENCE_ROOT = GOV_ROOT.derive("confluence").derive(c_name)
  SERVICE_ROOT    = GOV_ROOT.derive("service").derive(s_name)

  <root>_committee = blake3(
      <root>
      || ordered LatticeConfig fingerprints it spans
      || ordered OrganismRef fingerprints it spans
      || content_fingerprint
      || acl_fingerprint
  ).derive("committee")

The distinction between "confluence" and "service" in the derivation path is cosmetic; "service" is reserved for the four specified basic services (basic services). Commissioned confluences use "confluence".

The derivation produces the usual failure mode: a confluence misconfigured against the wrong gov, or the wrong set of citizens, derives a disjoint GroupId and surfaces as ConnectTimeout rather than silent cross- citizen mis-bond. A confluence therefore cannot be moved from one gov to another — a different GOV_ROOT yields a different confluence identity. Operators who want to achieve that deploy a second confluence.

No cross-Group, cross-citizen, or cross-gov atomicity

Every rung below refuses cross-Group atomicity. The gov rung refuses cross-citizen and cross-gov atomicity by the same argument:

Cross-Group (one citizen, two organisms) — refused by builder and by every organism’s own design. Organisms subscribe to each other’s public surfaces; there is no atomic multi-organism commit.
Cross-citizen (one gov, two citizens) — refused by this blueprint. Confluences read public surfaces of the citizens they span; their state machine commits its own facts. A confluence never forces two citizens to commit atomically.
Cross-gov (two govs) — refused by this blueprint. Govs do not coordinate in consensus. A use case for cross-gov coordination resolves either to an integrator spanning govs or to a new confluence whose content fingerprint folds gov fingerprints in place of citizen fingerprints — at which point the “govs” are citizens of a super-gov and the rung ladder extends.

Fixed shapes, open catalogs

The blueprint’s central discipline; restated because every downstream choice flows from it.

Specified

The GovConfig struct and derivation rules. Every gov has this shape; every gov’s identity is computed this way.
The ConfluenceConfig and OrganismRef structs. Every confluence and every standalone-organism reference has these shapes.
The four basic-service shapes (Atlas, Almanac, Chronicle, Passport). Every instance of “Atlas” in any gov has the same Config signature, public surface, and derivation. Same for the other three. Specification in basic services.
Citizenship discipline — by-reference, multi-gov-compatible, no re-derivation.
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 commissioned confluences beyond the four basic services. Each arrives when a cross- citizen problem forces it.
The catalog of standalone-organism categories and lattice classes. New categories arrive with their own books. Block-building lattices are the first specified class; attestation fabrics, oracle grids, DA shards, and other categories follow their own proposals.
Inter-gov coordination. Govs coexist on the shared universe; a concrete need for coordination earns its way in through a fresh proposal.
Governance of the gov itself. Who approves GovConfig bumps, how operator coalitions form and dissolve, what contracts federations sign — all out of band.

Deliberately deferred (heavy-gov)

A family of primitives the gov metaphor could support and the blueprint refuses:

Enforceable policies over citizens — a GovConfig declaring constraints citizens must satisfy (MR_TD requirements, bond minimums, code-audit attestations).
Taxation — a protocol-level mechanism for the gov to collect fees from citizens’ commits.
Judiciary — a confluence whose commits have protocol-level precedence over individual citizens’, resolving disputes.
Mandatory citizenship — a Passport variant in which absence of a Passport renders a citizen’s commits invalid in the gov’s view.
Legislation — a state machine in the gov that citizens must query and conform to before acting.

Each moves the gov from offering to compelling. Each is a coherent design space, and adopting any one forces the blueprint to restate what the gov is for, rewrite the trust composition, and rebuild every passage that assumes non-authority. Any future heavy-gov proposal lives on its own branch and earns the transition; the current blueprint neither anticipates nor precludes one.

Flag in-source and in-docs as “heavy-gov” when the topic arises so the word’s current scope is unambiguous.

Gov identity

A gov is identified by a GovConfig folding every root input into one deterministic fingerprint. Operators publish the GovConfig as lattice operators publish a LatticeConfig and organism operators publish their own Config; integrators compile it in.

pub struct GovConfig {
    /// Short, stable, namespaced name chosen by the gov
    /// operator (e.g. "ethereum.superchain",
    /// "signals.euro-fx").
    pub name: &'static str,

    /// Ordered set of block-building lattices this gov
    /// composes. Referenced by LatticeConfig fingerprint;
    /// this struct does NOT re-derive any lattice's
    /// organism IDs.
    pub lattices: &'static [LatticeConfig],

    /// Ordered set of standalone organisms this gov
    /// composes — any mosaik organism with a Config
    /// fingerprint living directly on the universe. Held
    /// by reference; the concrete Config type lives in
    /// the organism's own crate.
    pub organisms: &'static [OrganismRef],

    /// Ordered set of cross-citizen organisms the gov
    /// runs (basic services + commissioned confluences).
    /// Each folds a subset of the citizens above into its
    /// own Config fingerprint. Derived under the gov
    /// root.
    pub confluences: &'static [ConfluenceConfig],
}

/// Reference to a standalone organism by role name and
/// Config fingerprint. Not a concrete Config — that lives
/// in the organism's own crate.
pub struct OrganismRef {
    pub role: &'static str,
    pub fingerprint: UniqueId,
}

impl GovConfig {
    /// blake3("gov|" || name || "|" || lattices
    ///         || "|" || organisms || "|" || confluences)
    pub const fn gov_id(&self) -> UniqueId { /* ... */ }

    /// Basic-service lookup helpers. Return Some if the
    /// gov ships that service, None otherwise.
    pub const fn atlas    (&self) -> Option<&ConfluenceConfig> { /* ... */ }
    pub const fn almanac  (&self) -> Option<&ConfluenceConfig> { /* ... */ }
    pub const fn chronicle(&self) -> Option<&ConfluenceConfig> { /* ... */ }
    pub const fn passport (&self) -> Option<&ConfluenceConfig> { /* ... */ }
}

An integrator binds to the gov by passing the GovConfig into whichever citizen or confluence handles they need:

use std::sync::Arc;
use mosaik::Network;
use builder::{LatticeConfig, UNIVERSE};
use gov::GovConfig;

const ETH_SUPERCHAIN: GovConfig = GovConfig {
    name: "ethereum.superchain",
    lattices:    &[ETH_MAINNET, UNICHAIN_MAINNET, BASE_MAINNET],
    organisms:   &[EUR_PRICE_FEED],
    confluences: &[SUPERCHAIN_ATLAS, INTENTS_ROUTER, SHARED_LEDGER],
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let network = Arc::new(Network::new(UNIVERSE).await?);

    let eth_bid  = offer::Offer::<Bundle>::bid(&network, &ETH_SUPERCHAIN.lattices[0].offer).await?;
    let eur_feed = oracle::Feed::<Price>::read(&network, ETH_SUPERCHAIN.organisms[0].config()).await?;
    let intents  = intents::Router::<Intent>::publish(&network, &ETH_SUPERCHAIN.confluences[1]).await?;
    let atlas    = atlas::Atlas::<CitizenCard>::read(&network, ETH_SUPERCHAIN.atlas().unwrap()).await?;
    // ...
    Ok(())
}

Each confluence, basic service, and standalone organism exposes typed free-function constructors in the shape zipnet ships and builder reproduces (Organism::<D>::verb(&network, &Config)). Raw mosaik IDs never cross a crate boundary.

Fingerprint convention, not a registry

Same discipline as zipnet and builder:

The gov operator publishes the GovConfig struct (or a serialised fingerprint) as the handshake.
Consumers compile it in.
If TDX-gated, the operator publishes the committee MR_TDs for every confluence, basic service, and commissioned standalone organism whose admission is TDX- attested. Per-citizen MR_TDs are published by the per- citizen operator; the gov operator re-publishes them for convenience, not as authority.
There is no on-network gov registry. A directory collection of known govs may exist as a devops convenience; it is never part of the binding path.

Typos in the gov instance name, in citizen fingerprint ordering, or in any confluence parameter surface as Error::ConnectTimeout, not “gov not found”. The library cannot distinguish “nobody runs this” from “operator is not up yet” without a registry, and adding one would misrepresent the error.

What a gov is not

A citizen’s owner. A gov references a citizen; per-citizen operators control admission, rotate keys, retire instances. The gov’s GovConfig updates independently.
A consensus unit. There is no gov-level Raft group, no gov state machine, no gov log. The gov layer adds naming, basic services, and confluence derivation — no consensus.
A routing device. Govs do not carry traffic between citizens. Every citizen and confluence discovers peers via mosaik’s usual gossip on the shared universe. The gov fingerprint is a compile-time token, not a runtime hub.
An ACL root. A gov does not issue tickets on behalf of referenced citizens. Each citizen’s TicketValidator composition is unchanged; each confluence has its own TicketValidator. The gov fingerprint may appear in ticket claims only as context, never as authority.
A closed catalog. Unlike builder’s six organisms, this blueprint does not enumerate a canonical set of lattice classes, standalone-organism categories, or confluences. Real citizens and confluences ship when a concrete problem forces them.
A heavy-gov. See Fixed shapes, open catalogs above.

Four conventions (three inherited, one added)

Every confluence, basic service, and standalone organism the blueprint references reproduces the three zipnet conventions verbatim; the gov adds one.

Identifier derivation from the organism’s Config fingerprint. Inherited from zipnet.
Typed free-function constructors. Organism::<D>::verb(&network, &Config) returning typed handles; raw IDs never leak across crate boundaries. Inherited from zipnet; mirrored by every organism in every lattice, every confluence, and every basic service.
Fingerprint, not registry. Inherited from zipnet; reaffirmed by builder and here.
Citizenship-by-reference, confluence-by-derivation. New for the gov rung. A GovConfig folds citizen fingerprints as content without re-deriving their organism IDs; a ConfluenceConfig folds citizen fingerprints as content and does derive its own organism IDs under the gov root. This mechanism lets citizens participate in multiple govs while retaining one canonical identity each.

What the pattern buys

Collapsed integrator model: one Network, one GovConfig per gov, typed handles on each referenced citizen and each consumed confluence.
Federation at operator pace. A gov starts as one operator’s set of citizens, adds a second operator’s citizen without touching the first’s, and adds a confluence or basic service without forcing either per-citizen operator to change anything.
Clean confluence retirement. Because a confluence’s fingerprint folds the gov root, retiring a confluence means the next GovConfig omits it. Integrators compiled against the previous GovConfig see ConnectTimeout, the ladder’s standard failure mode.
Cross-citizen services as organisms, not protocols. A shared-ledger confluence, cross-feed correlator, cross-chain intent router, Atlas, or Almanac is a mosaik organism following the zipnet pattern. Its author reuses every primitive, ticket validator, and replication guarantee.
Open catalog. New lattice classes, standalone- organism categories, and confluences arrive on their own schedules and fold into the existing handshake shape without forcing the gov layer to change.
Civic coordination without coercion. The four basic services give operator coalitions a shared vocabulary (directory, clock, audit log, optional citizenship) without forcing citizens to participate in anything.

Where the pattern strains

Three limitations a contributor extending this must be explicit about.

Citizen upgrades can churn a gov’s content fingerprint

A citizen-level change bumping its Config fingerprint — a new parameter, a MR_TD rotation the operator folds in — changes the corresponding entry in GOV_LATTICES or GOV_ORGANISMS for every gov that references the citizen, which in turn changes GOV_ROOT and every confluence derived under it.

For a small gov (one or two citizens) the cascade is bounded. For a gov referencing many citizens across many operators, a cascading chain of confluence re-derivations becomes operationally costly.

Two mitigations, both deferred to the roadmap:

Versioned citizen references. A GovConfig could carry citizen fingerprints at named versions, tolerating internal bumps up to a declared compatibility bound.
Narrow content. A confluence whose state machine reads only one or two citizens’ public surfaces does not need its content fingerprint to fold citizens it does not touch. Keeping confluences narrow limits the blast radius of a citizen bump.

Wide confluences are heavy

A confluence reading public surfaces from ten citizens simultaneously runs ten subscriptions, holds peer entries for ten ticket-issuance roots, and is sensitive to the liveness of all ten. The gov blueprint does not make this easier; it makes it legible.

Commissioning contributors should consider sharding: a per-pair confluence over interesting citizen pairs, composed by an integrator, is often cheaper and more debuggable than one wide confluence.

The gov is not cryptographically authoritative

A GovConfig fingerprint is a naming convenience. It does not sign, commit on-chain, or expose a channel for per-citizen operators to discover which govs reference their citizen. A per-citizen operator objecting to being referenced has no technical recourse — anyone with a list of citizen fingerprints can publish a GovConfig.

This is intentional. Making the gov authoritative would reintroduce the supra-citizen-authority shape the blueprint refuses. Per-citizen and gov operators negotiate out of band; the only cryptographic check is whether each referenced citizen admits the confluences’ committee peers via its own TicketValidator.

Checklist for commissioning a new confluence

Identify the one or two public primitives. If the surface is not a small, named, finite set of streams or collections, the interface is not yet designed.
Identify the citizens it spans. Record as ordered sequences of citizen fingerprints in the confluence’s Config — lattices, organisms, or both. Order matters; changing it changes the fingerprint.
Pick a confluence root. GOV_ROOT.derive("confluence").derive(name). The name is the confluence’s role (intents, ledger, market, correlate, …).
Define the Config fingerprint inputs. Content parameters affecting the state-machine signature, upstream public surfaces subscribed to, ACL composition.
Write typed constructors. Confluence::<D>::verb(&network, &Config). Never export raw StreamId/StoreId/GroupId across the crate boundary.
Specify TicketValidator composition on the public primitives. ACL lives there.
Decide per-citizen-failure behaviour. If citizen A is down, does the confluence keep processing remaining citizens’ inputs or stall? Document as part of the composition contract.
Document which citizens’ public surfaces are read. This is the composition contract; changes to it touch Composition.
Declare dependency on any basic services. If the confluence aligns to Almanac ticks or observes Chronicle entries, state so in the crate documentation.
Answer: does this confluence meaningfully aggregate across citizens, or is it an integrator in disguise? If an ordinary integrator holding the same N citizen handshakes could do the same work, skip the confluence. The confluence pattern earns its keep when the aggregated fact is itself a commit with its own consumers.
State the versioning story. If the answer to “what happens when one of the referenced citizens bumps its fingerprint?” is not defined, the design is incomplete.

Cross-references

Anatomy of a gov — concrete instantiation of the pattern for one example gov.
Basic services — Atlas, Almanac, Chronicle, Passport specified.
Confluences — shape and discipline of cross-citizen organisms.
Composition — how citizens and confluences wire together without cross-Group atomicity.
Atomicity boundary — what the gov layer inherits and adds.
Threat model — compositional trust.
Roadmap — versioning, heavy-gov as a deferred space, first commissioned confluences.

Keyboard shortcuts

Governments on mosaik