Rotations and upgrades

audience: operators

Rotation discipline at the coalition layer is thin: most rotations occur inside one citizen (a lattice, a standalone organism) or inside one confluence (including a module). The coalition operator’s task is to republish the CoalitionConfig when any referenced component changes identity in a way that folds into COALITION_ROOT. This page lists the rotations that materially affect a coalition 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 coalition’s fingerprint

Any of the following forces a new CoalitionConfig 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 stable id changes (retirement).
2. A referenced standalone organism’s stable id changes (retirement).
3. A referenced confluence’s ConfluenceConfig fingerprint changes (content, ACL, span, or MR_TD bump on a TDX-gated confluence).
4. A module’s ConfluenceConfig fingerprint changes (content, ACL, or MR_TD bump).
5. The coalition’s lattice set changes (add or remove a lattice).
6. The coalition’s organism set changes (add or remove a standalone organism).
7. The coalition’s confluence set changes (add or remove a confluence or module).
8. The coalition’s ticket issuer is added, rotated, or removed.
9. The coalition instance name changes (rare — effectively a retirement; see below).

Rotations that do not change a coalition’s fingerprint

• Committee member rotations inside a referenced citizen, under a stable per-citizen Config.
• Committee member rotations inside a confluence or module, 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 content-hash bumps (MR_TD rotations, ACL rotations) if confluences pin only the stable id, not the content hash. Confluences that pinned content hash do bump.

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

Ordering a citizen retirement

When a referenced citizen’s stable id changes, follow this sequence.

1. Receive the retirement notification from the per- citizen operator via the federation change channel. The notification includes the old and new stable ids and the cutover time.
2. Prepare the new CoalitionConfig. Update the citizen’s reference in the CoalitionConfig definition. Re-derive the coalition fingerprint. Modules re-derive automatically because COALITION_ROOT has changed. Commissioned confluences referenced by the coalition re-derive only if they themselves span the retired citizen.
3. Redeploy modules under the new ConfluenceConfigs. Because each module’s content folds the coalition root, module fingerprints have bumped. Bring up new committee members on the new ConfluenceConfigs while old members continue on the old ones; rotate over.
4. Publish the new CoalitionConfig fingerprint on the handshake page and change channel.
5. Wait for integrators to recompile. Old- fingerprint handles time out (or, better, see a RetirementMarker from each retiring committee pointing at the replacement); integrators reach out if they miss the change.
6. Retire the old module deployments once the old CoalitionConfig is no longer in use by the integrators the operator cares about. Each committee emits a terminal RetirementMarker before shutdown.

Ordering a confluence or module upgrade

A confluence or module’s Config may change for reasons other than upstream citizen retirements: new content parameters, MR_TD bump, ACL change.

1. Stand up the new deployment under the new ConfluenceConfig alongside the old.
2. Update any referencing coalitions’ CoalitionConfigs to reference the new confluence fingerprint. Recompute each coalition fingerprint.
3. Publish each new CoalitionConfig.
4. Announce the change via the change channel, with migration notes. If any referencing coalition ships a Chronicle, its next commit records the rotation.
5. Retire the old deployment. The committee emits a RetirementMarker pointing at the new deployment so integrators rebind cleanly.

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

Retiring a coalition

A coalition 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 participating in the coalition has reorganised.
• Branding or regulatory considerations.

Sequence:

1. Announce retirement with substantial lead time. Integrators relying on the coalition need weeks to migrate. A shipped Chronicle records the retirement in its next commit.
2. Stand up the replacement coalition (e.g. ethereum.superchain-v2026q2) with a fresh CoalitionConfig fingerprint and the desired composition.
3. Run both coalitions in parallel until most integrator traffic has migrated.
4. Retire the old coalition’s modules (committees emit RetirementMarkers pointing at the replacement coalition’s modules) once integrator traffic drops to zero or acceptable levels. Referenced confluences are independent of the retired coalition and continue if other coalitions or direct integrators still use them.
5. Publish a retirement note. The old CoalitionConfig fingerprint is formally deprecated; integrators still on it see ConnectTimeout once the old modules are down.

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

Cross-references

• Coalition overview
• Running a confluence
• Federating under a coalition
• builder rotations