From 58df66dc6de6c3aabcafeb70a4d3082cc6bcecdc Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Thu, 21 Aug 2025 23:47:07 +0200 Subject: [PATCH 1/8] refactor: update sidebar links and remove outdated guides - Renamed sidebar items for clarity: - 'Quick Start for Developers' to 'Quick Start' - Updated links for 'Build your first application', 'End-to-end Encryption', and 'Build Intel TDX app' to reflect new paths. - Deleted outdated guides: 'Create Your First SGX App', 'Build Intel TDX App (Experimental)', 'End-to-End Encryption', 'Quick Start for Developers', 'Your First Application', and 'Web3 Messaging'. --- .vitepress/sidebar.ts | 10 +- src/get-started/protocol/tee/intel-tdx.md | 4 +- src/get-started/protocol/tee/introduction.md | 2 +- src/get-started/protocol/tee/sgx-vs-tdx.md | 2 +- ...r-first-app.md => build-your-first-app.md} | 0 .../advanced/build-your-first-sgx-app.md | 264 +++++++++++++ ...tdx-app.md => build-your-first-tdx-app.md} | 10 +- .../advanced/create-your-first-sgx-app.md | 263 ------------- ...nd-encryption.md => protect-the-result.md} | 0 .../advanced/quick-start-for-developers.md | 365 ------------------ src/guides/build-iapp/advanced/quick-start.md | 365 ++++++++++++++++++ ...ssaging.md => integrate-web3-messaging.md} | 0 src/references/iapp-generator.md | 2 +- src/references/web3telegram.md | 4 +- 14 files changed, 647 insertions(+), 644 deletions(-) rename src/guides/build-iapp/advanced/{your-first-app.md => build-your-first-app.md} (100%) create mode 100644 src/guides/build-iapp/advanced/build-your-first-sgx-app.md rename src/guides/build-iapp/advanced/{create-your-first-tdx-app.md => build-your-first-tdx-app.md} (97%) rename src/guides/build-iapp/advanced/{end-to-end-encryption.md => protect-the-result.md} (100%) create mode 100644 src/guides/build-iapp/advanced/quick-start.md rename src/guides/use-iapp/{web3-messaging.md => integrate-web3-messaging.md} (100%) diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index a14553b0..bac9cc53 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -203,12 +203,12 @@ export function getSidebar() { collapsed: true, items: [ { - text: 'Quick Start for Developers', - link: '/guides/build-iapp/advanced/quick-start-for-developers', + text: 'Quick Start', + link: '/guides/build-iapp/advanced/quick-start', }, { text: 'Build your first application', - link: '/guides/build-iapp/advanced/your-first-app', + link: '/guides/build-iapp/advanced/build-your-first-app', }, { text: 'Build your first SGX app', @@ -216,7 +216,7 @@ export function getSidebar() { }, { text: 'End-to-end Encryption', - link: '/guides/build-iapp/advanced/end-to-end-encryption', + link: '/guides/build-iapp/advanced/protect-the-result', }, { text: 'Access Confidential Assets', @@ -224,7 +224,7 @@ export function getSidebar() { }, { text: 'Build Intel TDX app', - link: '/guides/build-iapp/advanced/create-your-first-tdx-app', + link: '/guides/build-iapp/advanced/build-your-first-tdx-app', }, ], }, diff --git a/src/get-started/protocol/tee/intel-tdx.md b/src/get-started/protocol/tee/intel-tdx.md index 1263f0be..fa083bb2 100644 --- a/src/get-started/protocol/tee/intel-tdx.md +++ b/src/get-started/protocol/tee/intel-tdx.md @@ -137,9 +137,9 @@ graph TD **Ready to experiment with TDX?** Check out the practical guides: -- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/create-your-first-tdx-app)** - +- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-app)** - Build TDX applications with traditional deployment and iApp Generator -- **[Create Your First TDX App](/guides/build-iapp/advanced/create-your-first-tdx-app)** - +- **[Build Your First TDX App](/guides/build-iapp/advanced/build-your-first-tdx-app)** - Build TDX applications **For production applications, use SGX**: diff --git a/src/get-started/protocol/tee/introduction.md b/src/get-started/protocol/tee/introduction.md index ea209af9..58be2126 100644 --- a/src/get-started/protocol/tee/introduction.md +++ b/src/get-started/protocol/tee/introduction.md @@ -119,7 +119,7 @@ TEE technologies have evolved to address different use cases: **Ready to build with TEE?** Check out the practical guides: -- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/create-your-first-tdx-app)** - +- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-app)** - Build TDX applications with traditional deployment and iApp Generator - **[Deploy & Run](/guides/build-iapp/deploy-&-run)** - Create your first TEE application diff --git a/src/get-started/protocol/tee/sgx-vs-tdx.md b/src/get-started/protocol/tee/sgx-vs-tdx.md index d33bf491..bdbb89c4 100644 --- a/src/get-started/protocol/tee/sgx-vs-tdx.md +++ b/src/get-started/protocol/tee/sgx-vs-tdx.md @@ -79,7 +79,7 @@ technology** for advanced use cases. **Ready to build with TEE?** Check out the practical guides: -- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/create-your-first-tdx-app)** - +- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-app)** - Build TDX applications with traditional deployment and iApp Generator - **[Deploy & Run](/guides/build-iapp/deploy-&-run)** - Create your first TEE application diff --git a/src/guides/build-iapp/advanced/your-first-app.md b/src/guides/build-iapp/advanced/build-your-first-app.md similarity index 100% rename from src/guides/build-iapp/advanced/your-first-app.md rename to src/guides/build-iapp/advanced/build-your-first-app.md diff --git a/src/guides/build-iapp/advanced/build-your-first-sgx-app.md b/src/guides/build-iapp/advanced/build-your-first-sgx-app.md new file mode 100644 index 00000000..de15c0ba --- /dev/null +++ b/src/guides/build-iapp/advanced/build-your-first-sgx-app.md @@ -0,0 +1,264 @@ +--- +title: Build Your First Application with Scone Framework +description: + Learn how to build and run Confidential Computing applications with the Scone + TEE framework for secure, privacy-preserving computation +--- + +# Build your first application with Scone framework + +In this tutorial, you will learn how to build and run a Confidential Computing +application with the Scone TEE framework. + +::: warning + +Before going any further, make sure you managed to +[Build your first application](./build-your-first-app). + +::: + +::: tip Prerequisites: + +- [Docker](https://docs.docker.com/install/) 17.05 or higher on the daemon and + client. +- [iExec SDK](https://www.npmjs.com/package/iexec) 8.0.0 or higher. + [Install the iExec SDK](./quick-start-for-developers.md#install-the-iexec-sdk) +- Familiarity with the basic concepts of + [Intelยฎ SGX](/get-started/protocol/tee/intel-sgx) and + [SCONE](https://scontain.com) framework. + +::: + +In order to follow this tutorial, you will need to register a +[free SCONE Account](https://scontain.com) to access SCONE build tools and +curated images from the [SCONE registry](https://gitlab.scontain.com/). + +Once your account is activated, you need to +[request access to the SCONE build tools for iExec](mailto:info@scontain.com?cc=scone-access@iex.ec&subject=iExec%20Build%20Tools&body=Hi%20SCONE%20Team%2C%0D%0A%0D%0AI%20would%20like%20to%20get%20access%20to%20the%20SCONE%20build%20tools%20for%20iExec:%0A%20-%20scone-production/iexec-sconify-image%0A%20-%20sconecuratedimages%20%28all%20curated%20images%20such%20as%20nodejs%2C%20python...%29%0A%0AMy%20DockerID%20is%20...%0A%0ABest%20regards%0A%0A...). + +```bash +# when your account is ready, run `docker login` to connect the SCONE registry +docker login registry.scontain.com +``` + +## Prepare your application + +Before going further, your `/hello-world:1.0.0` image built +previously is required. + +If you missed that part, please go back to +[Build your first application](./build-your-first-app). + +For this tutorial, you can reuse the same directory tree or create a new one. + +To create a new directory tree, execute the following commands in +`~/iexec-projects/`. + +```bash +cd ~/iexec-projects +mkdir tee-hello-world-app && cd tee-hello-world-app +iexec init --skip-wallet +mkdir src +touch Dockerfile +touch sconify.sh +chmod +x sconify.sh +``` + +## Build the TEE docker image + +Before wrapping your iExec confidential application with Scone, you need to +generate a custom signing key. This key is used for the sconification process. + +Generate your enclave signing key with: + +```bash +openssl genrsa -3 -out enclave-key.pem 3072 +``` + +This will create an `enclave-key.pem` file in your current directory. You will +use this file in the sconify Docker command to sign your TEE image. + +We will use the following script to wrap the sconification process, copy the +`sconify.sh` script in the current directory: + +::: code-group + +```bash [Javascript] +#!/bin/bash + +# Declare image related variables +IMG_FROM=/hello-world:1.0.0 +IMG_TO=/tee-scone-hello-world:1.0.0 + +# Run the sconifier to build the TEE image based on the non-TEE image +docker run -it --rm \ + -v $PWD/enclave-key.pem:/sig/enclave-key.pem \ + -v /var/run/docker.sock:/var/run/docker.sock \ + registry.scontain.com/scone-production/iexec-sconify-image:5.9.1-v16\ + sconify_iexec \ + --from=${IMG_FROM} \ + --to=${IMG_TO} \ + --binary-fs \ + --fs-dir=/app \ + --host-path=/etc/hosts \ + --host-path=/etc/resolv.conf \ + --binary=/usr/local/bin/node \ + --heap=1G \ + --dlopen=1 \ + --verbose \ + && echo -e "\n------------------\n" \ + && echo "successfully built TEE docker image => ${IMG_TO}" \ + && echo "application mrenclave.fingerprint is $(docker run --rm -e SCONE_HASH=1 ${IMG_TO})" +``` + +```bash [Python] +#!/bin/bash + +# Declare image related variables +IMG_FROM=/hello-world:1.0.0 +IMG_TO=/tee-scone-hello-world:1.0.0 + +# Run the sconifier to build the TEE image based on the non-TEE image +docker run -it --rm \ + -v $PWD/enclave-key.pem:/sig/enclave-key.pem \ + -v /var/run/docker.sock:/var/run/docker.sock \ + registry.scontain.com/scone-production/iexec-sconify-image:5.9.1-v16\ + sconify_iexec \ + --from=${IMG_FROM} \ + --to=${IMG_TO} \ + --binary-fs \ + --fs-dir=/app \ + --host-path=/etc/hosts \ + --host-path=/etc/resolv.conf \ + --binary=/usr/local/bin/python3 \ + --heap=1G \ + --dlopen=1 \ + --verbose \ + && echo -e "\n------------------\n" \ + && echo "successfully built TEE docker image => ${IMG_TO}" \ + && echo "application mrenclave.fingerprint is $(docker run --rm -e SCONE_HASH=1 ${IMG_TO})" +``` + +::: + +Run the `sconify.sh` script to build the Scone TEE application: + +```bash +./sconify.sh +``` + +Push your image on DockerHub: + +```bash +docker push /tee-scone-hello-world:1.0.0 +``` + +Congratulations, you just built your Scone TEE application. + +## Test your app on iExec + +At this stage, your application is ready to be tested on iExec. The process is +similar to testing any type of application on the platform, with these minor +exceptions: + +### Deploy the TEE app on iExec + +TEE applications require some additional information to be filled in during +deployment. + +```bash +# prepare the TEE application template +iexec app init --tee +``` + +Edit `iexec.json` and fill in the standard keys and the `mrenclave` object: + +```json +{ + ... + "app": { + "owner": "", // starts with 0x + "name": "tee-scone-hello-world", // application name + "type": "DOCKER", + "multiaddr": "docker.io//tee-scone-hello-world:1.0.0", // app image + "checksum": "", // starts with 0x, update it with your own image digest + "mrenclave": { + "framework": "SCONE", // TEE framework (keep default value) + "version": "v5.9", // Scone version (keep default value) + "entrypoint": "node /app/app.js" OR "python3 /app/app.py", // update it with your own image entrypoint + "heapSize": 1073741824, // heap size in bytes, update it with --heap option value used in sconify.sh script during TEE image build + "fingerprint": "" // fingerprint of the enclave code (mrenclave), without 0x prefix, see how to retrieve it below + } + }, + ... +} +``` + +::: info + +See +[Create your identity on the blockchain](./quick-start-for-developers.md#create-your-identity-on-the-blockchain) +to retrieve `` value. + +See +[Deploy your app on iExec](./build-your-first-app.md#deploy-your-app-on-iexec) +to retrieve your image ``. + +Run your TEE image with `SCONE_HASH=1` to get the enclave fingerprint +(mrenclave): + +```bash +docker run --rm -e SCONE_HASH=1 /tee-scone-hello-world:1.0.0 +``` + +::: + +Deploy the app with the standard command: + +```bash twoslash +iexec app deploy --chain {{chainName}} +``` + +### Run the TEE app + +Specify the tag `--tag tee,scone` in `iexec app run` command to run a tee app. + +One last thing, in order to run a **TEE** app you will also need to select a +workerpool, use the iexec workerpool `{{workerpoolAddress}}`. + +You are now ready to run the app + +```bash twoslash +iexec app run --chain {{chainName}} --tag tee,scone --workerpool {{workerpoolAddress}} --watch +``` + +::: info + +Remember, you can access task and app logs by following the instructions on page +[Debug your tasks](/guides/build-iapp/debugging). + +::: + +## Next step? + +In this tutorial, you learned how to leverage your application with the power of +Trusted Execution Environments using iExec. But according to your use case, you +may need to use some confidential data to get the full potential of the +**Confidential Computing** paradigm. Check out next chapters to see how: + +- [Access confidential assets from your app](access-confidential-assets.md) +- [Protect the result](./protect-the-result.md) + + diff --git a/src/guides/build-iapp/advanced/create-your-first-tdx-app.md b/src/guides/build-iapp/advanced/build-your-first-tdx-app.md similarity index 97% rename from src/guides/build-iapp/advanced/create-your-first-tdx-app.md rename to src/guides/build-iapp/advanced/build-your-first-tdx-app.md index 91742fba..8a6689a1 100644 --- a/src/guides/build-iapp/advanced/create-your-first-tdx-app.md +++ b/src/guides/build-iapp/advanced/build-your-first-tdx-app.md @@ -67,8 +67,9 @@ need to be changed compared to the usual SGX workflow: `chain.json` and `iexec.json`. iApps using Intel TDX technology follow the same format as non-TEE applications; -follow the instructions on [Build your first application](./your-first-app) to -create and Dockerize your iApp. +follow the instructions on +[Build your first application](./build-your-first-app) to create and Dockerize +your iApp. After this step, the Docker image of your iApp should be published on Docker Hub (e.g. `/hello-world:1.0.0`). @@ -118,8 +119,9 @@ Your `iexec.json` should now look like this example: ::: info -See [Deploy your app on iExec](./your-first-app.md#deploy-your-app-on-iexec) to -retrieve your image ``. +See +[Deploy your app on iExec](./build-your-first-app.md#deploy-your-app-on-iexec) +to retrieve your image ``. ::: diff --git a/src/guides/build-iapp/advanced/create-your-first-sgx-app.md b/src/guides/build-iapp/advanced/create-your-first-sgx-app.md index 9d6ae452..e69de29b 100644 --- a/src/guides/build-iapp/advanced/create-your-first-sgx-app.md +++ b/src/guides/build-iapp/advanced/create-your-first-sgx-app.md @@ -1,263 +0,0 @@ ---- -title: Build Your First Application with Scone Framework -description: - Learn how to build and run Confidential Computing applications with the Scone - TEE framework for secure, privacy-preserving computation ---- - -# Build your first application with Scone framework - -In this tutorial, you will learn how to build and run a Confidential Computing -application with the Scone TEE framework. - -::: warning - -Before going any further, make sure you managed to -[Build your first application](./your-first-app). - -::: - -::: tip Prerequisites: - -- [Docker](https://docs.docker.com/install/) 17.05 or higher on the daemon and - client. -- [iExec SDK](https://www.npmjs.com/package/iexec) 8.0.0 or higher. - [Install the iExec SDK](./quick-start-for-developers.md#install-the-iexec-sdk) -- Familiarity with the basic concepts of - [Intelยฎ SGX](/get-started/protocol/tee/intel-sgx) and - [SCONE](https://scontain.com) framework. - -::: - -In order to follow this tutorial, you will need to register a -[free SCONE Account](https://scontain.com) to access SCONE build tools and -curated images from the [SCONE registry](https://gitlab.scontain.com/). - -Once your account is activated, you need to -[request access to the SCONE build tools for iExec](mailto:info@scontain.com?cc=scone-access@iex.ec&subject=iExec%20Build%20Tools&body=Hi%20SCONE%20Team%2C%0D%0A%0D%0AI%20would%20like%20to%20get%20access%20to%20the%20SCONE%20build%20tools%20for%20iExec:%0A%20-%20scone-production/iexec-sconify-image%0A%20-%20sconecuratedimages%20%28all%20curated%20images%20such%20as%20nodejs%2C%20python...%29%0A%0AMy%20DockerID%20is%20...%0A%0ABest%20regards%0A%0A...). - -```bash -# when your account is ready, run `docker login` to connect the SCONE registry -docker login registry.scontain.com -``` - -## Prepare your application - -Before going further, your `/hello-world:1.0.0` image built -previously is required. - -If you missed that part, please go back to -[Build your first application](./your-first-app). - -For this tutorial, you can reuse the same directory tree or create a new one. - -To create a new directory tree, execute the following commands in -`~/iexec-projects/`. - -```bash -cd ~/iexec-projects -mkdir tee-hello-world-app && cd tee-hello-world-app -iexec init --skip-wallet -mkdir src -touch Dockerfile -touch sconify.sh -chmod +x sconify.sh -``` - -## Build the TEE docker image - -Before wrapping your iExec confidential application with Scone, you need to -generate a custom signing key. This key is used for the sconification process. - -Generate your enclave signing key with: - -```bash -openssl genrsa -3 -out enclave-key.pem 3072 -``` - -This will create an `enclave-key.pem` file in your current directory. You will -use this file in the sconify Docker command to sign your TEE image. - -We will use the following script to wrap the sconification process, copy the -`sconify.sh` script in the current directory: - -::: code-group - -```bash [Javascript] -#!/bin/bash - -# Declare image related variables -IMG_FROM=/hello-world:1.0.0 -IMG_TO=/tee-scone-hello-world:1.0.0 - -# Run the sconifier to build the TEE image based on the non-TEE image -docker run -it --rm \ - -v $PWD/enclave-key.pem:/sig/enclave-key.pem \ - -v /var/run/docker.sock:/var/run/docker.sock \ - registry.scontain.com/scone-production/iexec-sconify-image:5.9.1-v16\ - sconify_iexec \ - --from=${IMG_FROM} \ - --to=${IMG_TO} \ - --binary-fs \ - --fs-dir=/app \ - --host-path=/etc/hosts \ - --host-path=/etc/resolv.conf \ - --binary=/usr/local/bin/node \ - --heap=1G \ - --dlopen=1 \ - --verbose \ - && echo -e "\n------------------\n" \ - && echo "successfully built TEE docker image => ${IMG_TO}" \ - && echo "application mrenclave.fingerprint is $(docker run --rm -e SCONE_HASH=1 ${IMG_TO})" -``` - -```bash [Python] -#!/bin/bash - -# Declare image related variables -IMG_FROM=/hello-world:1.0.0 -IMG_TO=/tee-scone-hello-world:1.0.0 - -# Run the sconifier to build the TEE image based on the non-TEE image -docker run -it --rm \ - -v $PWD/enclave-key.pem:/sig/enclave-key.pem \ - -v /var/run/docker.sock:/var/run/docker.sock \ - registry.scontain.com/scone-production/iexec-sconify-image:5.9.1-v16\ - sconify_iexec \ - --from=${IMG_FROM} \ - --to=${IMG_TO} \ - --binary-fs \ - --fs-dir=/app \ - --host-path=/etc/hosts \ - --host-path=/etc/resolv.conf \ - --binary=/usr/local/bin/python3 \ - --heap=1G \ - --dlopen=1 \ - --verbose \ - && echo -e "\n------------------\n" \ - && echo "successfully built TEE docker image => ${IMG_TO}" \ - && echo "application mrenclave.fingerprint is $(docker run --rm -e SCONE_HASH=1 ${IMG_TO})" -``` - -::: - -Run the `sconify.sh` script to build the Scone TEE application: - -```bash -./sconify.sh -``` - -Push your image on DockerHub: - -```bash -docker push /tee-scone-hello-world:1.0.0 -``` - -Congratulations, you just built your Scone TEE application. - -## Test your app on iExec - -At this stage, your application is ready to be tested on iExec. The process is -similar to testing any type of application on the platform, with these minor -exceptions: - -### Deploy the TEE app on iExec - -TEE applications require some additional information to be filled in during -deployment. - -```bash -# prepare the TEE application template -iexec app init --tee -``` - -Edit `iexec.json` and fill in the standard keys and the `mrenclave` object: - -```json -{ - ... - "app": { - "owner": "", // starts with 0x - "name": "tee-scone-hello-world", // application name - "type": "DOCKER", - "multiaddr": "docker.io//tee-scone-hello-world:1.0.0", // app image - "checksum": "", // starts with 0x, update it with your own image digest - "mrenclave": { - "framework": "SCONE", // TEE framework (keep default value) - "version": "v5.9", // Scone version (keep default value) - "entrypoint": "node /app/app.js" OR "python3 /app/app.py", // update it with your own image entrypoint - "heapSize": 1073741824, // heap size in bytes, update it with --heap option value used in sconify.sh script during TEE image build - "fingerprint": "" // fingerprint of the enclave code (mrenclave), without 0x prefix, see how to retrieve it below - } - }, - ... -} -``` - -::: info - -See -[Create your identity on the blockchain](./quick-start-for-developers.md#create-your-identity-on-the-blockchain) -to retrieve `` value. - -See [Deploy your app on iExec](./your-first-app.md#deploy-your-app-on-iexec) to -retrieve your image ``. - -Run your TEE image with `SCONE_HASH=1` to get the enclave fingerprint -(mrenclave): - -```bash -docker run --rm -e SCONE_HASH=1 /tee-scone-hello-world:1.0.0 -``` - -::: - -Deploy the app with the standard command: - -```bash twoslash -iexec app deploy --chain {{chainName}} -``` - -### Run the TEE app - -Specify the tag `--tag tee,scone` in `iexec app run` command to run a tee app. - -One last thing, in order to run a **TEE** app you will also need to select a -workerpool, use the iexec workerpool `{{workerpoolAddress}}`. - -You are now ready to run the app - -```bash twoslash -iexec app run --chain {{chainName}} --tag tee,scone --workerpool {{workerpoolAddress}} --watch -``` - -::: info - -Remember, you can access task and app logs by following the instructions on page -[Debug your tasks](/guides/build-iapp/debugging). - -::: - -## Next step? - -In this tutorial, you learned how to leverage your application with the power of -Trusted Execution Environments using iExec. But according to your use case, you -may need to use some confidential data to get the full potential of the -**Confidential Computing** paradigm. Check out next chapters to see how: - -- [Access confidential assets from your app](access-confidential-assets.md) -- [Protect the result](end-to-end-encryption.md) - - diff --git a/src/guides/build-iapp/advanced/end-to-end-encryption.md b/src/guides/build-iapp/advanced/protect-the-result.md similarity index 100% rename from src/guides/build-iapp/advanced/end-to-end-encryption.md rename to src/guides/build-iapp/advanced/protect-the-result.md diff --git a/src/guides/build-iapp/advanced/quick-start-for-developers.md b/src/guides/build-iapp/advanced/quick-start-for-developers.md index 0d044dc1..e69de29b 100644 --- a/src/guides/build-iapp/advanced/quick-start-for-developers.md +++ b/src/guides/build-iapp/advanced/quick-start-for-developers.md @@ -1,365 +0,0 @@ ---- -title: Quick Start for Developers -description: - Learn how to create and deploy decentralized applications on the iExec - infrastructure using the iExec SDK command-line interface ---- - -# Quick Start - -> In this tutorial we will show you how you can create decentralized application -> over the iExec infrastructure. - -iExec enables decentralized docker app deployment and monetization on the -blockchain. - -In this guide, we will use the iExec SDK command-line interface to deploy an -iExec app on a test blockchain. - -## Install the iExec SDK - -Requirements: -[![npm version](https://img.shields.io/badge/nodejs-%3E=18.0.0-brightgreen.svg)](https://nodejs.org/en/) - -```bash -npm -g install iexec # install the CLI -iexec --version -iexec --help -``` - -## Create your identity on the blockchain - -On the blockchain, your identity is defined by your **wallet,** consisting of -cryptographically encrypted **private key** and **public address.** What you own -on the blockchain is associated with your address. The applications you deploy -on iExec are associated with your wallet. - -Let's set up your wallet. - -Create a new Wallet file - -```text -iexec wallet create -``` - -You will be asked to choose a password to protect your wallet, don't forget it -since there is no way to recover it. The SDK creates a wallet file that contains -a randomly generated private key encrypted by the chosen password and the -derived public address. Make sure to back up the wallet file in a safe place and -write down your address. - -::: tip Your wallet is stored in the ethereum keystore, the location depends on -your OS: - -- On Linux: ~/.ethereum/keystore -- On Mac : ~/Library/Ethereum/keystore -- On Windows: ~/AppData/Roaming/Ethereum/keystore - -Wallet file name follow the pattern `UTC----
` - -::: - -::: info - -iExec SDK uses standard Ethereum wallet, you can reuse or import existing -Ethereum wallet. See iExec SDK documentation -[wallet command](https://github.com/iExecBlockchainComputing/iexec-sdk/blob/v8.1.5/CLI.md#iexec-wallet). - -::: - -## Initialize your iExec project - -Create a new folder for your iExec project and initialize the project: - -```bash -mkdir ~/iexec-projects -cd ~/iexec-projects -iexec init --skip-wallet -``` - -::: info - -The iExec SDK creates the minimum configuration files: - -- `iexec.json` contains the project configuration -- `chain.json` contains the blockchain connection configuration -- we use `--skip-wallet` to skip wallet creation as we already created it - -::: - -You can now connect to the desired supported blockchain. In the following steps, -we will use the chosen blockchain to deploy and run your iExec app. See the -[supported blockchains](/get-started/tooling-and-explorers/blockchain-explorer) -for a full list. - -You can now check your wallet content: - -```bash -iexec wallet show -``` - -## Deploy your app on iExec - -iExec enables decentralized deployment of dockerized applications. The -applications deployed on iExec are Smart Contracts identified by their Ethereum -address and referencing a public docker image. Each iExec application has an -owner who can set the execution permissions on iExec platform. - -Let's deploy an iExec app! - -Initialize a new application - -```bash -iexec app init -``` - -The iExec SDK writes the minimum app configuration in `iexec.json` - -| **key** | **description** | -| --------- | --------------------------------------------------------------------------- | -| owner | app owner ethereum address \(default your wallet address\) | -| name | name of the application | -| type | type of application \("DOCKER" for docker container\) | -| multiaddr | download URI of the application \(a public docker registry\) | -| checksum | checksum of the app \("0x" + docker image digest\) | -| mrenclave | app fingerprint used for confidential computing use cases \(default empty\) | - -::: info - -The default app is the public docker image -[iexechub/python-hello-world](https://hub.docker.com/repository/docker/iexechub/python-hello-world). - -Given an input string, the application generates an ASCII art greeting. - -::: - -You can deploy this application on iExec, it will run out of the box. When you -are confident with iExec concept, you can read -[Your first app](your-first-app.md) and learn how to setup your own app on -iExec. - -You will now deploy your app on iExec, this will be your first transaction on -the blockchain: - -```bash twoslash -iexec app deploy --chain arbitrum-mainnet -``` - -::: tip - -While running `iexec app deploy` you sent your first transaction on the -arbitrum-mainnet blockchain. - -::: - -You can check your deployed apps with their index, let's check your last -deployed app: - -```bash twoslash -iexec app show --chain arbitrum-mainnet -``` - -## Run your app on iExec - -iExec allows you to run applications on a decentralized infrastructure with -payment in **RLC** tokens \(the native cryptocurrency of iExec\). - -::: info - -To run an application you must have enough RLC staked on your iExec account to -pay for the computing resources. - -Your iExec account is managed by smart contracts \(and not owned by iExec\). - -When you request an execution the price for the task is locked from your -account's stake then transferred to accounts of the workers contributing to the -task \(read more about -[Proof of Contribution](/get-started/protocol/proof-of-contribution) protocol\). - -At any time you can: - -- view your balance - -```bash twoslash -iexec account show --chain arbitrum-mainnet -``` - -- deposit RLC from your wallet to your iExec Account - -```bash twoslash -iexec account deposit --chain arbitrum-mainnet -``` - -- withdraw RLC from your iExec account to your wallet \(only stake can be - withdrawn\) - -```bash twoslash -iexec account withdraw --chain arbitrum-mainnet -``` - -::: - -Currently, iExec sponsors applications running on Bellecour, and you won't have -to pay for the computation. - -Everything is ready to run your application! - -```bash twoslash -iexec app run --chain arbitrum-mainnet --args --workerpool {{workerpoolAddress}} --watch -``` - -::: info - -`iexec app run` allows to run an application on iExec at the market price. - -Useful options: - -- `--args ` specify the app execution arguments -- `--watch` watch execution status changes -- `--workerpool
` specify the workerpool to use (for example: - `--workerpool {{workerpoolAddress}}`) - -Discover more option with `iexec app run --help` - -::: - -::: tip Congratulation you requested the execution of -[iexechub/python-hello-world](https://hub.docker.com/repository/docker/iexechub/python-hello-world). - -This will generate an ASCII art greeting with your name. - -::: - -The execution of tasks on the iExec network is asynchronous by design. - -```mermaid -graph TD - Requester["Requester (or anyone)"] --> |"1 . Match compatible orders \n(request, application, dataset & workerpool orders) \n & Wait result" | Blockchain - Blockchain --> |2 . Notify new deal with tasks to compute| Scheduler - Worker --> |3 . Request new task to compute| Scheduler - Worker --> |4 . Run application| Application[Application image] - Worker --> |5.a. Push result| ResultStorage["Result Storage"] - Worker --> |5.b. Commit result proof| Blockchain - Workerpool --> |6 . Publish result link or callback| Blockchain - - subgraph Workerpool - Scheduler - Worker - Application - end -``` - -Guaranties about completion times (fast/slow) are available in the -[category section](/get-started/protocol/pay-per-task): - -- maximum deal/task time -- maximum computing time - -Once the task is completed copy the taskid from `iexec app run` output \(taskid -is a 32Bytes hexadecimal string\). - -Download the result of your task - -```bash twoslash -iexec task show --chain arbitrum-mainnet --download my-result -``` - -You can get your taskid with the command: - -```bash twoslash -iexec deal show --chain arbitrum-mainnet -``` - -::: info - -A task result is a zip file containing the output files of the application. - -::: - -[iexechub/python-hello-world](https://hub.docker.com/repository/docker/iexechub/python-hello-world) -produce an text file in `result.txt`. - -Let's discover the result of the computation. - -```bash -unzip my-result.zip -d my-result -cat my-result/result.txt -``` - -Congratulations! You successfully executed your application on iExec! - -## Publish your app on the iExec Marketplace - -Your application is deployed on iExec and you completed an execution on iExec. -For now, only you can request an execution of your application. The next step is -to publish it on the iExec Marketplace, making it available for anyone to use. - -As the owner of this application, you can define the conditions under which it -can be used - -::: info - -iExec uses orders signed by the resource owner's wallet to ensure resources -governance. - -The conditions to use an app are defined in the **apporder**. - -::: - -Publish a new apporder for your application. - -```bash twoslash -iexec app publish --chain arbitrum-mainnet -``` - -::: info - -`iexec app publish` command allows to define custom access rules to the app -\(run `iexec app publish --help` to discover all the possibilities\). - -You will learn more about orders management later, keep the apporder default -values for now. - -::: - -Your application is now available for everyone on iExec marketplace on the -conditions defined in apporder. - -You can check the published apporders for your app - -```bash twoslash -iexec orderbook app --chain arbitrum-mainnet -``` - -Congratulation you just created a decentralized application! Anyone can now -trigger an execution of your application on the iExec decentralized -infrastructure. - -## What's next? - -You are now familiar with the following key iExec concepts for developers: - -- Your wallet is your on-chain ID and blockchain account -- You can deploy decentralized applications on iExec -- Anyone can run tasks against payment in RLC on iExec -- Payments are processed by the decentralized platform between users' iExec - Accounts -- Resource governance is managed by orders - -Continue with these guides: - -- [Learn how to build your first application running on iExec](your-first-app.md) - - diff --git a/src/guides/build-iapp/advanced/quick-start.md b/src/guides/build-iapp/advanced/quick-start.md new file mode 100644 index 00000000..1f17b7ef --- /dev/null +++ b/src/guides/build-iapp/advanced/quick-start.md @@ -0,0 +1,365 @@ +--- +title: Quick Start for Developers +description: + Learn how to create and deploy decentralized applications on the iExec + infrastructure using the iExec SDK command-line interface +--- + +# Quick Start + +> In this tutorial we will show you how you can create decentralized application +> over the iExec infrastructure. + +iExec enables decentralized docker app deployment and monetization on the +blockchain. + +In this guide, we will use the iExec SDK command-line interface to deploy an +iExec app on a test blockchain. + +## Install the iExec SDK + +Requirements: +[![npm version](https://img.shields.io/badge/nodejs-%3E=18.0.0-brightgreen.svg)](https://nodejs.org/en/) + +```bash +npm -g install iexec # install the CLI +iexec --version +iexec --help +``` + +## Create your identity on the blockchain + +On the blockchain, your identity is defined by your **wallet,** consisting of +cryptographically encrypted **private key** and **public address.** What you own +on the blockchain is associated with your address. The applications you deploy +on iExec are associated with your wallet. + +Let's set up your wallet. + +Create a new Wallet file + +```text +iexec wallet create +``` + +You will be asked to choose a password to protect your wallet, don't forget it +since there is no way to recover it. The SDK creates a wallet file that contains +a randomly generated private key encrypted by the chosen password and the +derived public address. Make sure to back up the wallet file in a safe place and +write down your address. + +::: tip Your wallet is stored in the ethereum keystore, the location depends on +your OS: + +- On Linux: ~/.ethereum/keystore +- On Mac : ~/Library/Ethereum/keystore +- On Windows: ~/AppData/Roaming/Ethereum/keystore + +Wallet file name follow the pattern `UTC----
` + +::: + +::: info + +iExec SDK uses standard Ethereum wallet, you can reuse or import existing +Ethereum wallet. See iExec SDK documentation +[wallet command](https://github.com/iExecBlockchainComputing/iexec-sdk/blob/v8.1.5/CLI.md#iexec-wallet). + +::: + +## Initialize your iExec project + +Create a new folder for your iExec project and initialize the project: + +```bash +mkdir ~/iexec-projects +cd ~/iexec-projects +iexec init --skip-wallet +``` + +::: info + +The iExec SDK creates the minimum configuration files: + +- `iexec.json` contains the project configuration +- `chain.json` contains the blockchain connection configuration +- we use `--skip-wallet` to skip wallet creation as we already created it + +::: + +You can now connect to the desired supported blockchain. In the following steps, +we will use the chosen blockchain to deploy and run your iExec app. See the +[supported blockchains](/get-started/tooling-and-explorers/blockchain-explorer) +for a full list. + +You can now check your wallet content: + +```bash +iexec wallet show +``` + +## Deploy your app on iExec + +iExec enables decentralized deployment of dockerized applications. The +applications deployed on iExec are Smart Contracts identified by their Ethereum +address and referencing a public docker image. Each iExec application has an +owner who can set the execution permissions on iExec platform. + +Let's deploy an iExec app! + +Initialize a new application + +```bash +iexec app init +``` + +The iExec SDK writes the minimum app configuration in `iexec.json` + +| **key** | **description** | +| --------- | --------------------------------------------------------------------------- | +| owner | app owner ethereum address \(default your wallet address\) | +| name | name of the application | +| type | type of application \("DOCKER" for docker container\) | +| multiaddr | download URI of the application \(a public docker registry\) | +| checksum | checksum of the app \("0x" + docker image digest\) | +| mrenclave | app fingerprint used for confidential computing use cases \(default empty\) | + +::: info + +The default app is the public docker image +[iexechub/python-hello-world](https://hub.docker.com/repository/docker/iexechub/python-hello-world). + +Given an input string, the application generates an ASCII art greeting. + +::: + +You can deploy this application on iExec, it will run out of the box. When you +are confident with iExec concept, you can read +[Your first app](./build-your-first-app.md) and learn how to setup your own app +on iExec. + +You will now deploy your app on iExec, this will be your first transaction on +the blockchain: + +```bash twoslash +iexec app deploy --chain arbitrum-mainnet +``` + +::: tip + +While running `iexec app deploy` you sent your first transaction on the +arbitrum-mainnet blockchain. + +::: + +You can check your deployed apps with their index, let's check your last +deployed app: + +```bash twoslash +iexec app show --chain arbitrum-mainnet +``` + +## Run your app on iExec + +iExec allows you to run applications on a decentralized infrastructure with +payment in **RLC** tokens \(the native cryptocurrency of iExec\). + +::: info + +To run an application you must have enough RLC staked on your iExec account to +pay for the computing resources. + +Your iExec account is managed by smart contracts \(and not owned by iExec\). + +When you request an execution the price for the task is locked from your +account's stake then transferred to accounts of the workers contributing to the +task \(read more about +[Proof of Contribution](/get-started/protocol/proof-of-contribution) protocol\). + +At any time you can: + +- view your balance + +```bash twoslash +iexec account show --chain arbitrum-mainnet +``` + +- deposit RLC from your wallet to your iExec Account + +```bash twoslash +iexec account deposit --chain arbitrum-mainnet +``` + +- withdraw RLC from your iExec account to your wallet \(only stake can be + withdrawn\) + +```bash twoslash +iexec account withdraw --chain arbitrum-mainnet +``` + +::: + +Currently, iExec sponsors applications running on Bellecour, and you won't have +to pay for the computation. + +Everything is ready to run your application! + +```bash twoslash +iexec app run --chain arbitrum-mainnet --args --workerpool {{workerpoolAddress}} --watch +``` + +::: info + +`iexec app run` allows to run an application on iExec at the market price. + +Useful options: + +- `--args ` specify the app execution arguments +- `--watch` watch execution status changes +- `--workerpool
` specify the workerpool to use (for example: + `--workerpool {{workerpoolAddress}}`) + +Discover more option with `iexec app run --help` + +::: + +::: tip Congratulation you requested the execution of +[iexechub/python-hello-world](https://hub.docker.com/repository/docker/iexechub/python-hello-world). + +This will generate an ASCII art greeting with your name. + +::: + +The execution of tasks on the iExec network is asynchronous by design. + +```mermaid +graph TD + Requester["Requester (or anyone)"] --> |"1 . Match compatible orders \n(request, application, dataset & workerpool orders) \n & Wait result" | Blockchain + Blockchain --> |2 . Notify new deal with tasks to compute| Scheduler + Worker --> |3 . Request new task to compute| Scheduler + Worker --> |4 . Run application| Application[Application image] + Worker --> |5.a. Push result| ResultStorage["Result Storage"] + Worker --> |5.b. Commit result proof| Blockchain + Workerpool --> |6 . Publish result link or callback| Blockchain + + subgraph Workerpool + Scheduler + Worker + Application + end +``` + +Guaranties about completion times (fast/slow) are available in the +[category section](/get-started/protocol/pay-per-task): + +- maximum deal/task time +- maximum computing time + +Once the task is completed copy the taskid from `iexec app run` output \(taskid +is a 32Bytes hexadecimal string\). + +Download the result of your task + +```bash twoslash +iexec task show --chain arbitrum-mainnet --download my-result +``` + +You can get your taskid with the command: + +```bash twoslash +iexec deal show --chain arbitrum-mainnet +``` + +::: info + +A task result is a zip file containing the output files of the application. + +::: + +[iexechub/python-hello-world](https://hub.docker.com/repository/docker/iexechub/python-hello-world) +produce an text file in `result.txt`. + +Let's discover the result of the computation. + +```bash +unzip my-result.zip -d my-result +cat my-result/result.txt +``` + +Congratulations! You successfully executed your application on iExec! + +## Publish your app on the iExec Marketplace + +Your application is deployed on iExec and you completed an execution on iExec. +For now, only you can request an execution of your application. The next step is +to publish it on the iExec Marketplace, making it available for anyone to use. + +As the owner of this application, you can define the conditions under which it +can be used + +::: info + +iExec uses orders signed by the resource owner's wallet to ensure resources +governance. + +The conditions to use an app are defined in the **apporder**. + +::: + +Publish a new apporder for your application. + +```bash twoslash +iexec app publish --chain arbitrum-mainnet +``` + +::: info + +`iexec app publish` command allows to define custom access rules to the app +\(run `iexec app publish --help` to discover all the possibilities\). + +You will learn more about orders management later, keep the apporder default +values for now. + +::: + +Your application is now available for everyone on iExec marketplace on the +conditions defined in apporder. + +You can check the published apporders for your app + +```bash twoslash +iexec orderbook app --chain arbitrum-mainnet +``` + +Congratulation you just created a decentralized application! Anyone can now +trigger an execution of your application on the iExec decentralized +infrastructure. + +## What's next? + +You are now familiar with the following key iExec concepts for developers: + +- Your wallet is your on-chain ID and blockchain account +- You can deploy decentralized applications on iExec +- Anyone can run tasks against payment in RLC on iExec +- Payments are processed by the decentralized platform between users' iExec + Accounts +- Resource governance is managed by orders + +Continue with these guides: + +- [Learn how to build your first application running on iExec](./build-your-first-app.md) + + diff --git a/src/guides/use-iapp/web3-messaging.md b/src/guides/use-iapp/integrate-web3-messaging.md similarity index 100% rename from src/guides/use-iapp/web3-messaging.md rename to src/guides/use-iapp/integrate-web3-messaging.md diff --git a/src/references/iapp-generator.md b/src/references/iapp-generator.md index f334eaba..11e82e4e 100644 --- a/src/references/iapp-generator.md +++ b/src/references/iapp-generator.md @@ -53,7 +53,7 @@ Once you've built your first iApp, level up with these practical guides: Ready for production? Dive into specialized topics: -- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/create-your-first-tdx-app)** - +- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-app)** - Next-gen TEE with traditional deployment and iApp Generator technology - **[Complete Guides Overview](/guides/build-iapp/build-&-test)** - All development guides in one place diff --git a/src/references/web3telegram.md b/src/references/web3telegram.md index b2034903..2707c18f 100644 --- a/src/references/web3telegram.md +++ b/src/references/web3telegram.md @@ -19,8 +19,8 @@ telegram chat ID recipients through use of Ethereum addresses. iExec's protocol the telegram chat ID as a `protectedData` entity using [iExec Data Protector](/references/dataProtector). Through this mechanism, users have complete control over which applications may use their -[chat ID](/guides/use-iapp/web3-messaging#retrieve-chat-id) for sending -communications. +[chat ID](/guides/use-iapp/integrate-web3-messaging#retrieve-chat-id) for +sending communications. Sending a user a message, therefore, requires knowledge of the Ethereum address of their `protectedData` as well as an explicit authorization for your account From 1038eb3adedf05306a31fa67447b3bc618f8e2fb Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Fri, 22 Aug 2025 00:12:57 +0200 Subject: [PATCH 2/8] refactor: update iApp guides and sidebar links - Renamed sidebar links for clarity, changing 'Build your first application' to 'Build your first iApp' and 'Build Intel TDX app' to 'Build Intel TDX iApp'. - Updated references in documentation to reflect the new iApp terminology and paths. - Added new guides for building Intel TDX and SGX iApps, while removing outdated references to 'Create Your First SGX App'. --- .vitepress/sidebar.ts | 6 +- src/get-started/protocol/tee/intel-sgx.md | 2 +- src/get-started/protocol/tee/intel-tdx.md | 4 +- src/get-started/protocol/tee/introduction.md | 2 +- src/get-started/protocol/tee/sgx-vs-tdx.md | 2 +- .../advanced/access-confidential-assets.md | 10 +- ...-first-app.md => build-your-first-iapp.md} | 89 ++++++++------- ...gx-app.md => build-your-first-sgx-iapp.md} | 32 +++--- ...dx-app.md => build-your-first-tdx-iapp.md} | 29 +++-- .../advanced/create-your-first-sgx-app.md | 0 .../build-iapp/advanced/protect-the-result.md | 11 +- .../advanced/quick-start-for-developers.md | 0 src/guides/build-iapp/advanced/quick-start.md | 4 +- src/references/iapp-generator.md | 2 +- .../iapp-generator/building-your-iexec-app.md | 103 +++++++++++------- 15 files changed, 159 insertions(+), 137 deletions(-) rename src/guides/build-iapp/advanced/{build-your-first-app.md => build-your-first-iapp.md} (81%) rename src/guides/build-iapp/advanced/{build-your-first-sgx-app.md => build-your-first-sgx-iapp.md} (89%) rename src/guides/build-iapp/advanced/{build-your-first-tdx-app.md => build-your-first-tdx-iapp.md} (90%) delete mode 100644 src/guides/build-iapp/advanced/create-your-first-sgx-app.md delete mode 100644 src/guides/build-iapp/advanced/quick-start-for-developers.md diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index bac9cc53..c170a31d 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -208,11 +208,11 @@ export function getSidebar() { }, { text: 'Build your first application', - link: '/guides/build-iapp/advanced/build-your-first-app', + link: '/guides/build-iapp/advanced/build-your-first-iapp', }, { text: 'Build your first SGX app', - link: '/guides/build-iapp/advanced/create-your-first-sgx-app', + link: '/guides/build-iapp/advanced/build-your-first-sgx-iapp', }, { text: 'End-to-end Encryption', @@ -224,7 +224,7 @@ export function getSidebar() { }, { text: 'Build Intel TDX app', - link: '/guides/build-iapp/advanced/build-your-first-tdx-app', + link: '/guides/build-iapp/advanced/build-your-first-tdx-iapp', }, ], }, diff --git a/src/get-started/protocol/tee/intel-sgx.md b/src/get-started/protocol/tee/intel-sgx.md index f21db094..74fe41b0 100644 --- a/src/get-started/protocol/tee/intel-sgx.md +++ b/src/get-started/protocol/tee/intel-sgx.md @@ -144,5 +144,5 @@ graph TD - **[Deploy & Run](/guides/build-iapp/deploy-&-run)** - Create your first SGX application -- **[Advanced SGX Development](/guides/build-iapp/advanced/create-your-first-sgx-app)** - +- **[Advanced SGX Development](/guides/build-iapp/advanced/build-your-first-sgx-iapp)** - Deep dive into SGX development diff --git a/src/get-started/protocol/tee/intel-tdx.md b/src/get-started/protocol/tee/intel-tdx.md index fa083bb2..eff8f0db 100644 --- a/src/get-started/protocol/tee/intel-tdx.md +++ b/src/get-started/protocol/tee/intel-tdx.md @@ -137,9 +137,9 @@ graph TD **Ready to experiment with TDX?** Check out the practical guides: -- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-app)** - +- **[Build Intel TDX iApp (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-iapp)** - Build TDX applications with traditional deployment and iApp Generator -- **[Build Your First TDX App](/guides/build-iapp/advanced/build-your-first-tdx-app)** - +- **[Build Your First TDX iApp](/guides/build-iapp/advanced/build-your-first-tdx-iapp)** - Build TDX applications **For production applications, use SGX**: diff --git a/src/get-started/protocol/tee/introduction.md b/src/get-started/protocol/tee/introduction.md index 58be2126..54b4084a 100644 --- a/src/get-started/protocol/tee/introduction.md +++ b/src/get-started/protocol/tee/introduction.md @@ -119,7 +119,7 @@ TEE technologies have evolved to address different use cases: **Ready to build with TEE?** Check out the practical guides: -- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-app)** - +- **[Build Intel TDX iApp (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-iapp)** - Build TDX applications with traditional deployment and iApp Generator - **[Deploy & Run](/guides/build-iapp/deploy-&-run)** - Create your first TEE application diff --git a/src/get-started/protocol/tee/sgx-vs-tdx.md b/src/get-started/protocol/tee/sgx-vs-tdx.md index bdbb89c4..fa713a49 100644 --- a/src/get-started/protocol/tee/sgx-vs-tdx.md +++ b/src/get-started/protocol/tee/sgx-vs-tdx.md @@ -79,7 +79,7 @@ technology** for advanced use cases. **Ready to build with TEE?** Check out the practical guides: -- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-app)** - +- **[Build Intel TDX iApp (Experimental)](/guides/build-iapp/advanced/build-your-first-tdx-iapp)** - Build TDX applications with traditional deployment and iApp Generator - **[Deploy & Run](/guides/build-iapp/deploy-&-run)** - Create your first TEE application diff --git a/src/guides/build-iapp/advanced/access-confidential-assets.md b/src/guides/build-iapp/advanced/access-confidential-assets.md index 4518cd97..fce0ea7f 100644 --- a/src/guides/build-iapp/advanced/access-confidential-assets.md +++ b/src/guides/build-iapp/advanced/access-confidential-assets.md @@ -1,17 +1,17 @@ --- -title: Access Confidential Assets from Your App +title: Access Confidential Assets from Your iApp description: Learn how to access confidential assets including secrets, protected data, and requester secrets from your iExec application using the Secret Management Service --- -# Access confidential assets from your app +# Access confidential assets from your iApp ::: warning Before going any further, make sure you managed to -[Build your first application with Scone framework](create-your-first-sgx-app.md). +[Build your first application with Scone framework](build-your-first-sgx-iapp.md). ::: @@ -53,8 +53,8 @@ graph TD ProtectedDataOwn[ProtectedData owner] -->|1.c. Push secret| SMS Req --> |2 . Buy task| Chain Chain[Blockchain] --> |3 . Notify task to compute| Worker[Worker/Workerpool] - Worker --> |4 . Launch TEE application| App[TEE application] - App --> |5.a. Get secrets for task| SMS + Worker --> |4 . Launch TEE application| iApp[TEE application] + iApp --> |5.a. Get secrets for task| SMS SMS --> |5.b. Check authorization for secrets| Chain ``` diff --git a/src/guides/build-iapp/advanced/build-your-first-app.md b/src/guides/build-iapp/advanced/build-your-first-iapp.md similarity index 81% rename from src/guides/build-iapp/advanced/build-your-first-app.md rename to src/guides/build-iapp/advanced/build-your-first-iapp.md index 0fc9a29e..ced98339 100644 --- a/src/guides/build-iapp/advanced/build-your-first-app.md +++ b/src/guides/build-iapp/advanced/build-your-first-iapp.md @@ -1,14 +1,14 @@ --- -title: Build Your First Application +title: Build Your First iApp description: - In this section we will show you how you can create a Docker dapp over the - iExec infrastructure. + In this section we will show you how you can create an iApp over the iExec + infrastructure. --- -# Build your first application +# Build your first iApp -> In this section we will show you how you can create a Docker dapp over the -> iExec infrastructure. +> In this section we will show you how you can create an iApp (iExec +> confidential application) over the iExec infrastructure. ::: tip Prerequisites @@ -16,15 +16,14 @@ description: client. - [Dockerhub](https://hub.docker.com/) account. - [iExec SDK](https://www.npmjs.com/package/iexec) 8.0.0 or higher. - [Install the iExec SDK](quick-start-for-developers.md#install-the-iexec-sdk). -- [Quickstart](quick-start-for-developers.md) tutorial completed +- [Quickstart](./quick-start.md) tutorial completed ::: -In this guide, we will prepare an iExec app based on an existing docker image +In this guide, we will prepare an iExec iApp based on an existing docker image and we will run it on iExec decentralized infrastructure. -## Understand what is an iExec decentralized application? +## Understand what is an iExec decentralized application (iApp)? iExec leverage [Docker](https://www.docker.com/why-docker) containers to ensure the execution of your application on a decentralized infrastructure. iExec @@ -46,19 +45,19 @@ supports Linux-based docker images. Today you can run any application as a task. This means services are not supported for now. -## Build your app +## Build your iApp Create the folder tree for your application in `~/iexec-projects/`. ```bash cd ~/iexec-projects -mkdir hello-world-app -cd hello-world-app +mkdir hello-world-iapp +cd hello-world-iapp mkdir src touch Dockerfile ``` -### Write the app +### Write the iApp ::: warning @@ -137,7 +136,7 @@ application. Execution logs are accessible by: ::: -### Dockerize your app +### Dockerize your iApp **Copy the following content** in `Dockerfile` . @@ -192,7 +191,7 @@ way to name the image to reuse it in the next steps. **Congratulations you built your first docker image for iExec!** -## Test your app locally +## Test your iApp locally ### Basic test @@ -261,9 +260,9 @@ docker run \ arg1 arg2 arg3 ``` -## Test your app on iExec +## Test your iApp on iExec -### Push your app to Dockerhub +### Push your iApp to Dockerhub Login to your Dockerhub account. @@ -289,12 +288,12 @@ Push the image to Dockerhub. docker push /hello-world:1.0.0 ``` -**Congratulations, your app is ready to be deployed on iExec!** +**Congratulations, your iApp is ready to be deployed on iExec!** -### Deploy your app on iExec +### Deploy your iApp on iExec -You already learned how to deploy the default app on iExec in the -[previous tutorial](quick-start-for-developers.md). +You already learned how to deploy the default iApp on iExec in the +[previous tutorial](./quick-start.md). Go back to the `iexec-project` folder. @@ -302,17 +301,17 @@ Go back to the `iexec-project` folder. cd ~/iexec-projects/ ``` -You will need a few configurations in `iexec.json` to deploy your app: +You will need a few configurations in `iexec.json` to deploy your iApp: -- Replace app **name** with your application name \(display only\) -- Replace app **multiaddr** with your app image download URI \(should looks like - `docker.io//hello-world:1.0.0`\) -- Replace app **checksum** with your application image checksum \(see tip +- Replace iApp **name** with your application name \(display only\) +- Replace iApp **multiaddr** with your iApp image download URI \(should looks + like `docker.io//hello-world:1.0.0`\) +- Replace iApp **checksum** with your application image checksum \(see tip below\) ::: info -The checksum of your app is the sha256 digest of the docker image prefixed with +The checksum of your iApp is the sha256 digest of the docker image prefixed with `0x` , you can use the following command to get it. ```bash @@ -321,19 +320,19 @@ docker pull /hello-world:1.0.0 | grep "Digest: sha256:" | sed ' ::: -Deploy your app on iExec +Deploy your iApp on iExec ```bash twoslash iexec app deploy --chain {{chainName}} ``` -Verify the deployed app \(name, multiaddr, checksum, owner\) +Verify the deployed iApp \(name, multiaddr, checksum, owner\) ```bash twoslash iexec app show --chain {{chainName}} ``` -### Run your app on iExec +### Run your iApp on iExec ```bash twoslash iexec app run --chain {{chainName}} --workerpool {{workerpoolAddress}} --watch @@ -343,19 +342,19 @@ iexec app run --chain {{chainName}} --workerpool {{workerpoolAddress}} --watch **Using arguments:** -You can pass arguments to the app using `--args ` option. +You can pass arguments to the iApp using `--args ` option. -With `--args "dostuff --with-option"` the app will receive +With `--args "dostuff --with-option"` the iApp will receive `["dostuff", "--with-option"]` as process args. **Using input files:** -You can pass input files to the app using `--input-files ` option. +You can pass input files to the iApp using `--input-files ` option. With `--input-files https://example.com/file-A.txt,https://example.com/file-B.zip` -the iExec worker will download the files before running the app in `IEXEC_IN`, -and let the app access them through variables: +the iExec worker will download the files before running the iApp in `IEXEC_IN`, +and let the iApp access them through variables: - `file-A.txt` as`IEXEC_INPUT_FILE_NAME_1` - `file-B.zip` as`IEXEC_INPUT_FILE_NAME_2` @@ -370,9 +369,9 @@ iexec task show --chain {{chainName}} --download my-app-result \ && unzip my-app-result.zip -d my-app-result ``` -**Congratulations your app successfully ran on iExec!** +**Congratulations your iApp successfully ran on iExec!** -## Manage your app's output +## Manage your iApp's output iExec enables running apps producing output files, you will need a place for storing your apps outputs. @@ -390,12 +389,12 @@ the[iExec SDK](https://github.com/iExecBlockchainComputing/iexec-sdk). ::: -## Access to app and task logs on iExec +## Access to iApp and task logs on iExec Sometimes things don't work out right the first time and you may need to [Debug your tasks](/guides/build-iapp/debugging). -## Publish your app on the iExec marketplace +## Publish your iApp on the iExec marketplace ```bash twoslash iexec app publish --chain {{chainName}} @@ -405,14 +404,14 @@ iexec app publish --chain {{chainName}} ## What's next? -In this tutorial you learned about the key concepts for building an app on +In this tutorial you learned about the key concepts for building an iApp on iExec: -- iExec app inputs and outputs -- iExec app must produce a `computed.json` file \(required for the proof of +- iExec iApp inputs and outputs +- iExec iApp must produce a `computed.json` file \(required for the proof of execution\) -- using docker to package your app with all its dependencies -- testing an iExec app locally +- using docker to package your iApp with all its dependencies +- testing an iExec iApp locally - publishing on dockerhub From 2ae480ddcb44e3a802cd97921921b51a925eaa86 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Fri, 22 Aug 2025 00:15:10 +0200 Subject: [PATCH 3/8] docs: refine TDX iApp guide content - Removed redundant section on understanding TDX concepts to streamline the guide. - Updated formatting for clarity and consistency. --- src/guides/build-iapp/advanced/build-your-first-tdx-iapp.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/guides/build-iapp/advanced/build-your-first-tdx-iapp.md b/src/guides/build-iapp/advanced/build-your-first-tdx-iapp.md index a24b5f60..8e9fee25 100644 --- a/src/guides/build-iapp/advanced/build-your-first-tdx-iapp.md +++ b/src/guides/build-iapp/advanced/build-your-first-tdx-iapp.md @@ -19,15 +19,11 @@ instabilities, limited compatibility, and potential outages. ::: -:::info Understanding TDX Concepts - Before implementing TDX, make sure you understand the foundational concepts and differences between TEE technologies. Check out our **[Intel TDX Technology](/get-started/protocol/tee/intel-tdx)** guide for comprehensive explanations of TDX technology and its benefits. -::: - ::: info **Request access to the experimental feature** From 44feb95fa4475334047582aba07b412bf72a7aed Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Fri, 22 Aug 2025 10:20:43 +0200 Subject: [PATCH 4/8] refactor: update CLI command documentation for iApp initialization and testing --- .../iapp-generator/building-your-iexec-app.md | 112 ++++++++++++------ 1 file changed, 75 insertions(+), 37 deletions(-) diff --git a/src/references/iapp-generator/building-your-iexec-app.md b/src/references/iapp-generator/building-your-iexec-app.md index 7a5fa848..1abda4ff 100644 --- a/src/references/iapp-generator/building-your-iexec-app.md +++ b/src/references/iapp-generator/building-your-iexec-app.md @@ -81,7 +81,7 @@ You'll set up: - **Protected Data** โ€“ Encrypted data accessible only inside the TEE. - **App Secret** โ€“ Immutable secret provisioned by the iApp owner. -::: warning ๐Ÿ’ก +::: tip ๐Ÿ’ก The Secret Management Service (SMS) securely stores application developer secrets. Once set, the App Secret is immutable and cannot be updated. Use with @@ -126,68 +126,106 @@ algorithms and data processing here. ## ๐Ÿ› ๏ธ CLI Commands Reference -### Core Commands - -#### `iapp init` +### `iapp init` **Purpose**: Initialize a new iApp project -**Usage**: `iapp init` -**Options**: Interactive prompts for project configuration +**Usage**: `iapp init [options]` **What it does**: Creates project structure, configuration files, and basic -templates +templates through interactive prompts. -#### `iapp test` +### `iapp test` **Purpose**: Test your iApp locally before deployment -**Usage**: `iapp test` -**Options**: None -**What it does**: Runs a basic test locally to validate your application logic +**Usage**: `iapp test [options]` +**Options**: + +- `-v, --version` [boolean] โ€“ Show version number +- `--args ` โ€“ Arguments accessible inside the iApp (use quotes to group) +- `--protectedData ` โ€“ Specify the protected data mock name (default or + custom via `iapp mock`) +- `--inputFile ` โ€“ One or multiple input files (public URLs) available + inside the iApp at `$IEXEC_INPUT_FILE_NAME_*` +- `--requesterSecret ` โ€“ Key-value requester secrets (`index=value`) + available inside the iApp at `$IEXEC_REQUESTER_SECRET_*` -#### `iapp deploy` +### `iapp deploy` **Purpose**: Deploy your iApp to the iExec network -**Usage**: `iapp deploy` -**Options**: None -**What it does**: Turns your code into a TEE app and registers the iApp on iExec +**Usage**: `iapp deploy [options]` +**Options**: -#### `iapp run ` +- `--chain ` โ€“ Specify the blockchain network for deployment (e.g., + `goerli`, `mainnet`) + +### `iapp run ` **Purpose**: Execute your deployed iApp on a worker node -**Usage**: `iapp run ` -**Options**: None -**What it does**: Sends your iApp for execution on the iExec network +**Usage**: `iapp run [options]` +**Positional arguments**: + +- `` โ€“ Address of the deployed iApp to run -#### `iapp debug ` +**Options**: + +- `--args ` โ€“ Arguments accessible inside the iApp (use quotes to group) +- `--protectedData ` โ€“ Specify the protected data mock name (default or + custom via `iapp mock`) +- `--inputFile ` โ€“ One or multiple input files (public URLs) available + inside the iApp at `$IEXEC_INPUT_FILE_NAME_*` +- `--requesterSecret ` โ€“ Key-value requester secrets (`index=value`) + available inside the iApp at `$IEXEC_REQUESTER_SECRET_*` +- `--chain ` โ€“ Specify the blockchain network to run the iApp on (e.g., + `goerli`, `mainnet`) + +### `iapp debug ` **Purpose**: Retrieve detailed execution logs from worker nodes -**Usage**: `iapp debug ` -**Options**: None -**What it does**: Provides detailed logs for debugging failed or slow executions +**Usage**: `iapp debug [options]` +**Positional arguments**: + +- `` โ€“ The ID of the task to debug -#### `iapp mock ` +**Options**: + +- `--chain ` โ€“ Specify the blockchain network of the task (e.g., + `goerli`, `mainnet`) + +### `iapp mock ` **Purpose**: Create mocked input for testing purposes -**Usage**: `iapp mock ` -**Options**: None -**What it does**: Generates sample input data to test your iApp locally +**Usage**: `iapp mock [options]` +**Positional arguments**: + +- `` โ€“ Type of input to mock (e.g., `default`, `custom`) + +**Options**: + +- `--args ` โ€“ Arguments to use in the mock data +- `--protectedData ` โ€“ Protected data mock name to use +- `--inputFile ` โ€“ Input files to mock +- `--requesterSecret ` โ€“ Requester secrets to mock + +### `iapp wallet ` + +**Purpose**: Manage wallet-related operations +**Usage**: `iapp wallet [options]` +**Positional arguments**: -#### `iapp --help` +- `` โ€“ Wallet action to perform (e.g., `balance`, `address`, `sign`) -**Purpose**: Display all available commands and options -**Usage**: `iapp --help` -**Options**: None -**What it does**: Shows comprehensive help information for all CLI commands +**Options**: -### Advanced Options +- `--chain ` โ€“ Specify the blockchain network (e.g., `goerli`, + `mainnet`) +- `--data ` โ€“ Data to sign (for `sign` action) -#### Environment Variables +## Advanced Options -##### `EXPERIMENTAL_TDX_APP=true` +### `EXPERIMENTAL_TDX_APP=true` **Purpose**: Enable experimental Intel TDX support **Usage**: Set as environment variable before running commands -**Example**: `EXPERIMENTAL_TDX_APP=true iapp test` -**What it does**: Enables TDX mode for testing, deployment, and execution +**Example**: `EXPERIMENTAL_TDX_APP=true iapp test` **Available with**: From a23f88d896df28458d2716e8428286915ad6f700 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Fri, 22 Aug 2025 10:39:19 +0200 Subject: [PATCH 5/8] docs: update links and references in iApp guides - Replaced outdated protocol documentation links with updated internal paths for better navigation. - Enhanced clarity in the iApp build documentation by linking to relevant advanced guides and resources. - Removed redundant sections to streamline content and improve user experience. --- src/get-started/helloWorld/1-overview.md | 2 +- src/get-started/helloWorld/3-buildIApp.md | 4 ++-- src/guides/build-iapp/inputs-and-outputs.md | 6 ------ src/guides/build-iapp/manage-access.md | 2 -- .../dataProtector/advanced/apps-whitelist.md | 2 +- .../dataProtectorCore/processProtectedData.md | 2 +- .../consume/consumeProtectedData.md | 2 +- src/references/dataProtector/types.md | 8 ++++---- src/references/iapp-generator.md | 2 -- .../iapp-generator/building-your-iexec-app.md | 19 ++++--------------- 10 files changed, 14 insertions(+), 35 deletions(-) diff --git a/src/get-started/helloWorld/1-overview.md b/src/get-started/helloWorld/1-overview.md index 4863a05b..9ff80713 100644 --- a/src/get-started/helloWorld/1-overview.md +++ b/src/get-started/helloWorld/1-overview.md @@ -70,7 +70,7 @@ lifecycle - during storage, transfer, and even while **being processed by applications.** This is made possible thanks to -Trusted +Trusted Execution Environment (TEE) and Confidential Computing technologies. diff --git a/src/get-started/helloWorld/3-buildIApp.md b/src/get-started/helloWorld/3-buildIApp.md index 6ab83a99..c35141dc 100644 --- a/src/get-started/helloWorld/3-buildIApp.md +++ b/src/get-started/helloWorld/3-buildIApp.md @@ -394,8 +394,8 @@ iapp run To sum up the process, we take the **iApp** and wrap it in the iExec framework, allowing it to run securely in a **Trusted Execution Environment (TEE)** for -**confidential computing**. If you want to explore further, you can check the -protocol documentation [here](https://protocol.docs.iex.ec/). +**confidential computing**. To learn more, check out the +[advanced iApp build documentation](guides/build-iapp/advanced/quick-start).

๐ŸŽ‰ Congratulations! You've successfully deployed and run your first iApp on iExec. This is a significant milestone - your application is now ready to securely process confidential data in a trusted environment.

diff --git a/src/guides/build-iapp/inputs-and-outputs.md b/src/guides/build-iapp/inputs-and-outputs.md index 6b9a5b3c..be9f9d71 100644 --- a/src/guides/build-iapp/inputs-and-outputs.md +++ b/src/guides/build-iapp/inputs-and-outputs.md @@ -605,9 +605,3 @@ Continue building with these guides: execution issues - **[How to Get and Decrypt Results](/guides/build-iapp/inputs-and-outputs)** - User-side result handling - -### Technical Deep Dive - -- **[SDK Deep Dive](/references/sdk)** - Advanced SDK concepts -- **[Application I/O Protocol Docs](https://protocol.docs.iex.ec/for-developers/application-io)** - - Low-level protocol details diff --git a/src/guides/build-iapp/manage-access.md b/src/guides/build-iapp/manage-access.md index 6efb38ff..a9707208 100644 --- a/src/guides/build-iapp/manage-access.md +++ b/src/guides/build-iapp/manage-access.md @@ -306,8 +306,6 @@ Next steps: - **[iExec SDK Documentation](https://github.com/iExecBlockchainComputing/iexec-sdk)** - Complete CLI reference -- **[Official Orders Documentation](https://protocol.docs.iex.ec/for-developers/advanced/manage-your-apporders)** - - Protocol-level order management