> For the complete documentation index, see [llms.txt](https://docs.ethernity.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ethernity.cloud/developer-guide/the-ec-protocol.md).

# The EC Protocol

The Ethernity Cloud (EC) Protocol lets a Web3 dApp run confidential computation on untrusted, decentralized nodes while keeping user data private and producing a verifiable **Proof of eXecution** on-chain. Client code runs inside a hardware **Trusted Execution Environment (TEE)** -- concretely **Intel SGX**, hardened by the **SCONE** runtime -- so neither the node operator nor anyone else can read the data or tamper with the computation.

### Actors and components

```mermaid
graph TD
    Dev["Web3 dApp Developer"] -->|writes backend + frontend| DApp["dApp"]
    User["Web3 dApp User"] -->|submits task| DApp
    DApp -->|addDORequest / read result| SC["EC Smart Contract (PoX)"]
    DApp -->|upload encrypted challenge/payload/input| IPFS["Decentralized Storage (IPFS)"]

    SC <-->|match order, advertise resources, submit proof| Node["EC Node"]
    Node -->|download image + encrypted data| IPFS
    Node -->|resolve enclave cert + MRENCLAVE by name,'v3'| IR["On-chain Image Registry"]

    subgraph TEE["EC Node -- SGX enclaves (SCONE)"]
        TZ["trustedzone (gatekeeper)"]
        SL["securelock (executor)"]
        VAL["validator (attester)"]
    end
    Node --> TEE
    TZ <-->|payload / input / result / transaction objects| SS["SwiftStream (MinIO object store)"]
    SL <-->|payload / input / result objects| SS

    TZ -.->|mainnet: attest| CAS["CAS (Config & Attestation Service)"]
    SL -.->|mainnet: attest| CAS
    TZ -.->|testnet: self-sign from MR_ENCLAVE| Self["[TESTNET-INSECURE] self-signed cert"]
```

1. **Web3 dApp Developer** -- builds the dApp with the Ethernity Cloud SDK, packaging the backend into an attestable enclave image, adding encryption and decentralized storage.
2. **Web3 dApp User** -- uses the dApp; their sensitive data stays encrypted end-to-end.
3. **EC Smart Contract (Proof of eXecution)** -- handles task-request submission and approval, matches task requirements to suitable EC Nodes, lets nodes advertise resource availability, and receives Proof of eXecution submissions.
4. **Decentralized Storage (IPFS)** -- where the dApp uploads encrypted input, payload, and metadata; the node downloads it, and uploads the encrypted result.
5. **EC Node** -- advertises resources on-chain, matches and downloads tasks, and orchestrates the SGX enclaves that do the confidential work.
6. **On-chain Image Registry** -- stores each enclave image's certificate (public key) and its `MRENCLAVE` measurement, keyed by image name and protocol version `v3`. This is how the network verifies a node is running the exact, untampered code, and how one enclave obtains another's public key.
7. **CAS (Configuration and Attestation Service)** -- on **mainnet**, registers the enclaves and provisions their certificate after a real SGX **DCAP** attestation, guaranteeing consistent Proof of eXecution signatures. On **testnet**, CAS is not used (see below).

### The v3 enclaves and their roles

A task is processed by cooperating SGX enclaves that **communicate only through a shared object store (SwiftStream / MinIO)** -- they never call each other directly, and each only decrypts what was encrypted for its own key.

#### trustedzone -- the gatekeeper

Decrypts the client challenge with its enclave key, derives a per-task wallet, and reads the order metadata from the PoX smart contract. It **validates the client's payload and input checksums** against the data owner's signature, then **re-encrypts the payload and input with securelock's public key** (fetched from the on-chain Image Registry) and hands them to securelock via SwiftStream. After securelock finishes, trustedzone reads the result, **builds and signs the `_addResultToOrder` transaction** -- the Proof of eXecution -- and writes it out for the node to submit. trustedzone is the only enclave that holds the task wallet and the only one that produces the on-chain result. Its identity/certificate come from CAS on mainnet, or are self-signed from `MR_ENCLAVE` on testnet.

#### securelock -- the executor

Waits for the payload and input objects that trustedzone placed in SwiftStream, **decrypts them with its own enclave key**, and **runs the client's code** (the payload) inside the SGX enclave. It produces an encrypted result plus a status code and writes them back through SwiftStream for trustedzone. securelock is where untrusted client code actually executes, fully isolated in the TEE; it never talks to the blockchain directly. Its public key -- registered on-chain -- is what trustedzone encrypts for.

#### validator -- the attester

Verifies a node's enclaves. Its `MRENCLAVE` is pinned into the trustedzone attestation session so the chain can attest the validator's identity. It is present on networks that deploy a ValidatorSlasher contract.

> **Security boundary.** The client payload runs **only** in securelock. trustedzone never executes client code -- it validates, brokers keys, and signs -- so a malicious payload cannot forge a Proof of eXecution or reach the on-chain wallet. Because the enclaves exchange data only through SwiftStream, and each decrypts only what was encrypted for its own on-chain-registered key, compromise of the untrusted host cannot read task data or tamper with results.

### Attestation: mainnet vs testnet

Attestation -- proving an enclave is genuine, unmodified SGX code -- works differently per network type:

* **Mainnet** -- enclaves are signed for production and attested through **CAS** using a real SGX **DCAP** quote. CAS provisions the enclave's server certificate only after verifying the quote. This is the secure path.
* **Testnet** -- enclaves run in a **non-CAS** mode and **self-sign** their certificate deterministically from their own `MR_ENCLAVE` (`[TESTNET-INSECURE]`). This removes the CAS dependency for development, but is **not** a production security guarantee.

### Trusted Execution Environment

The TEE is the secure execution environment where encrypted user tasks are processed and encrypted results are returned. Ethernity Cloud uses **Intel SGX** (via the SCONE runtime); confidential-computing technologies of this class also include AMD SEV and ARM TrustZone.