Setup and shape

audience: ai

Three things are fixed before any code runs: the crate-level dependencies, the oracle-γ coalition shape, and the Measurements set the oracle publishes. The Measurements set is the whole trust anchor of the example; everything that follows refers to it.

Dependencies

Cargo.toml, [dependencies]
mosaik          = "0.3"
coalition       = "0.1"     # this book's crate once published
oracle-feed     = "0.1"     # hypothetical helper for source catalogs
tokio           = { version = "1", features = ["full"] }

mosaik::tee::tdx is re-exported from mosaik. Versions land alongside the coalition crate; until then, everything below is a specification shape.

The oracle’s OrganismConfig

The oracle is a standalone organism. Its Config fingerprint does not fold a coalition root; the same organism can be referenced by many coalitions.

use coalition::{OrganismConfig, SCHEMA_VERSION_U8};
use mosaik::tee::tdx::Measurements;

pub const ORACLE_MEASUREMENTS: Measurements =
    Measurements::from_hex(
        // MR_TD, MR_CONFIG_ID, MR_OWNER, MR_OWNER_CONFIG
        // published on the oracle operator's release page
        "b7f2…c9",
    );

pub const ORACLE: OrganismConfig<'static> = OrganismConfig {
    schema_version: SCHEMA_VERSION_U8,
    role:           "oracle",
    instance_name:  "oracle-γ.oracle",
    members:        &[],               // simple organism
    parameters:     &OracleParameters::DEFAULT.preimage(),
    measurements:   Some(ORACLE_MEASUREMENTS),
    acl:            &OracleAcl::DEFAULT,
};

OracleParameters folds every state-affecting parameter of the oracle’s deployment: the supported-pair set, the source-catalog digest, the aggregation-policy identifier, the publication cadence, and the staleness thresholds. Any change to any of them is a new Config.content — which, since Measurements are folded in, forces a coincident image republish. The two invariants travel together by construction.

pub struct OracleParameters {
    /// Every token pair the oracle publishes a stream for.
    /// Pair form: ("USDC", "ETH") etc. Ordered
    /// lexicographically so the preimage is canonical.
    pub pairs:                 &'static [TokenPair],

    /// blake3 of the source-catalog spec (see ch. 3).
    pub source_catalog_digest: [u8; 32],

    /// Identifier for the aggregation policy (ch. 5).
    pub aggregation_policy:    AggregationPolicyId,

    /// Nominal inter-tick cadence in milliseconds.
    pub cadence_ms:            u32,

    /// Per-source staleness threshold in milliseconds.
    pub max_source_age_ms:     u32,
}

OracleAcl composes the TicketValidator the oracle bonds against: in the minimal version, an open subscribe ticket (anyone can read any stream) and a closed publish ticket (only the oracle’s own operator key publishes). A consumer coalition’s admission is on the consumer’s side, by admitting ORACLE_MEASUREMENTS in its own TicketValidator — not by being on a list here.

The oracle-γ coalition

oracle-γ is the thinnest coalition that wraps the oracle as a single referenced member:

use coalition::{
    CoalitionConfig, OrganismRef,
    COALITION_ROOT_SEED, SCHEMA_VERSION_U8,
};

pub const ORACLE_ORG: OrganismRef<'static> = OrganismRef {
    role:         "oracle",
    stable_id:    const_blake3!(
        b"instance|oracle-γ.oracle|", UNIVERSE.bytes()
    ),
    content_hash: Some(ORACLE.content_hash()),
};

pub const ORACLE_GAMMA: CoalitionConfig<'static> =
    CoalitionConfig {
        schema_version:    SCHEMA_VERSION_U8,
        coalition_seed:    COALITION_ROOT_SEED,
        instance_name:     "oracle-γ",
        lattices:          &[],
        organisms:         &[ORACLE_ORG],
        atlas:             None,
        almanac:           None,
        chronicle:         None,         // added in chapter 7
        compute:           None,
        randomness:        None,
        ticket_issuer:     None,
        retirement_policy: Default::default(),
    };

Notes on the shape above:

• content_hash is pinned. Unlike searcher-α (which omits the content hash on its member pointer), oracle-γ pins the oracle’s current content hash inside its own coalition. Every Measurements rotation is a new content hash and a coincident oracle-γ republish, observable through the retirement chain.
• One-member coalition is not a contradiction. Coalitions with one referenced organism are a packaging convenience; they give the operator a coalition-scoped retirement chain and an optional Chronicle without implying any coordination.
• Consumers need not reference oracle-γ. A consumer coalition may reference the oracle directly via a matching OrganismRef on its own side. oracle-γ is for the oracle operator’s retirement and Chronicle; it is not the handshake surface.

TDX posture

The oracle operator’s public handshake surface is two values:

1. ORACLE.content_hash() — the oracle organism’s current content hash.
2. ORACLE_MEASUREMENTS — the TDX Measurements set folded into that content hash.

Publishing both on a release page is sufficient for any consumer to compose admission. Nothing else is needed out-of-band.

Forward

Chapter 2 (binding) is the consumer side: how a coalition references the oracle, composes its TicketValidator, and performs its first stream subscription. Chapters 3–5 walk the oracle’s interior: what it reads, how it wraps non-mosaik feeds, how it derives each tick. Chapter 6 walks publication. Chapter 7 walks rotation, retirement, and the operator exit.