What a coalition gives you

audience: integrators

A coalition is a single handshake token binding an agent to multiple citizens of the mosaik universe at once: block-building lattices, standalone organisms (oracles, attestation fabrics, identity substrates, analytics pipelines, …), confluences (cross-citizen organisms), and the coalition’s optional basic services (Atlas, Almanac, Chronicle, Compute — whichever are shipped). Compile one CoalitionConfig and obtain typed handles on every citizen, every basic service, and every confluence 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 citizens 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 confluences: cross-citizen organisms that aggregate, route, or attest across the citizens in the coalition. Confluences are not coalition-scoped; the same confluence may be referenced by many coalitions.
Optional basic services: up to four well-known shapes — Atlas (directory), Almanac (clock beacon), Chronicle (audit log), Compute (scheduler and registry for image-hash-identified workloads).
An optional coalition-scoped ticket issuer. Components choose whether to recognise its tickets; nothing is required to.
No loss of identity. Every citizen’s GroupId, every ClientId, every StreamId you already use stays byte-for-byte the same under routine operational rotations (MR_TD bumps, ACL rotations). A coalition references citizens; it does not re-derive them.

An agent binding to one citizen only does not need a CoalitionConfig; bind directly to that citizen’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 MR_TDs, and any referenced confluences (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 confluence, you can read one aggregated feed instead of polling per-lattice tally::Refunds.

Cross-domain agent

Your agent consumes outputs from a mix of citizens — 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.

Confluence 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 citizen only.
You are an integrator testing a standalone confluence whose operator has given you its ConfluenceConfig 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 confluences — each with its ConfluenceConfig and a pointer to the confluence operator’s handshake.
The included modules — each a ConfluenceConfig with the shape documented in basic services.
The ticket-issuer root if the coalition ships one.
MR_TDs for every TDX-gated confluence, every TDX-gated module, and every TDX-gated standalone organism 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 confluence, 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 confluence — same shape, one rung up.
    let ledger = ledger::Shared::<Refund>::read(
        &network, &ETH_SUPERCHAIN.confluences[0],
    ).await?;
    // A module — the coalition's Atlas, if shipped.
    let atlas  = atlas::Atlas::<CitizenCard>::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 citizen. Your per- citizen admission ticket was not issued or was revoked. Per-citizen operators issue their own tickets; the coalition operator does not. Contact the per-citizen operator.
Confluence or standalone organism down. A committee lost majority. Other citizens 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.

Keyboard shortcuts

AI