Quickstart — stand up a coalition

audience: operators

This runbook brings up a minimal coalition: one CoalitionConfig referencing two existing members (two block-building lattices, two standalone organisms, or one of each) and shipping one module — an Atlas — that publishes a per-coalition directory. Assumptions:

• The members 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, TDX Measurements publication. The discipline is identical for any organism committee.
• The coalition meta-crate (coalition) exists in a form sufficient to derive CoalitionConfig fingerprints. Until v0.2 lands, this is a paper exercise; the steps below are the target shape.

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

Step 1 — enumerate the members to reference

Record, for each member, the canonical stable id (and optional content hash, if you choose to pin it) as published by its operator.

member                        kind      stable_id (hex)      content_hash       ticket-issuance root
-----------------------------+---------+---------------------+------------------+----------------------
ethereum.mainnet               lattice   0x…                  (unpinned)         0x…
unichain.mainnet               lattice   0x…                  (unpinned)         0x…
price-feed.eur                 organism  0x…                  0x…                0x…

Do not invent stable ids locally. Always use the per- member operator’s authoritative value. A per-member operator’s stable id that cannot be reproduced from its published Config definition is a member-level issue; do not paper over it in the coalition.

Step 2 — pick the coalition name

Short, stable, namespaced. Examples:

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

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

Step 3 — decide which modules to ship

One module suffices for a minimal coalition. Atlas is the usual first choice:

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

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

A concrete cross-member problem (paired-bundle auctions, cross-chain attribution, oracle/lattice correlation) motivates commissioning a relevant organism beyond the modules. Each organism is a separate crate and committee; organisms are coalition-independent, so the same organism may also be referenced by other coalitions.

Step 4 — draft the CoalitionConfig

use builder::LatticeConfig;
use coalition::{CoalitionConfig, ModuleConfig, OrganismRef};

pub const ETHEREUM_MAINNET: LatticeConfig<'static> = /* from ethereum.mainnet operator */;
pub const UNICHAIN_MAINNET: LatticeConfig<'static> = /* from unichain.mainnet operator */;
pub const EUR_PRICE_FEED:   OrganismRef<'static>   = OrganismRef {
    role: "oracle",
    stable_id: /* from the price-feed operator */,
    content_hash: None,
};

pub const SUPERCHAIN_ATLAS: ModuleConfig<'static> = ModuleConfig {
    name: "atlas",
    content: /* atlas content params */,
    acl:     /* TicketValidator composition */,
};

pub const SUPERCHAIN_ATLAS_ORG: OrganismRef<'static> =
    OrganismRef {
        role:         "atlas",
        stable_id:    /* derived from SUPERCHAIN_ATLAS */,
        content_hash: None,
    };

pub const ETH_SUPERCHAIN: CoalitionConfig<'static> =
    CoalitionConfig {
        schema_version:    SCHEMA_VERSION_U8,
        coalition_seed:    COALITION_ROOT_SEED,
        instance_name:     "ethereum.superchain",
        lattices:  &[
            ETHEREUM_MAINNET.stable_id(),
            UNICHAIN_MAINNET.stable_id(),
        ],
        organisms: &[EUR_PRICE_FEED],
        atlas:             Some(SUPERCHAIN_ATLAS_ORG),
        almanac:           None,
        chronicle:         None,
        compute:           None,
        randomness:        None,
        ticket_issuer:     None,
        retirement_policy: RetirementPolicy::default(),
    };

Note: an OrganismConfig does not fold a coalition root; organism identity is independent. For a module like Atlas, the meta-crate’s derivation routes the identity under COALITION_ROOT.derive("module").derive("atlas") internally when the helper atlas() returns the matching OrganismRef.

Step 5 — freeze the fingerprint

The derivation order is:

1. Compute COALITION = blake3("coalition|" || SCHEMA_VERSION_U8 || "|" || name).
2. Compute COA_LATTICES = ordered stable ids.
3. Compute COA_ORGANISMS = ordered stable ids (plus content hashes if pinned per-organism). Standalone and composite organisms share this slice.
4. Compute COA_MODULES = ordered ModuleConfig fingerprints.
5. Compute COA_TICKETS = TicketIssuerConfig fingerprint if present, else 0 bytes.
6. Compute COALITION_ROOT = blake3(COALITION || COA_LATTICES || COA_ORGANISMS || COA_MODULES || COA_TICKETS).
7. Module identities are derived from COALITION_ROOT via COALITION_ROOT.derive("module").derive(name).

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

Every module is a mosaik-native organism (specifically, coalition-scoped). 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 OrganismConfig under COALITION_ROOT.derive("module").derive("atlas").
3. Publish the Atlas’s TDX Measurements (if TDX-gated) or the committee roster (if not).

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

Step 7 — publish the handshake

Collect everything integrators need:

• CoalitionConfig Rust const (or the hex fingerprint paired with the struct definition).
• The ordered list of referenced LatticeConfigs with links to each lattice operator’s handshake.
• The ordered list of referenced OrganismRefs with role names, stable ids (plus content hashes if pinned), and a link to each organism operator’s handshake. Standalone and composite organisms share this shape; composite-organism entries additionally note TDX Measurements and state-machine signature where applicable.
• Each module’s ModuleConfig with TDX Measurements, state-machine signature, and a short description.
• A statement of which modules the coalition ships and which it does not — silence is ambiguous.
• The coalition-scoped ticket issuer root, if any.
• 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 coalition’s first CoalitionConfig 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 an organism for operating each committee (including modules).
• Multi-operator coalitions for coordinating with other per-member and per-composite-organism operators.
• Rotations and upgrades for key rotations, TDX Measurements bumps, and member retirements.

Failure modes

• Integrators report ConnectTimeout. Either the published CoalitionConfig drifted from the live deployment, or a referenced member retired and the coalition operator has not republished. Recompile the struct, freeze the fingerprint, publish.
• A module’s committee lost majority. Standard mosaik recovery. Referenced members and referenced organisms continue; integrators reading the module temporarily see no new commits.
• A referenced member retired silently. The per- member operator should have notified the coalition operator. File an anomaly with them, publish a new CoalitionConfig against the new stable id, and tighten change-channel discipline with that operator.

Cross-references

• Coalition overview
• Running an organism
• Multi-operator coalitions
• Contributor — basic services
• builder operator quickstart