Composite organisms

audience: contributors

A composite organism is an organism whose Config fingerprint folds two or more member references (lattice references, OrganismRefs, or a mix) and whose public surface coordinates across the referenced members. “Composite” is a role-name convention, not a type: the organism follows the same OrganismRef shape as any other. This chapter specifies when to commission one and how its Config preimage works.

Modules (Atlas, Almanac, Chronicle) are, mechanically, organisms too; their shapes are specified once in basic services. They differ from general organisms in one way: modules derive under a coalition root, while commissioned organisms derive independently of any coalition. The generic organism discipline below applies to both; the derivation difference is called out where it matters.

The reader is assumed to have read Designing coalitions on mosaik and Anatomy of a coalition.

Definition

A composite organism is an organism in every sense the zipnet and builder books use the word. It has:

• one Config fingerprint;
• a narrow public surface (one or two named primitives);
• a TicketValidator composition gating bonds;
• typed Organism::<D>::verb(&network, &Config) free- function constructors;
• a deterministic state machine inside a mosaik Group.

What distinguishes a composite organism from a standalone organism:

• Its content fingerprint folds in multiple member references — the ordered set of members whose public surfaces it reads from (or writes to).
• Its state machine’s commits are a function of inputs drawn from more than one member’s public surface, and serve consumers on more than one member.

A composite organism is not a seventh lattice organism; it is not part of any lattice’s identity derivation; no per-member operator has to know what composite organisms reference their member. A composite organism is independent of any coalition that references it — its committee, state machine, and log are shared across coalition references.

When to commission one

Commission a composite organism when all three of the following hold.

1. The aggregated fact is itself a commit. If what you need can be computed ad hoc by an integrator across N member handles, it does not need a composite organism. If multiple downstream consumers would each have to repeat the same aggregation, or if the aggregation is itself the input to yet another organism, the commit pays for itself.

2. The inputs span more than one member. A composite organism that reads only from one member is a single-member organism in disguise; it belongs as a standalone organism (or inside that member’s own composition, if the member is a lattice).

3. The trust model is coherent across the inputs. A composite organism inherits the worst-case trust assumption of the member inputs it reads. If you cannot name the cross-member trust shape (e.g. “majority-honest across each lattice’s unseal committee, t-of-n on the oracle organism, plus majority-honest composite-organism committee”), you have not finished the design.

When any of the three is false, the right answer is one of:

• A cross-member integrator (Shape 1 in builder’s cross- chain chapter, generalised to any mix of members).
• An in-lattice organism that reads a sibling lattice’s public surface (Shape 2).
• A new standalone organism.
• A new organism inside an existing lattice.

Composite organism versus cross-member integrator

Heuristic: if three different integrators would all perform the same aggregation, it is a candidate composite organism. If exactly one integrator needs it, keep it in the agent.

The Config fingerprint

A composite organism’s Config folds in:

#[non_exhaustive]
pub struct OrganismConfig<'a> {
    /// Role name: "intents", "ledger", "market",
    /// "correlate", … For modules:
    /// "atlas", "almanac", "chronicle".
    pub name: &'a str,

    /// Ordered set of block-building lattices whose
    /// public surfaces this organism reads or writes.
    pub lattices: &'a [LatticeConfig<'a>],

    /// Ordered set of standalone organisms whose public
    /// surfaces this organism reads or writes. Same
    /// story as `lattices` above, for non-lattice
    /// members.
    pub organisms: &'a [OrganismRef<'a>],

    /// State-affecting parameters specific to this
    /// organism. E.g. an intent router's policy
    /// constants, a shared ledger's attribution model,
    /// an almanac's tick cadence.
    pub content: ContentParams<'a>,

    /// TicketValidator composition gating committee
    /// admission.
    pub acl: AclComposition<'a>,
}

impl OrganismConfig<'_> {
    pub const fn organism_id(&self) -> UniqueId { /* ... */ }
}

Identity derives from (name, spanned members, content, acl) with no coalition root folded in:

  ORGANISM(cfg) = blake3(
                      "organism|"
                      || SCHEMA_VERSION_U8
                      || "|" || name
                      || ordered spanned LatticeConfig references
                      || ordered spanned OrganismRef references
                      || content_fingerprint
                      || acl_fingerprint
                    )

A composite organism can therefore be referenced by N coalitions; its committee, state machine, and log are shared across those references. Operators wanting two independent deployments deploy two composite organisms with different content or different ACLs — the cryptographic gate is the fingerprint, not coalition scope.

For modules the derivation is different — they derive under a coalition root (see basic services — Deriving a module’s identity). The public surface, state-machine discipline, and OrganismConfig fields are otherwise identical.

Public surface

Composite organisms follow the narrow-public-surface discipline without modification. Guidelines for picking the surface:

• Key every commit by (member_id, slot) or (member_id, tick) when the organism is per- clock-event per-origin-member. member_id is the 20-byte truncated prefix of the member’s blake3 fingerprint. Integrators that join commits across composite organisms need this key.
• Separate routing and attestation. If your composite organism both routes inputs (a write-side stream) and commits the routing outcome (a read-side collection), keep the two primitives named. Do not fold them into one.
• Expose attestations separately when the commit carries an attestable signature. Integrators that pull attestations to on-chain settlement contracts want the signature surface distinct from the routing surface.
• If your composite organism depends on a module, declare it. A correlator that aligns to Almanac ticks reads Almanac and commits under (member_id, almanac_tick) keys; state that in the crate’s composition-hooks doc and in the OrganismConfig.content parameters (since the alignment is state-affecting).

A design wanting three or more public primitives is likely two composite organisms.

State machine shape

Inside the composite organism’s Group, the state machine is an ordinary mosaik StateMachine<M>. It differs from a standalone organism’s state machine only in what its inputs look like: driver code outside the state machine subscribes to public surfaces on each spanned member and feeds observed facts into the composite organism’s group via group.execute(...).

Template for a composite-organism driver:

// Inside the composite organism's node crate, role: committee member.
loop {
    tokio::select! {
        // Per-member subscriptions the composite organism reads from.
        ev = lattice_a_subscription.next() => {
            let evidence = build_evidence_for_a(ev);
            organism_group.execute(OrganismCmd::ObserveLatticeA(evidence)).await?;
        }
        ev = lattice_b_subscription.next() => {
            let evidence = build_evidence_for_b(ev);
            organism_group.execute(OrganismCmd::ObserveLatticeB(evidence)).await?;
        }
        ev = organism_c_subscription.next() => {
            let evidence = build_evidence_for_c(ev);
            organism_group.execute(OrganismCmd::ObserveOrganismC(evidence)).await?;
        }
        // Optional: align to a coalition's Almanac the
        // composite organism has been configured to track.
        ev = almanac_subscription.next() => {
            let tick = /* ... */;
            organism_group.execute(OrganismCmd::AdvanceTick(tick)).await?;
        }
        // Composite organism's own timers, per its state machine.
        _ = apply_deadline.tick() => {
            organism_group.execute(OrganismCmd::Apply).await?;
        }
    }
}

Rules:

• Observations are evidence, not authority. The Observe* commands carry a pointer to the upstream member commit (member id, slot or tick, commit hash). The composite organism’s state machine validates the pointer against the member’s public surface on replay.
• Applies are pure functions. apply(OrganismCmd::Apply) reads the accumulated observations and emits the composite organism’s commit. It does not make new cross-member reads inside apply; reads belong to the driver.
• No cross-Group calls inside apply. Same discipline as every organism.

ACL and attestation

A composite organism’s TicketValidator composition can include:

• Per-member readership tickets. A composite organism reading from lattice A’s unseal::UnsealedPool or from an oracle organism’s feed is an integrator of that member from the member’s perspective. Committee members must hold tickets the per-member operator issues, same as any other integrator reading that surface.
• TDX attestation. If the composite organism sees cleartext order flow or otherwise-sensitive data, the committee members are almost always required to run an attested TDX image. .require_ticket(Tdx::new().require_mrtd(organism_mrtd)) is the standard line.
• Optional coalition-scoped issuer recognition. If a composite organism expects to be used predominantly under one coalition whose ticket issuer is stable, it may include that issuance root in its validator composition — a choice made on the composite organism’s side, not imposed by the coalition. See ticket issuance.

Failure modes

A composite organism has more failure modes than a standalone organism because its inputs are multi-operator:

• One spanned member stalls. The composite organism’s state machine must decide whether to commit with partial evidence (degrading quality but preserving liveness) or to stall that slot pending the missing member (preserving quality but sacrificing liveness on the slot). This is a per-organism choice; document it in the composition contract.
• One spanned member’s stable id changes. The composite organism’s Config folds that reference; a change means the composite organism must be redeployed. Until it is, the composite organism’s subscriptions to the old member simply stop producing events.
• One spanned member’s content hash changes (if pinned). Same as above but limited to composite organisms that chose to pin content — stable-id-only pinners are unaffected.
• Composite-organism committee loses majority. Same failure mode as any mosaik Raft group. Liveness is lost; integrity is intact.
• Spanned member’s ACL changes. If a per-member operator revokes the ticket committee members hold, the composite organism loses read access to that member’s public surface. Negotiated out of band; there is no technical recourse.

Composition patterns worth naming

Three patterns recur often enough to name. These are patterns, not required composite organisms; modules are the specified shapes.

Intent-router pattern

A composite organism whose state machine commits per-slot routed intents keyed by (target_lattice_id, slot). Reads cleartext from each spanned lattice’s unseal::UnsealedPool; commits a RoutedIntents collection each target lattice’s offer subscribes to. Trust shape: TDX-attested committee plus t-of-n threshold on the cross-member cleartext channel.

The builder book’s Shape 3 bridge organism is an intent- router pattern seed.

Shared-ledger pattern

A composite organism whose state machine aggregates per-lattice tally::Refunds into a cross-origin-member attribution set, committed as SharedRefunds and SharedAttestations. Trust shape: majority-honest composite-organism committee plus the per-member trust shape of each spanned tally. An on-chain settlement contract verifying a SharedAttestation verifies both the composite organism’s signature and the underlying per-lattice tally::Attestation referenced as evidence.

Integrators needing one refund feed across chains bind the composite organism; integrators concerned with a single chain bind that lattice’s tally directly. Both paths coexist.

Cross-feed correlator pattern

A composite organism that pairs ticks from two or more oracle organisms (or more generally, two or more non-slotted standalone organisms), committing correlated values under (member_id, almanac_tick) when a coalition referencing the composite organism ships an Almanac and the composite organism opts in, or under (member_id, timestamp_bin) otherwise. Trust shape: majority-honest composite-organism committee plus the signing assumptions of each upstream oracle.

Other patterns worth naming (non-block-building)

The three patterns above originate in block-building. Other domains will yield more. Sketches:

• Attestation aggregator. A composite organism that folds TDX Measurements quotes from multiple attestation organisms across vendors or regions into a single attested membership set.
• Coordination-market organiser. A composite organism that runs an allocation auction where inputs come from several independent signal organisms and outputs drive several independent downstream members.
• Cross-DA committer. A composite organism that commits a combined availability proof over two or more DA shards.

Each is an OrganismConfig whose lattices slice may be empty and whose organisms slice names the upstreams.

Checklist mirror

The commissioning checklist in topology-intro — Checklist for commissioning a new composite organism applies verbatim. This page is the reference; the topology-intro page is the forcing function when commissioning one.

Cross-references

• topology-intro — why this rung exists.
• basic-services — the three specified module shapes plus retirement markers.
• ticket-issuance — the optional coalition-scoped issuance root.
• architecture — where composite organisms sit in one example coalition.
• composition — the subscription graph that members and composite organisms share.
• atomicity — what composite organisms deliberately do not guarantee.
• threat-model — how a composite organism’s trust assumption composes with the spanned members’.