Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Anatomy of a gov

audience: contributors

This chapter is the concrete instantiation of the pattern described in Designing governments on mosaik. It walks one example gov end-to-end: the fingerprint derivation, the public surface each component exposes on the shared universe, the subscription graph across citizen boundaries, and the way an integrator binds handles through one GovConfig.

The reader is assumed to have read the topology intro, the basic-services spec, and the builder architecture chapter.

Gov identity recap

  GOV             = blake3("gov|" || gov_name)
  GOV_ROOT        = blake3(
                      GOV
                      || LatticeConfig fingerprints (ordered)
                      || OrganismRef fingerprints (ordered)
                      || ConfluenceConfig fingerprints (ordered)
                    )

  // Lattice IDs: NOT re-derived by the gov.
  LATTICE_i       = <builder's own derivation for lattice i>
  ORGANISM_IN_i   = <builder's own derivation for each organism in lattice i>

  // Standalone-organism IDs: NOT re-derived by the gov.
  STANDALONE_j    = <the organism's own derivation>

  // Confluence IDs: derived under the gov root.
  CONFLUENCE_c    = GOV_ROOT.derive("confluence").derive(c_name)

  // Basic-service IDs: derived under the gov root with a
  // "service" segment to distinguish them from commissioned
  // confluences.
  ATLAS_ROOT      = GOV_ROOT.derive("service").derive("atlas")
  ALMANAC_ROOT    = GOV_ROOT.derive("service").derive("almanac")
  CHRONICLE_ROOT  = GOV_ROOT.derive("service").derive("chronicle")
  PASSPORT_ROOT   = GOV_ROOT.derive("service").derive("passport")

Citizen identity travels with the citizen; only confluence and basic-service identity is gov-bound. See topology-intro — Citizenship-by-reference and topology-intro — Confluences where govs do derive.

Integrators bind via the GovConfig they compile in from operator-published release notes:

use std::sync::Arc;
use mosaik::Network;
use builder::UNIVERSE;
use gov::GovConfig;

const ETH_SUPERCHAIN: GovConfig = /* operator-published */;

let network = Arc::new(Network::new(UNIVERSE).await?);

// Lattice organism handles — identical to the builder book.
let eth_bid   = offer::Offer::<Bundle>::bid (&network, &ETH_SUPERCHAIN.lattices[0].offer ).await?;
let uni_bid   = offer::Offer::<Bundle>::bid (&network, &ETH_SUPERCHAIN.lattices[1].offer ).await?;
let eth_tally = tally::Tally::<Attribution>::read(&network, &ETH_SUPERCHAIN.lattices[0].tally).await?;

// Standalone-organism handles — same shape, concrete crate on the right.
let eur_feed  = oracle::Feed::<Price>::read(&network, ETH_SUPERCHAIN.organisms[0].config()).await?;

// Basic service handles — resolved via typed helpers.
let atlas     = atlas::Atlas::<CitizenCard>::read(&network, ETH_SUPERCHAIN.atlas().unwrap()).await?;
let almanac   = almanac::Almanac::<Tick>::read   (&network, ETH_SUPERCHAIN.almanac().unwrap()).await?;

// Confluence handles — the same shape, one rung up.
let intents   = intents::Router::<Intent>::publish(&network, ETH_SUPERCHAIN.confluences_by_name("intents").unwrap()).await?;
let ledger    = ledger ::Shared ::<Refund>::read  (&network, ETH_SUPERCHAIN.confluences_by_name("ledger").unwrap()).await?;

An integrator only opens the handles they need. A cross- chain searcher typically holds bid for several lattices and intents::publish; a shared-ledger analytics consumer typically holds ledger::read only; a cross-feed correlator holds one oracle handle plus one confluence handle; an observability operator holds atlas::read and opens per-citizen handles from there.

Public surface summary

The gov’s outward-facing primitives decompose into:

  1. Every public primitive of every referenced lattice, unchanged. The builder book’s lattice public surface table applies without modification — the gov does not touch lattice primitives.

  2. Every public primitive of every referenced standalone organism, unchanged. Each organism’s own book is the reference.

  3. Every basic service’s public surface (Atlas, Almanac, Chronicle, Passport — whichever are shipped), specified in basic services.

  4. One or two public primitives per commissioned confluence, following the same narrow-surface discipline as every other organism.

For an example gov containing two commissioned confluences — an intent router and a shared ledger — plus Atlas and Almanac as basic services, the gov’s own added surfaces might look like:

ComponentWrite-side primitivesRead-side primitives
atlas(committee-only)Atlas map (CitizenId → CitizenCard)
almanac(committee-only)Ticks stream
intentsPublish<Intent> streamRoutedIntents collection (per slot, per target lattice)
ledger(internal commits only)SharedRefunds collection (keyed by origin citizen)

“Committee-only” and “internal commits only” mean the primitive is ticket-gated to the organism’s committee peers. It still lives on the shared universe; the ticket gate supplies access control.

Names above are illustrative. The blueprint specifies Atlas/Almanac/Chronicle/Passport by role; all other confluence names are per-gov choices.

An example gov: ethereum.superchain

Concrete walk-through of one plausible gov. None of the confluences or services below are shipped; the sketch shows how the composition composes.

Composition

  • Lattices: ethereum.mainnet, unichain.mainnet, base.mainnet — all three referenced by LatticeConfig fingerprint, none re-derived.
  • Standalone organisms: price-feed.eur — an oracle feed publishing EUR/USD prices on the shared universe, referenced by OrganismRef.
  • Basic services shipped: Atlas (directory), Almanac (tick beacon). Chronicle and Passport not shipped in this example; the operator can add them later without reshuffling citizens.
  • Commissioned confluences:
    • intents — a cross-chain intent router (reads from each lattice’s unseal::UnsealedPool, commits per- slot RoutedIntents keyed by target lattice).
    • ledger — a shared-refund aggregator (reads from each lattice’s tally::Refunds, commits SharedRefunds keyed by origin citizen).

Fingerprint sketch

  ETH_SUPERCHAIN = blake3("gov|ethereum.superchain")

  GOV_ROOT = blake3(
    ETH_SUPERCHAIN
    || LatticeConfig.id(ethereum.mainnet)
    || LatticeConfig.id(unichain.mainnet)
    || LatticeConfig.id(base.mainnet)
    || OrganismRef.id(price-feed.eur)
    || ConfluenceConfig.id(atlas)       // basic service
    || ConfluenceConfig.id(almanac)     // basic service
    || ConfluenceConfig.id(intents)     // commissioned
    || ConfluenceConfig.id(ledger)      // commissioned
  )

  ATLAS_ROOT      = GOV_ROOT.derive("service").derive("atlas")
  ALMANAC_ROOT    = GOV_ROOT.derive("service").derive("almanac")
  INTENTS_ROOT    = GOV_ROOT.derive("confluence").derive("intents")
  LEDGER_ROOT     = GOV_ROOT.derive("confluence").derive("ledger")

  // Per-component committee derivations follow the usual pattern.

A confluence’s spanned-citizen set may be a subset of the gov’s citizen set. An intents confluence might span all three lattices while a feed-oracle confluence spans price-feed.eur and one lattice. Each confluence chooses its own span.

Participants

Not every component is operated by the same entity. The gov distinguishes six classes of participant.

  • Lattice operator — the team responsible for a referenced LatticeConfig’s identity, its committees, and its ACL. One or more lattice operators per gov; each operates independently of the gov.
  • Standalone-organism operator — the team responsible for a standalone organism (e.g. price-feed.eur). Operates independently of the gov.
  • Confluence operator — the team responsible for one commissioned confluence’s committee members.
  • Basic-service operator — the team responsible for Atlas, Almanac, Chronicle, or Passport’s committee members. Often the gov operator themselves; may be delegated.
  • Gov operator — the team responsible for publishing and maintaining the GovConfig itself. Often coincides with one of the above; does not have to. Has no technical authority over the referenced citizens.
  • Integrator — external dev, runs no committee members, binds handles against the gov from their own mosaik agent.

Data flow across one slot

The canonical happy path for one slot through this example gov. Each step is a commit into one organism’s (or one confluence’s) state machine; transitions between steps are stream/collection subscriptions. No arrow represents an atomic multi-Group commit.

  integrator                    organism / confluence      commit / effect
  ----------                    ----------------------     ----------------------------

  wallet       ──► zipnet[eth]           ───► Broadcasts grows (sealed envelopes for slot S)
                   unseal[eth]           ───► UnsealedPool[S] populated

  (same for uni, base)

  (publisher) ──► price-feed.eur         ───► Price[tick T] committed (async, no slot clock)

  (internal)  ──► almanac                ───► Ticks[K] committed (shared time axis)
  (internal)  ──► atlas                  ───► CitizenCard updates (any time)

  confluence   ──► intents               ───► RoutedIntents[S] committed per target lattice
                                                 (sees cross-chain intents, routes them)

  searcher     ──► offer[eth]            ───► AuctionOutcome[S] (incorporates routed intents)
  searcher     ──► offer[uni]            ───► AuctionOutcome[S]
  searcher     ──► offer[base]           ───► AuctionOutcome[S]

                   atelier[eth]          ───► Candidates[S] committed
                   atelier[uni]          ───► Candidates[S]
                   atelier[base]         ───► Candidates[S]

                   relay[eth]            ───► AcceptedHeaders[S]
                   relay[uni]            ───► AcceptedHeaders[S]
                   relay[base]           ───► AcceptedHeaders[S]

  (chain inclusion watchers observe each lattice independently)

                   tally[eth]            ───► Refunds[S]
                   tally[uni]            ───► Refunds[S]
                   tally[base]           ───► Refunds[S]

  confluence   ──► ledger                ───► SharedRefunds[S] committed per origin citizen

  wallet / searcher ◄──  ledger              refunds + attestations stream (aggregated)
  dashboard        ◄──  atlas                directory of citizens (for observability)
  correlator       ◄──  almanac              shared tick axis (for cross-citizen joins)

Two properties of this flow:

  • The slot number remains the foreign key for block- building lattices but is per-citizen. Slot S on ethereum.mainnet is unrelated to slot S on unichain.mainnet. Confluences crossing citizen boundaries key commits by (citizen_id, slot) pairs (or (citizen_id, tick) for non-slotted standalone organisms). If the gov ships an Almanac, confluences may optionally carry the current almanac_tick as an additional alignment key.
  • Each citizen’s pipeline is unchanged. The intents confluence injects routed-intent entries into a lattice’s offer input via a subscription, not a cross-Group command. Each offer decides whether and how to include routed intents in its auction. Non- slotted organisms like price-feed.eur continue publishing on their own clock; confluences read their ticks as they appear.

Where each confluence commits

The rule from the builder book — “what decision is the organism actually making at commit time” — carries to confluences and basic services:

  • atlas commits CitizenCard updates. The state machine merges operator-submitted cards (signed by the contributing per-citizen operator, or by the gov operator in single-operator govs) into the Atlas map.

  • almanac commits a monotonic tick. The state machine runs a deadline-driven Raft round; winner’s tick becomes Ticks[K+1].

  • intents commits a routed-intents entry per slot per target lattice. State machine reads cross-chain intents from each spanned lattice’s UnsealedPool, applies the routing policy, commits {citizen_id, slot, intents[]} into RoutedIntents.

  • ledger commits a shared-refund entry per origin citizen per slot. State machine reads each spanned lattice’s tally::Refunds, performs attribution across origin citizens, and commits {origin_citizen, slot, shares[]} into SharedRefunds.

The same discipline every organism in every lattice observes: one decision per commit, state-machine-local, no cross-organism transactions.

Internal plumbing (optional derived private networks)

Same pattern zipnet established and builder reaffirmed: the public surface lives on UNIVERSE; high-churn internal plumbing may move to a derived private network keyed off the organism’s root.

For confluences and basic services:

  • Per-citizen subscription fan-in. Gossip between committee members about per-citizen cursor state may live on <component>_root.derive("private").
  • Attestation gossip. Committee members signing off on a commit can exchange signatures privately before the public commit lands.

Committee Groups themselves stay on UNIVERSE. The argument is unchanged across every rung.

Identity under citizen upgrades

A citizen’s fingerprint is stable unless its operator chooses to bump it. Two scenarios:

  • Citizen internal upgrade (fingerprint stable). An operator-level rotation inside a citizen that does not change any Config input is invisible to the gov. No re-publish.
  • Citizen fingerprint bump. The per-citizen operator publishes a new Config. Govs that reference this citizen must re-publish their GovConfig with the new fingerprint. Every confluence’s and every basic service’s ConnectTimeout path triggers until the new GovConfig is compiled in downstream.

A gov operator insulating integrators from citizen fingerprint bumps carries a version-stable alias in the gov name (ethereum.superchain-v2026q2). See Roadmap — Versioning.

Sizing — Phase 1 gov

Order-of-magnitude targets for an illustrative gov with three lattices, one standalone organism, two basic services, and two commissioned confluences. Indicative, not binding.

ComponentCommittee members (v1)Stream bytes / eventNotable bonds
Per lattice (×3)see builder sizingsee builder sizingsee builder sizing
price-feed.eursee organism sizingsee organism sizingcommittee + publishers
atlas (basic service)3 membersO(citizens × card size)committee + gov operator
almanac (basic service)3–5 membersO(1) per tickcommittee only
intents confluence3–7 TDX membersO(intents × lattices)committee + each lattice
ledger confluence3–5 membersO(refunds)committee + each lattice

“v1” here means the gov-level Phase 1 shape. Phase 2 adds more confluences as cross-citizen problems arise; Phase 3 introduces cross-operator confluences where committee members span organisations.

What this chapter deliberately does not cover

  • Per-confluence state machines. Each confluence owns its own spec in its own crate once commissioned.
  • Per-confluence wire formats. Same.
  • Chain-specific nuance inside a lattice. The builder book covers this; govs do not touch it.
  • Organism-specific nuance inside a standalone organism. Each organism’s own book covers that.
  • A canonical list of commissioned confluences or organism categories. See topology-intro — What a gov deliberately is not.
  • Heavy-gov primitives (enforcement, taxation, judiciary). Deferred; see topology-intro — Fixed shapes, open catalogs.