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

Who this book is for

audience: all

The book has three audiences, the same three the zipnet and builder books use, scoped to multi-citizen govs rather than single lattices or single organisms:

• Integrators — external developers whose agent binds across citizens (lattices, standalone organisms), into a confluence, or into a gov’s basic services.
• Operators — teams standing up and running a gov (a confluence, a standalone organism, a basic service, a federated multi-citizen composition, or any combination).
• Contributors — engineers commissioning a new confluence, commissioning a new class of mid-rung composition, specifying a new basic service, or extending the gov-level composition model.

Each page declares its audience on the first line (audience: integrators | operators | contributors | both | all) and respects that audience’s conventions. When content serves more than one audience, use both or all, and structure the page so each audience gets its answer in the first paragraph.

Integrators

Who. External Rust developers whose mosaik agent binds across multiple citizens of a gov, or into a confluence’s public surface. Typical roles:

• Cross-chain searchers — placing bundle bids on several block-building lattices’ offer organisms and reconciling paired-leg outcomes.
• Multi-chain wallets — submitting intents via zipnet on several lattices and reading refund attestations across their tally organisms.
• Oracle and attestation consumers — subscribing to standalone organisms (price feeds, attestation aggregators, identity substrates) referenced by a gov.
• Analytics agents — aggregating per-citizen public surfaces across any mix of lattices and organisms into a single view.
• Confluence consumers — reading from an intent router, a shared ledger, a cross-chain oracle aggregator, or any other commissioned confluence.
• Basic-service consumers — reading the gov’s Atlas, aligning to its Almanac, auditing its Chronicle, or presenting a Passport.

They do not run committee servers (operator role); they do not modify organism, lattice-organism, or confluence crates (contributor role).

Assumed background.

• Async Rust, the mosaik book, and — for block-building use cases — the builder book.
• Per-organism ergonomics (Organism::<D>::verb(&network, &Config) constructors); the gov layer extends this pattern rather than replacing it.
• Own Arc<Network> lifecycle.
• Zipnet book if submission-layer anonymity is relevant.

Not expected.

• Citizen internals beyond the corresponding organism or lattice book.
• A full census of confluences or organisms unused by their workload.
• Re-exposition of mosaik, zipnet, or builder primitives.

Concerns.

• Which citizens and which confluences the workload touches.
• Which GovConfig to compile in.
• How to reconcile partial outcomes across citizens.
• What the gov operator owes out of band: the GovConfig, citizen fingerprints, and MR_TDs for any TDX-gated confluences or organisms.

Tone. Code-forward and cookbook-style. Snippets are rust,ignore, self-contained, and meant to be lifted. Public API surfaces are listed as tables. Pitfalls are called out inline. Second person throughout.

Entry point. Quickstart — bind many citizens from one agent.

Operators

Who. Teams running one or more of:

• Confluence operators — running committee members for an intent router, shared ledger, attestation aggregator, or other commissioned confluence.
• Basic-service operators — running committee members for an Atlas, Almanac, Chronicle, or Passport.
• Standalone-organism operators — running committee members for an organism living directly on the universe and referenced by a gov as a citizen.
• Lattice federators — publishing a GovConfig that names a set of lattices they (or a peer coalition) run.
• Multi-role operators — running several of the above simultaneously.

Assumed background.

• Linux ops, systemd units, cloud networking, TLS, Prometheus.
• Builder operator overview and comfort with lattice-level runbooks when the gov includes block-building lattices. The gov layer adds runbooks for confluences, basic services, and federated composition; it does not replace per-citizen runbooks.
• Not expected to read Rust source. Any Rust or protocol detail that is load-bearing for an operational decision belongs in a marked dev-note aside that may be skipped.

Not expected.

• Confluence or organism internals.
• Integrator-side ergonomics.

Concerns.

• What to run, on what hardware, with what environment variables, for a confluence, basic service, or standalone organism.
• How to publish a GovConfig that references citizens run by other operators.
• What cross-operator agreements federation requires.
• How to rotate a confluence’s committee without breaking the gov’s fingerprint.

Tone. Runbook register. Numbered procedures, parameter tables, one-line shell snippets. Pre-empt the obvious what-ifs inline. Avoid “simply” and “just”. Each command is either safe verbatim or clearly marked as needing adaptation.

Entry point. Quickstart — stand up a gov.

Contributors

Who. Senior Rust engineers with distributed-systems and cryptography backgrounds, commissioning a new confluence, a new class of mid-rung composition, a new basic service, or extending the gov-level composition model itself.

Assumed background.

• The mosaik book, zipnet book, builder book, and the corresponding CLAUDE.md convention files.
• Async Rust, modified Raft, threshold cryptography, TDX attestation flows, and organism-level primitives.
• Familiarity with at least one production organism shape (a zipnet deployment, a tally organism, an oracle or attestation organism on another production universe) and with the builder book’s cross-chain chapter.

Not expected.

• Re-exposition of mosaik, zipnet, or builder primitives.
• Integrator ergonomics unless they drive a design choice.
• Motivation for cross-citizen coordination in the abstract.

Concerns.

• The confluence pattern and when to use it versus a cross-citizen integrator.
• Composition with lattice organisms, standalone organisms, and basic services.
• Invariants a confluence must hold and where they are enforced.
• Interaction of gov-level derivation with existing LatticeConfig or organism Config fingerprints.
• Behaviour when a citizen referenced by a gov upgrades.
• Extension points: which trait, which test, which fingerprint field.

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

Entry point. Designing governments on mosaik.

Shared writing rules

• No emojis.
• No exclamation marks outside explicit security warnings.
• Link the mosaik, zipnet, and builder books rather than re-explaining their primitives.
• Tag security-relevant facts with a visible admonition, not inline prose.
• Keep the three quickstarts synchronised. When the gov shape, a confluence’s public surface, a basic service’s specification, or the composition handshake changes, update integrators, operators, and contributors quickstarts in one pass.
• Use the terms in Glossary consistently. Do not coin synonyms for gov, lattice, citizen, confluence, organism, universe mid-page.
• Minimise ornament. No epigraphs, no literary or sci-fi name-drops, no rhetorical flourishes. Restate the non-authority stance where it is load-bearing; otherwise keep prose dense.

What a gov gives you

audience: integrators

A gov is a single handshake token binding an agent to multiple citizens of the mosaik universe at once: block- building lattices, standalone organisms (oracles, attestation fabrics, identity substrates, analytics pipelines, …), confluences (cross-citizen organisms), and the gov’s basic services (Atlas, Almanac, Chronicle, Passport — whichever are shipped). Compile one GovConfig and obtain typed handles on every citizen, every basic service, and every confluence the gov composes, from one Arc<Network>.

If you already bind to one lattice via a LatticeConfig, or to one standalone organism via its Config, a gov does not change any of that. It adds:

• A single reference to a set of citizens the operator has chosen to yoke together (e.g. every chain in a superchain stack; every oracle feed in a region; a set of lattices plus a shared attestation fabric).
• Optional confluences: cross-citizen organisms that aggregate, route, or attest across the citizens in the gov.
• Optional basic services: up to four well-known shapes — Atlas (directory), Almanac (clock beacon), Chronicle (audit log), Passport (citizenship tokens).
• No loss of identity. Every citizen’s GroupId, every ClientId, every StreamId you already use stays byte- for-byte the same. A gov references citizens; it does not re-derive them.

An agent binding to one citizen only does not need a GovConfig; bind directly to that citizen’s Config (for a block-building lattice, see the builder integrators overview; for a standalone organism, see its own crate docs). The gov layer is additive, not a replacement.

Non-authority stance

A gov is not an authority over its citizens. It does not issue tickets on behalf of a lattice or standalone organism; it does not override their ACLs; a citizen may belong to many govs simultaneously without its identity changing. A gov operator asking you to trust the gov fingerprint in place of the per-citizen fingerprints is asking you to skip a load-bearing check; decline. The per-citizen handshake remains the cryptographic gate. See What you need from the gov operator.

When you want a GovConfig

Four common cases.

Cross-chain searcher

You bid on bundles across three block-building lattices and want one handshake token that carries all three LatticeConfigs, their MR_TDs, and any commissioned confluences (e.g. a shared ledger that aggregates your refunds across chains).

Hold one GovConfig, open three offer::Offer<Bundle>::bid handles, one ledger::Shared<Refund>::read. See the quickstart.

Multi-chain wallet

You submit intents on several lattices and need refund attestations from each. If the gov includes a shared-ledger confluence, you can read one aggregated feed instead of polling per-lattice tally::Refunds.

Cross-domain agent

Your agent consumes outputs from a mix of citizens — say, two block-building lattices, an oracle grid, and an attestation aggregator — and you want one compile-time token that pins the full set. A GovConfig lets you hold one handshake instead of four.

Confluence or basic-service consumer

You are an analytics, routing, or dashboard service that reads an intent router, a shared ledger, a cross-chain oracle aggregator, or the gov’s Atlas. Without a GovConfig, you would re-derive each fingerprint yourself; with it, you compile one struct.

When you do not need a GovConfig

• You bind to one citizen only.
• You are an integrator testing a standalone confluence whose operator has given you its ConfluenceConfig directly.
• You only read a public collection whose StoreId you already have; govs are compile-time ergonomics, not runtime authority.

What the operator gives you

When a gov operator hands you a handshake, you should receive:

• The GovConfig struct (or its serialised fingerprint).
• The included LatticeConfigs — either inline or by reference to each lattice operator’s published handshake.
• The included standalone-organism references — each with role name, Config fingerprint, and a pointer to that organism’s own handshake.
• The included basic services — each a ConfluenceConfig with the shape documented in basic services.
• MR_TDs for every TDX-gated confluence, every TDX-gated basic service, and every TDX-gated standalone organism the gov commissioned.
• Endpoint hints for at least one initial peer on the shared universe, if your agent is cold-starting.

See What you need from the gov operator for the full checklist.

What you compile in

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

const ETH_SUPERCHAIN: GovConfig = /* pasted from operator release notes */;

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

    // Pick handles you need — any lattice organism, any
    // standalone organism, any confluence, any basic service.
    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?;
    // A standalone organism the gov references — here, an
    // attestation aggregator with its own Config.
    let attest = attest::Aggregator::<Quote>::read(
        &network, ETH_SUPERCHAIN.organisms[0].config(),
    ).await?;
    // A confluence — same shape, one rung up.
    let ledger = ledger::Shared::<Refund>::read(
        &network, &ETH_SUPERCHAIN.confluences[0],
    ).await?;
    // A basic service — the gov's Atlas, if shipped.
    let atlas  = atlas::Atlas::<CitizenCard>::read(
        &network, ETH_SUPERCHAIN.atlas().unwrap(),
    ).await?;
    // ... use them.
    Ok(())
}

ETH_SUPERCHAIN.atlas() returns the Atlas confluence’s Config if the gov ships one. The same helper exists for almanac(), chronicle(), passport(). A gov that does not ship a given service returns None.

No additional plumbing. UNIVERSE is the same constant every lattice and zipnet deployment uses.

What can go wrong

• ConnectTimeout. The GovConfig you compiled in does not match what the operator is running. Recompile against the current release notes.
• Ticket missing on a specific citizen. Your per- citizen admission ticket was not issued or was revoked. Per-citizen operators issue their own tickets; the gov operator does not. Contact the per- citizen operator.
• Confluence or standalone organism down. A committee lost majority. Other citizens continue; the affected component’s next commit is delayed.
• Basic service returns None. The gov does not ship that service. Drop the dependency or request the service be added.

Cross-references

• Quickstart — bind many citizens from one agent
• What you need from the gov operator
• Binding to a confluence
• Cross-citizen flows
• Contributor — basic services

Quickstart — bind many citizens from one agent

audience: integrators

This quickstart stands up an agent that submits and reads across three block-building lattices, one standalone attestation organism, one confluence, and one basic service (the gov’s Atlas) — all bound through a single GovConfig. It assumes familiarity with the builder integrators quickstart when the gov includes block-building lattices; the gov layer extends that pattern rather than replacing it.

If the gov contains no lattices (for example, a composition of oracle organisms plus a cross-oracle confluence), the same pattern applies with different crates on the right-hand side of each handle.

What you need before you start

• A GovConfig from the gov operator (struct definition, or a serialised fingerprint you copy into your crate).
• A LatticeConfig per referenced lattice (inline in the GovConfig the operator published, or pulled from each lattice operator’s handshake page).
• A standalone-organism reference per referenced organism (role name + Config fingerprint + pointer to the organism’s own handshake).
• A ticket from each per-citizen operator you intend to write to. Per-citizen admission is per-citizen; the gov operator does not issue per-citizen tickets.
• A ticket from each confluence or basic-service operator whose write-side primitive you intend to use. Usually none: most confluences and basic services are read-only for external integrators.
• Your TDX image (if any citizen or service you write to requires attested client admission).

Step 1 — declare the GovConfig in your crate

Paste the operator’s published GovConfig definition, or import it from the operator’s handshake crate if they publish one:

use builder::LatticeConfig;
use gov::{GovConfig, ConfluenceConfig, OrganismRef};

// Exactly the bytes the operator publishes.
const ETH_MAINNET:      LatticeConfig = /* from ethereum.mainnet operator */;
const UNICHAIN_MAINNET: LatticeConfig = /* from unichain.mainnet operator */;
const BASE_MAINNET:     LatticeConfig = /* from base.mainnet operator */;

// A standalone organism the gov references — here, an
// attestation aggregator with its own Config fingerprint.
const ATTEST_AGG: OrganismRef = OrganismRef {
    role: "attest",
    fingerprint: /* published by the attest-aggregator operator */,
};

// The gov's Atlas basic service (if shipped).
const SUPERCHAIN_ATLAS:  ConfluenceConfig = /* from gov operator */;
const INTENTS_CONF:      ConfluenceConfig = /* from gov operator */;
const LEDGER_CONF:       ConfluenceConfig = /* from gov operator */;

pub const ETH_SUPERCHAIN: GovConfig = GovConfig {
    name: "ethereum.superchain",
    lattices:    &[ETH_MAINNET, UNICHAIN_MAINNET, BASE_MAINNET],
    organisms:   &[ATTEST_AGG],
    confluences: &[SUPERCHAIN_ATLAS, INTENTS_CONF, LEDGER_CONF],
};

For a gov-agnostic library, take &'static GovConfig as a constructor argument and let the binary crate pick the constant.

Step 2 — bring up the network handle

Same UNIVERSE as every other mosaik service:

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

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

One Arc<Network> per agent regardless of how many citizens, confluences, or basic services are bound.

Step 3 — bind the lattice handles you need

Indexes into lattices[] match the order in the GovConfig. A cross-chain searcher that bids on all three:

use offer::Offer;

let eth_bid  = Offer::<Bundle>::bid (&network, &ETH_SUPERCHAIN.lattices[0].offer).await?;
let uni_bid  = Offer::<Bundle>::bid (&network, &ETH_SUPERCHAIN.lattices[1].offer).await?;
let base_bid = Offer::<Bundle>::bid (&network, &ETH_SUPERCHAIN.lattices[2].offer).await?;

let eth_wins  = Offer::<Bundle>::outcomes(&network, &ETH_SUPERCHAIN.lattices[0].offer).await?;
let uni_wins  = Offer::<Bundle>::outcomes(&network, &ETH_SUPERCHAIN.lattices[1].offer).await?;
let base_wins = Offer::<Bundle>::outcomes(&network, &ETH_SUPERCHAIN.lattices[2].offer).await?;

Keep handles alive while needed; drop them when done. Each handle carries its own subscriptions and is cheap atop the shared Network.

Step 4 — bind the standalone-organism handles you need

Each OrganismRef carries the fingerprint; the concrete organism crate gives you the typed constructor:

use attest::Aggregator;

let attest = Aggregator::<Quote>::read(
    &network, ETH_SUPERCHAIN.organisms[0].config(),
).await?;

OrganismRef::config() resolves to the organism’s Config — either because the gov operator embeds the full Config struct in their published GovConfig, or because the organism crate ships a helper that rebuilds the Config from the published fingerprint and known role constants. Either way, the concrete organism crate is what gives you the typed handle.

Step 5 — bind the basic services you want

Basic services are confluences with well-known shapes. GovConfig exposes helpers:

use atlas::Atlas;
use almanac::Almanac;

// The Atlas lists every citizen in the gov with operator metadata.
if let Some(atlas_cfg) = ETH_SUPERCHAIN.atlas() {
    let atlas = Atlas::<CitizenCard>::read(&network, atlas_cfg).await?;
    // Use the atlas as your canonical "what's in this gov" reference.
}

// The Almanac is a shared tick beacon for timing correlations.
if let Some(almanac_cfg) = ETH_SUPERCHAIN.almanac() {
    let almanac = Almanac::<Tick>::read(&network, almanac_cfg).await?;
    // Use almanac ticks as the time axis for cross-citizen commits.
}

A gov may ship zero, one, two, three, or all four basic services. Always check the helper’s Option return; do not assume presence.

Step 6 — bind the confluence handles you need

The shared ledger is typical for a searcher seeking aggregated refund attribution:

use ledger::Shared;

let refunds = Shared::<Refund>::read(&network, &ETH_SUPERCHAIN.confluences[2]).await?;

tokio::spawn(async move {
    while let Some(r) = refunds.next().await {
        // Each entry carries (origin_citizen, slot, share, evidence).
        handle_refund(r);
    }
});

Step 7 — submit paired bundles

Cross-chain bundles are a searcher-level problem. The gov layer surfaces the handles; reconciliation logic is the integrator’s responsibility.

async fn submit_paired_bundle(
    eth_bid: &Offer<Bundle>::Bid,
    uni_bid: &Offer<Bundle>::Bid,
    sell_on_eth: Bundle,
    buy_on_uni:  Bundle,
) -> anyhow::Result<()> {
    let eth_ack = eth_bid.send(sell_on_eth).await?;
    let uni_ack = uni_bid.send(buy_on_uni ).await?;
    // Reconcile: if only one leg commits, post-bond collateral or
    // on-chain HTLC logic applies. The gov layer does NOT
    // provide cross-citizen atomicity. See
    // /contributors/atomicity.md.
    Ok(())
}

A paired-bundle correlator joining AuctionOutcome[L1, S] to AuctionOutcome[L2, S'] is the most common in-agent utility. Compute it in-memory as in builder’s Shape 1, or rely on the gov’s intents confluence if one is commissioned.

Step 8 — read the aggregated result

With a shared-ledger confluence, a single subscription surfaces refunds originating from any of the gov’s lattices.

while let Some(entry) = refunds.next().await {
    tracing::info!(
        origin = %entry.origin_citizen,
        slot   = entry.slot,
        share  = %entry.share,
        "refund attributed",
    );
}

Without a shared-ledger confluence, open three per- lattice tally::Tally::<Attribution>::read handles and join in memory. Both paths are valid; the confluence is a shared precomputation.

What to do when things go wrong

• ConnectTimeout on a lattice or organism handle. The per-citizen Config does not match what the citizen’s operator is running. Recompile against that operator’s latest handshake.
• ConnectTimeout on a confluence or basic-service handle. The ConfluenceConfig does not match, or the committee is down and has not yet published peers on the universe, or the confluence has been retired and the gov operator should have sent an updated GovConfig.
• Admission denied on a write-side stream. Ticket missing or expired. Contact the per-citizen operator, not the gov operator.
• Basic-service helper returns None. The gov does not ship that service. See contributor basic services for the spec if proposing addition.

Cross-references

• What a gov gives you
• What you need from the gov operator
• Binding to a confluence
• Cross-citizen flows
• builder quickstart

What you need from the gov operator

audience: integrators

Before compiling a GovConfig into an agent, the integrator requires a short item list from the gov operator plus a pair of sanity checks. This page is the checklist.

The eight items

1. The GovConfig definition. Either a Rust const declaration pasted into the integrator crate, or a serialised fingerprint (hex of gov_id()) paired with the integrator’s own copy of the struct definition.

2. Every included LatticeConfig. Typically pulled by reference from each lattice operator’s handshake page. The gov operator should publish a per-gov table listing the referenced lattices and a link to each lattice operator’s release notes.

3. Every included standalone-organism reference. For each organism the gov composes outside a lattice, the gov operator publishes the role name, the organism’s Config fingerprint, and a link to that organism’s own handshake page.

4. Every basic service’s ConfluenceConfig. Atlas, Almanac, Chronicle, Passport — whichever the gov ships. Services not shipped are stated explicitly; silence is ambiguous.

5. MR_TDs for every TDX-gated unit the gov operator commissions — confluences, basic services, and standalone organisms they run. (Per-citizen MR_TDs come from the per-citizen operators; the gov operator re- publishes for convenience.)

6. A short description of each confluence, each basic service, and each standalone organism: what it commits, which citizens it spans or depends on, what its trust assumption is, what its public primitives look like.

7. At least one initial peer hint for the shared universe (cold-start bootstrap). Typically the same hint every mosaik service uses; re-published for convenience.

8. A change channel. The mechanism through which the gov operator notifies of a referenced citizen’s fingerprint bump or a confluence’s Config change.

Gov operators do not issue per-citizen tickets; those come from per-citizen operators. A gov operator offering to issue them is overstepping the gov layer’s non- authority stance; decline.

Verification

Perform two sanity checks once the items above are in hand.

Fingerprint round-trip

Compile the pasted GovConfig. Call gov_id() on it. Compare to the operator’s published fingerprint. Both must match byte-for-byte. A mismatch means the struct definition drifted or the serialiser differs; do not proceed until the mismatch resolves.

Citizen fingerprint cross-check

For each referenced LatticeConfig, call lattice_id() and compare to the lattice operator’s published fingerprint. For each referenced standalone organism, compare the OrganismRef fingerprint to the organism operator’s published one. A mismatch means the gov operator’s copy drifted from the per-citizen operator’s. Request an updated GovConfig.

Trust

Nothing in the gov operator’s handshake is cryptographically authoritative: a gov fingerprint names a composition, it does not sign it. The checks above suffice because the identity work is done at the per- citizen rung. The gov layer stitches known fingerprints together and adds a small catalog of basic services.

A gov operator asking an integrator to trust the gov fingerprint in place of the per-citizen fingerprints is asking the integrator to skip one of the checks above. Decline. The gov’s non-authority stance depends on integrators performing these checks.

Cross-references

• Quickstart — bind many citizens from one agent
• builder’s integrators handshake page

Binding to a confluence

audience: integrators

A confluence is a mosaik organism whose public surface spans multiple citizens — some combination of block-building lattices and standalone organisms. Binding is the same as for any organism — Confluence::<D>::verb(&network, &Config) — with two small differences in what the operator owes the integrator and in failure-mode reasoning.

The same reasoning applies to a gov’s basic services (Atlas, Almanac, Chronicle, Passport) — each is a confluence with a well-known shape.

One handle per verb

Each confluence exposes one or two public primitives. A read-only integrator typically needs exactly one handle; a write-side integrator a second. Typical shapes:

// Read-only: subscribe to the confluence's output.
let intents = intents::Router::<Intent>::routed(&network, &INTENTS_CONF).await?;

// Write-side (if the confluence publishes a write stream):
let publish = intents::Router::<Intent>::publish(&network, &INTENTS_CONF).await?;

Verb names come from the confluence’s own crate docs, following the same convention as every organism (Offer::bid, Tally::read, Zipnet::submit, Aggregator::read, Atlas::read).

What the confluence operator owes you

A confluence operator (who may coincide with the gov operator) is responsible for:

• The ConfluenceConfig fingerprint, publishable and byte-for-byte compilable.
• The ordered list of spanned citizen fingerprints the confluence depends on — lattices, standalone organisms, or any mix. Cross-check each against the corresponding per-citizen operator’s publication.
• MR_TDs if the confluence is TDX-gated.
• The confluence’s state-machine version / signature. A bump surfaces as ConnectTimeout on compiled handles; the change channel warns ahead.
• A failure-mode statement. Whether a stall in spanned citizen A causes a commit with partial evidence or an event stall. Documented in the crate’s composition-hooks page.

Failure-mode reasoning for confluence consumers

Three properties to internalise before reading a confluence.

The confluence commit lags the upstream commits

A confluence’s (citizen_id, slot) commit is observable only after the underlying citizen commits are observable, plus one Raft round inside the confluence’s committee. Latency-sensitive consumers read the upstream citizen surfaces directly and use the confluence only for the aggregated view.

Partial evidence is a valid confluence commit

Depending on the confluence’s stall policy, a commit may reflect inputs from only some spanned citizens. The commit carries evidence pointers; checking the pointers indicates which citizens’ inputs were present. Do not assume every spanned citizen contributed to every commit.

A stalled confluence does not block upstream pipelines

If the confluence’s committee loses majority or lags, the spanned citizens’ pipelines are unaffected. Fall back to binding per-citizen handles directly; the confluence’s precomputation is a convenience, not a dependency.

What to do when your agent relies on a confluence that changes

Confluence Config fingerprints change for three reasons:

• Gov re-publication. The gov operator added a citizen, removed a citizen, or added another confluence / basic service; every confluence in the gov gets a new fingerprint under the new gov root.
• Confluence upgrade. The confluence’s content or ACL changed; its fingerprint bumps independently.
• Upstream citizen bump. A citizen the confluence spans bumped its fingerprint; the confluence inherits the change.

In every case the old handle starts failing with ConnectTimeout. The operator’s change channel should warn ahead; the integrator’s process should include a path to recompile against the new GovConfig and restart.

Cross-references

• What a gov gives you
• Quickstart
• Contributor — confluences
• Contributor — basic services

Cross-citizen flows

audience: integrators

This page catalogues cross-citizen flows an agent may run and indicates which are cheap at the integrator level versus when requesting a confluence is warranted.

The underlying theory for block-building cross-chain cases is in the builder book’s cross-chain chapter. The gov layer formalises its Shape 3 (bridge organism) as a confluence and generalises the pattern beyond block- building to any mix of lattices and standalone organisms. This page is the integrator-facing view.

Four recurring flows

Paired bundles (two block-building lattices)

An agent publishes bundle A to offer[L1] and bundle B to offer[L2], expecting paired-slot commits.

• Without a confluence. Keep a per-agent correlator table keyed by bundle id; watch both lattices’ AuctionOutcome and join. Handle partial fills (A committed, B did not) with post-bond collateral or on- chain HTLC logic. This is the builder book’s Shape 1.
• With an intents confluence. Publish one intent to the confluence’s write stream; the confluence routes sub-bundles to each target lattice’s offer. Subscribe to the confluence’s RoutedIntents for cross-chain outcome reconciliation.
• Decision rule. If only one searcher runs the correlator, keep it in the agent. If three unrelated agents would each run the same correlator, request an intents confluence from the gov operator.

Cross-origin attribution (lattice + lattice)

A bundle submitted on lattice A but captured MEV on lattice B. Without coordination, tally[A] never sees the attribution on B’s block; tally[B] sees it but without knowing the origin was A.

• Without a confluence. Subscribe to both tally[A] and tally[B], join in memory on submission ids, compute the cross-origin view locally.
• With a shared-ledger confluence. One Shared::<Refund>::read handle yields aggregated attribution across all citizens the ledger spans.
• Decision rule. If on-chain settlement requires a pre-aggregated attestation (e.g. one signature for a cross-chain refund claim), the confluence is load- bearing. If each consumer can perform the join, the confluence is a convenience.

Oracle + lattice correlation (organism + lattice)

An agent that needs to correlate an oracle organism’s price feed with block-building auction outcomes on one or more lattices. The citizens are heterogeneous: one is a standalone organism, the others are lattices.

• Without a confluence. Subscribe to the oracle organism’s feed and each lattice’s AuctionOutcome; join in memory with a timestamp tolerance window.
• With a correlator confluence. The confluence’s commit pairs (oracle_tick, lattice_slot) tuples under one attested key, letting multiple downstream agents consume the same correlation without re-computing. When the gov ships an Almanac, both the oracle tick and the lattice slot align to almanac ticks, providing a shared correlation window.
• Decision rule. Do three different agents need the same correlation? If yes, the confluence amortises.

Cross-citizen observability

A dashboard, an analytics agent, or an oncall who wants “one view of the gov’s activity” — across lattices, standalone organisms, or both.

• Without a confluence. N citizen subscriptions plus local aggregation.
• With the gov’s Atlas basic service. Start from the Atlas (directory of citizens, with endpoint hints); subscribe per citizen. Atlas is the reference; the aggregation remains the integrator’s.
• Decision rule. Atlas pays off once more than one dashboard operator exists. A single on-call team can skip it; most govs ship an Atlas anyway because the cost is small and the coordination benefit is high.

The decision framework

Every cross-citizen flow reduces to one question:

Do three different agents (searchers, dashboards, analytics) need the same pre-aggregated fact?

If yes, a confluence is the right shape: commit once per slot, consume N times.

If no, a per-agent driver is the right shape: keep the logic where the decisions are made.

A confluence is not generic cross-citizen infrastructure. It is a mosaik organism with a narrow public surface and the same operational cost as any other committee-backed organism. Use it when a committed, reusable fact pays for the cost; use an in-agent driver when it does not.

What the gov layer does not give you

• Atomic cross-citizen commits. The gov does not provide send-both-or-neither. See atomicity.
• Cross-gov coordination. Two GovConfigs on the same universe are two handshake tokens; they do not coordinate.
• Trust in a confluence beyond its committee. A confluence’s commit is trustworthy up to its committee’s assumption plus the upstream citizens it reads. Know the trust shape before relying on it.
• Enforcement over citizens. A gov operator cannot force a citizen to change behaviour via the GovConfig. A citizen’s misbehaviour is addressed by the gov operator publishing an updated GovConfig that no longer references it.

Cross-references

• Quickstart
• Binding to a confluence
• Contributor — confluences
• Contributor — basic services
• Contributor — atomicity
• builder cross-chain

Gov overview

audience: operators

A gov is an operator-published handshake token naming a set of mosaik citizens — block-building lattices, standalone organisms, and zero or more confluences (cross-citizen organisms) — and handing the set to integrators as one GovConfig they compile in. A gov may also ship up to four basic services (Atlas, Almanac, Chronicle, Passport) under the same handshake.

This page is the operator’s introduction: what running a gov means, what the operator owns, what they do not, and how the gov’s identity relates to the citizens it references. The non-authority stance is load-bearing throughout: the gov offers services to citizens; it does not compel.

Operator roles, often one team

Running a gov means any combination of the following roles, often held by the same team:

• Lattice operator — responsible for one LatticeConfig: its committees, its ACL, its organism rotations. Lattice operations are covered by the builder operator book. The gov layer does not change any lattice-operator responsibilities.
• Standalone-organism operator — responsible for one organism living directly on the universe (an oracle feed, an attestation aggregator, an identity substrate, …). Same shape as any mosaik-native service: a committee, a Config, a narrow public surface.
• Confluence operator — responsible for one confluence’s committee: running the binaries, holding the admission secrets, rotating the attestation images if TDX-gated.
• Basic-service operator — responsible for an Atlas, Almanac, Chronicle, or Passport committee. Mechanically identical to running any other confluence; the shape is specified in basic services.
• Gov operator — responsible for publishing and maintaining the GovConfig: keeping its content accurate, notifying integrators when referenced citizens’ fingerprints bump, and retiring the gov instance name cleanly when it is no longer needed.

A single team commonly holds two or more of these roles. A team running a shared-ledger confluence usually also publishes the GovConfig naming it. A team operating an oracle organism may or may not run the gov that references it.

What the gov operator owns

• The GovConfig struct and its serialised fingerprint.
• A published change channel (release notes, a CHANGELOG, an RSS feed — whatever), through which you notify integrators of citizen fingerprint bumps, confluence upgrades, or composition changes.
• The set of ConfluenceConfigs shipped with the gov (if you also run the confluences and any basic services).
• The set of OrganismRefs the gov composes (the role name + fingerprint for each referenced standalone organism).
• A gov-scoped operator handshake page — one URL or repository section integrators can link in their own docs.

What the gov operator does not own

• The referenced citizens. The gov operator references lattices and standalone organisms; they do not admit peers into them, issue tickets on their behalf, or dictate internal parameters.
• Citizen fingerprints. When a referenced citizen bumps, the gov operator updates the GovConfig to match; they do not dictate the per-citizen operator’s bump cadence.
• Cross-operator contracts. Federating citizens run by other operators brings SLAs, data-sharing arrangements, and attribution splits — all negotiated out of band. The blueprint does not provide a standard form.
• Integrator lifecycle. Integrators compile in and recompile on their own schedule. A compiled-in GovConfig cannot be revoked; the gov operator publishes a new one and relies on integrators to upgrade.
• Citizen behaviour. A citizen’s misbehaviour is addressed by publishing an updated GovConfig that drops or replaces it. The gov operator has no protocol- level power to constrain a citizen.

What per-citizen operators can expect from a gov operator

Worth formalising with any citizen referenced:

• Notification of inclusion. The gov operator informs the per-citizen operator of the reference at publication time. The blueprint does not enforce this; it is a courtesy.
• No admission requests. The gov operator does not ask the per-citizen operator to issue special-case tickets for confluences or basic services. Committee members bond into referenced citizens as ordinary integrators under the citizen’s normal admission policy.
• Observability of referenced citizens’ public surfaces only. The gov operator does not expect private plumbing access.
• Bump coordination. Citizen-fingerprint bumps are notified to the gov operator via the per-citizen operator’s integrator channel ahead of cutover; this lets the gov operator publish a matching GovConfig without a ConnectTimeout gap.

A typical gov’s shape

Three common archetypes:

• Ecosystem gov. One operator; several lattices across related chains (every chain in a superchain stack, every chain in an L2 family). Basic services: usually Atlas at minimum, often Chronicle. Confluences: often an intent router or shared ledger.
• Service gov. One operator; one or a handful of standalone organisms composed together (an attestation aggregator paired with an identity substrate; an oracle feed paired with an analytics pipeline). Often no lattices at all. Almanac is common because organisms without slot clocks benefit from a shared tick.
• Federated gov. Multiple operators, each running one or a few citizens (lattices, standalone organisms, or both); one operator runs the gov and one or more confluences. Common when an ecosystem wants a shared attribution or routing layer while the underlying citizens operate independently. Passport is more likely here (cross-operator identity).

All three archetypes use the same GovConfig shape; the difference is who runs what.

Critical path

• Keep the GovConfig in sync. When a referenced citizen bumps, publish a new gov fingerprint promptly.
• Operate confluences, basic services, and any standalone organisms commissioned. Standard committee-organism operations: monitor, rotate, respond to anomalies.
• Respond to integrators. Three typical questions: the current gov composition, the cause of a ConnectTimeout, and how to bind to a newly shipped confluence or service. The handshake page answers the first; the change channel the second; per-service docs the third.

Off the critical path

• Per-citizen operations for citizens not run by the gov operator. Those citizens operate themselves.
• Inter-citizen consensus. None exists; the gov is not a consensus unit.
• Cross-gov coordination. Two govs coexist on the universe and do not coordinate.
• Enforcement. The gov operator cannot force a citizen to change. Citizen changes are negotiated out of band.

Cross-references

• Quickstart — stand up a gov
• Running a confluence
• Federating under a gov
• Rotations and upgrades
• Contributor — basic services
• builder operator overview

Quickstart — stand up a gov

audience: operators

This runbook brings up a minimal gov: one GovConfig referencing two existing citizens (two block-building lattices, two standalone organisms, or one of each) and commissioning one basic service — an Atlas — that publishes a per-gov directory. Assumptions:

• The citizens to be referenced exist. If any are block- building lattices not yet run by the operator, follow the builder operator quickstart first; if any are standalone organisms not yet run, follow the organism crate’s runbook.
• Familiarity with the builder operator workflow: systemd units, published handshake pages, committee bring-up, MR_TD publication. The discipline is identical for any organism committee.
• The gov meta-crate (gov) exists in a form sufficient to derive GovConfig fingerprints. Until v0.2 lands, this is a paper exercise; the steps below are the target shape.

Estimated time to first GovConfig: two engineer-days, assuming referenced citizens and the Atlas crate are already running.

Step 1 — enumerate the citizens to reference

Record, for each citizen, the canonical fingerprint as published by its operator.

citizen                        kind      fingerprint (hex)    ticket-issuance root
-----------------------------+---------+---------------------+----------------------
ethereum.mainnet               lattice   0x…                  0x…
unichain.mainnet               lattice   0x…                  0x…
price-feed.eur                 organism  0x…                  0x…

Do not invent fingerprints locally. Always use the per- citizen operator’s authoritative value. A per-citizen operator’s fingerprint that cannot be reproduced from its published Config definition is a citizen-level issue; do not paper over it in the gov.

Step 2 — pick the gov name

Short, stable, namespaced. Examples:

• ethereum.superchain
• mev.mainnet-q2
• oplabs.testnet
• signals.euro-fx

The name is folded into the gov fingerprint; a typo propagates through every confluence derivation. Pick once. Rename via a new instance name, never via in-place edit.

Step 3 — decide which basic services to ship

One basic service suffices for a minimal gov. Atlas is the usual first choice:

• Small state machine — one CitizenCard commit per referenced citizen.
• Low trust requirement — usually non-TDX, majority- honest.
• High utility — integrators pin the Atlas in their own docs as the canonical gov-composition reference.

Ship Almanac, Chronicle, and Passport on their own schedules. Specifications in basic services.

A concrete cross-citizen problem (paired-bundle auctions, cross-chain attribution, oracle/lattice correlation) motivates commissioning the relevant confluence beyond the basic services. Each confluence is a separate crate and committee; do not conflate them.

Step 4 — draft the GovConfig

use builder::LatticeConfig;
use gov::{GovConfig, ConfluenceConfig, OrganismRef};

pub const ETHEREUM_MAINNET: LatticeConfig = /* from ethereum.mainnet operator */;
pub const UNICHAIN_MAINNET: LatticeConfig = /* from unichain.mainnet operator */;
pub const EUR_PRICE_FEED:   OrganismRef   = OrganismRef {
    role: "oracle",
    fingerprint: /* from the price-feed operator */,
};

pub const SUPERCHAIN_ATLAS: ConfluenceConfig = ConfluenceConfig {
    name: "atlas",
    lattices:  &[ETHEREUM_MAINNET, UNICHAIN_MAINNET],
    organisms: &[EUR_PRICE_FEED],
    content:   /* atlas content params */,
    acl:       /* TicketValidator composition */,
    gov_root:  /* filled in once GovConfig is frozen — see step 5 */,
};

pub const ETH_SUPERCHAIN: GovConfig = GovConfig {
    name: "ethereum.superchain",
    lattices:    &[ETHEREUM_MAINNET, UNICHAIN_MAINNET],
    organisms:   &[EUR_PRICE_FEED],
    confluences: &[SUPERCHAIN_ATLAS],
};

The gov_root field in a ConfluenceConfig is populated from the GovConfig’s fingerprint before the confluence itself is derived. See step 5 for the ordering.

Step 5 — freeze the fingerprint

The derivation order is:

1. Compute GOV = blake3("gov|" || name).
2. Compute GOV_LATTICES = ordered LatticeConfig fingerprints.
3. Compute GOV_ORGANISMS = ordered OrganismRef fingerprints.
4. For each confluence (including basic services), set its gov_root to the value produced in step 6 below. This requires a small fixed-point: compute the confluence fingerprints with gov_root stubbed, include the stubbed fingerprints in GOV_CONFS, compute GOV_ROOT, then re-evaluate each confluence with the real gov_root. The meta-crate’s derivation helper handles this.
5. Compute GOV_CONFS = ordered ConfluenceConfig fingerprints.
6. Compute GOV_ROOT = blake3(GOV || GOV_LATTICES || GOV_ORGANISMS || GOV_CONFS).
7. This GOV_ROOT is the gov_root each confluence folds in. The meta-crate’s helper ensures the round-trip is deterministic.

Once the fingerprint is frozen, record its hex in release-notes.md. Integrators verify that hex against the struct they compile.

Step 6 — stand up the Atlas (and any other basic services)

Every basic service is a mosaik-native organism (specifically, a confluence). To bring up the Atlas committee:

1. Install the Atlas binary on committee hosts (default N = 3; scale up as needed).
2. Bootstrap Raft peers on the shared universe using the Atlas’s GroupId derived from its ConfluenceConfig.
3. Publish the Atlas’s MR_TD (if TDX-gated) or the committee roster (if not).

Bring-up details are in the Atlas crate’s runbook and in Running a confluence. Atlas does not require TDX.

Step 7 — publish the handshake

Collect everything integrators need:

• GovConfig Rust const (or the hex fingerprint + struct definition).
• The ordered list of referenced LatticeConfig fingerprints with links to each lattice operator’s handshake.
• The ordered list of referenced OrganismRefs with role names, fingerprints, and a link to each organism operator’s handshake.
• Each confluence’s ConfluenceConfig (including basic services) with MR_TDs, state-machine signature, and a short description.
• A statement of which basic services the gov ships and which it does not — silence is ambiguous.
• An initial peer hint for the shared universe.
• Your change channel (email, feed, repo).

Post as a single page on the operator site or handshake repo. Link integrators to it.

Step 8 — notify integrators

A message on the change channel announcing the gov’s first GovConfig fingerprint is sufficient. Waiting integrators compile in the constant and open handles.

Ongoing operations

Day-to-day work is covered by the other operator pages:

• Running a confluence for operating each committee (including basic services).
• Federating under a gov for coordinating with other per-citizen operators.
• Rotations and upgrades for key rotations, MR_TD bumps, and citizen-fingerprint churn.

Failure modes

• Integrators report ConnectTimeout. Either the published GovConfig drifted from the live deployment, or a referenced citizen bumped and the gov operator has not republished. Recompile the struct, freeze the fingerprint, publish.
• A confluence’s committee lost majority. Standard mosaik recovery. Referenced citizens continue; integrators reading the confluence temporarily see no new commits.
• A referenced citizen bumped its fingerprint silently. The per-citizen operator should have notified the gov operator. File an anomaly with them, publish a new GovConfig against the new fingerprint, and tighten change-channel discipline with that operator.

Cross-references

• Gov overview
• Running a confluence
• Federating under a gov
• Contributor — basic services
• builder operator quickstart

Running a confluence

audience: operators

Operating a confluence is, at the protocol level, identical to operating any mosaik-native committee organism: a committee, a state machine, a narrow public surface. This page is the delta — what is new because the confluence spans multiple citizens (lattices, standalone organisms, or a mix).

Basic services (Atlas, Almanac, Chronicle, Passport) are confluences; the same rules apply. Each basic service’s crate publishes its own page once commissioned.

For the base runbook — systemd units, dashboards, incident response — follow the builder operator runbooks. Each per-confluence crate publishes its own page once commissioned.

What to add on top of a single-committee runbook

• Per-citizen subscription health. A confluence reads from multiple citizens’ public surfaces. The dashboard carries one subscription-lag metric per spanned citizen, not an aggregated metric. A confluence that stalls typically stalls on one citizen first.

• Per-citizen ticket health. Committee members hold tickets from each spanned citizen’s operator. When a per-citizen operator rotates their ticket-issuance root, the confluence’s bonds into that citizen break until new tickets are issued to the committee. Monitor ticket validity horizons per citizen.

• Citizen-fingerprint monitoring. When a referenced citizen bumps its Config fingerprint, the confluence’s own Config fingerprint is stale; the confluence must be redeployed under an updated ConfluenceConfig. Detect this before integrators do.

• Cross-operator communications. A confluence with citizens run by different operators requires a standing channel with each — at minimum a mailing list or chat channel for advance announcements of fingerprint bumps.

The lifecycle of a confluence commit

1. Committee driver watches each spanned citizen’s public collection / stream.
2. An upstream event fires; the driver wraps it in an Observe* command with an evidence pointer back to the upstream commit.
3. The confluence’s Group commits the Observe* via Raft.
4. Periodically (or on an apply-deadline timer), the driver issues an Apply command. The state machine reads accumulated observations and commits the confluence’s own fact.
5. The confluence’s public surface serves the committed fact to integrators and to any downstream consumers (other confluences, other organisms).

Every step is standard mosaik machinery. The confluence- specific work is the driver’s multi-subscription logic.

Rotations

A confluence rotates like any other organism:

• Committee member rotation. Add a new member under the same ConfluenceConfig; drain the old member; decommission. No fingerprint change.
• Committee admission policy rotation (e.g. an MR_TD bump). Requires a new ConfluenceConfig fingerprint. Publish an updated GovConfig. Follow the rotations and upgrades sequence.
• Spanned-citizen-set rotation. Adding or removing a spanned citizen changes the confluence’s content fingerprint. This is a larger change; typically accompanied by a GovConfig republication.

Rotations that do NOT break integrators

• Committee member swaps under a stable ConfluenceConfig. Integrators see a brief latency bump during drain; no handle failures.

Rotations that DO break integrators

• Any ConfluenceConfig fingerprint bump. Integrators compiled against the old config see ConnectTimeout on the confluence handle until they recompile against the new GovConfig. Announce ahead of time via the change channel.

Incident response specific to confluences

Two incident classes to add to your playbook on top of the single-organism classes in builder incident response.

Evidence-pointer resolution fails on replay

Symptom: a committee member replaying the log fails to resolve an evidence pointer to an upstream citizen commit. Cause: the upstream citizen committed the fact, the confluence observed it, but the citizen has since gone through a state compaction / reorg that removed the referenced commit from the public surface the confluence reads.

Response:

• The confluence state machine is required to reject such replays, not tolerate them.
• Confirm the issue is upstream-citizen retention, not confluence state.
• Coordinate with the per-citizen operator. The fix is usually citizen-side configuration: longer retention on the public surface the confluence subscribes to.

One spanned citizen goes dark

Symptom: no events from one of the spanned citizens’ public surfaces for multiple slots (or multiple publish ticks, if the citizen is an organism without a slot clock).

Response:

• Confirm with the per-citizen operator whether the outage is on their side or on the subscription.
• If on their side, fall back to the stall policy. A confluence committing partial evidence yields degraded commits; one stalling per slot yields no commits until the citizen returns. Integrators were warned in the composition-hooks doc.
• If on the subscription side: mosaik transport troubleshooting; nothing confluence-specific.

Cross-references

• Gov overview
• Quickstart — stand up a gov
• Federating under a gov
• Rotations and upgrades
• Contributor — basic services
• builder operator runbooks

Federating under a gov

audience: operators

A federated gov is one whose referenced citizens — lattices, standalone organisms, or a mix — are operated by different teams. The blueprint does not make federation special: a GovConfig references citizen fingerprints regardless of who runs them. Coordination patterns succeed or fail based on a few out-of-band agreements.

This page catalogues the agreements. The gov is not an authority, and federation does not grant new authority. Federation provides a shared handshake and a coordination channel.

The blueprint minimum

The gov operator needs the fingerprint of each referenced citizen. Any operator holding those fingerprints can publish a GovConfig including those citizens; there is no technical gate on referencing, and the GovConfig does not require the per-citizen operator’s signature.

This is intentional. A fingerprint reference is not a claim of authority over the citizen. A per-citizen operator objecting to a gov reference has no technical recourse, and the reference also has no technical consequence: every confluence committee member still needs tickets from each per-citizen operator to bond into those citizens’ public surfaces.

What a federation agreement should cover

Documented even when trust between operators is high.

Notification cadence

• Citizen-fingerprint bumps. The per-citizen operator notifies the gov operator at least one business day ahead of a bump.
• Ticket rotations. When a per-citizen operator rotates their ticket-issuance root, confluence committee members need new tickets before cutover.
• Retention changes. A citizen shortening retention of a public surface the confluence subscribes to breaks confluence replay. Notify the gov operator.

Ticket issuance for confluence committee members

The confluence committee reads each spanned citizen’s public surfaces and so requires per-citizen tickets. Agreements should cover:

• Who issues. Each per-citizen operator issues tickets for confluence committee members, exactly as for any integrator.
• Under what policy. Confluences usually need read- only tickets on specific surfaces (for a lattice: UnsealedPool, tally::Refunds; for an oracle organism: its feed stream). Scope accordingly.
• Rotation schedule. Tickets expire. A rotation cadence matching the per-citizen operator’s standard schedule is acceptable; unannounced rotations are not.

Confluence governance

When multiple citizens contribute inputs to one confluence, the confluence is itself a governance concern. Agreements cover:

• Who runs the committee? Often the gov operator; sometimes a subset of the per-citizen operators; occasionally a separate team.
• Who decides on Config bumps? The confluence operator, informed by the affected per-citizen operators.
• Conflict resolution. The escalation path when the confluence commits a record one per-citizen operator disputes (an attribution split, a cross-feed correlation).

None of this is in-protocol; all of it is contract. The gov does not arbitrate.

Publishing a federated gov

The handshake page makes federation visible:

• Per-citizen links. Each LatticeConfig or OrganismRef reference includes a link to the corresponding per-citizen operator’s handshake page.
• Operator roll call. A table listing each operator and the roles it holds (lattice, organism, confluence, basic service, gov).
• Federation change channel. Typically a shared channel across all participating operators rather than the gov operator’s individual channel, so that citizen-side changes are visible to every participant in-flight.

What federation does not change

• Mosaik-level security. Each citizen’s ACL is unchanged. Each confluence’s ACL is unchanged.
• Atomicity. No cross-citizen atomic commit. Federation does not provide it; no contract can.
• Integrator ergonomics. Integrators still compile one GovConfig; a federated gov is indistinguishable from a single-operator gov at the handle API.
• The non-authority stance. A federated gov does not acquire authority over its citizens by having more operators. The rules are unchanged: offer, do not compel.

A healthy federated-gov checklist

• Each referenced per-citizen operator has been notified.
• Ticket issuance for confluence committee members is documented per citizen.
• The change channel covers citizen bumps, ticket rotations, and confluence config changes.
• The handshake page lists every operator and their role.
• The gov operator’s confluences (including basic services) have a documented stall / degradation policy consistent with each spanned citizen’s expected availability.

Cross-references

• Gov overview
• Running a confluence
• Rotations and upgrades
• Contributor — threat model

Rotations and upgrades

audience: operators

Rotation discipline at the gov layer is thin: most rotations occur inside one citizen (a lattice, a standalone organism) or inside one confluence (including a basic service). The gov operator’s task is to republish the GovConfig when any referenced component changes. This page lists the rotations that materially affect a gov and the operation order for each.

For rotations inside a block-building lattice organism, follow the builder rotations page. For rotations inside a standalone organism, follow that organism’s own runbook.

Rotations that change a gov’s fingerprint

Any of the following forces a new GovConfig fingerprint. Publication is not optional: integrators compiled against the old fingerprint see ConnectTimeout on every handle until they recompile against the new one.

1. A referenced lattice’s LatticeConfig fingerprint changes.
2. A referenced standalone organism’s Config fingerprint changes.
3. A confluence’s ConfluenceConfig fingerprint changes (including basic services).
4. The gov’s lattice set changes (add or remove a lattice).
5. The gov’s organism set changes (add or remove a standalone organism).
6. The gov’s confluence set changes (add or remove a confluence or a basic service).
7. The gov instance name changes (rare — effectively a retirement; see below).

Items 1 and 2 are the most frequent. Items 4 through 6 are deliberate operational changes, typically announced weeks ahead.

Rotations that do not change a gov’s fingerprint

• Committee member rotations inside a referenced citizen, under a stable per-citizen Config.
• Committee member rotations inside a confluence (or basic service), under a stable ConfluenceConfig.
• MR_TD republications that match the previously pinned value (i.e. the image was rebuilt from the same source).
• Per-citizen secret rotations that do not touch the citizen’s Config inputs.

These are invisible to integrators at the gov layer. Documented per-citizen or per-confluence, not per-gov.

Ordering a citizen-fingerprint bump

When a referenced citizen bumps, follow this sequence.

1. Receive the bump notification from the per-citizen operator via the federation change channel. The notification includes the old and new fingerprints and the cutover time.
2. Prepare the new GovConfig. Update the citizen’s fingerprint in the GovConfig definition. Re-derive the gov fingerprint. Re-derive every confluence fingerprint (including basic services) folding the affected citizen.
3. Redeploy confluences under the new ConfluenceConfig. Because the confluence’s content folds the citizen fingerprint, its own fingerprint has bumped. Bring up new committee members on the new ConfluenceConfig while old members continue on the old one; rotate over.
4. Publish the new GovConfig fingerprint on the handshake page and change channel.
5. Wait for integrators to recompile. Old-fingerprint handles time out; integrators reach out if they miss the change.
6. Retire the old confluence deployments once the old GovConfig is no longer in use by the integrators the operator cares about.

Ordering a confluence (or basic-service) upgrade

A confluence’s Config may change for reasons other than upstream citizen bumps: new content parameters, MR_TD bump, ACL change. Basic services rotate under the same procedure.

1. Stand up the new deployment under the new ConfluenceConfig alongside the old.
2. Update the gov’s GovConfig to reference the new confluence. Recompute the gov fingerprint.
3. Publish the new GovConfig.
4. Announce the change via the change channel, with migration notes. If the Chronicle is shipped, its next commit records the rotation.
5. Retire the old deployment once integrators have migrated.

A transition window where old and new coexist is required; a hard cutover leaves every integrator timing out simultaneously.

Retiring a gov

A gov may be retired (renamed). Reasons:

• The composition has drifted far enough from the original intent that a clean break is preferable to incremental bumps.
• The set of operators federating under the gov has reorganised.
• Governance, branding, or regulatory considerations.

Sequence:

1. Announce retirement with substantial lead time. Integrators relying on the gov need weeks to migrate. A shipped Chronicle records the retirement in its next commit.
2. Stand up the replacement gov (e.g. ethereum.superchain-v2026q2) with a fresh GovConfig fingerprint and the desired composition.
3. Run both govs in parallel until most integrator traffic has migrated.
4. Retire the old gov’s confluences and basic services once integrator traffic drops to zero or acceptable levels.
5. Publish a retirement note. The old GovConfig fingerprint is formally deprecated; integrators still on it see ConnectTimeout once the confluences are down.

Do not reuse an instance name for a different composition. A retired gov’s name is spent; reissuing it under a new composition would produce silent mis-bindings across the integrator base.

Cross-references

• Gov overview
• Running a confluence
• Federating under a gov
• builder rotations

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.

1. Network topology. Does a gov live on its own NetworkId, or share a universe with every other mosaik service?
2. 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.

1. Identifier derivation from the organism’s Config fingerprint. Inherited from zipnet.

2. 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.

3. Fingerprint, not registry. Inherited from zipnet; reaffirmed by builder and here.

4. 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

1. 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.

2. 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.

3. Pick a confluence root. GOV_ROOT.derive("confluence").derive(name). The name is the confluence’s role (intents, ledger, market, correlate, …).

4. Define the Config fingerprint inputs. Content parameters affecting the state-machine signature, upstream public surfaces subscribed to, ACL composition.

5. Write typed constructors. Confluence::<D>::verb(&network, &Config). Never export raw StreamId/StoreId/GroupId across the crate boundary.

6. Specify TicketValidator composition on the public primitives. ACL lives there.

7. 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.

8. Document which citizens’ public surfaces are read. This is the composition contract; changes to it touch Composition.

9. Declare dependency on any basic services. If the confluence aligns to Almanac ticks or observes Chronicle entries, state so in the crate documentation.

10. 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.

11. 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.

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:

“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.

“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.

Basic services — Atlas, Almanac, Chronicle, Passport

audience: contributors

A basic service is a confluence (or, in the simplest shape, a single-committee organism) whose role is specified once in this blueprint so every instance means the same thing across govs. This chapter specifies the four basic services.

None of the four is mandatory. A gov may ship zero, one, two, three, or all four. If a gov ships a service named “Atlas”, it must have the shape on this page. A service named “Atlas” with a different shape is a bug, not a variant — the point of the catalog is that integrators and other confluences depend on the shape without reading per-gov operator prose.

Guiding discipline:

Fix the shapes, leave the catalogs open.

The four basic services, the GovConfig structure, and the ConfluenceConfig structure are shapes. Which of them any given gov ships, and what other confluences it commissions, and what citizens it composes, are open.

Atlas — the directory

Problem. Integrators need a canonical list of the gov’s citizens with operator metadata: role name, fingerprint, endpoint hint, ticket-issuance root, MR_TD pins, subscription schema version. Every gov currently invents its own handshake table; standardising the shape lets a dashboard, analytics agent, or failover service read any gov’s directory without per-gov parsing.

Shape. Atlas is a confluence whose public surface is a Map<CitizenId, CitizenCard>. Each card is co-signed by the Atlas committee:

pub struct CitizenCard {
    /// The citizen's fingerprint (LatticeConfig or
    /// OrganismRef fingerprint).
    pub citizen_id: UniqueId,
    /// Role name ("lattice", "oracle", "attest", ...).
    pub role: &'static str,
    /// Endpoint hints for cold-start bootstrap.
    pub endpoint_hints: &'static [EndpointHint],
    /// Ticket-issuance root of the citizen's per-operator
    /// ACL.
    pub ticket_issuance_root: UniqueId,
    /// MR_TD pins for TDX-gated organisms inside the
    /// citizen (if any).
    pub mrtd_pins: &'static [Mrtd],
    /// Free-form metadata the operator surfaces.
    pub metadata: &'static [(&'static str, &'static str)],
}

Config signature. An Atlas’s ConfluenceConfig folds:

• the gov root;
• the ordered list of citizen fingerprints the Atlas catalogues (usually identical to the gov’s, but may be a subset);
• the Atlas committee’s ACL.

State machine. One command per card write, one command per card retirement. Applies produce card updates in deterministic order.

Trust shape. Usually majority-honest, non-TDX. A TDX- attested Atlas is a natural v1+ refinement if the gov requires signed provenance of the directory itself.

When to ship. Almost always. Atlas is the cheapest basic service to operate and the highest-leverage for integrators.

When to skip. A single-citizen gov does not need a directory.

Almanac — the shared clock

Problem. Confluences correlating facts across citizens need a shared time axis. Each citizen’s clock is local — a block-building lattice has slots, an oracle has ticks, an analytics pipeline has batches. Without a shared monotonic beacon, every correlator re-invents its own tolerance window.

Shape. Almanac is a confluence whose public surface is a single append-only Stream<AlmanacTick>. Each tick is co-signed by the Almanac committee and carries a monotonic sequence number plus an observed wall-clock timestamp:

pub struct AlmanacTick {
    pub seq: u64,
    /// Approximate wall-clock, observed by the quorum at
    /// commit time. Not a precise clock; use `seq` for
    /// ordering and `observed_at` for loose alignment
    /// with external events.
    pub observed_at: SystemTime,
}

Config signature. An Almanac’s ConfluenceConfig folds:

• the gov root;
• the tick cadence (target inter-tick interval; state- affecting);
• the Almanac committee’s ACL.

State machine. A per-cadence-deadline Commit command. Committee members propose ticks; the one that wins the Raft round commits; others observe.

Trust shape. Majority-honest committee; optionally TDX-attested if the gov requires observed_at to carry an attested source.

When to ship. When more than one confluence needs cross-citizen timing, or when a standalone organism without a slot clock participates in cross-citizen correlation.

What it is not. Almanac is not a consensus clock for the universe; it is not synchronised across govs; it is not a substitute for each citizen’s own local clock. Ticks are ordering markers, not timestamps.

Chronicle — the audit log

Problem. A gov operator makes decisions that outlive any one GovConfig — publications, rotations, retirements, federation changes, basic-service upgrades. Integrators, auditors, and future operators need a tamper-evident record. Operator-published release notes are insufficient; they can be edited in place.

Shape. Chronicle is a confluence whose public surface is an append-only Stream<ChronicleEntry>. Each entry is co-signed by the Chronicle committee:

pub struct ChronicleEntry {
    pub seq: u64,
    pub kind: ChronicleKind,
    /// The gov fingerprint at the moment of entry.
    pub gov_root: UniqueId,
    /// Structured payload per kind.
    pub payload: ChronicleBody,
    pub observed_at: SystemTime,
}

pub enum ChronicleKind {
    GovPublication,          // new GovConfig fingerprint
    CitizenAdded,            // new lattice / organism reference
    CitizenRemoved,
    ConfluenceUpgraded,      // ConfluenceConfig fingerprint bump
    BasicServiceAdded,
    BasicServiceRetired,
    FederationChanged,       // operator added / removed
    Retirement,              // gov retirement announcement
    Other(&'static str),
}

Config signature. A Chronicle’s ConfluenceConfig folds:

• the gov root;
• the Chronicle committee’s ACL;
• the schema version of ChronicleEntry.

State machine. One command per entry. Applies maintain a strictly monotonic seq. Retention is operator-configured but must be substantial (years, not days) — the point is longevity.

Trust shape. Majority-honest; TDX is common when the Chronicle must attest observed_at accurately. A gov that also ships a Passport often lets Chronicle entries be countersigned by the actor that triggered them (a federation operator, a basic-service operator).

When to ship. When the gov has more than one operator, a contested lineage (retirements, splits, forks), or a real need for externally verifiable provenance.

What it is not. Chronicle is descriptive, not prescriptive. It records decisions; it does not ratify them. A heavy-gov proposal could build ratification on top of Chronicle; that is not this blueprint.

Passport — optional citizenship

Problem. Some govs want a lightweight notion of “citizen of this gov” separate from the per-citizen ticket discipline — for discount rates, preferred routing, cross-operator recognition, or brand alignment. Ad hoc implementation per gov invites inconsistency and silent privilege leaks.

Shape. Passport is a confluence whose public surface is:

• a write-side Stream<PassportRequest> (a citizen’s operator submits a request to be recognised);
• a read-side Map<OperatorId, PassportGrant> (the committee’s decision, with an expiry).

pub struct PassportRequest {
    pub operator_id: UniqueId,
    pub citizens: &'static [UniqueId],
    pub attestation: Option<Mrtd>,
    pub purpose: &'static str,
}

pub struct PassportGrant {
    pub operator_id: UniqueId,
    pub granted_at: SystemTime,
    pub expires_at: SystemTime,
    pub scopes: &'static [&'static str],
}

Config signature. A Passport’s ConfluenceConfig folds:

• the gov root;
• the Passport committee’s ACL;
• the grant policy (state-affecting: issuable scopes, default expiry, attestation thresholds).

State machine. Request commands are validated against the policy; grant commands commit grants with expiries; revocation commands invalidate grants before expiry.

Trust shape. Variable. Passport for a single-operator gov is usually a thin layer over the operator’s own identity; Passport for a federated gov typically requires TDX attestation and a majority-honest committee to resist any one operator-member forging grants.

When to ship. When the gov has cross-operator federation and wants a durable cross-operator recognition primitive outside each citizen’s per-lattice ACL. Rarer than Atlas, Almanac, or Chronicle.

What it is not — strict. Passport is opt-in for citizens and integrators alike. Never required for a citizen to operate. A citizen’s operator may decline to request a Passport and the gov has no recourse. Integrators may present a Passport for preferred routing or ignore it. This is load-bearing: a Passport that required citizens to hold one would cross from light- gov to heavy-gov (authority over membership), which this blueprint refuses.

Deriving a basic service’s identity

Every basic service is a confluence; its derivation follows the confluence rule:

  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")

  <service>_committee = blake3(
      <service>_root
      || ordered citizen ids it spans (if any)
      || service_content_fingerprint
      || service_acl_fingerprint
  ).derive("committee")

The "service" prefix distinguishes basic services from commissioned confluences (which use "confluence"). The distinction is cosmetic but useful: an operator reading peer-discovery gossip can tell which is which at a glance.

GovConfig helpers

Because basic services have well-known names, the gov meta-crate ships typed helpers returning their ConfluenceConfigs from a GovConfig:

impl GovConfig {
    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> { /* ... */ }
}

Each helper looks up a ConfluenceConfig in the gov’s confluences slice by name ("atlas", etc.) and returns Some if found, None otherwise. A gov that ships the service names its ConfluenceConfig accordingly; a gov that does not ship it omits the entry.

Integrators use these helpers to stay forward-compatible: a gov adding Almanac later does not break an integrator that did not use it before, and the integrator can start using it simply by re-reading gov.almanac().

Deliberately unspecified

• Chronicle retention policy and storage layout. Operator-configured. The spec requires durability and a monotonic seq; it does not prescribe how operators achieve them.
• Passport grant policies. Each gov picks its own issuance criteria; the spec pins only the request / grant surface.
• Almanac tick cadence. The spec allows any state- affecting cadence; different govs will pick substantially different rates.
• Atlas metadata schema. Free-form (key, value) pairs beyond the required fields. Operators add what they need; standardisation emerges from patterns over time.
• Whether a basic service is required for any downstream confluence. Confluences may depend on a basic service (e.g. a correlator aligning to Almanac ticks), but the blueprint does not require it; a confluence that needs a service declares the dependency in its own ConfluenceConfig.
• Heavy-gov extensions. Law, taxation, enforcement, mandatory citizenship — all deferred, all requiring a fresh proposal that restates the non-authority line.

Cross-references

• topology-intro — rationale for the gov rung.
• architecture — basic services in an example gov.
• confluences — the generic shape every basic service inherits.
• composition — how a basic service’s subscriptions compose with the rest of the gov.
• threat model — trust composition when a confluence depends on a basic service.

Confluences — the cross-citizen organism

audience: contributors

A confluence is a mosaik-native organism whose Config fingerprint folds two or more citizen fingerprints (LatticeConfig fingerprints, OrganismRef fingerprints, or a mix) and whose public surface coordinates across the referenced citizens. It is the new primitive the gov rung introduces. This chapter specifies its shape, compares it against alternatives, and provides a template for commissioning a new one.

Basic services (Atlas, Almanac, Chronicle, Passport) are confluences. Their shapes are specified once in basic services; the generic confluence discipline below applies to all of them.

The reader is assumed to have read Designing governments on mosaik and Anatomy of a gov.

Definition

A confluence is an organism in every sense the zipnet and builder books use the word. It has:

• one Config fingerprint derived under a gov root;
• a narrow public surface (one or two named primitives);
• a TicketValidator composition gating bonds;
• typed Confluence::<D>::verb(&network, &Config) free- function constructors;
• a deterministic state machine inside a mosaik Group.

What distinguishes a confluence from a standalone organism:

• Its content fingerprint folds in multiple citizen fingerprints — the ordered set of citizens whose public surfaces it reads from (or writes to).
• Its state machine’s commits are a function of inputs drawn from more than one citizen’s public surface, and serve consumers on more than one citizen.

A confluence is not a seventh lattice organism; it is not part of any lattice’s identity derivation; no per-citizen operator has to know what confluences reference their citizen.

When to commission one

Commission a confluence when all three of the following hold.

1. The aggregated fact is itself a commit. If what you need can be computed ad hoc by an integrator across N citizen handles, it does not need a confluence. If multiple downstream consumers would each have to repeat the same aggregation, or if the aggregation is itself the input to yet another organism, the commit pays for itself.

2. The inputs span more than one citizen. A confluence that reads only from one citizen is an organism in disguise; it belongs as a standalone organism (or inside that citizen’s own composition, if the citizen is a lattice).

3. The trust model is coherent across the inputs. A confluence inherits the worst-case trust assumption of the citizen inputs it reads. If you cannot name the cross-citizen trust shape (e.g. “majority-honest across each lattice’s unseal committee, t-of-n on the oracle organism, plus majority-honest confluence committee”), you have not finished the design.

When any of the three is false, the right answer is one of:

• A cross-citizen integrator (Shape 1 in builder’s cross- chain chapter, generalised to any mix of citizens).
• An in-lattice organism that reads a sibling lattice’s public surface (Shape 2).
• A new standalone organism.
• A new organism inside an existing lattice.

Confluence versus cross-citizen integrator

Heuristic: if three different integrators would all perform the same aggregation, it is a candidate confluence. If exactly one integrator needs it, keep it in the agent.

The Config fingerprint

A confluence’s Config folds in:

pub struct ConfluenceConfig {
    /// Role name: "intents", "ledger", "market",
    /// "correlate", … For basic services:
    /// "atlas", "almanac", "chronicle", "passport".
    pub name: &'static str,

    /// Ordered set of block-building lattices whose
    /// public surfaces this confluence reads or writes.
    pub lattices: &'static [LatticeConfig],

    /// Ordered set of standalone organisms whose public
    /// surfaces this confluence reads or writes. Same
    /// story as `lattices` above, for non-lattice
    /// citizens.
    pub organisms: &'static [OrganismRef],

    /// State-affecting parameters specific to this
    /// confluence. E.g. an intent router's policy
    /// constants, a shared ledger's attribution model,
    /// an almanac's tick cadence.
    pub content: ContentParams,

    /// TicketValidator composition gating committee
    /// admission.
    pub acl: AclComposition,

    /// The GovConfig fingerprint this confluence was
    /// commissioned under. Pinned so a confluence
    /// misfiled into the wrong gov derives a disjoint
    /// GroupId and fails to bond, rather than silently
    /// cross-mounting.
    pub gov_root: UniqueId,
}

impl ConfluenceConfig {
    pub const fn confluence_id(&self) -> UniqueId { /* ... */ }
}

The gov_root field pins the confluence to a specific gov’s fingerprint. A confluence with a given content + acl + lattices + organisms deployed under gov A and gov B derives different GroupIds because the gov roots differ — the same discipline every organism uses to pin its parent root.

A use case requiring “the same confluence under two govs” deploys two confluences with matching content and different gov_roots. Whether the two committees share members is an operator decision, not a protocol constraint.

Public surface

Confluences follow the narrow-public-surface discipline without modification. Guidelines for picking the surface:

• Key every commit by (citizen_id, slot) or (citizen_id, tick) when the confluence is per- clock-event per-origin-citizen. Integrators that join commits across confluences need this key.
• Separate routing and attestation. If your confluence both routes inputs (a write-side stream) and commits the routing outcome (a read-side collection), keep the two primitives named. Do not fold them into one.
• Expose attestations separately when the commit carries an attestable signature. Integrators that pull attestations to on-chain settlement contracts want the signature surface distinct from the routing surface.
• If your confluence depends on a basic service, declare it. A correlator that aligns to Almanac ticks reads Almanac and commits under (citizen_id, almanac_tick) keys; state that in the crate’s composition-hooks doc and in the ConfluenceConfig.content parameters (since the alignment is state-affecting).

A design wanting three or more public primitives is likely two confluences.

State machine shape

Inside the confluence’s Group, the state machine is an ordinary mosaik StateMachine<M>. It differs from a standalone organism’s state machine only in what its inputs look like: driver code outside the state machine subscribes to public surfaces on each spanned citizen and feeds observed facts into the confluence group via group.execute(...).

Template for a confluence driver:

// Inside the confluence's node crate, role: committee member.
loop {
    tokio::select! {
        // Per-citizen subscriptions the confluence reads from.
        ev = lattice_a_subscription.next() => {
            let evidence = build_evidence_for_a(ev);
            confluence_group.execute(ConfluenceCmd::ObserveLatticeA(evidence)).await?;
        }
        ev = lattice_b_subscription.next() => {
            let evidence = build_evidence_for_b(ev);
            confluence_group.execute(ConfluenceCmd::ObserveLatticeB(evidence)).await?;
        }
        ev = organism_c_subscription.next() => {
            let evidence = build_evidence_for_c(ev);
            confluence_group.execute(ConfluenceCmd::ObserveOrganismC(evidence)).await?;
        }
        // Optional: align to the gov's Almanac.
        ev = almanac_subscription.next() => {
            let tick = /* ... */;
            confluence_group.execute(ConfluenceCmd::AdvanceTick(tick)).await?;
        }
        // Confluence's own timers, per its state machine.
        _ = apply_deadline.tick() => {
            confluence_group.execute(ConfluenceCmd::Apply).await?;
        }
    }
}

Rules:

• Observations are evidence, not authority. The Observe* commands carry a pointer to the upstream citizen commit (citizen id, slot or tick, commit hash). The confluence’s state machine validates the pointer against the citizen’s public surface on replay.
• Applies are pure functions. apply(ConfluenceCmd::Apply) reads the accumulated observations and emits the confluence’s commit. It does not make new cross-citizen reads inside apply; reads belong to the driver.
• No cross-Group calls inside apply. Same discipline as every organism.

ACL and attestation

A confluence’s TicketValidator composition can include:

• Per-citizen readership tickets. A confluence reading from lattice A’s unseal::UnsealedPool or from an oracle organism’s feed is an integrator of that citizen from the citizen’s perspective. Committee members must hold tickets the per-citizen operator issues, same as any other integrator reading that surface.
• TDX attestation. If the confluence sees cleartext order flow or otherwise-sensitive data, the committee members are almost always required to run an attested TDX image. .require_ticket(Tdx::new().require_mrtd(confluence_mrtd)) is the standard line.
• Gov-scoped admission. The gov operator may want to require confluence members to hold a “member of gov X” ticket, separate from the per-citizen tickets — often via the gov’s Passport basic service when one is shipped. This is optional; the discipline is up to the confluence.

Failure modes

A confluence has more failure modes than a standalone organism because its inputs are federated:

• One spanned citizen stalls. The confluence’s state machine must decide whether to commit with partial evidence (degrading quality but preserving liveness) or to stall that slot pending the missing citizen (preserving quality but sacrificing liveness on the slot). This is a per-confluence choice; document it in the composition contract.
• One spanned citizen’s fingerprint changes. The confluence’s Config folds that fingerprint; a change means the confluence must be redeployed. Until it is, the confluence’s subscriptions to the old citizen fingerprint simply stop producing events.
• Confluence committee loses majority. Same failure mode as any mosaik Raft group. Liveness is lost; integrity is intact.
• Spanned citizen’s ACL changes. If a per-citizen operator revokes the ticket committee members hold, the confluence loses read access to that citizen’s public surface. Negotiated out of band; there is no technical recourse.

Composition patterns worth naming

Three patterns recur often enough to name. These are patterns, not required confluences; basic services are the specified shapes.

Intent-router pattern

A confluence whose state machine commits per-slot routed intents keyed by (target_lattice_id, slot). Reads cleartext from each spanned lattice’s unseal::UnsealedPool; commits a RoutedIntents collection each target lattice’s offer subscribes to. Trust shape: TDX-attested committee plus t-of-n threshold on the cross-citizen cleartext channel.

The builder book’s Shape 3 bridge organism is an intent- router pattern seed.

Shared-ledger pattern

A confluence whose state machine aggregates per-lattice tally::Refunds into a cross-origin-citizen attribution set, committed as SharedRefunds and SharedAttestations. Trust shape: majority-honest confluence committee plus the per-citizen trust shape of each spanned tally. An on-chain settlement contract verifying a SharedAttestation verifies both the confluence’s signature and the underlying per-lattice tally::Attestation referenced as evidence.

Integrators needing one refund feed across chains bind the confluence; integrators concerned with a single chain bind that lattice’s tally directly. Both paths coexist.

Cross-feed correlator pattern

A confluence that pairs ticks from two or more oracle organisms (or more generally, two or more non-slotted standalone organisms), committing correlated values under (citizen_id, almanac_tick) when the gov ships an Almanac, or under (citizen_id, timestamp_bin) otherwise. Trust shape: majority-honest confluence committee plus the signing assumptions of each upstream oracle.

Other patterns worth naming (non-block-building)

The three patterns above originate in block-building. Other domains will yield more. Sketches:

• Attestation aggregator. A confluence that folds MR_TD quotes from multiple attestation organisms across vendors or regions into a single attested membership set.
• Coordination-market organiser. A confluence that runs an allocation auction where inputs come from several independent signal organisms and outputs drive several independent downstream citizens.
• Cross-DA committer. A confluence that commits a combined availability proof over two or more DA shards.

Each is a ConfluenceConfig whose lattices slice may be empty and whose organisms slice names the upstreams.

Checklist mirror

The commissioning checklist in topology-intro — Checklist for commissioning a new confluence applies verbatim. This page is the reference; the topology-intro page is the forcing function when commissioning one.

Cross-references

• topology-intro — why this rung exists.
• basic-services — the four specified confluence shapes.
• architecture — where confluences sit in one example gov.
• composition — the subscription graph that citizens and confluences share.
• atomicity — what confluences deliberately do not guarantee.
• threat-model — how a confluence’s trust assumption composes with the spanned citizens’.

Composition: citizens and confluences in a gov

audience: contributors

Architecture maps confluences and citizens onto one example gov. Confluences specifies the confluence organism. Basic services specifies Atlas, Almanac, Chronicle, and Passport. This chapter shows the wiring: which public surface each confluence subscribes to on each spanned citizen, how the subscription graph grows as confluences and basic services are added, and what fails where when an upstream stalls.

The wiring is deliberately weak. No cross-Group atomicity, no shared state across citizens, no global scheduler. Citizens and confluences react to each other’s public commits via mosaik’s when() DSL and Collection / Stream subscriptions. This is the composition model at every rung.

Two keys: citizen id and clock event

Every commit in every block-building lattice is keyed by slot (see builder composition). Every commit in a standalone organism is keyed by that organism’s own clock event — a slot, a tick, a round, a sequence number. A gov adds the citizen id as an outer key on every cross-citizen fact. Concretely:

• Intra-citizen commits continue to key on their own clock alone (no change from the citizen’s own book).
• Confluence commits that fan-out to multiple target citizens key on (target_citizen_id, target_clock_event).
• Confluence commits that fan-in from multiple origin citizens key on (origin_citizen_id, origin_clock_event).
• An integrator joining commits across a confluence and the citizens the confluence touches keys on (citizen_id, clock_event) everywhere.
• When the gov ships an Almanac, a confluence may additionally carry almanac_tick as an alignment key for cross-citizen joins where the citizens’ native clocks are not commensurate.

The citizen id is the LatticeConfig or OrganismRef fingerprint of the citizen in question: small, stable, and monotonic in the sense that it never changes for a given deployment. A citizen bump yields a new fingerprint and is therefore a new citizen id for every gov that adopts it.

The subscription graph

Each arrow is a subscription. The downstream component watches the upstream’s public collection or stream and reacts in its own state machine. No arrow represents atomic cross-Group commit. Dashed boxes are confluences; the oracle box on the left is a standalone organism.

   integrators
   (wallets,
    searchers)
        │
        ├──► zipnet[L1]:Submit ────► Broadcasts[L1] ──► UnsealedPool[L1] ─┐
        │                                                                  │
        ├──► zipnet[L2]:Submit ────► Broadcasts[L2] ──► UnsealedPool[L2] ─┤
        │                                                                  │
        └──► offer[L1]:Bid / offer[L2]:Bid                                 │
                                                                            │
   price-feed.eur ──► Price[tick]                                          │
                                                                            │
   almanac     ──► Ticks[K]                                                │
        │                                                                   │
        └──────────── referenced by confluences for alignment ──────┐     │
                                                                    ▼     │
                                                       ┌────────────────── ┘
                                                       ▼
                                          ┌───────────────────────┐
                                          │ intents (confluence)  │
                                          │ reads UnsealedPool[*] │
                                          │   + price-feed.eur    │
                                          │ commits RoutedIntents │
                                          └───────────────────────┘
                                                       │
                      RoutedIntents[L1,S] / RoutedIntents[L2,S]
                                                       ▼
                       offer[L1]:AuctionOutcome     offer[L2]:AuctionOutcome
                                 │                            │
                         atelier[L1]:Candidates       atelier[L2]:Candidates
                                 │                            │
                         relay[L1]:AcceptedHeaders    relay[L2]:AcceptedHeaders
                                 │                            │
                         tally[L1]:Refunds            tally[L2]:Refunds
                                 │                            │
                                 └────────────┬──────────────┘
                                              ▼
                                   ┌──────────────────────────┐
                                   │ ledger (confluence)      │
                                   │ reads Refunds[*]         │
                                   │ commits SharedRefunds    │
                                   └──────────────────────────┘
                                              │
                                              ▼
                                         integrators

   atlas ──► CitizenCards (consumed by dashboards, not gov pipeline)
   chronicle ──► ChronicleEntries (consumed by auditors, not gov pipeline)

Read top to bottom:

1. Wallets submit to each lattice’s zipnet::Submit; searchers submit to each lattice’s offer::Bid. Neither changes from builder.
2. Each lattice’s zipnet and unseal do their usual work independently. The oracle organism price-feed.eur publishes ticks on its own clock. The Almanac (if shipped) publishes its own tick stream.
3. The intents confluence subscribes to every spanned citizen’s relevant public surface — lattices’ UnsealedPools and, in this example, price-feed.eur’s Price stream. It may additionally subscribe to the Almanac for alignment keys. It observes cross-citizen intents and commits routed-intents entries per target lattice.
4. Each lattice’s offer subscribes to the confluence’s RoutedIntents collection filtered for its own citizen id. Routed intents are an additional input to the auction, along with the lattice’s own UnsealedPool.
5. Each lattice’s atelier and relay proceed as in builder.
6. Each lattice’s tally commits independently.
7. The ledger confluence subscribes to every spanned lattice’s tally::Refunds and commits the aggregated SharedRefunds collection.
8. Integrators read SharedRefunds and per-citizen surfaces depending on their use case. Dashboards read the Atlas. Auditors read the Chronicle.

Atlas and Chronicle are not on any confluence’s critical path in this example; they are consumed by dashboards and auditors directly. Basic services serve observability and provenance, not the gov’s data flow.

Subscription code shape

A contributor implementing a confluence writes a role driver in that confluence’s crate. The driver is a mosaik event loop multiplexing subscriptions across citizens and calling group.execute(...) on its own Group. The pattern is identical to any organism driver, fanned out across more citizen kinds.

// Inside intents::node::roles::committee_member.
//
// `lattices` and `organisms` are the ordered sets of
// citizen fingerprints the confluence spans, sourced from
// self.config.lattices and self.config.organisms.
loop {
    tokio::select! {
        // One subscription per spanned lattice's UnsealedPool.
        ev = pool_a.when().appended() => {
            let round = pool_a.get(ev).expect("appended implies present");
            let intents = extract_cross_chain_intents(&round);
            self.group.execute(IntentsCmd::ObservePool {
                citizen_id: lattice_a_id,
                slot: round.slot,
                intents,
            }).await?;
        }
        ev = pool_b.when().appended() => {
            // ... same shape
        }
        // One subscription per spanned standalone organism.
        ev = price_feed_eur.when().appended() => {
            let tick = price_feed_eur.get(ev).unwrap();
            self.group.execute(IntentsCmd::ObservePrice {
                citizen_id: eur_feed_id,
                tick: tick.seq,
                price: tick.value,
            }).await?;
        }
        // Optional: align to the gov's Almanac.
        ev = almanac.when().appended() => {
            let t = almanac.get(ev).unwrap();
            self.group.execute(IntentsCmd::AdvanceAlmanacTick(t.seq)).await?;
        }
        _ = self.apply_clock.tick() => {
            // Per-slot deadline: seal the routing decision.
            self.group.execute(IntentsCmd::SealSlot).await?;
        }
    }
}

Every observed event carries enough evidence ((citizen_id, clock_event, commit_pointer)) that the state machine can validate it against the citizen’s public surface during replay.

Apply order across the graph

Within one confluence’s Group, mosaik’s Raft variant guarantees every committee member applies commands in the same order. Across confluences, and across citizens, no such guarantee exists. The gov layer relies on the same two properties the builder layer does, scaled up:

1. Monotonicity by key. Within any component, commits for key (C, K+1) are not applied before (C, K). The component’s state machine enforces this per- citizen in its apply handler.
2. Eventual consistency by subscription. A downstream component’s driver observes every upstream commit eventually, because mosaik collections are append-only and readers converge.

Together these are enough to reconstruct a consistent per-citizen per-clock-event view across the whole gov without global atomicity. An integrator wanting “the canonical decision for citizen C, clock event K, across citizens and confluences” reads each component’s per- (C, K) commit independently and joins on the key.

When an upstream stalls

Failure propagation is a small matrix. Rows are the failing component; columns are downstream components’ observable behaviour.

Two properties fall out, mirroring builder’s:

• Upstream failures degrade downstream outputs; they do not corrupt them. A missing UnsealedPool[L1, S] narrows the intents confluence’s commit for that slot; the commit itself remains well-formed.
• The pipeline is drainable per citizen. Failures on one citizen do not block the gov’s other citizens. Each citizen’s pipeline is local; each confluence applies what it observes.

What the gov composition contract guarantees

Given the full commit logs of every citizen and every confluence the gov references:

• Deterministic replay per (citizen_id, clock_event). Anyone can recompute each component’s per-(C, K) decision and cross-check confluence commits against the citizen inputs they folded in.
• Independent auditability. A confluence’s commit carries evidence pointers to the citizen commits it depends on. A consumer that trusts the citizens can verify a confluence’s commit without trusting the confluence’s committee, as long as the evidence pointers resolve.
• No silent corruption across govs. A citizen referenced from multiple govs is still one citizen; its commit log is one log. Different govs reading the same citizen see the same facts.

What the contract does not guarantee

• Atomic all-or-nothing commits across citizens. Already refused. An integrator reading a confluence’s commit and the spanned citizens’ commits must tolerate differing commit wall-clock times.
• Cross-gov coordination. Govs coexist, they do not coordinate. If a cross-gov commit is genuinely needed, that confluence either spans govs (in which case it is still just a confluence whose content folds multiple GovConfigs — see topology-intro — No cross-Group, cross-citizen, or cross-gov atomicity) or the two govs should have been one.
• Bounded end-to-end latency. As in builder: if a confluence stalls, downstream consumers never see its next commit. No confluence-level timeout triggers a dummy commit; operators requiring bounded latency add per-slot deadlines at the confluence level.

Contributors implementing a new confluence

Wiring checklist for a confluence:

1. Identify every spanned citizen’s public surface you subscribe to. Record as ordered slices of citizen references in your Config — lattices, organisms, or both.
2. Decide whether your commits fan-in, fan-out, or both. Fan-in confluences aggregate per-origin- citizen facts; fan-out confluences distribute one fact to multiple target citizens; some confluences do both.
3. Key every commit by (citizen_id, clock_event). Never by one alone. If your state machine has a natural sub-clock-event cadence, commit at that cadence but carry the owning (citizen_id, clock_event) pair. If the gov ships an Almanac and your confluence needs cross-citizen alignment, also carry almanac_tick.
4. Write one role driver per Group member role. Keep it as a tokio::select! over the upstream subscriptions (one per citizen) and your local timers.
5. Validate evidence on replay. The upstream-event pointers carried in your Observe* commands must be checkable against the citizen’s public surface during replay; a replay that sees an unresolved evidence pointer must reject the command.
6. Document your per-citizen-failure policy. What happens when one spanned citizen stalls, reorders, or bumps its fingerprint — all three are operational realities.
7. Declare dependency on basic services. If you require an Almanac for alignment, or consume Chronicle entries, document it.
8. Document the composition contract in your confluence’s contributors/composition-hooks.md (per-confluence documentation). Update architecture and this page’s subscription graph to include the new confluence if the example gov is the right place for it.

Cross-references

• Architecture — the gov shape these subscriptions run on.
• Confluences — the organism the arrows land on.
• Basic services — Atlas, Almanac, Chronicle, Passport details.
• Atomicity — what the subscription graph deliberately does not buy you.
• Threat model — how trust assumptions compose across the subscription graph.

Atomicity boundary

audience: contributors

This chapter states what the gov layer does and does not guarantee about atomicity, supplying one reference page for design reviews of new confluences or extensions to the gov model.

The rules are inherited from zipnet and builder. The gov layer introduces no new atomicity primitive; it makes the inherited boundary legible one rung higher.

What the gov layer does not provide

The gov layer does not provide:

• Cross-Group atomicity inside a citizen. Rejected by builder for lattices and by each organism’s own design for standalone organisms. Two organisms commit independently and subscribe to each other’s public surfaces.
• Cross-citizen atomicity inside a gov. Rejected by this blueprint. Two citizens in the same gov commit independently and a confluence subscribes to both.
• Cross-gov atomicity. Rejected by this blueprint. Two govs coexist on the shared universe and have no shared consensus unit.
• Multi-confluence atomicity. Rejected by this blueprint. Two confluences in the same gov each commit to their own Group; integrators that need joint commits join by key.

The rejection is load-bearing at every rung. Admitting one atomicity primitive at any rung forces every rung below to carry it, collapsing the trust and operational boundaries the rungs were designed to isolate. It also re-enters heavy-gov territory: a gov-level atomicity primitive is a gov-level enforcement primitive.

What the gov layer does provide

The gov layer provides, as a consequence of the composition discipline:

• Per-component atomicity. Every organism, every confluence, and every basic service commits atomically within its own Group. Mosaik’s Raft variant guarantees single-Group atomicity.
• Determinism of replay. Given the commit logs of all components the gov references, each component’s per-key decision is reproducible. The evidence pointers confluences carry make cross-component replay legible.
• Independent auditability. A consumer verifying a confluence’s commit need trust only the spanned citizens’ own commit logs (and the confluence’s committee, to whatever its trust shape permits). They do not need a gov-wide replay to audit one confluence’s decision.
• Provenance (if Chronicle is shipped). Not atomicity, but a record of gov-level decisions over time: which GovConfigs were published when, which confluences were added or retired, which federations joined. Audit trail, not atomicity.

What integrators and operators must design around

Three recurring realities.

Partial outcomes across citizens

An integrator placing paired bundles on two lattices, or correlating an oracle tick with a lattice auction outcome, must tolerate partial observation: citizen A commits, citizen B does not. The gov layer surfaces this, it does not mitigate it. Every integrator driver spanning citizens carries reconciliation logic (post-bond collateral, on-chain HTLCs, searcher-level risk management, timestamp tolerance windows — whichever matches the domain).

Staggered commits through confluences

A confluence’s commit for (citizen_id, clock_event) lags the upstream citizens’ own commits for that event by at least one Raft round inside the confluence’s committee. Consumers reading both treat the citizen commit as ground truth and the confluence commit as derived aggregation.

Citizen fingerprint bumps

A citizen bump changes the citizen’s Config fingerprint. A gov that references that citizen sees its confluences derive new IDs on the next GovConfig publication. During the transition, old and new confluence deployments coexist: old committee members under the old gov root, new under the new. Neither interferes with the other. If the gov ships a Chronicle, the next Chronicle entry records the transition.

Promotion path if atomicity is genuinely required

If a concrete use case forces atomicity across components:

• If it’s one lattice, two organisms: design a lattice organism that owns both decisions. That is the same answer builder topology-intro gives.
• If it’s one gov, two citizens: design a confluence that owns both decisions, subscribing to the two citizens’ relevant public surfaces. The state machine will commit one atomic record per event-pair; the two citizens themselves still commit independently, but the confluence’s commit is the authoritative joint fact. HTLC-style commit semantics live inside the confluence’s state machine, not across citizens.
• If it’s two govs: the govs should have been one, or the cross-gov confluence pattern should be promoted — at which point the hierarchy extends. See topology-intro — Confluences where govs do derive.

In every case the atomicity primitive lives inside one Group, not across Groups. This is the rule the whole ladder obeys.

Cross-references

• topology-intro — No cross-Group, cross-citizen, or cross-gov atomicity
• Composition — What the contract does not guarantee
• builder — No cross-Group atomicity

Threat model

audience: contributors

This chapter states the trust assumptions the gov layer adds over the builder and zipnet trust models, and describes how per-component trust composes when citizens (lattices and standalone organisms) and confluences (including basic services) are referenced under one GovConfig.

It does not re-derive per-organism trust shapes inside a lattice; those live in builder threat model. It does not re- derive trust shapes for standalone organisms; those live in each organism’s own book. The gov layer inherits them unchanged.

Goals and non-goals at the gov layer

Goals.

• Trust is strictly compositional. A property of a single citizen is not weakened by that citizen being referenced in a gov. Referencing is ambient; it does not open new channels into the citizen.
• Confluence commits are independently auditable against the citizen commits they fold in. A consumer that trusts the spanned citizens can verify a confluence’s commit without trusting the confluence’s committee, up to the confluence’s own majority-honest bound.
• Gov identity is not spoofable past its use. A gov fingerprint is a naming convenience; code treating it as authority is misusing it. The blueprint makes this explicit so misuse is a design bug, not a protocol bug. The word government connotes authority, so the blueprint restates the non-authority stance wherever it is load-bearing.
• Basic services do not gate. Atlas, Almanac, Chronicle, and Passport are services a gov offers; none is on any citizen’s critical path for admission or operation. A compromised basic service can mislead consumers but cannot compel a citizen.

Non-goals.

• Cross-gov confidentiality. Two govs coexisting on the shared universe do not get any additional confidentiality over “two services on the shared universe” already get. Mosaik’s ACL and tickets are the only gates.
• Cross-citizen atomic integrity. Ruled out at the composition layer. See atomicity.
• Protection against a malicious gov operator. A gov operator can publish a GovConfig referencing any citizen whose fingerprint they know, including citizens whose operators have not consented to the reference. The reference has no technical consequence for the citizen’s integrity or confidentiality; it is a social or legal matter between operators. The blueprint surfaces the observability required to flag the misuse; it does not prevent it.
• Protection against heavy-gov drift. A future proposal promoting a heavy-gov primitive (enforcement, taxation, judiciary) requires its own threat model. The current model assumes light-gov only.

The confluence’s trust composition

Every confluence’s trust shape is determined by two inputs:

1. The confluence’s own committee assumption. Usually majority-honest for integrity, possibly TDX-attested for confidentiality of the cleartext it processes.
2. The worst-case assumption across the spanned citizens’ public surfaces it reads. If the confluence reads cleartext from each spanned lattice’s unseal::UnsealedPool and a signed feed from an oracle organism, it inherits the t-of-n threshold of every spanned unseal committee and the signing-quorum assumption of the oracle organism.

The composed assumption is the conjunction: the confluence’s guarantee holds while every component’s assumption holds simultaneously. Breaking any one component can at most degrade the confluence’s output per the weakest component’s failure mode.

Example: the intents confluence

An intents confluence reads cleartext from three lattices’ UnsealedPools and commits a per-target- lattice routed-intents commit under a TDX-attested, majority-honest committee.

• Confidentiality of cross-chain intents to external observers: holds while every spanned lattice’s zipnet any-trust assumption and unseal t-of-n threshold assumption hold and the confluence’s TDX image is attested.
• Integrity of the routed commit: holds while the confluence’s majority-honest committee assumption holds.
• Availability of routing: holds while at least one of the spanned lattices reaches UnsealedPool for the target slot and a confluence majority commits.

Example: the shared-ledger confluence

A ledger confluence reads each spanned lattice’s tally::Refunds and commits an aggregated SharedRefunds under a majority-honest committee.

• Faithfulness of the aggregated attribution: holds while every spanned lattice’s tally majority-honest assumption and the confluence’s own majority-honest assumption hold. A malicious lattice tally majority can poison the aggregated commit; the on-chain settlement contract receiving SharedAttestations is the final check.
• Non-duplication of refunds: holds while the aggregation rule is implemented correctly and state- machine-deterministic.

Basic-service trust shapes

Each of the four basic services has its own trust shape, summarised here and specified in basic services.

Atlas trust

• Faithfulness of CitizenCard contents: holds while the Atlas committee is majority-honest. A compromised Atlas can publish incorrect endpoint hints or stale MR_TD pins. Integrators are expected to cross-check with per-citizen operators’ own handshake pages; Atlas is a convenience, not a certificate.
• Confidentiality: N/A; Atlas is public by design.

Almanac trust

• Monotonicity of ticks: holds while the Almanac committee is majority-honest. A compromised Almanac can skip ticks or delay them, but cannot un-commit previously committed ticks.
• observed_at timestamps are advisory. A compromised committee can publish ticks with implausible timestamps; consumers should treat observed_at as a hint, not a cryptographic timestamp.

Chronicle trust

• Tamper-evidence of past entries: holds while at least one honest replayer can read the full stream. Chronicle entries are append-only; once committed, a compromised committee cannot retroactively rewrite them without being detected by any honest reader.
• Completeness of recent entries: majority-honest. A compromised committee can omit entries from being committed; it cannot forge them without being detected, but it can DoS provenance.

Passport trust

• Grant integrity: holds while the Passport committee’s policy is deterministic and majority- honest. A compromised Passport can issue grants outside policy, but cannot force a citizen to present a Passport (it remains optional) or force an integrator to honour one.
• Revocation timeliness: majority-honest, subject to expiry windows set in the Config.

Gov operator responsibilities

Gov operators carry a narrow set of responsibilities; respecting the narrowness prevents the gov layer from reclaiming the authority it disclaims.

Must do:

• Publish the GovConfig struct (and the derived fingerprint) as the handshake.
• Publish every confluence’s and every basic- service’s MR_TD if TDX-gated.
• Publish every standalone organism’s MR_TD that the gov operator commissioned and that is TDX-gated. If the organism is operated by a different team, that team publishes its own MR_TD and the gov operator re-publishes for convenience.
• Document the set of citizens referenced, including a pointer to each per-citizen operator’s handshake page.
• State explicitly which basic services the gov ships and which it does not. Silence is ambiguous.
• Notify integrators when a referenced citizen’s fingerprint bumps and publish the updated GovConfig promptly.

Must not do:

• Issue tickets on behalf of any referenced citizen.
• Override a referenced citizen’s ACL.
• Represent the referenced citizens’ integrity.
• Use a Passport to gate citizen operation. Passport remains opt-in; a gov that treats absence-of-Passport as grounds for exclusion has crossed into heavy-gov and needs a fresh proposal.

What a compromised gov cannot do

Regardless of how many confluences or basic services a gov operator runs maliciously:

• Cannot change a referenced citizen’s commits. Each citizen’s commit log is authoritative in its own Groups. A compromised confluence cannot forge a citizen commit.
• Cannot mint money. Same argument as builder: on- chain settlement contracts enforce the evidence carried in attestations.
• Cannot produce cross-citizen atomic outcomes. Atomicity is not a primitive; a compromised confluence cannot force two citizens to jointly commit something they did not independently commit.
• Cannot compel citizens. A compromised Passport cannot make a citizen do anything; a compromised Atlas cannot force dashboards to trust it; a compromised Chronicle cannot rewrite what honest replayers have already seen.

What a compromised gov can do

Conservatively:

• Poison confluence commits. A majority-compromised confluence can commit misattribution, mis-routing, mis-correlation, or otherwise dishonest records. Integrators reading those commits observe the misbehaviour in public and can object, migrate, or appeal to on-chain settlement.
• Mislead Atlas consumers. A compromised Atlas can publish wrong endpoint hints, stale MR_TD pins, or fabricate membership. Dashboards relying on Atlas see degraded accuracy; the citizens themselves are unaffected.
• DoS the confluence or basic-service tier. A committee that loses majority stops producing new commits. Referenced citizens and their own pipelines are unaffected.
• Publish a misleading GovConfig. A gov operator can publish a GovConfig that references citizens the integrator did not expect. Integrators guard against this by compiling in the GovConfig explicitly and auditing its contents — a misleading fingerprint is a visible artefact.
• Stop publishing Chronicle entries. The absence of an entry is observable; a gov that goes silent loses trust even if it cannot rewrite the past.

Compositional table

The decomposition is the point. A gov that misbehaves at one tier degrades the guarantee dependent on that tier; it does not collapse everything.

Operator responsibilities recap

Every operator running a committee member in any confluence, basic service, or standalone organism is responsible for the same set of obligations a lattice- organism operator is (running the attested image, protecting committee-admission secrets, rotating on schedule, reporting anomalies).

Cross-citizen confluence-operator adds one responsibility:

• Cross-citizen dependency reporting. When a referenced citizen’s fingerprint bumps, the confluence operator files an advisory to the gov operator and to integrators so that GovConfig updates propagate with a known cadence, not silently. If the gov ships a Chronicle, that advisory lands in the next Chronicle entry.

Cross-references

• builder threat model — per-lattice trust shapes this layer composes over.
• confluences — the organism the compositional trust statements above are about.
• basic services — trust shapes for Atlas, Almanac, Chronicle, Passport.
• composition — the subscription graph these trust statements travel along.
• atomicity — the one thing that does not compose.

Roadmap

audience: contributors

This roadmap covers the gov blueprint, not the v2 lists of any individual confluence, basic service, or standalone organism. Each crate ships its own internal roadmap; the zipnet crate’s Roadmap to v2 is the template future crates follow.

Items below are ordered by external-impact visibility, not by engineering order; implementation order is determined by what the first production gov requires.

v0.1 — Blueprint (this document)

Specification complete. No crates shipped. Audience: contributors who want to challenge the composition shape before confluence or basic-service implementation starts.

v0.2 — Gov meta-crate walking skeleton

Goal: one gov meta-crate exists, its GovConfig type compiles against a fixed set of example citizen fingerprints, and its gov_id() derivation is stable and testable.

Minimum content:

• Crate layout. One gov meta-crate owning GovConfig, ConfluenceConfig, OrganismRef, the derivation helpers, the basic-service lookup helpers (atlas(), almanac(), chronicle(), passport()), and re-exports of builder::{LatticeConfig, UNIVERSE}. No runtime yet.
• Derivation tests. Golden-vector tests ensuring a fixed GovConfig produces a fixed fingerprint, and that each included citizen’s fingerprint is unchanged by gov membership.
• Mixed-composition tests. A gov with zero lattices and two standalone organisms derives correctly; a gov with two lattices and zero organisms derives correctly; mixes derive correctly.
• Basic-service-helper tests. Helpers return Some when a service by the well-known name is present, None otherwise.
• Book examples. Every rust,ignore snippet in this book that references GovConfig type-checks against the v0.2 meta-crate signature.

Non-goals for v0.2:

• Any confluence implementation. Confluences arrive piecemeal once the meta-crate is stable.
• Any basic-service implementation. First basic service lands in v0.3.
• Any standalone-organism implementation. Those live in their own crates; the meta-crate only references them.
• On-wire types. No new wire types are added at the gov layer beyond what each confluence, basic service, or organism commissions for itself.

v0.3 — First basic service: Atlas

Goal: the first basic service ships end-to-end and validates the gov’s civic-services pattern.

Atlas is chosen first because it has the narrowest trust shape and the shortest state machine. It exercises every part of the derivation and subscription path without introducing threshold cryptography or cross-chain auction semantics.

Minimum content:

• gov-atlas crate with:
  • Config fingerprint folding the gov root and the set of citizen fingerprints the Atlas catalogues.
  • Atlas::<CitizenCard>::read and Atlas::<CitizenCard>::publish typed constructors.
  • A small state machine that commits citizen cards (metadata, endpoint hints, ticket-issuance roots, MR_TDs) per citizen fingerprint, co-signed by the Atlas committee. The card format handles both lattices and standalone organisms.
• Integration test: stand up two citizens (mocked — one lattice, one organism), one Atlas basic service, and demonstrate an integrator binding to all three through one GovConfig.

v0.4 — Almanac + Chronicle

Goal: the remaining non-identity basic services ship.

• gov-almanac crate with committee-driven tick commits. Integration test: a correlator confluence aligns events from two citizens to almanac ticks.
• gov-chronicle crate with append-only audit log. Integration test: gov republishes a GovConfig with a new citizen; Chronicle records the transition.

These land together because they share infrastructure (monotonic committee-signed commits) and because both are strictly additive to v0.3.

v0.5 — First commissioned confluence

Goal: the first confluence whose state machine depends on cleartext order flow from multiple lattices.

Minimum content:

• gov-intents crate following the intent-router pattern in confluences.
• TDX admission on every committee member.
• Integration test: intents submitted on lattice A are routed to lattice B’s offer input and a downstream tally commit reflects the cross-chain attribution.
• Per-citizen stall policy documented in the crate’s composition-hooks.md.

v0.6 — Shared attribution ledger + Passport

Goal: complete the first round of commissioned confluences and the remaining basic service.

• gov-ledger crate following the shared-ledger pattern in confluences.
• gov-passport crate implementing the optional- citizenship basic service. Passport ships last among the basic services because it touches cross-operator trust and benefits from operational experience from v0.3–v0.5.

v1.0 — First production gov

Goal: one gov runs on mainnet references continuously for a month with no protocol-level incidents.

• Rolling upgrades of confluences and basic services. Until this point, “stop the service, bump the GovConfig, restart” is an acceptable release strategy; at v1.0 it is not.
• Snapshot + state-sync for every confluence’s and every basic service’s state machine.
• Full operator runbooks under operators/, graded by severity and audited externally.
• Stable GovConfig serialisation format. GovConfig::from_hex is safe to use as the handshake after v1.0.

Longer-term items (no version assigned)

Versioning

Carrying the zipnet/builder policy into the gov model with one adjustment.

• Per confluence / basic service: lockstep. Operators and integrators cut releases against matching crate versions. StateMachine::signature() bumps are uncommon in steady state and coordinated.
• Per gov: version-in-name for the gov identity. A gov retirement is an operator-level decision and produces a new instance name (ethereum.superchain-v2026q2). Individual confluences and basic services inside a stable gov name can still upgrade lockstep without retiring the gov.
• Per citizen reference: canonical fingerprint or named alias. A GovConfig references citizens by their fingerprint. An operator who wants a gov to tolerate citizen internal bumps within a compatibility bound may publish “named alias” references (e.g. ethereum.mainnet@^2) that the gov’s derivation resolves at publish time to the latest compatible fingerprint. Whether this ships as a blueprint-level primitive or stays a per-gov operator convention is open.

Neither policy is load-bearing for v0.2 / v0.3. The first v1.0 release forces the decision.

Cross-gov coordination

Out of scope for v0.1. If a concrete use case for two govs committing a joint fact emerges, the answer has the same shape as the rung below: either an integrator spans govs, or a confluence folds multiple GovConfig fingerprints into its content and is commissioned under both govs. Research-complete, engineering-deferred.

TDX-attested basic services

The v0.3 Atlas is a minimal, non-TDX basic service. A TDX-attested Atlas — where the committee commits cards only over attested images — is a v1+ refinement. Same for TDX-attested Almanac, Chronicle, Passport. The blueprint is unchanged; the refinement touches only the crates.

Optional cross-gov directory

Not a core feature; same argument as the lattice directory in builder. A shared Map<GovName, GovCard> listing known govs may ship as a devops convenience. If built, it must:

• be documented as a convenience, not a binding path;
• be independently bindable — the gov meta-crate never consults it;
• not become load-bearing for ACL or attestation.

Flag in-source as // CONVENIENCE: if it lands.

Byzantine liveness for confluence, basic-service, and organism committees

Mosaik’s Raft variant is crash-fault tolerant. The zipnet liveness item applies to every committee. A future BFT variant in mosaik would be inherited by every component; until then, a deliberately compromised committee member can DoS liveness in its own committee.

Confluence-level confidentiality beyond TDX

Some confluence roles (cross-chain intent routing over many chains, cross-feed correlation of sensitive oracles) may want post-quantum confidentiality ahead of their upstream citizens themselves. Research-complete for several threshold schemes; engineering-deferred. The organism surface does not change; only the crypto inside the confluence’s state machine does.

New mid-rung composition classes

Builder is the first fully-specified class of mid-rung composition (block-building lattices). Other classes may follow — attestation fabrics, oracle grids, identity substrates with their own collective shape — each with its own book and its own handshake. When one does:

• The new class’s book specifies its own FooConfig and derivation discipline, mirroring builder.
• The gov meta-crate may add a new referenced slice (pub fabrics: &'static [FabricConfig], etc.) or may continue referencing those compositions via their root organisms. Either works; the tradeoff is ergonomic.
• Confluences gain the ability to fold the new class’s fingerprints into their Config alongside lattices and organisms.
• Basic services (Atlas especially) need their CitizenCard schemas updated to carry metadata about the new kind.

Research-and-engineering-deferred. The gov blueprint grows in lockstep with whichever class lands first.

Heavy-gov as a research space (deferred)

The blueprint explicitly refuses heavy-gov primitives: enforceable policies over citizens, taxation, judiciary, mandatory citizenship. The refusal is load-bearing for the current trust and composition stories.

A future proposal could make a case for one heavy-gov primitive at a time, as a separate design with its own book branch. Any such proposal must:

• restate the non-authority rules the current blueprint relies on and explain which ones it breaks;
• give a full trust composition for the new primitive showing what it does to the existing guarantees;
• specify a migration path for govs that ship the old (light) shape;
• earn its way past the objection that it reintroduces the supra-citizen-authority shape this blueprint refused.

No concrete heavy-gov proposal is planned. The space is flagged so contributors know where the current scope ends and where fresh proposal work would begin.

What this roadmap does not include

• Specific crate-versioning schedules. Each crate owns its own version cadence.
• A list of confluences, organisms, or lattice classes the blueprint wants shipped. Unlike builder’s six-organism commitment, the gov blueprint stays open beyond the four basic services. The roadmap names three plausible first commissioned confluences; the catalogue grows as cross-citizen problems force new ones.
• Operator-onboarding contractual detail. Gov operators run different organisations under different legal regimes; the book does not try to standardise that.
• Adoption strategy. The book specifies and documents; adoption is the operators’ concern.

Glossary

audience: all

Domain terms as used in this book. Where a term is inherited from mosaik, zipnet, or builder, the entry points at the authoritative source rather than re- deriving.

Almanac. A basic service: a shared clock / sequence beacon citizens may use for cross-citizen timing. See basic services.

Atlas. A basic service: a directory of citizens with operator-supplied metadata (endpoint hints, ticket- issuance roots, MR_TD pins). See basic services.

Basic service. A confluence or organism whose shape is specified once in the blueprint so every instance means the same thing across govs. Four are specified: Atlas, Almanac, Chronicle, Passport. A gov may ship zero, one, or all four.

Bridge organism. The name the builder book uses for a speculative cross-lattice organism. In this blueprint, promoted to a first-class category and generalised to confluence — a cross-citizen organism. See topology-intro.

Chronicle. A basic service: a tamper-evident audit log of gov actions (publications, rotations, retirements). See basic services.

Citizen. A lattice or standalone organism referenced by a gov’s GovConfig. Used interchangeably with unit when the civic framing is ambient; unit is used when the mechanical framing is clearer.

Confluence. A mosaik-native organism whose Config fingerprint folds two or more citizen fingerprints (lattices, standalone organisms, or a mix) and whose public surface spans the referenced citizens. The one new primitive the gov rung introduces. See confluences.

ConfluenceConfig. The parent struct for a confluence’s Config. Folds the confluence’s role name, ordered spanned lattices, ordered spanned standalone organisms, content parameters, ACL, and pinned gov root. See confluences — the Config fingerprint.

Content + intent addressing. The discipline every consensus-critical id in every organism, lattice, confluence, or gov obeys: id = blake3(intent ‖ content ‖ acl). Inherited verbatim from zipnet and builder.

Deployment. A single running instance of an organism, confluence, lattice, or gov. Identified by the relevant Config fingerprint.

Evidence pointer. A reference from a confluence’s commit back to the citizen commit it depends on. Resolved on replay to validate the confluence’s state-machine transition.

Fan-in confluence. A confluence aggregating facts from multiple origin citizens (e.g. a shared-ledger confluence, a cross-feed correlator).

Fan-out confluence. A confluence distributing a fact to multiple target citizens (e.g. an intent router).

Fingerprint. A synonym for the content + intent addressed id of a Config (gov, lattice, organism, or confluence). Mismatched fingerprints are the ladder’s debuggable failure mode at every rung.

Fixed shapes, open catalogs. The blueprint discipline of specifying shapes (GovConfig, ConfluenceConfig, the four basic services) once and leaving the catalogs (which confluences, which organism categories, which lattice classes, whether a given gov ships any basic services) open. See introduction — Fixed shapes, open catalogs.

Gov. A fingerprint-addressed composition of zero or more lattices, zero or more standalone organisms, and zero or more confluences (possibly including basic services), identified by a GovConfig. Operator-scoped, not a consensus unit, not an ACL root. A coalition that offers services to its citizens without compelling them. See topology-intro.

GovConfig. The parent struct a gov operator publishes and an integrator compiles in. Contains the gov’s name, the ordered LatticeConfigs it references, the ordered OrganismRefs it references, and the ordered ConfluenceConfigs it ships (basic services and any commissioned confluences). See topology-intro — Gov identity.

GOV_ROOT. The derived fingerprint used as the root for every confluence’s and every basic service’s identity derivation under a gov. See topology-intro — Citizenship-by-reference.

Heavy-gov. The speculative (and deferred) class of govs carrying enforceable policies over citizens — laws, taxation, judiciary. Explicitly out of scope; see introduction — Fixed shapes, open catalogs.

Integrator. External developer consuming a gov, citizen, or confluence. Never client (ambiguous with zipnet’s ClientId).

Intent-router pattern. A confluence that reads cleartext from spanned lattices’ unseal::UnsealedPools and commits a routed-intents collection per target lattice. See confluences — intent-router pattern.

Lattice. One fully-specified mid-rung composition of organisms. Builder specifies the first class of lattice: one end-to-end block-building deployment for one EVM chain, identified by a LatticeConfig fingerprint. Nothing in this blueprint assumes a lattice is a block-building lattice; other classes may follow their own proposals. Govs reference lattices; they do not own them.

LatticeConfig. Builder’s parent struct for a block- building lattice. Unchanged in this blueprint. See builder glossary.

Light-gov. The non-authority stance this blueprint adopts: a gov offers basic services to its citizens, does not compel them, does not gate their ACLs, and does not override their operators.

MR_TD. Intel TDX measurement register binding a boot image to the hardware root of trust. Pinned per TDX-gated confluence or organism in that component’s Config.

Narrow public surface. The discipline of exposing one or two primitives per organism (or confluence) on the shared universe. Inherited from the zipnet design intro.

Operator. Team running a lattice, standalone organism, confluence, basic service, or gov (or any combination). See audiences.

Organism. A mosaik-native service with a narrow public surface. The six builder organisms (zipnet, unseal, offer, atelier, relay, tally) inside each block- building lattice, every confluence, every basic service, and every standalone organism a gov references are organisms.

OrganismRef. The gov’s reference type for a standalone organism: a role name plus the organism’s Config fingerprint. The concrete Config type lives in the organism’s own crate and is opaque to the gov meta- crate. See topology-intro — Gov identity.

Passport. A basic service: optional citizenship tokens a citizen may accept. Never required for a citizen to operate. See basic services.

Shared-ledger pattern. A confluence that aggregates per-lattice tally::Refunds into a cross-origin-citizen attribution feed. See confluences — shared-ledger pattern.

Standalone organism. An organism living directly on the universe rather than inside a lattice. Oracles, attestation fabrics, identity substrates, data- availability shards, analytics pipelines, and the like — all referenced by a gov via OrganismRef.

StateMachine. Mosaik’s term for the deterministic command processor inside a Group<M>. Every confluence and every organism has its own state machine. See mosaik groups.

Stall policy. Per-confluence rule for behaviour when one spanned citizen is not producing inputs for the current clock event. Either commit with partial evidence (preserving liveness) or stall the event (preserving quality). Documented per confluence.

TDX. Intel Trust Domain Extensions. The TEE technology mosaik ships first-class support for. Used by confluences and sensitive standalone organisms. See mosaik TDX.

Unit. Informal cover term for anything a gov composes: a lattice, a standalone organism, or — when a category exists — any other named mid-rung composition. Used interchangeably with citizen when the mechanical framing is clearer than the civic one.

Universe. The shared mosaik NetworkId (builder::UNIVERSE = unique_id!("mosaik.universe")) hosting every gov, every lattice, every organism, and every confluence.