Cross-citizen flows

audience: integrators

This page catalogues cross-citizen flows an agent may run and indicates which are cheap at the integrator level versus when a confluence is warranted.

The underlying theory for block-building cross-chain cases is in the builder book’s cross-chain chapter. The coalition layer formalises its Shape 3 (bridge organism) as a confluence and generalises the pattern beyond block- building to any mix of lattices and standalone organisms. This page is the integrator-facing view.

Four recurring flows

Paired bundles (two block-building lattices)

An agent publishes bundle A to offer[L1] and bundle B to offer[L2], expecting paired-slot commits.

Without a confluence. Keep a per-agent correlator table keyed by bundle id; watch both lattices’ AuctionOutcome and join. Handle partial fills (A committed, B did not) with post-bond collateral or on- chain HTLC logic. This is the builder book’s Shape 1.
With an intents confluence. Publish one intent to the confluence’s write stream; the confluence routes sub-bundles to each target lattice’s offer. Subscribe to the confluence’s RoutedIntents for cross-chain outcome reconciliation.
Decision rule. If only one searcher runs the correlator, keep it in the agent. If three unrelated agents would each run the same correlator, an intents confluence is warranted.

Cross-origin attribution (lattice + lattice)

A bundle submitted on lattice A but captured MEV on lattice B. Without coordination, tally[A] never sees the attribution on B’s block; tally[B] sees it but without knowing the origin was A.

Without a confluence. Subscribe to both tally[A] and tally[B], join in memory on submission ids, compute the cross-origin view locally.
With a shared-ledger confluence. One Shared::<Refund>::read handle yields aggregated attribution across all citizens the ledger spans.
Decision rule. If on-chain settlement requires a pre-aggregated attestation (e.g. one signature for a cross-chain refund claim), the confluence is load- bearing. If each consumer can perform the join, the confluence is a convenience.

Oracle + lattice correlation (organism + lattice)

An agent that needs to correlate an oracle organism’s price feed with block-building auction outcomes on one or more lattices. The citizens are heterogeneous: one is a standalone organism, the others are lattices.

Without a confluence. Subscribe to the oracle organism’s feed and each lattice’s AuctionOutcome; join in memory with a timestamp tolerance window.
With a correlator confluence. The confluence’s commit pairs (oracle_tick, lattice_slot) tuples under one attested key, letting multiple downstream agents consume the same correlation without re-computing. When a coalition ships an Almanac the confluence has opted into, both the oracle tick and the lattice slot align to almanac ticks, providing a shared correlation window.
Decision rule. Do three different agents need the same correlation? If yes, the confluence amortises.

Cross-citizen observability

A dashboard, an analytics agent, or an oncall who wants “one view of the coalition’s activity” — across lattices, standalone organisms, or both.

Without a confluence. N citizen subscriptions plus local aggregation.
With the coalition’s Atlas module. Start from the Atlas (directory of citizens, with endpoint hints); subscribe per citizen. Atlas is the reference; the aggregation remains the integrator’s.
Decision rule. Atlas pays off once more than one dashboard operator exists. A single on-call team can skip it; most coalitions ship an Atlas anyway because the cost is small and the coordination benefit is high.

The decision framework

Every cross-citizen flow reduces to one question:

Do three different agents (searchers, dashboards, analytics) need the same pre-aggregated fact?

If yes, a confluence is the right shape: commit once per slot, consume N times.

If no, a per-agent driver is the right shape: keep the logic where the decisions are made.

A confluence is not generic cross-citizen infrastructure. It is a mosaik organism with a narrow public surface and the same operational cost as any other committee-backed organism. Use it when a committed, reusable fact pays for the cost; use an in-agent driver when it does not.

What the coalition layer does not give you

Atomic cross-citizen commits. The coalition does not provide send-both-or-neither. See atomicity.
Cross-coalition coordination. Two CoalitionConfigs on the same universe are two handshake tokens; they do not coordinate. A cross- coalition commit resolves to a confluence folding the relevant citizens directly, referenced independently by both coalitions.
Trust in a confluence beyond its committee. A confluence’s commit is trustworthy up to its committee’s assumption plus the upstream citizens it reads. Know the trust shape before relying on it.

AI