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.

Governments on mosaik