Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Roadmap

audience: contributors

This roadmap covers the coalition blueprint, not the v2 lists of any individual composite organism, module, or standalone organism. Each crate ships its own internal roadmap; the zipnet crate’s Roadmap to v2 is the template future crates follow.

Items below are ordered by external-impact visibility, not by engineering order; implementation order is determined by what the first production coalition requires.

v0.1 — Blueprint (this document)

Specification complete. No crates shipped. Audience: contributors who want to challenge the composition shape before composite-organism or module implementation starts.

v0.2 — Coalition meta-crate walking skeleton

Goal: one coalition meta-crate exists, its CoalitionConfig type compiles against a fixed set of example member references, and its coalition_id() derivation is stable and testable.

Minimum content:

  • Crate layout. One coalition meta-crate owning CoalitionConfig<'a>, OrganismRef<'a>, OrganismConfig<'a>, TicketIssuerConfig<'a>, the derivation helpers, the module lookup helpers (atlas(), almanac(), chronicle()), and re-exports of builder::{LatticeConfig, UNIVERSE}. No runtime yet.
  • Lifetime parameterisation. Every public struct is #[non_exhaustive] and parameterised over 'a. const instances continue to compile under 'static inference; runtime construction is first-class.
  • Schema version byte. SCHEMA_VERSION_U8 = 1 folded as the first element of every identity preimage.
  • Stable-id / content-hash split. Both LatticeConfig and OrganismRef expose a stable_id() accessor separate from their full fingerprint.
  • Derivation tests. Golden-vector tests ensuring a fixed CoalitionConfig produces a fixed fingerprint, and that each included member’s fingerprint is unchanged by coalition membership.
  • Mixed-composition tests. A coalition with zero lattices and two standalone organisms derives correctly; a coalition with two lattices and zero organisms derives correctly; mixes derive correctly.
  • Module-helper tests. Helpers return Some when a module by the well-known name is present, None otherwise.
  • Book examples. Every rust,ignore snippet in this book that references CoalitionConfig type-checks against the v0.2 meta-crate signature.

Non-goals for v0.2:

  • Any composite-organism implementation. Composite organisms arrive piecemeal once the meta-crate is stable.
  • Any module implementation. First module and the ticket issuer land in v0.3.
  • Any standalone-organism implementation. Those live in their own crates; the meta-crate only references them.
  • On-wire types. No new wire types are added at the coalition layer beyond what each organism (composite, module, or standalone) commissions for itself.

v0.3 — First module (Atlas) + ticket issuance

Goal: the first module ships end-to-end and validates the coalition’s civic-services pattern; the optional ticket-issuance root ships alongside because it is mechanically simpler than any module.

Atlas is chosen first because it has the narrowest trust shape and the shortest state machine. It exercises every part of the derivation and subscription path without introducing threshold cryptography or cross-chain auction semantics.

Minimum content:

  • coalition-atlas crate with:
    • Config fingerprint folding the coalition root and the set of member references the Atlas catalogues.
    • Atlas::<MemberCard>::read and Atlas::<MemberCard>::publish typed constructors.
    • A small state machine that commits member cards (metadata, endpoint hints, ticket-issuance roots, TDX Measurements) per member reference, co-signed by the Atlas committee. The card format handles both lattices and standalone organisms.
  • Ticket-issuance support in the coalition meta-crate: TicketIssuerConfig plumbed into CoalitionConfig with derivation under COALITION_ROOT.derive("tickets").
  • Integration test: stand up two members (mocked — one lattice, one organism), one Atlas module, optional ticket issuer, and demonstrate an integrator binding to all three through one CoalitionConfig.

v0.4 — Almanac + Chronicle

Goal: two more modules ship.

  • coalition-almanac crate with committee-driven tick commits. Per-member observed_at vector captured at commit time. Integration test: a correlator composite organism aligns events from two members to almanac ticks.
  • coalition-chronicle crate with append-only audit log. Per-member signatures on every entry; optional on-chain anchor path with configurable cadence. Integration test: coalition republishes a CoalitionConfig with a new member; Chronicle records the transition and emits an anchor commit at the next cadence boundary.

These land together because they share infrastructure (monotonic committee-signed commits) and because both are strictly additive to v0.3.

v0.5 — First commissioned composite organism + retirement markers

Goal: the first composite organism whose state machine depends on cleartext order flow from multiple lattices.

Minimum content:

  • coalition-intents crate following the intent-router pattern in composite organisms. Derives independently of any coalition; the crate ships an example OrganismConfig and example coalitions that reference it.
  • TDX admission on every committee member.
  • Integration test: intents submitted on lattice A are routed to lattice B’s offer input and a downstream tally commit reflects the cross-chain attribution.
  • Per-member stall policy documented in the crate’s composition-hooks.md.
  • Retirement marker support across all shipped crates (coalition-atlas, coalition-almanac, coalition-chronicle, coalition-intents): every committee emits a terminal RetirementMarker before shutting down; the Chronicle records it as OrganismRetired or ModuleRetired.

v0.6 — Shared attribution ledger + Compute

Goal: a second commissioned composite organism demonstrating fan-in attribution, plus the fourth module.

  • coalition-ledger crate following the shared-ledger pattern in composite organisms.
  • coalition-compute crate implementing the Compute module spec in basic services — Compute. Integration test: an agent organism submits a ComputeRequest for a TDX image, receives a ComputeGrant, the provider starts the workload with matching TDX Measurements, the provider emits a ComputeLog on completion.

(Passport is gone; ticket issuance is in v0.3.)

v1.0 — First production coalition

Goal: one coalition runs on mainnet references continuously for a month with no protocol-level incidents.

  • Rolling upgrades of composite organisms and modules. Until this point, “stop the service, bump the CoalitionConfig, restart” is an acceptable release strategy; at v1.0 it is not.
  • Snapshot + state-sync for every composite organism’s and every module’s state machine.
  • Full operator runbooks under operators/, graded by severity and audited externally.
  • Stable CoalitionConfig serialisation format. CoalitionConfig::from_hex is safe to use as the handshake after v1.0.

Longer-term items (no version assigned)

Versioning

Carrying the zipnet/builder policy into the coalition model with three adjustments.

  • Per composite organism / module: lockstep at the organism level. Commissioned composite organisms ship and version on their own schedule independent of any coalition that references them — because composite organisms no longer derive under a coalition root, a composite-organism upgrade does not force every coalition referencing it to re-derive. Coalitions simply reference the new fingerprint when they wish.
  • Per coalition: version-in-name for the coalition identity. A coalition retirement is an operator- level decision and produces a new instance name (ethereum.superchain-v2026q2). Individual modules inside a stable coalition name can still upgrade in lockstep without retiring the coalition.
  • Per member reference: stable-id pinning plus optional content-hash pinning. A CoalitionConfig references members by stable id. Composite organisms and modules choose per-component whether to also pin the content hash. Whether content-hash-pinning becomes a coalition-wide policy rather than a per-component choice is open for v0.3 decision.

Neither policy is load-bearing for v0.2 / v0.3. The first v1.0 release forces the decision.

Cross-coalition coordination

Out of scope for v0.1. A composite organism whose content folds the relevant members directly can be referenced independently by multiple coalitions; the cross- coalition commit is whatever that composite organism commits. No new primitive is needed. Research-complete, engineering-deferred.

TDX-attested modules

The v0.3 Atlas is a minimal, non-TDX module. A TDX- attested Atlas — where the committee commits cards only over attested images — is a v1+ refinement. Same for TDX-attested Almanac, Chronicle. The blueprint is unchanged; the refinement touches only the crates.

Optional cross-coalition directory

Not a core feature; same argument as the lattice directory in builder. A shared Map<CoalitionName, CoalitionCard> listing known coalitions may ship as a devops convenience. If built, it must:

  • be documented as a convenience, not a binding path;
  • be independently bindable — the coalition meta-crate never consults it;
  • not become load-bearing for ACL or attestation.

Flag in-source as // CONVENIENCE: if it lands.

Byzantine liveness for every organism committee

Mosaik’s Raft variant is crash-fault tolerant. The zipnet liveness item applies to every committee. A future BFT variant in mosaik would be inherited by every component; until then, a deliberately compromised committee member can DoS liveness in its own committee.

Composite-organism-level confidentiality beyond TDX

Some composite-organism roles (cross-chain intent routing over many chains, cross-feed correlation of sensitive oracles) may want post-quantum confidentiality ahead of their upstream members themselves. Research-complete for several threshold schemes; engineering-deferred. The organism surface does not change; only the crypto inside the composite organism’s state machine does.

New mid-rung composition classes

Builder is the first fully-specified class of mid-rung composition (block-building lattices). Other classes may follow — attestation fabrics, oracle grids, identity substrates with their own collective shape — each with its own book and its own handshake. When one does:

  • The new class’s book specifies its own FooConfig and derivation discipline, mirroring builder.
  • The coalition meta-crate may add a new referenced slice (pub fabrics: &'a [FabricConfig<'a>], etc.) or may continue referencing those compositions via their root organisms. Either works; the tradeoff is ergonomic.
  • Composite organisms gain the ability to fold the new class’s fingerprints into their Config alongside lattices and organisms.
  • Atlas MemberCard schemas are extended via #[non_exhaustive] field additions to carry metadata about the new kind.

Research-and-engineering-deferred. The coalition blueprint grows in lockstep with whichever class lands first.

Deferred-primitives space (research stance)

The blueprint explicitly refuses deferred-primitives: enforceable policies over members, taxation, judiciary, mandatory membership. The refusal is load-bearing for the current trust and composition stories.

A future proposal could make a case for one deferred primitive at a time, as a separate design with its own book branch. Any such proposal must:

  • give a full trust composition for the new primitive showing what it does to the existing guarantees;
  • specify a migration path for coalitions that ship the current opt-in shape;
  • earn its way past the objection that it reintroduces supra-member authority the current blueprint does not provide.

No concrete deferred-primitives proposal is planned. The space is flagged so contributors know where the current scope ends and where fresh proposal work would begin.

What this roadmap does not include

  • Specific crate-versioning schedules. Each crate owns its own version cadence.
  • A list of composite organisms, organism categories, or lattice classes the blueprint wants shipped. Unlike builder’s six-organism commitment, the coalition blueprint stays open beyond the five basic services. The roadmap names three plausible first commissioned composite organisms; the catalogue grows as cross- member problems force new ones.
  • Operator-onboarding contractual detail. Coalition operators run different organisations under different legal regimes; the book does not try to standardise that.
  • Adoption strategy. The book specifies and documents; adoption is the operators’ concern.