Coalition overview

audience: operators

A coalition 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 CoalitionConfig they compile in. A coalition may also ship up to four modules (Atlas, Almanac, Chronicle, Compute) and an optional coalition-scoped ticket issuer under the same handshake.

This page is the operator’s introduction: what running a coalition means, what the operator owns, and what they do not.

Operator roles, often one team

Running a coalition 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 coalition 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. Confluences are coalition-independent; the same confluence may be referenced by several coalitions.
Module operator — responsible for an Atlas, Almanac, Chronicle, or Compute committee. Mechanically identical to running any other coalition- scoped organism; the shape is specified in basic services.
Ticket-issuer operator — responsible for the coalition-scoped ticket issuance root when the coalition ships one. See ticket issuance.
Coalition operator — responsible for publishing and maintaining the CoalitionConfig: keeping its content accurate, notifying integrators when referenced citizens’ stable ids bump, and retiring the coalition instance name cleanly when it is no longer needed.

A single team commonly holds two or more of these roles.

What the coalition operator owns

The CoalitionConfig struct and its serialised fingerprint.
A published change channel (release notes, a CHANGELOG, an RSS feed — whatever), through which you notify integrators of citizen stable-id bumps, referenced-confluence upgrades, or composition changes.
The set of ConfluenceConfigs referenced by the coalition (if you also run the modules and any confluences).
The set of OrganismRefs the coalition composes (role name, stable id, optional content hash for each referenced standalone organism).
The optional coalition ticket issuer.
A coalition-scoped operator handshake page — one URL or repository section integrators can link in their own docs.

What the coalition operator does not own

The referenced citizens. The coalition operator references lattices and standalone organisms; they do not admit peers into them, issue tickets on their behalf, or dictate internal parameters.
The referenced confluences. Confluence identity is independent of any coalition. The coalition operator references the confluence; the confluence operator controls its committee and Config.
Citizen stable ids. When a referenced citizen retires, the coalition operator updates the CoalitionConfig to match; they do not dictate the per-citizen operator’s retirement cadence.
Cross-operator contracts. Multi-operator coalitions bring 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 CoalitionConfig cannot be revoked; the coalition operator publishes a new one and relies on integrators to upgrade.
Citizen behaviour. A citizen’s misbehaviour is addressed by publishing an updated CoalitionConfig that drops or replaces it. The coalition operator has no protocol-level power to constrain a citizen.

What per-citizen operators can expect from a coalition operator

Worth formalising with any citizen referenced:

Notification of inclusion. The coalition 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 coalition operator does not ask the per-citizen operator to issue special-case tickets for confluences or modules. Committee members bond into referenced citizens as ordinary integrators under the citizen’s normal admission policy.
Observability of referenced citizens’ public surfaces only. The coalition operator does not expect private plumbing access.
Bump coordination. Citizen stable-id bumps (retirements) are notified to the coalition operator via the per-citizen operator’s integrator channel ahead of cutover; this lets the coalition operator publish a matching CoalitionConfig without a ConnectTimeout gap. Routine content-hash bumps (MR_TD rotations, ACL rotations) do not require coalition-level updates unless confluences opted to pin the content hash.

A typical coalition’s shape

Three common archetypes:

Ecosystem coalition. One operator; several lattices across related chains (every chain in a superchain stack, every chain in an L2 family). Modules: usually Atlas at minimum, often Chronicle. Confluences: often an intent router or shared ledger.
Service coalition. 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.
Multi-operator coalition. Multiple operators, each running one or a few citizens (lattices, standalone organisms, or both); one operator runs the coalition and one or more confluences. Common when an ecosystem wants a shared attribution or routing layer while the underlying citizens operate independently. An optional coalition-scoped ticket issuer is more likely here.

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

Critical path

Keep the CoalitionConfig in sync. When a referenced citizen retires or a referenced confluence bumps, publish a new coalition fingerprint promptly.
Operate modules, the optional ticket issuer, and any standalone organisms or confluences commissioned. Standard committee-organism operations: monitor, rotate, respond to anomalies.
Respond to integrators. Three typical questions: the current coalition composition, the cause of a ConnectTimeout, and how to bind to a newly shipped confluence or module. 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 coalition operator. Those citizens operate themselves.
Inter-citizen consensus. None exists; the coalition is not a consensus unit.
Cross-coalition coordination. Two coalitions coexist on the universe and do not coordinate.

AI