What a coalition gives you

audience: integrators

A coalition is a single handshake token binding an agent to multiple members of the mosaik universe at once: block-building lattices, standalone organisms (oracles, attestation fabrics, identity substrates, analytics pipelines, …), composite organisms (cross-member organisms), and the coalition’s optional basic services (Atlas, Almanac, Chronicle, Compute, Randomness — whichever are shipped). Compile one CoalitionConfig and obtain typed handles on every member, every basic service, and every organism the coalition references, from one Arc<Network>.

If you already bind to one lattice via a LatticeConfig, or to one standalone organism via its Config, a coalition does not change any of that. It adds:

A single reference to a set of members the operator has chosen to yoke together (e.g. every chain in a superchain stack; every oracle feed in a region; a set of lattices plus a shared attestation fabric).
Optional composite organisms: cross-member organisms that aggregate, route, or attest across the members in the coalition. Composite organisms are not coalition-scoped; the same organism may be referenced by many coalitions.
Optional basic services: up to five well-known shapes — Atlas (directory), Almanac (clock beacon), Chronicle (audit log), Compute (scheduler and registry for image-hash-identified workloads), Randomness (scheduler and registry for beacon rounds; beacon producers compete to supply).
An optional coalition-scoped ticket issuer. Components choose whether to recognise its tickets; nothing is required to.
No loss of identity. Every member’s GroupId, every PeerId, every StreamId you already use stays byte-for-byte the same under routine operational rotations (TDX Measurements bumps, ACL rotations). A coalition references members; it does not re-derive them.

An agent binding to one member only does not need a CoalitionConfig; bind directly to that member’s Config (for a block-building lattice, see the builder integrators overview; for a standalone organism, see its own crate docs). The coalition layer is additive, not a replacement.

When you want a `CoalitionConfig`

Four common cases.

Cross-chain searcher

You bid on bundles across three block-building lattices and want one handshake token that carries all three LatticeConfigs, their TDX Measurements, and any referenced organisms (e.g. a shared ledger that aggregates your refunds across chains).

Hold one CoalitionConfig, open three offer::Offer<Bundle>::bid handles, one ledger::Shared<Refund>::read. See the quickstart.

Multi-chain wallet

You submit intents on several lattices and need refund attestations from each. If the coalition references a shared-ledger organism, you can read one aggregated feed instead of polling per-lattice tally::Refunds.

Cross-domain agent

Your agent consumes outputs from a mix of members — say, two block-building lattices, an oracle grid, and an attestation aggregator — and you want one compile-time token that pins the full set. A CoalitionConfig lets you hold one handshake instead of four.

Composite-organism or module consumer

You are an analytics, routing, or dashboard service that reads an intent router, a shared ledger, a cross-chain oracle aggregator, or the coalition’s Atlas. Without a CoalitionConfig, you would re-derive each fingerprint yourself; with it, you compile one struct.

When you do not need a `CoalitionConfig`

You bind to one member only.
You are an integrator testing a standalone organism whose operator has given you its OrganismConfig directly.
You are an integrator testing a composite organism whose operator has given you its OrganismConfig directly.
You only read a public collection whose StoreId you already have; coalitions are compile-time ergonomics.

What the operator gives you

When a coalition operator hands you a handshake, you should receive:

The CoalitionConfig struct (or its serialised fingerprint).
The included LatticeConfigs — either inline or by reference to each lattice operator’s published handshake.
The included standalone-organism references — each with role name, stable id, optional content hash, and a pointer to that organism’s own handshake.
The included composite organisms — each with its OrganismConfig and a pointer to the organism operator’s handshake.
The included modules — each an OrganismConfig with the shape documented in basic services.
The ticket-issuer root if the coalition ships one.
TDX Measurements for every TDX-gated organism (standalone, composite, or module) the coalition commissioned.
Endpoint hints for at least one initial peer on the shared universe, if your agent is cold-starting.

See What you need from the coalition operator for the full checklist.

What you compile in

use std::sync::Arc;
use mosaik::Network;
use builder::UNIVERSE;
use coalition::CoalitionConfig;

const ETH_SUPERCHAIN: CoalitionConfig<'static> = /* pasted from operator release notes */;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let network = Arc::new(Network::new(UNIVERSE).await?);

    // Pick handles you need — any lattice organism, any
    // standalone organism, any composite organism, any
    // module.
    let eth_bid = offer::Offer::<Bundle>::bid(
        &network, &ETH_SUPERCHAIN.lattices[0].offer,
    ).await?;
    let uni_bid = offer::Offer::<Bundle>::bid(
        &network, &ETH_SUPERCHAIN.lattices[1].offer,
    ).await?;
    // A standalone organism the coalition references — here, an
    // attestation aggregator with its own Config.
    let attest = attest::Aggregator::<Quote>::read(
        &network, ETH_SUPERCHAIN.organisms[0].config(),
    ).await?;
    // A composite organism — same shape, one rung up.
    let ledger = ledger::Shared::<Refund>::read(
        &network, ETH_SUPERCHAIN.organisms[1].config(),
    ).await?;
    // A module — the coalition's Atlas, if shipped.
    let atlas  = atlas::Atlas::<MemberCard>::read(
        &network, ETH_SUPERCHAIN.atlas().unwrap(),
    ).await?;
    // ... use them.
    Ok(())
}

ETH_SUPERCHAIN.atlas() returns the Atlas module’s Config if the coalition ships one. The same helper exists for almanac() and chronicle(). A coalition that does not ship a given module returns None.

No additional plumbing. UNIVERSE is the same constant every lattice and zipnet deployment uses.

What can go wrong

ConnectTimeout. The CoalitionConfig you compiled in does not match what the operator is running. Recompile against the current release notes.
Ticket missing on a specific member. Your per- member admission ticket was not issued or was revoked. Per-member operators issue their own tickets; the coalition operator does not. Contact the per-member operator.
An organism down. A committee lost majority. Other members continue; the affected component’s next commit is delayed.
Module helper returns None. The coalition does not ship that module. Drop the dependency or request the module be added.

ai on mosaik