Iris by Hubble Labs

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.html on the docs site.

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.

A round, end to end: Requester through the on-chain IrisVerifierA sequence diagram across five lanes -- Requester, Relayer, Regular Nodes, Leader Node, and the on-chain IrisVerifier -- through six phases: Idle, Observing, Aggregating, PreCommit, Voting, and Commit. The Requester posts a DataRequest; the Relayer publishes it and committee members independently fetch imagery from a Data Provider inside their TEE; nodes gossip manifests while the Leader Node pulls full payloads over direct libp2p streams; the Leader Node runs the normalization pipeline and selects the medoid; committee members verify that selection and sign a BLS share over the finalized panel; the Leader Node aggregates shares into a single threshold signature; and a Relayer delivers the signed report to IrisVerifier, which verifies it against the committee's aggregate BLS key.CommitteeIrisVerifierLeader NodeRegular NodesRelayerRequesterIrisVerifierLeader NodeRegular NodesRelayerRequesterIdleObservingAggregatingPreCommitVotingCommitDataRequest(Area of Interest, timestamp)Publish DataRequest on iris/requests/v1Fetch imagery from a Data Providerinside their TEEGossip manifest on iris/observations/v1Pull payloads over direct libp2p streamsRun normalization pipeline,select the medoidProposed medoid for the finalized panelBLS signature shareAggregate shares into a singlet-of-n threshold signature (t > ⌊2n/3⌋)Finalized panel + aggregate signaturedeliverReport(panel, signature)Verify against the committee'saggregate BLS key A round, end to end: Requester through the on-chain IrisVerifierA sequence diagram across five lanes -- Requester, Relayer, Regular Nodes, Leader Node, and the on-chain IrisVerifier -- through six phases: Idle, Observing, Aggregating, PreCommit, Voting, and Commit. The Requester posts a DataRequest; the Relayer publishes it and committee members independently fetch imagery from a Data Provider inside their TEE; nodes gossip manifests while the Leader Node pulls full payloads over direct libp2p streams; the Leader Node runs the normalization pipeline and selects the medoid; committee members verify that selection and sign a BLS share over the finalized panel; the Leader Node aggregates shares into a single threshold signature; and a Relayer delivers the signed report to IrisVerifier, which verifies it against the committee's aggregate BLS key.CommitteeIrisVerifierLeader NodeRegular NodesRelayerRequesterIrisVerifierLeader NodeRegular NodesRelayerRequesterIdleObservingAggregatingPreCommitVotingCommitDataRequest(Area of Interest, timestamp)Publish DataRequest on iris/requests/v1Fetch imagery from a Data Providerinside their TEEGossip manifest on iris/observations/v1Pull payloads over direct libp2p streamsRun normalization pipeline,select the medoidProposed medoid for the finalized panelBLS signature shareAggregate shares into a singlet-of-n threshold signature (t > ⌊2n/3⌋)Finalized panel + aggregate signaturedeliverReport(panel, signature)Verify against the committee'saggregate BLS key
Five lanes, six phases — a DataRequest becomes a sealed panel on IrisVerifier.
Text description of this diagram

The diagram reads left to right across five lanes: Requester, Relayer, the committee of Regular Nodes, the round's Leader Node, and the on-chain IrisVerifier contract, with each of the six phases marked as a band spanning all five lanes. In Idle, the Requester hands a DataRequest — an Area of Interest and a timestamp — to the Relayer. Observing begins when the Relayer publishes that request on iris/requests/v1; each Regular Node independently fetches imagery from a Data Provider inside its own TEE. In Aggregating, nodes gossip a manifest of their result on iris/observations/v1, and the Leader Node pulls the full payloads directly over point-to-point libp2p streams. PreCommit shows the Leader Node running the normalization pipeline and selecting the medoid. In Voting, the Leader Node proposes that medoid back to the committee, and each Regular Node returns a BLS signature share once it verifies the selection. Commit closes the loop: the Leader Node aggregates the shares into a single threshold signature, then hands the finalized panel and signature to the Relayer, who calls IrisVerifier.deliverReport — the diagram's last arrow, landing in the IrisVerifier lane, where the contract checks the signature against the committee's aggregate BLS key.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

Medoid selection: one of five submitted images, never the centroidFive images submitted by the round's committee -- Image 1 through Image 5 -- each point toward a centroid, a calculated reference point that is never itself selected, downloaded, or produced. Image 3 is highlighted in Panel orange and labeled directly as the medoid: one of the five original submitted images, chosen because it sits closest overall to the rest of the group. The centroid represents only the idea of 'the rest of the group' for comparison -- it is not a file, not a blend, and never the output.

Image 1

Image 2

Image 3
Selected as the medoid

Image 4

Image 5

Centroid
not selected — reference point only

 Medoid selection: one of five submitted images, never the centroidFive images submitted by the round's committee -- Image 1 through Image 5 -- each point toward a centroid, a calculated reference point that is never itself selected, downloaded, or produced. Image 3 is highlighted in Panel orange and labeled directly as the medoid: one of the five original submitted images, chosen because it sits closest overall to the rest of the group. The centroid represents only the idea of 'the rest of the group' for comparison -- it is not a file, not a blend, and never the output.

Image 1

Image 2

Image 3
Selected as the medoid

Image 4

Image 5

Centroid
not selected — reference point only
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.

Chain of provenance, from satellite provider to the on-chain VerifierEight nodes joined by seven links, rendered left to right: Data Provider API, TEE Remote Attestation, TLS session inside the enclave, libp2p Noise with ed25519 PeerId, BLAKE2b content hash, IPFS pin, BLS threshold signature, and the on-chain Verifier contract. Each arrow is a cryptographically auditable link; together they trace an unbroken chain from the original satellite provider to the sealed on-chain output.

Data Provider API

TEE Remote
Attestation

TLS session
inside the enclave

libp2p Noise +
ed25519 PeerId

BLAKE2b
content hash

IPFS pin

BLS threshold
signature

on-chain Verifier contract
IrisVerifier

 Chain of provenance, from satellite provider to the on-chain VerifierEight nodes joined by seven links, rendered left to right: Data Provider API, TEE Remote Attestation, TLS session inside the enclave, libp2p Noise with ed25519 PeerId, BLAKE2b content hash, IPFS pin, BLS threshold signature, and the on-chain Verifier contract. Each arrow is a cryptographically auditable link; together they trace an unbroken chain from the original satellite provider to the sealed on-chain output.

Data Provider API

TEE Remote
Attestation

TLS session
inside the enclave

libp2p Noise +
ed25519 PeerId

BLAKE2b
content hash

IPFS pin

BLS threshold
signature

on-chain Verifier contract
IrisVerifier
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.html §2 or on this site — it means exactly this: one Iris result.

Read the full spec See the use cases