How It Works

What happens between a smart contract and a sealed image.

This page walks through everything that happens between a smart contract posting a DataRequest and a sealed image arriving on-chain — the five actors involved, how a round reaches consensus, and the chain of provenance that makes the result auditable. It's intentionally non-exhaustive: it explains the shape of the protocol, not every parameter and edge case. For the complete specification, read architecture.md in the protocol repo.

How It Works — Step 01 of 05

The five actors

Every request that reaches Iris moves through five roles, each accountable in a different way.

Requester

A smart contract or dApp on the host chain. It posts a DataRequest naming an Area of Interest polygon and a timestamp, and pays for the round in the host chain's native token plus a small protocol fee. It has no say in which committee is assigned — assignment happens independently of who's asking. Its only leverage over the outcome is the request it wrote and the panel it eventually gets back through IrisVerifier.

Regular Node

A staked committee member assigned to a round. It fetches imagery from a Data Provider from inside a TEE, produces a remote attestation proving what code ran, and contributes a BLS signature share once it agrees with the round's result. It has no visibility into other nodes' fetches while the round is in progress. Equivocating — signing two conflicting outcomes — or submitting an invalid attestation is slashable.

Leader Node

A Regular Node elected to lead a single round. It aggregates the committee's manifests, runs the normalization pipeline, selects the medoid, and aggregates the committee's signature shares into the round's threshold signature. Leadership rotates and earns no extra fee, so there's no incentive to hold onto the role. It cannot censor by stalling — an on-chain timeout triggers re-election if it goes quiet.

Data Provider

An external commercial imagery service — Maxar, Planet, Sentinel, and others. A Data Provider is not a network participant and runs no Iris software; it serves imagery over TLS the same way it would to any other client. Iris does not trust the pixel content of what comes back. It trusts the TLS-attested fact that a specific enclave received a specific response from a specific provider at a specific time.

Relayer

An opt-in role bridging the host chain to the Iris network. A Relayer watches for on-chain requests, publishes them as DataRequest events on GossipSub, and submits the committee's finalized panel to IrisVerifier.deliverReport once consensus completes. It cannot forge a result — the signature has to verify against the committee's aggregate key regardless of who delivers it. It can only delay delivery, bounded by an on-chain timeout fallback.

Two more names round out the picture, though neither gets its own card. An Attestor is the TEE vendor PKI — AWS, Intel, AMD — whose signature backs every remote attestation a Regular Node produces. The Iris Foundation is the Phase-1 governance steward for the on-chain attestation whitelist; it doesn't participate in any individual round.

How It Works — Step 02 of 05

A round, end to end

A round moves through six phases — from a DataRequest hitting the network to a sealed panel landing on-chain.

01

Observing

A Relayer publishes the round's DataRequest on the iris/requests/v1 topic. Every committee member picks it up independently and fetches imagery for the requested Area of Interest from a Data Provider, each from inside its own TEE — no coordination between nodes yet.
02

Aggregating

Each Regular Node gossips a manifest describing its result — not the payload itself — on iris/observations/v1. The Leader Node collects these manifests, then pulls the actual GeoTIFF payloads from contributing nodes directly, over point-to-point libp2p streams rather than the shared gossip channel.
03

PreCommit

With every contributed image in hand, the Leader Node runs the normalization pipeline — orthorectification and per-band correction — across the full set, then selects the medoid: the one submitted image most representative of the group.
04

Voting

Committee members independently verify the Leader Node's medoid selection against their own copies of the submitted set. Once satisfied, each signs a BLS signature share over the finalized panel — its vote that the round's output is correct.
05

Commit

The Leader Node aggregates the committee's signature shares into a single threshold signature, valid once enough of the committee has signed — t > ⌊2n/3⌋ of it, specifically. No individual signature appears on-chain, only the aggregate.
06

Delivery

A Relayer calls IrisVerifier.deliverReport with the finalized panel and its threshold signature. The contract checks the signature against the committee's known aggregate BLS key and, if it verifies, records the panel on-chain for the Requester's contract to read.

How It Works — Step 03 of 05

The average scenario

Every round produces exactly one medoid — never a blend of the group.

A medoid is the existing point in a set that minimizes the sum of distances to every other point in that set — not a new point constructed from the set, an existing member of it. Iris applies the same idea to a round's submissions: the Leader Node takes every image the committee fetched for a given Area of Interest and timestamp, and picks the one that sits closest, collectively, to all the others.

"Closest" is measured concretely, not aesthetically. After orthorectification and per-band normalization bring every submission into a comparable pixel space, the Leader Node scores each candidate against the rest using standard image-distance metrics — mean absolute difference, mean squared error, and spectral angle mapper — and the image with the lowest total distance to the group wins. There's no machine learning model in this step and no embedding space: the metric is concrete, and it's auditable by anyone willing to rerun it.

The medoid is one of the five submitted images — highlighted here, never the centroid and never a blend of the group.

Text description of this diagram

Five images arrive at this stage of the round, each one a real file a Regular Node fetched from a Data Provider. Every image points toward a centroid — drawn with a dashed border to mark it as a calculation rather than a file, standing in for "the rest of the group" the way the pairwise MAD, MSE, and SAM comparisons described above actually work. The centroid itself is never downloaded, never signed, and never appears in the output; it exists only so each image's overall closeness to the group can be visualized. One image — labeled directly as the medoid and highlighted in Panel orange — sits closest overall. It is not a sixth, newly created image and not the centroid: it is one of the five original submissions, unchanged, selected because it best represents what the committee saw.

Iris never produces a composite image.

The medoid a round selects is one specific GeoTIFF submitted by one specific Regular Node — a real, downloadable file, byte-for-byte what that node fetched from a Data Provider. Iris does not blend, stitch, merge, average, or synthesize a new image from the group. "Average" names the selection criterion here — the submission closest to consensus — never an operation performed on pixels. The chosen file carries the same unbroken TEE-attested TLS provenance back to the Data Provider that any single submission would.

How It Works — Step 04 of 05

Chain of provenance, expanded

Seven links carry a panel's provenance from a satellite provider's TLS handshake to the value your contract reads on-chain.

Every link is auditable. The on-chain output carries a cryptographic chain back to the TLS handshake with the satellite provider.

Text description of this diagram

Provenance for a panel starts at a Data Provider's API and ends at the on-chain Verifier contract, in seven verifiable steps. A Regular Node requests imagery from a Data Provider over a TLS session that runs entirely inside a hardware-attested TEE — the TEE Remote Attestation step proves what code is running, and the TLS-in-enclave step proves the response wasn't tampered with in transit. Once the node has the image, it speaks to the rest of the committee over libp2p connections authenticated by its staked ed25519 identity. The eventual medoid gets a BLAKE2b hash computed over its bytes, which becomes both its content address on IPFS and the value the committee signs. The committee's threshold signature attests to that hash, and a Relayer delivers the signature and the panel to the on-chain Verifier contract, which checks the signature against the committee's aggregate key before recording the result. Follow the chain backward from any on-chain panel and it terminates at one specific TLS handshake with one specific Data Provider.

TEE Remote Attestation

Hardware-rooted proof that the code running inside a Regular Node's enclave is the exact code it claims to be, signed by an Attestor — AWS, Intel, or AMD. Anyone can check the attestation without taking the node operator's word for it.

TLS session inside the enclave

The Data Provider speaks ordinary TLS to the enclave, the same way it would to any client. The session keys are generated and used entirely inside the enclave and never leave it, so nothing outside the TEE — including the node operator — can see or tamper with the exchange.

libp2p Noise + ed25519 PeerId

Every node-to-node message on the network is authenticated by the sending node's staked key, over a Noise-encrypted libp2p connection. A message's origin is tied to a specific staked identity, not just a claimed one.

BLAKE2b content hash

The payload's identifier on the wire and in storage: a BLAKE2b hash of the GeoTIFF bytes. Anyone holding the hash can verify a downloaded file is the exact bytes the committee agreed on, byte for byte.

IPFS pin

The medoid GeoTIFF is pinned to IPFS for durable retrieval, addressed by its content hash. The on-chain record points at content, not at a location — the file doesn't move even if the host serving it does.

BLS threshold signature

The committee's aggregate signature attests, on-chain, to the selected medoid and its content hash. It's a single compact threshold signature, but it only validates if enough of the committee actually signed.

On-chain Verifier contract

IrisVerifier checks the threshold signature against the committee's known aggregate key and, once it verifies, records the panel on-chain — the last link, and the one a Requester's contract actually reads.

How It Works — Step 05 of 05

What we mean by "panel"

Every request Iris fulfills reconstructs one panel — a single Area of Interest at a single timestamp, sealed with its medoid and chain of provenance. If you see "panel" used elsewhere — in architecture.md §2 or on this site — it means exactly this: one Iris result.

Read the full spec See the use cases