Iris Glossary

The canonical, project-specific dictionary for the Iris Protocol — the first place to look when a term feels load-bearing in docs/ or in the crates/, and the first place to update when new vocabulary lands. Other documents (architecture spec, implementation plans, threat model, crate READMEs, code comments) should use these names consistently; if you find a contradiction, fix the other document — or update the entry here and propagate.

Reading this glossary.

Entries are grouped by category, alphabetical within each group.
Each entry follows the shape: Term — one-line definition, an optional second sentence for nuance, then a See: pointer to the canonical home (architecture section, crate, or other doc).
Backticked names like RoundDispatcher are Rust identifiers; bolded names like Leader Node are protocol-level actors. The casing matches the place each term is defined.
"Stub" in a definition means the named code component exists but is a placeholder pending a future phase (see implementation_demo.html for Phases 0 → 4.5, implementation_mvp.md for Phase 5+).
Cross-references use architecture.html §N for spec sections or crates/iris-foo for code locations.

Actors

Protocol participants

Bolded everywhere in prose to keep cross-doc references readable (CLAUDE.md style convention). Full definitions with responsibilities, trust grants, and constraints live in architecture.html §1.2; this section is the quick reference.

Attestor: A TEE vendor whose hardware-rooted PKI signs the attestation documents produced inside iris-fetch enclaves. Each accepted vendor (AWS, Intel, AMD) is a distinct Attestor; the protocol is multi-vendor by design. Not an Iris network participant. See: architecture.html §1.2, §5.
Committee: The active set of staked Regular Nodes at a given epoch. Network-wide, slow-moving (Layer 4). Produces t-of-n BLS threshold signatures; rotates only on membership change, protocol-version bump, or scheduled DKG re-key. See: architecture.html §3.4.
Data Provider: External commercial satellite imagery service (Maxar, Planet, Sentinel) that serves raw GeoTIFFs over HTTPS to Iris nodes. Not a network participant; Iris trusts only the TLS-attested fact of delivery, not pixel content. See: architecture.html §1.2, §5.
Iris Foundation: Phase-1 / MVP steward of the on-chain attestation whitelist, the Foundation Relayer, and governance until decentralization completes. A trusted role with a phased decentralization roadmap. See: architecture.html §5.5, §8.7; governance.html.
Iris Protocol LLC: The legal/operational counterpart to the Iris Foundation in the Foundation/LLC organizational split. Responsibility-split is specified in governance.html.
Leader Node: A Regular Node elected per-round by the deterministic formula in architecture.html §7.1 to aggregate manifests, run the normalization pipeline, select the medoid, and aggregate BLS shares. Leadership is a rotating duty with no extra fee — see Average Scenario. See: architecture.html §1.2, §7.1–§7.4.
Regular Node: An active committee member that observes imagery, generates attestation documents, and contributes BLS signature shares. Staking-gated; misbehavior is slashed on-chain. See: architecture.html §1.2, §3.2, §3.4.
Relayer: Opt-in, reputation-gated role that bridges the host blockchain to the Iris network: publishes DataRequest events on GossipSub and submits finalized panels via IrisVerifier.deliverReport. Cannot forge consensus; can only censor (bounded by the on-chain timeout fallback). See: architecture.html §1.2, §8.7.
Requester: A dapp or smart contract that submits a DataRequest on-chain (specifying AoI, timestamp, fee) and consumes the resulting verified panel. Has no influence over consensus or panel content beyond the request parameters. See: architecture.html §1.2.

State Layers

The four nested scopes

The four nested state scopes that organize every protocol concept. Each layer has its own lifetime, its own mutation rules, and its own crate ownership. See: architecture.html §3.

Layer 1 — Round State: Per-request, ephemeral. The Round FSM (Idle → Observing → Aggregating → PreCommit → Voting → Commit | Failed) lives here. Owned by iris-consensus (currently a stub) plus the iris-data RoundDispatcher which runs the Observing slice today. See: architecture.html §3.1.
Layer 2 — Node State: Per-node, persistent across rounds. Holds ed25519 keypair, BLS share, peer table, local cache, and at-most-one active Round (the MVP single-active-round invariant). The vocabulary of Layer 2 lives in iris-core. See: architecture.html §3.2.
Layer 3 — Panel State: Global, immutable once committed. A finalized Panel is one geodesic facet — bounding box + timestamp + IPFS CID + BLS threshold signature. See: architecture.html §3.3.
Layer 4 — Committee State: Network-wide, slow-moving. Tracks the active Committee set, aggregate BLS public key, current epoch, and DKG state. Rotates only on membership change, version bump, or scheduled DKG re-key. See: architecture.html §3.4.

Round Phases

Layer-1 FSM states

States in the Layer-1 Round FSM. Capitalized in prose as proper nouns. Full state definitions (who's active, what's tracked, exit condition) are in architecture.html §3.1; this section is the one-liner reference.

Idle

Listening on iris/requests/v1 for the next DataRequest. Round has not yet started. See: architecture.html §3.1.

Observing

All committee members fetch imagery from their Data Provider through an iris-fetch enclave. Two sub-phases:

Observing Phase 1 (≤60 s) — Each node publishes a lightweight TlsCommitment proving the in-enclave TLS handshake succeeded. Failing to meet this deadline excludes the node from the round. See: architecture.html §7.2.
Observing Phase 2 (≤300 s from round start) — Each committed node finishes the in-enclave download, computes BLAKE2b(payload) and attestation_hash, and publishes a full Manifest. See: architecture.html §7.2.

Aggregating

Leader Node only. Pulls each contributor's GeoTIFF over /iris/geotiff/1.0.0, runs the Normalization Pipeline, selects the medoid, pins it to IPFS, and broadcasts a Proposal. See: architecture.html §7.3.

PreCommit

Each Regular Node independently re-verifies the Leader's proposal (Tier-1 mandatory checks + Tier-2 probabilistic spot-checks per architecture.html §7.4) and either broadcasts a BLS signature share or a rejection.

Voting

Leader collects BLS shares. Reaching t valid shares advances to Commit; the voting_timeout_seconds timer expiring with < t shares fails the round.

Commit

Leader aggregates the t partial shares into a single 48-byte BLS threshold signature; the Relayer submits IrisVerifier.deliverReport. See: architecture.html §3.1, §8.

Failed

Terminal failure. The round records a FailureReason, reportFailure is called on-chain, and contributor credits / slashing rules from architecture.html §8.8 apply. See: error_handling_strategies.md.

Runtime Components

Process-internal types

Code-level abstractions inside a running iris-node. These are the words that show up in crates/*/src/*.rs, in PR descriptions, and in implementation_demo.html / implementation_mvp.md task breakdowns. They are process-internal — none of them are on-the-wire concepts. When discussing a Runtime Component in prose:

Use backticks and PascalCase for the type name (RoundDispatcher, SwarmHandle).
Use lowercase prose ("the dispatcher", "the swarm") for the running instance.
Cross-reference the canonical module via crates/<crate>/src/<file>.rs.

ActiveRoundHandle: Cloneable wrapper around the dispatcher's "currently-running round" set. Lets the DiskCache exempt the active round's hashes from GC. See: crates/iris-data/src/dispatcher.rs.
AssetCatalog: Trait that resolves a DataRequest (AoI + timestamp) to one or more provider-specific asset URLs. StaticCatalog is the test impl; the production STAC client lands later. See: crates/iris-data/src/observer.rs.
AttestationDocument: In-memory representation of a TEE vendor attestation document (CBOR payload + vendor signature + cert chain). Persisted as ~/.iris/attestations/<hash>.att via write_attestation_atomic. See: crates/iris-data/src/attestation_doc.rs; architecture.html §5.3.
AttestationEnvelope: Outer CBOR envelope wrapping an AttestationDocument for on-disk and over-the-wire transport. See: crates/iris-data/src/attestation_doc.rs.
Chain Watcher (ChainWatcher): alloy-backed task that subscribes to the host chain via WebSocket, decodes DataRequest / EpochEvent / CommitteeRotated / UpgradeScheduled events, and forwards them on ChainWatcherInboxes. Reconnects with exponential backoff. See: crates/iris-network/src/chain_watcher.rs; architecture.html §8.
ChainWatcherInboxes: The mpsc-channel set the chain watcher writes to: one inbox per host-chain event type. Consumed by the dispatcher and (Phase 4+) the consensus FSM. See: crates/iris-network/src/chain_watcher.rs.
CommittedSession: The output of the IrisObservingWorker's provider race: the winning (provider, asset_url, AttestorSession) triple that Phase 2 will stream from. See: crates/iris-data/src/observer.rs.
DiskCache: On-disk cache for GeoTIFFs (~/.iris/cache/objects/<blake2b>.tiff) and attestations (~/.iris/attestations/<hash>.att). Atomic writes via tempfile-then-rename, recursive scan on startup, statvfs-based disk-pressure measurement. See: crates/iris-data/src/cache.rs; architecture.html §3.3.
DispatcherHandle: Cloneable handle for sending commands to the RoundDispatcher task without owning it. See: crates/iris-data/src/dispatcher.rs.
EnclaveAttestor: Trait abstracting the per-vendor TEE attestation API (open_session, attested_fetch, etc.). Per-vendor impls: MockAttestor (devnet only), Nitro, SGX, TDX, SEV-SNP. The dependency-injection seam between iris-data and the TEE SDKs. See: crates/iris-data/src/attestor.rs; architecture.html §5.2.
EnclaveTransport: Trait wrapping HttpTransport so TLS terminates inside the enclave. The Phase 2.4 in-enclave fetch path. See: crates/iris-data/src/attestor.rs.
GeotiffCache: Trait used by the Swarm's /iris/geotiff/1.0.0 serve-side to look up payloads by ContentHash. MemoryCache is a test impl; production uses DiskCache. See: crates/iris-network/src/transfer.rs.
GeotiffRequest / GeotiffResponse: Wire types for the /iris/geotiff/1.0.0 RequestResponse protocol. Direct stream, max payload 16 GB, timeout 3600 s. See: crates/iris-network/src/transfer.rs; architecture.html §4.5.
HttpTransport: Trait that hides reqwest so tests can inject a mock. ReqwestTransport is the production impl. See: crates/iris-data/src/transport.rs.
iris-fetch enclave: The TEE-resident binary that terminates the TLS connection to the Data Provider, hashes the streaming response with BLAKE2b, and emits a vendor-signed attestation document. Distinct from the host-side iris-node. See: architecture.html §5.2.
IrisObservingWorker: The production ObservingWorker impl — runs the live two-phase Observing window inside iris-data. See: crates/iris-data/src/observer.rs.
IrisTopic: Enum of the three GossipSub topics (iris/requests/v1, iris/observations/v1, iris/consensus/v1). See: crates/iris-network/src/gossip.rs; architecture.html §4.4.
MemoryCache: In-memory GeotiffCache impl for tests and the iris-network test-utils feature. See: crates/iris-network/src/transfer.rs.
NodeIdentity: The persistent ed25519 keypair plus libp2p PeerId derivation. Stored at ~/.iris/identity.key with 0600 permissions on disk. See: crates/iris-core/src/identity.rs; architecture.html §4.2.1.
NoopObservingWorker: Test stub ObservingWorker impl with with_simulated_work for dispatcher unit tests. Never appears in a release binary. See: crates/iris-data/src/dispatcher.rs.
ObservationPublisher: Trait abstracting "publish CBOR bytes to a GossipSub topic" so the worker is testable without a real swarm. Production impl: impl ObservationPublisher for SwarmHandle. See: crates/iris-data/src/observer.rs.
ObservingWorker: Trait modeling the per-round task that owns the two-phase Observing window. The RoundDispatcher spawns one of these per DataRequest. See: crates/iris-data/src/dispatcher.rs.
Round Dispatcher (RoundDispatcher): The iris-data task that owns the consumer side of RouterChannels::data_requests. Spawns one ObservingWorker per round; enforces the MVP single-active-round invariant via a mutex; will be subsumed into the Phase-4 Iris-BFT FSM with no API churn. See: crates/iris-data/src/dispatcher.rs; implementation_demo.html [2.1].
RouterChannels: The set of typed mpsc channels the TopicRouter exposes to consumers (one per topic). See: crates/iris-network/src/codec.rs.
Routed<T>: Wrapper around a decoded GossipSub message that pairs the typed body with its routing metadata (peer of origin, topic). See: crates/iris-network/src/codec.rs.
RoundFailure: Enum carried in RoundOutcome describing why an observation failed. Phase-2 variants live in iris-data::observer::ObservationFailed; Phase-4 will add consensus-side variants. See: crates/iris-data/src/dispatcher.rs; error_handling_strategies.md.
RoundOutcome: Terminal value emitted by an ObservingWorker over a oneshot to the dispatcher: { request_id, completed_phases, failure: Option<RoundFailure> }. See: crates/iris-data/src/dispatcher.rs.
SignedRequestRecord: The detached record of a single DataRequest invocation (request bytes + ed25519 signature) bound into the attestation envelope. See: crates/iris-data/src/attestation_doc.rs.
Swarm: The libp2p::Swarm event loop owned by iris-network. Composes the Noise XX transport, Yamux multiplexer, Identify, Kademlia, GossipSub v1.1, and two RequestResponse protocols (/iris/geotiff/1.0.0, /iris/attestation/1.0.0). Single-threaded by libp2p constraint; lives in a dedicated tokio::task. Exactly one Swarm per running node. See: crates/iris-network/src/swarm.rs; architecture.html §4.
SwarmCommand: Enum of outbound requests from other tasks to the Swarm (publish, dial, ban, request-response). Sent over the mpsc carried by SwarmHandle. See: crates/iris-network/src/swarm.rs.
SwarmEvent: Enum of inbound events the Swarm surfaces to the rest of the node (gossip message, peer connected, request-response). See: crates/iris-network/src/swarm.rs.
SwarmHandle: Cloneable handle to the Swarm. Carries a SwarmCommand mpsc sender and helpers like publish(topic, bytes). The seam every other crate uses to talk to libp2p without owning the event loop. See: crates/iris-network/src/swarm.rs.
TopicRouter: Decodes raw GossipSub bytes into typed Routed<T> messages and demultiplexes them into the per-topic channels of RouterChannels. The Swarm hands raw bytes off here so consumers never see CBOR errors. See: crates/iris-network/src/codec.rs.
WorkerDeps: The dependency aggregate the RoundDispatcher plugs into each spawned IrisObservingWorker: { providers, catalog, attestor, identity, publisher, cache, observation_phase1_deadline, geotiff_body_deadline, manifest_deadline }. The two deadline-trio fields split out from the legacy tls_commitment_deadline in [4.5.17]. See: crates/iris-data/src/observer.rs.

Protocol Messages

On-the-wire CBOR structs

The on-the-wire CBOR structs that cross node boundaries on GossipSub or direct streams. All defined in iris-core::types. Capitalized in prose as their Rust type name (backticks where appropriate).

AttestationRef: Reference to a stored attestation document by hash, used inside Manifest to point at the .att blob held by the publishing node. See: crates/iris-core/src/types.rs.
CommitteeRotated: Host-chain event emitted when IrisVerifier.updateCommittee() succeeds — carries the new aggregate BLS key, threshold, and member set. See: architecture.html §8.3.
ConsensusMessage: Top-level enum on iris/consensus/v1 covering Proposal, BlsShare, Rejection, etc. See: crates/iris-core/src/types.rs.
DataRequest: On-chain request emitted by Requester → IrisVerifier. Specifies AoI, timestamp, fee. Travels onto iris/requests/v1 via the Relayer or self-watcher. See: architecture.html §3.1, §8.
EpochEvent: Host-chain event carrying epoch boundary info. See: architecture.html §3.4.
Manifest: Phase-2 observation message: {request_id, image_hash, bounding_box, timestamp, attestation_hash, node_signature}. Published on iris/observations/v1 by deadline 300 s. See: architecture.html §3.1, §7.2.
ObservationMessage: Top-level enum on iris/observations/v1 (variants: TlsCommitment, Manifest, ObservationFailure). See: crates/iris-core/src/types.rs.
Panel: One finalized geodesic facet — bounding box + timestamp + IPFS CID + BLS threshold signature. The Layer-3 output. See: architecture.html §3.3.
Proposal: Aggregating → PreCommit message broadcast by the Leader Node: {request_id, selected_image_hash, selected_index, ipfs_cid, contributors, similarity_matrix, leader_signature}. The full pairwise matrix is included so each node can deterministically verify the medoid pick. See: architecture.html §7.3.
Rejection: Negative vote during PreCommit, optionally carrying a fraud-proof seed if a Tier-2 spot-check failed. See: architecture.html §7.4.
TlsCommitment: Phase-1 observation message: lightweight proof that the in-enclave TLS handshake with the Data Provider succeeded. Published on iris/observations/v1 by deadline 60 s. See: architecture.html §3.1, §7.2.
UpgradeScheduled: Host-chain event announcing a future minProtocolVersion bump. Triggers epoch-windowed upgrade behavior in versioning_strategies.md. See: architecture.html §10.

Cryptographic Primitives & Identifiers

Primitives & identifiers

AggregateKey: The committee-wide BLS12-381 aggregate public key used by IrisVerifier. Domain alias for BlsPublicKey. Re-derived only on epoch rotation. See: architecture.html §3.4, §7.5.
AttestationHash: BLAKE2b(attestation_doc_bytes). The .att file's content hash, surfaced in Manifest.attestation_hash. Domain alias for Blake2bHash. See: crates/iris-core/src/hash.rs.
BLAKE2b-512: The off-chain content hash. 12 rounds, 256-bit Grover pre-image margin. Used for ContentHash, AttestationHash, signature digests, and IPFS-related content addressing. Implemented via the blake2 crate. See: architecture.html §10.1.
BLS12-381: The pairing-friendly elliptic curve used for the committee threshold signatures. Verified on-chain via the EIP-2537 precompile. See: architecture.html §7.5, §8.4.
ContentHash: BLAKE2b(geotiff_payload). The content-addressable name of a GeoTIFF in the cache. Domain alias for Blake2bHash. See: crates/iris-core/src/hash.rs.
ContributorId: PeerId of a node that contributed an observation in a given round. Domain alias for PeerId. See: architecture.html §3.1.
DKG (Distributed Key Generation): Off-chain ceremony via Feldman's VSS that produces individual BLS share keypairs and the committee aggregate public key. Runs only on committee changes — never per-request. Retry budget: 3 attempts within 15 minutes, then DkgAborted retains the prior committee. See: architecture.html §3.4.
ed25519: The signature scheme used for PeerId-derived node identity and per-message signatures (leader_signature, node_signature, verify_tls_commitment_signature). Implemented via ed25519-dalek. See: architecture.html §4.2.1.
EIP-2537: The Ethereum precompile that verifies BLS12-381 signatures on-chain. Available on Pectra+ networks (Sepolia, Holesky, mainnet). The reason BLS12-381 was chosen for the threshold signature. See: architecture.html §8.4.
Feldman's VSS: The verifiable secret-sharing scheme used for the DKG ceremony. See: architecture.html §3.4.
Keccak-256: The hash function used only for the leader-election seed (architecture.html §7.1). Chosen for EVM precompile reproducibility, not throughput. Distinct from BLAKE2b, which covers all other off-chain hashes. See: architecture.html §10.1.
LeaderId: PeerId of the elected leader for a round. Domain alias for PeerId. See: architecture.html §3.1.
PeerId: libp2p-canonical content-addressed identifier multihash(public_key_bytes) derived from the node's ed25519 public key. See: architecture.html §4.2.1.
ProofHash: Domain alias used to label hashes that play the role of cryptographic proofs (e.g. attestation references), distinguishing them from raw content hashes at the type level. See: crates/iris-core/src/hash.rs.
ProtocolVersion: The minProtocolVersion integer enforced by IrisVerifier and gated at epoch boundaries by versioning_strategies.md. Different from currentEpoch() and from the GossipSub vN topic suffix. See: architecture.html §10.
RequestId: Unique identifier for a DataRequest (typically the on-chain log-index hash). See: crates/iris-core/src/types.rs.
ShareSecretKey / SharePublicKey: A single node's BLS private/public key share issued by DKG. Domain aliases for BlsSecretKeyShare / BlsPublicKeyShare. See: architecture.html §3.4.
ThresholdSig: The aggregated t-of-n BLS signature carried in the on-chain panel report. 48 bytes. Domain alias for BlsSignature. See: architecture.html §7.5.
t-of-n threshold: Required quorum for committee signatures: t > ⌊2n/3⌋. The BFT safety boundary. See: architecture.html §3.4, §7.5.

Network Protocols & Identifiers

Protocols & identifiers

/iris/attestation/1.0.0: RequestResponse direct-stream protocol for fetching .att blobs from peers. Max 256 KiB per message; 120 s timeout. See: architecture.html §4.5.2.
/iris/geotiff/1.0.0: RequestResponse direct-stream protocol the Leader Node uses to pull contributor GeoTIFFs. Max 16 GB per payload; 3600 s timeout. Never runs over GossipSub. See: architecture.html §4.5.
CBOR (Concise Binary Object Representation): The on-the-wire encoding for every Iris message that crosses a process boundary on GossipSub or direct streams. Implemented via the ciborium crate (chosen over the unmaintained serde-cbor). See: architecture.html §4.4.
GossipSub v1.1: The libp2p pub/sub mesh. Iris uses three topics (iris/requests/v1, iris/observations/v1, iris/consensus/v1) with mesh parameters D=6, D_low=4, D_high=12, D_lazy=6, heartbeat 1 s, message TTL 600 s. Total per-round mesh traffic: ~50 KB. Never carries GeoTIFFs. See: architecture.html §4.4.
Identify: The libp2p protocol every connection negotiates first; nodes exchange PeerId, software version (iris-node/v1.0.0), and supported sub-protocols. See: architecture.html §4.2.
Kademlia DHT: The libp2p peer-discovery protocol Iris uses for committee peer lookup and bootstrap. See: architecture.html §4.3.
libp2p: The peer-to-peer networking framework the entire iris-network crate is built on. Pinned to an exact version (=0.56.0) because it has frequent breaking changes; bumps are deliberate PRs. See: architecture.html §4; root Cargo.toml.
Noise (XX handshake): The cryptographic transport layer running over TCP for every libp2p connection. Provides forward secrecy and ed25519-anchored peer authentication. See: architecture.html §4.2.
RequestResponse: The libp2p direct-stream protocol pattern Iris uses for the two large-payload protocols (/iris/geotiff/1.0.0, /iris/attestation/1.0.0). Distinct from GossipSub — point-to-point, not mesh. See: architecture.html §4.5.
Yamux: The libp2p stream multiplexer that lets a single Noise-encrypted TCP connection carry multiple logical streams. See: architecture.html §4.2.

TEE Vendors & Attestation

Multi-vendor whitelist

The multi-vendor whitelist (architecture.html §5.5) accepts attestations from any of these vendors, with the explicit goal of bounding the blast radius of any single-vendor compromise. Vendor names appear inside iris-data::attestor::* and the [attestation] section of iris.toml.

AMD SEV-SNP (Secure Encrypted Virtualization — Secure Nested Paging): VM-level confidential computing for EPYC Milan+ servers and bare-metal at OVH/Hetzner. KDS/VLEK attestation API. See: architecture.html §5.5; crates/iris-data/src/attestor/sev_snp.rs.
AWS Nitro Enclaves: Lowest barrier to entry — $0 surcharge on EC2. NSM_GetAttestationDoc attestation API. The default vendor for AWS-hosted operators. See: architecture.html §5.5; crates/iris-data/src/attestor/nitro.rs.
iris-fetch enclave: See Runtime Components.
MockAttestor: Devnet-only attestor that signs synthetic .att documents with a fixture root key. Excluded from the testnet/mainnet whitelists by [2.8.3] config validation regardless of the mock Cargo feature flag. See: crates/iris-data/src/attestor/mock.rs.
Intel SGX (Software Guard Extensions): Process-level confidential computing for Xeon-Scalable (Ice Lake-SP+) servers. DCAP/PCS attestation API. See: architecture.html §5.5; crates/iris-data/src/attestor/sgx.rs.
Intel TDX (Trust Domain Extensions): VM-level confidential computing on newer Xeon platforms. See: crates/iris-data/src/attestor/tdx.rs.
TEE (Trusted Execution Environment): Generic term for hardware-isolated execution: Nitro, SGX, TDX, SEV-SNP. The trust root for the Chain of Provenance since the 2026-05-09 pivot away from TLSNotary. See: architecture.html §5.

Smart Contracts

On-chain surface

The on-chain contract surface (Phase 5). iris-contracts will host the alloy bindings; today it is a stub.

IIrisReceiver: Callback interface a Requester smart contract may implement so IrisVerifier invokes it on panel delivery. Error semantics are still open in architecture_review.md §2.8. See: architecture.html §8.5.
IrisGovernance: Contract approving committee membership changes, governance-tunable parameters (reputation threshold, fee schedule, slash amounts), and contract upgrades. Multisig in MVP. See: architecture.html §8, governance.html.
IrisStaking: Contract holding committee stake and processing slashing. See: architecture.html §8.
IrisVerifier: The on-chain entrypoint for Requesters and Relayers. Owns the aggregate BLS key, the threshold t, the currentEpoch() counter, and the panel acceptance path (deliverReport / reportFailure). See: architecture.html §8.2.

Concepts

Cross-cutting concepts

Cross-cutting terms used in prose across the docs. None of these are types in any single crate; they describe ideas.

Average Scenario / Medoid: The medoid of a set of GeoTIFFs is the existing image whose row-sum of pairwise distances across the similarity matrix is minimal — i.e. the image most similar to all others. The Average Scenario is the protocol's name for the medoid in the context of one round's output. Iris does not synthesize a composite — picking an existing image preserves the unbroken TLS attestation through to the on-chain panel. See: architecture.html §6.4; data_normalization.html.
Chain of Provenance: The unbroken cryptographic chain from Data Provider API → TLS-in-TEE attestation → libp2p Noise + ed25519 transport → BLAKE2b content hash → IPFS CID → BLS threshold signature → on-chain IrisVerifier. Every link is independently auditable; this is the protocol's central design philosophy. See: architecture.html §1.
Geodesic Reconstruction Model: The architectural framing: each DataRequest reconstructs one panel — a single AoI at a single timestamp. The protocol's "Sphere of Flat Panels" analogy. See: architecture.html §2.
Normalization Pipeline: The four-stage math kernel run by the Leader Node in Aggregating: load → orthorectify → compare (MAD/MSE/SAM) → select medoid. Implemented in iris-normalize; spec'd in data_normalization.html. See: architecture.html §6; crates/iris-normalize.
MVP single-active-round: The Layer-2 invariant that a node runs at most one Round at a time during MVP. An implementation simplification (resource isolation during multi-GB transfers), not a protocol requirement — a future upgrade may lift it. Enforced today by a Mutex<Option<RequestId>> in the RoundDispatcher. See: architecture.html §3.2; crates/iris-data/src/dispatcher.rs.
Nadir / Nadir Angle: The Nadir is the point on Earth's surface directly below a satellite — the foot of the local vertical from the sensor. The Nadir Angle (a.k.a. off-nadir angle or view angle) is the angle between that vertical and the sensor's line-of-sight to a given pixel: 0° means looking straight down, larger values mean a more oblique view. Off-nadir views accumulate more terrain-induced parallax, which the orthorectifier must correct, so the bound Iris places on it is a load-bearing protocol parameter. At MVP the bound is expressed not as a raw-angle cap but as a per-sensor mis-registration stress cap — see Effective Nadir Angle for the phase-by-phase shape. See: architecture.html §2.3, §6.1; Effective Nadir Angle; Orthorectification.
Effective Nadir Angle: The Effective Nadir Angle (a.k.a. Usable Nadir Angle) is Iris's protocol-internal upper bound on the Nadir Angle it will accept for a manifest — computed per-AoI and per-sensor by the protocol, not read off vendor metadata. At demo the cap is a single scalar (the composite stress score 𝒮 = α·σ_px/m + β·sec(θ_g) with Foundation-set α, β); at MVP+ it is a per-sensor σ_px/m cap with a sigma_max_default fallback. The phase-by-phase decision ladder is in design_q1_effective_nadir_angle.md. Manifests whose computed stress exceeds the cap are dropped before scoring. See: architecture.html §2.3, §6.1; SensorMeta; Sensor Registry.
Mis-registration Stress (σ_px/m): The protocol's canonical measure of orthorectification difficulty, in pixels per meter of relief: σ_px/m ≈ sin(θ_g)·cos(θ_g)·f / (h_s·p), where θ_g is the Earth-curvature-corrected ground-incidence angle, f is the sensor's focal length, h_s its orbit altitude, p its pixel pitch. Computed per contributor in Tier-1 verification using the contributor's declared sensor_id and the corresponding SensorMeta from the on-chain registry. Adopted as the envelope-stress proxy from MVP onward rather than raw off-nadir angle, since raw θ is not comparable across heterogeneous sensors (a 30° view from 1000 km altitude differs from a 30° view at 500 km even before optics enter). See: design_q1_effective_nadir_angle.md §1.3.1.b; data_normalization.html § Effective Nadir Angle.
SensorMeta: Per-sensor metadata stored on-chain in the Sensor Registry, keyed by uint32 sensor_id. Carries the inputs the σ_px/m formula needs: (focal_length, orbit_altitude, pixel_pitch, detector_class, display_name). detector_class is one of Pushbroom | Whiskbroom | Frame, selecting which of the 2–3 MVP geometry formulas the Tier-1 verifier applies (design_q1 §1.3.3.b). iris-fetch parses sensor_id inside the enclave from GeoTIFF/NITF metadata and binds it into the BLAKE2b user_data commitment per architecture.html §5.2 / §5.4. See: design_q1_effective_nadir_angle.md §1.2.2.d; implementation_mvp.md [5.12].
Sensor Registry: The on-chain mapping(uint32 sensorId => SensorMeta) maintained by IrisGovernance. Single source of truth for which satellites are admissible into a round and what per-sensor envelope thresholds apply. Mutating entries (enrollSensor, updateSigmaMaxOverride) is gated by a 7-day soft-governance timelock per design_q1 §1.1.2.c; the shape (struct layout, key type) is fixed at deploy and changing it requires a MIN_PROTOCOL_VERSION hard fork. Tier-1 verifiers ([3.9.7]) fetch the full registry at round start and consume it locally without per-contributor on-chain calls. See: implementation_mvp.md [5.12]; SensorMeta.
On-the-wire: Idiom for "in serialized byte form, on a network link between two machines". Iris's on-the-wire encoding is CBOR via ciborium. Distinct from wiring. See: architecture.html §4.4.
Georeferencing: Attaching a coordinate reference frame to a raster — fitting a transform so pixel (col, row) resolves to world (lon, lat). In Iris this is the 2×3 affine GeoTransform in iris-normalize, populated from a GeoTIFF's ModelTiepointTag + ModelPixelScaleTag (or ModelTransformationTag) by read_geo_transform. Carried on every RawImage as transform: Option<GeoTransform> and consumed downstream by Orthorectification. Distinct from Geocoding, which is unrelated to imagery. See: crates/iris-normalize/src/image.rs (GeoTransform, RawImage, read_geo_transform); data_normalization.html §1.
Geocoding: The address-↔-coordinate translation problem in GIS — e.g. "1600 Pennsylvania Ave" → (38.8977, -77.0365), or the reverse. Not part of the Iris protocol. DataRequests arrive on-chain already specifying their AoI as a BoundingBox (min/max lat-lon); resolving place names into coordinates is the Requester dapp's responsibility before submission. Sometimes used in the SAR/InSAR community as a loose synonym for projecting raw sensor pixels into a map frame — that role in Iris is filled by Orthorectification, not by anything called "geocoding". See: architecture.html §1.2 (Requester); Georeferencing; Orthorectification.
Orthorectification: Resampling raw raster pixels onto a shared reference grid defined by an AoI bounding box and pixel resolution. Consumes the per-image Georeferencing transform and (from MVP onward) a height function ĥ(x, y) supplied by IrisDEM. Iris uses a flat-earth bilinear approximation at Demo (sufficient for nadir-pointed imagery); MVP/V1 swap in DEM-aware 3D reprojection over IrisDEM. See: architecture.html §6.1; data_normalization.html.
IrisDEM: The IrisDEM is the Iris Foundation's canonical reference Digital Elevation Model — the height function ĥ(x, y) fed to the orthorectifier 𝒯 in Phase 3. Pinned per protocol version, not chosen by operators, because all nodes in a committee must produce byte-identical Ā. Rolled out in tiers: IrisDEM-D0 (constant per AoI, paired with the flat-earth bilinear ortho and the demo's single-scalar 10°-equivalent envelope cap); IrisDEM-M1 (a frozen Copernicus DEM GLO-30 snapshot with DEM-aware 3D reprojection, MVP — paired with the MVP per-sensor σ_px/m table); IrisDEM-V1 (Copernicus GLO-30 with NASADEM void-fill on a per-tile primary/fallback basis, paired with V1's harness-calibrated per-sensor table); IrisDEM-V1+ (commercial radar/LiDAR augmentation — TanDEM-X, WorldDEM Neo, Maxar Precision3D, regional LiDAR, ICESat-2/GEDI calibration — post-v1.0). Distributed as a Foundation-hosted, content-addressed tile-set with a BLAKE3 manifest pinned in iris.toml; DEM fetches go through the same TLS-in-TEE attestation envelope as satellite GeoTIFFs. See: data_normalization.html §IrisDEM; architecture.html §6.1; Effective Nadir Angle.
Processing Level: How far a satellite product has been carried along the standard processing ladder: L0 raw downlink → L1A calibration coefficients computed and appended but not applied → L1B calibration applied, giving physical sensor units (radiance) → L2 derived geophysical variables at the same resolution and location as the L1 source (for optical land imaging, surface reflectance) → L3 variables resampled onto a uniform space-time grid (composites) → L4 model output. The ladder originates with NASA's EOSDIS data processing levels and is adopted broadly by ESA, USGS and CEOS; it describes a stage of processing, not a product. In Iris it is iris_core::types::ProcessingLevel (#[repr(u8)]), the middle element of the (mission, processing_level, radiometric_units) tuple the §6.1.1 dispatch table accepts, and it is bound into the attestation's user_data so an enclave attesting L1C cannot be wrapped in a Manifest claiming L2A. The variant names (L1C, L2A, L1Grd, L1Slc) are borrowed from ESA's Sentinel product names and are Iris's normalized vocabulary — not a claim that every provider labels its products this way. See: crates/iris-core/src/types.rs; parameters.html §14.2.8; data_normalization.html §Vendor Preprocessing Chains; Vendor Level-Name Collision.
Level-1 / Level-2 (L1 / L2): In optical land-imaging prose — including the docs/research/ surveys — bare L1 and L2 are shorthand for the two stages that actually matter to a comparison: L1 is top-of-atmosphere, radiometrically calibrated and geometrically corrected (orthorectified); L2 is surface reflectance, i.e. L1 with an atmospheric-correction model applied. The distinction is load-bearing because L2 is a model output, not a measurement — the same L1 scene through sen2cor, MAJA or LaSRC yields different numbers, so two contributors submitting different levels (or the same level from different processors) produce measurably divergent tensors for one physical scene. This is shorthand, not a product name: when citing a specific figure, use the mission's own name (Sentinel-2 L1C/L2A, Landsat L1TP/L2SP). See: image_comparison.html §3; data_normalization.html; Processing Level; TOA / BOA.
TOA / BOA: Top-of-atmosphere vs. bottom-of-atmosphere reflectance — the radiometric element of the accepted-tuple triple, iris_core::types::RadiometricUnits::{Toa, Boa}. TOA is what the sensor records including the atmospheric path; BOA is TOA with an atmospheric-correction model applied, i.e. surface reflectance. Both are dimensionless in [0, 1]. This field carries the physics that the Processing Level alone does not, and it is what keeps the (mission, processing_level, radiometric_units) triple unambiguous across vendors whose level names collide — a Sentinel-2 product ESA calls L2A and a Maxar product Maxar calls 2A land on (Sentinel2Msi, L2A, Boa) and (WorldView3, L1C, Toa) respectively, and stay distinguishable because level and units are declared separately. See: crates/iris-core/src/types.rs; parameters.html §14.2.8; Vendor Level-Name Collision.
Vendor Level-Name Collision: The fact that letter-suffixed product names are per-mission and do not carry the same meaning across providers, so a bare level string is not a provider-agnostic instruction. Sentinel-2 L2A is BOA surface reflectance from sen2cor. Maxar's Standard (2A) and Ortho Ready Standard (OR2A) are geometric and radiometric levels — map-projected to a plane at average or constant elevation with RPCs supplied for the consumer's own terrain correction, and calibrated to TOA reflectance via absCalFactor. They are not atmospherically corrected, so despite the shared "2A" spelling they must not map onto ProcessingLevel::L2A; the matrix maps Maxar Standard onto (WorldView3, L1C, Toa). Planet's PSScene 3B means orthorectified, not NASA Level-3 gridded composite; its surface-reflectance asset is ortho_analytic_*_sr, which is what carries it to (PlanetScope, L2A, Boa). Why it matters in Iris: ProcessingLevel is bound into attestation user_data and cohort homogeneity assumes one level per round, so a vendor product mapped onto the wrong variant would look homogeneous to the verifier while carrying different physics — inflating μ₁/μ₂/μ₃ against a boundary nobody declared. RadiometricUnits is the disambiguator; the per-vendor mapping is the accepted-tuple matrix's job. See: parameters.html §14.2.8; data_normalization.html §Other missions; image_comparison.html §3.
Provenance Pipeline: See Chain of Provenance.
Similarity Score: The exponential-decay score S(μ) = 100·exp(−(β₁·μ_MAD + β₂·μ_MSE + β₃·μ_SAM)) that combines the three pairwise similarity metrics (MAD, MSE, SAM) into a single number used to build the matrix. See: architecture.html §6.3; data_normalization.html.
Two-phase Observing window: The split of the Observing state into Phase 1 (≤60 s, TlsCommitment) and Phase 2 (≤300 s from round start, Manifest). Lets the Leader fail rounds early, before the expensive Aggregating phase, when fewer than t nodes commit. See: architecture.html §3.1, §7.2.
View-change: The Phase-4 recovery procedure when the Leader fails to broadcast a Proposal within proposal_deadline_seconds. The k=3 view-change re-runs leader election with a deterministic offset, capped at three attempts before the round terminates with LeaderTimeout. See: architecture.html §7.1, §8.8.
Wiring: Internal-process metaphor for connecting components together at startup: instantiating concrete types and passing handles/channels between them. When iris-node "wires" the RoundDispatcher to the SwarmHandle, both objects live inside one OS process — no network involved. Distinct from on-the-wire, which is between machines.

Product Phases

The four releases

The four product-release phases that the protocol ships under. Used as inline tags ([Demo v0.0.1], [MVP v0.1.0], [V1 v1.0.0], [V1+ post-v1]) throughout the concept docs to indicate design choices and constraints that vary by release. The canonical per-release ship-list lives in next_steps.md §Phase Roadmap. Distinct from the implementation Phase 0–5 in implementation_demo.html (Phases 0 → 4.5) and implementation_mvp.md (Phase 5) — internal engineering milestones leading up to a release cut — and from component-internal "Phase Roadmaps" in architecture.html §5.5 / §8.7 (whose Phase N labels are local to that component and mapped to product releases inline).

Demo v0.0.1: Local devnet. Single-machine multi-node loopback. No real TEE hardware (MockAttestor only). IrisDEM-D0 constant-plane. Flat-earth bilinear ortho. Single scalar envelope bar at 10°-equivalent, expressed as the composite stress score 𝒮 = α·σ_px/m + β·sec(θ_g) with Foundation-set (α, β) (no on-chain vote). Sentinel-only data provider. No on-chain. Single-active-round invariant. See: next_steps.md §Phase Roadmap.
MVP v0.1.0: Sepolia testnet. Multi-machine committee. Real TEE attestation on at least one vendor (Nitro + SGX/SEV-SNP). IrisDEM-M1 (Copernicus GLO-30, version-pinned). DEM-aware 3D reprojection. Per-sensor σ_px/m table + 15°-equivalent sigma_max_default fallback (β = 0, BRDF stress deferred to V1+ similarity kernel). Per-detector-class formulas (Pushbroom / Whiskbroom / Frame). Explicit sensor_id in attestation user_data via in-enclave parser. Sentinel + Maxar + Planet. On-chain DataRequest → Manifest. Threshold slashing only. Foundation Relayer. Single-active-round invariant carried forward. See: next_steps.md §Phase Roadmap; design_q1_effective_nadir_angle.md.
V1 v1.0.0: Mainnet production cut. Full nominal pipeline. IrisDEM-V1 (Copernicus + NASADEM void-fill). Same envelope shape as MVP (per-sensor σ_px/m table) but calibrated under AND-combined success metric (pixel-budget + medoid-flip-rate) and provider-supplied RPCs inside attestation user_data. Multi-active rounds (single-active-round lifted). Full slashing — threshold + submitFraudProof (BadMedoid + LeaderEquivocation + InvalidAttestation + WrongSensorClaimed). DKG + epoch rotation with BLS resharing. Cross-vendor quorum requirement. Reputation-gated Relayer Phase 2. Governance live. See: next_steps.md §Phase Roadmap.
V1+ post-v1: Post-v1.0 augmentation tier. Quality and coverage improvements that do not change the protocol shape. Candidates: IrisDEM-V1+ commercial radar/LiDAR (TanDEM-X, WorldDEM Neo, Maxar Precision3D, regional LiDAR, ICESat-2/GEDI calibration); BRDF-aware similarity metrics (may reactivate the β·sec(θ_g) composite term retired at MVP); multi-chain expansion; threshold attestation; Relayer Phase 3 (fully permissionless). See: next_steps.md §Phase Roadmap; data_normalization.html §IrisDEM-V1+.

iris