> 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/data-flow-inside-ec.md).

# Data flow inside EC

This section walks through how user data moves through the Ethernity Cloud Protocol, from a dApp submitting a task to the user retrieving a verified result -- all while the data stays encrypted end-to-end.

```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
```

### Step by step

1. **Input formatting and submission.** While using the dApp, the user formats and encrypts the input with the enclave's public key, keeping the data confidential.
2. **Upload and task request.** The encrypted content is uploaded to IPFS, and the user submits a task request on-chain through the EC Smart Contract (`addDORequest`).
3. **Node resource submission.** EC Nodes advertise their available compute resources on-chain, providing the data needed for order matching.
4. **Order matching.** The EC Smart Contract matches the user's request to a suitable node. The matched node downloads the encrypted data from IPFS. If no node matches yet, matching continues until one does.
5. **Secure environment setup.** The node acquires the enclave docker image, sets up the SGX enclaves, and attests them (CAS on mainnet; self-signed from `MR_ENCLAVE` on testnet).
6. **Execution and proof.** securelock executes the task on the decrypted input inside the enclave, produces an encrypted result, and a status code. trustedzone builds a Proof of eXecution that the user can validate.
7. **Result upload.** The encrypted result is stored on IPFS, encrypted with the user's public key.
8. **Proof on-chain.** trustedzone signs the Proof of eXecution -- a transaction containing the result hash and the execution status code -- and the node writes it to the blockchain (`_addResultToOrder`).
9. **Retrieval and verification.** The user reads the proof from the order, validates it, checks the status, downloads the encrypted result, and decrypts it with their private key.

### DO-request metadata layout (v3)

When the dApp calls `addDORequest`, it submits three metadata strings. Each is colon-delimited:

| 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** (the code to execute) IPFS hash is **required**.    |
| Input metadata | `v3:<input_ipfs_hash>:<fileset_checksum>`                                                         | The input IPFS hash is **optional** (a task may run with no input). |

> If a required IPFS hash (challenge or payload) is missing, the request cannot be fulfilled -- the node has nothing to download. Client SDKs validate that uploads succeeded before submitting, so a failed IPFS upload aborts the request instead of producing an un-runnable on-chain order.

### Execution status codes

The status code returned in the Proof of eXecution:

| Code | Name                     | Meaning                                |
| ---- | ------------------------ | -------------------------------------- |
| 0    | SUCCESS                  | Task executed successfully             |
| 1    | SYSTEM\_ERROR            | A system-level error occurred          |
| 2    | KEY\_ERROR               | A key error occurred during execution  |
| 3    | SYNTAX\_WARNING          | A syntax-related warning               |
| 4    | BASE\_EXCEPTION          | A general exception was raised         |
| 5    | PAYLOAD\_NOT\_DEFINED    | No source payload was found to execute |
| 6    | PAYLOAD\_CHECKSUM\_ERROR | The payload checksum did not match     |
| 7    | INPUT\_CHECKSUM\_ERROR   | The input checksum did not match       |