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:

Compute GOV = blake3("gov|" || name).
Compute GOV_LATTICES = ordered LatticeConfig fingerprints.
Compute GOV_ORGANISMS = ordered OrganismRef fingerprints.
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.
Compute GOV_CONFS = ordered ConfluenceConfig fingerprints.
Compute GOV_ROOT = blake3(GOV || GOV_LATTICES || GOV_ORGANISMS || GOV_CONFS).
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:

Install the Atlas binary on committee hosts (default N = 3; scale up as needed).
Bootstrap Raft peers on the shared universe using the Atlas’s GroupId derived from its ConfluenceConfig.
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.

Governments on mosaik