> 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/how-it-works.md).

# How it works

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** — 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. This page is the concept map: enough to make the hands-on chapters make sense, no node internals.

### 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"]
```

* **Web3 dApp Developer** — builds the dApp with the SDK, packaging the backend into an attestable enclave image.
* **Web3 dApp User** — uses the dApp; their sensitive data stays encrypted end-to-end.
* **EC Smart Contract (Proof of eXecution)** — takes task requests, matches them to nodes, and receives the on-chain proof.
* **IPFS** — carries the encrypted payload, input, and result; nothing readable ever touches it.
* **EC Node** — advertises resources, downloads tasks, and orchestrates the SGX enclaves that do the confidential work.
* **On-chain Image Registry** — stores each enclave image's certificate and `MRENCLAVE` measurement, keyed by image name and protocol version `v3`. This is how the network verifies a node runs your exact, untampered code — and how one enclave obtains another's public key.
* **CAS** — on **mainnet**, provisions enclave certificates only after a real SGX **DCAP** attestation. Not used on testnet (see below).

### The v3 enclaves

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

* **trustedzone — the gatekeeper.** Decrypts the client challenge, derives a per-task wallet, validates the payload/input checksums against the data owner's signature, re-encrypts them for securelock's on-chain-registered key, and — after execution — signs the `_addResultToOrder` transaction: the **Proof of eXecution**. It is the only enclave that holds the task wallet and the only one that writes on-chain.
* **securelock — the executor.** Decrypts the payload and input with its own key and **runs your code** inside SGX, producing an encrypted result plus a status code. It never talks to the blockchain.
* **validator — the attester.** Verifies a node's enclaves; its `MRENCLAVE` is pinned into the trustedzone attestation session.

> **Security boundary.** Client code 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 enclaves exchange data only through SwiftStream, and each decrypts only what was encrypted for its own registered key, a compromised host cannot read task data or tamper with results.

### Attestation: mainnet vs testnet

* **Mainnet** — enclaves are production-signed and attested through **CAS** with a real SGX **DCAP** quote; certificates are provisioned only after the quote verifies. This is the secure path.
* **Testnet** — enclaves **self-sign** their certificate deterministically from their own `MR_ENCLAVE` (`[TESTNET-INSECURE]`). No CAS dependency for development — but not a production security guarantee.

### The life of a task

```mermaid
sequenceDiagram
    autonumber
    actor User as dApp User
    participant IPFS as IPFS
    participant SC as EC Smart Contract
    participant Node as EC Node
    participant TZ as trustedzone
    participant SS as SwiftStream
    participant SL as securelock

    User->>IPFS: upload encrypted challenge, payload, input
    User->>SC: addDORequest(imageMetadata, codeMetadata, inputMetadata)
    Node->>SC: advertise resources
    SC-->>Node: match order to this node
    Node->>IPFS: download image + encrypted challenge/payload/input
    Node->>TZ: start enclaves
    TZ->>TZ: validate payload/input checksums vs owner signature
    TZ->>SS: re-encrypt payload+input for securelock's key
    SL->>SS: read payload+input, decrypt with own key
    SL->>SL: execute client code in SGX
    SL->>SS: write encrypted result + status code
    TZ->>SS: read result
    TZ->>SC: sign & submit _addResultToOrder (Proof of eXecution)
    User->>SC: read result reference from the order
    User->>IPFS: download encrypted result, decrypt with private key
```

In words: the user encrypts and uploads the payload/input, then places an on-chain request. A node matches the order, downloads the encrypted data, and starts the enclaves. trustedzone validates and re-encrypts for securelock; securelock executes the code and returns an encrypted result; trustedzone signs the Proof of eXecution and the node writes it on-chain. The user reads the proof from the order, downloads the encrypted result, and decrypts it with their own key. The data is encrypted at every hop — the only place it is ever clear is inside the enclave.

### DO-request metadata (v3)

`addDORequest` submits three colon-delimited metadata strings:

| Field          | Format                                                                                            | Notes                                    |
| -------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| Image metadata | `v3:<image_ipfs_hash>:<image_name>:<docker_compose_ipfs_hash>:<challenge_ipfs_hash>:<public_key>` | The **challenge** IPFS hash is required. |
| Code metadata  | `v3:<payload_ipfs_hash>:<code_checksum>`                                                          | The **payload** IPFS hash is required.   |
| Input metadata | `v3:<input_ipfs_hash>:<fileset_checksum>`                                                         | The input IPFS hash is optional.         |

If a required hash is missing the request cannot be fulfilled; the SDKs validate uploads before submitting, so a failed IPFS upload aborts the request instead of producing an un-runnable order.

The execution status code carried in every Proof of eXecution is listed in [Reference & troubleshooting](https://docs.ethernity.cloud/developer-guide/the-guide/reference-and-troubleshooting).

Ready to build? Continue to [Set up your environment](https://docs.ethernity.cloud/developer-guide/the-guide/environment-prerequisites).