From 3d9b5594a88c0f78705f1e2b0b64b3663076fa63 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Mon, 18 Aug 2025 19:43:41 +0200 Subject: [PATCH 01/17] fix: Refactor documentation and code examples for iApp result handling - Updated links in debugging and inputs/outputs guides to reflect new result decryption guide. - Added new guide on downloading and decrypting iApp results, detailing the process and providing code examples. - Removed outdated debug mode option from access management guide. - Streamlined input handling sections in execution guides, consolidating command-line argument examples. - Enhanced getting started guide with clearer prerequisites and installation instructions. - Removed unnecessary debug-related code snippets from the DataProtector documentation. - Updated iApp generator documentation to clarify project modes and removed debug mode references. - Improved formatting and clarity in the getting started guide for the iApp generator. --- .vitepress/sidebar.ts | 4 +- src/get-started/helloWorld/3-buildIApp.md | 8 +- src/guides/build-iapp/build-&-deploy.md | 115 ++---- src/guides/build-iapp/debugging.md | 2 +- ...lts.md => download-and-decrypt-results.md} | 84 +---- src/guides/build-iapp/inputs-and-outputs.md | 4 +- src/guides/manage-data/manage-access.md | 21 -- .../use-iapp/add-inputs-to-execution.md | 224 +----------- .../use-iapp/different-ways-to-execute.md | 76 +--- src/guides/use-iapp/getting-started.md | 37 +- .../use-iapp/use-iapp-with-protected-data.md | 333 +----------------- src/modules/helloWorld/ProtectData.vue | 9 +- .../dataProtectorCore/protectData.md | 28 -- src/references/iapp-generator.md | 9 +- .../iapp-generator/building-your-iexec-app.md | 13 +- .../iapp-generator/getting-started.md | 26 +- 16 files changed, 89 insertions(+), 904 deletions(-) rename src/guides/build-iapp/{how-to-get-and-decrypt-results.md => download-and-decrypt-results.md} (76%) diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index af4a6d47..87e2e559 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -182,8 +182,8 @@ export function getSidebar() { link: '/guides/build-iapp/using-tdx', }, { - text: 'How to Get and Decrypt Results', - link: '/guides/build-iapp/how-to-get-and-decrypt-results', + text: 'Download and Decrypt Results', + link: '/guides/build-iapp/download-and-decrypt-results', }, { text: 'Debugging', diff --git a/src/get-started/helloWorld/3-buildIApp.md b/src/get-started/helloWorld/3-buildIApp.md index 554dd493..6ab83a99 100644 --- a/src/get-started/helloWorld/3-buildIApp.md +++ b/src/get-started/helloWorld/3-buildIApp.md @@ -489,7 +489,7 @@ const arbitrumSteps = [ }, { showAt: 13, - question: 'Pushed TEE image bob/hello-world:0.0.1-tee-scone-5.9.1-v16-debug-ce3a01d9c5d7 on dockerhub', + question: 'Pushed TEE image bob/hello-world:0.0.1-tee-scone-5.9.1-v16-ce3a01d9c5d7 on dockerhub', answer: '', showTyping: false, isComplete: true @@ -558,7 +558,7 @@ const bellecourSteps = [ }, { showAt: 12, - question: 'Pushed TEE image bob/hello-world:0.0.1-tee-scone-5.9.1-v16-debug-ce3a01d9c5d7 on dockerhub', + question: 'Pushed TEE image bob/hello-world:0.0.1-tee-scone-5.9.1-v16-ce3a01d9c5d7 on dockerhub', answer: '', showTyping: false, isComplete: true @@ -573,12 +573,12 @@ const bellecourSteps = [ ]; const arbitrumCompletionItems = [ - '└ Docker image: bob/hello-world:0.0.1-tee-scone-5.9.1-v16-debug-ce3a01d9c5d7', + '└ Docker image: bob/hello-world:0.0.1-tee-scone-5.9.1-v16-ce3a01d9c5d7', '└ iApp address: 0x1f80DCebc2EAAff0Db7156413C43B7e88D189923' ]; const bellecourCompletionItems = [ - '└ Docker image: bob/hello-world:0.0.1-tee-scone-5.9.1-v16-debug-ce3a01d9c5d7', + '└ Docker image: bob/hello-world:0.0.1-tee-scone-5.9.1-v16-ce3a01d9c5d7', '└ iApp address: 0x1f80DCebc2EAAff0Db7156413C43B7e88D189923' ]; diff --git a/src/guides/build-iapp/build-&-deploy.md b/src/guides/build-iapp/build-&-deploy.md index ac6a28dc..459bbe3e 100644 --- a/src/guides/build-iapp/build-&-deploy.md +++ b/src/guides/build-iapp/build-&-deploy.md @@ -30,10 +30,27 @@ iApp Generator handles all the low-level complexity for you. Before getting started, make sure you have the following installed: -- **Node.js** (version 18 or higher) - [Download here](https://nodejs.org/) -- **Docker** - [Download here](https://www.docker.com/get-started) -- **Docker Hub account** - [Sign up here](https://hub.docker.com/) (required for - deployment) +
+
+
+ 📦 Node.js v20+ +
+ Download → +
+
+
+ 🐳 Docker installed +
+ Download → +
+ +
+
+ 🐳 DockerHub Account +
+ Sign Up → +
+
## Installation @@ -220,88 +237,6 @@ specify your app version, and push both standard and TEE-compatible images: /> -## Real Examples - -Here are some real-world examples of iApp to help you understand how they work -in practice. - -### Email Notification iApp - -This iApp lets you send updates to your contacts without ever seeing their email -addresses, privacy is preserved by design. - -::: code-group - -```js [Node.js] -/* User runs: "Send updates to my contacts about my project" */ -const contacts = loadProtectedData(); // User's protected contact list -contacts.forEach((contact) => { - sendEmail(contact, projectUpdateMessage); -}); -// → Emails sent directly, you never see the addresses -``` - -```python [Python] -# User runs: "Send updates to my contacts about my project" -contacts = load_protecteddata() # User's protected contact list -for contact in contacts: - send_email(contact, project_update_message) -# → Emails sent directly, you never see the addresses -``` - -::: - -### Oracle Update iApp - -This iApp securely updates a price oracle using private trading data, ensuring -sensitive information stays confidential. - -::: code-group - -```js [Node.js] -// User runs: "Update price oracle with my private trading data" -const tradingData = loadProtectedData(); // User's protected trading history -const averagePrice = calculateWeightedAverage(tradingData); -updateOracleContract(averagePrice); -// → Oracle updated with real data, trading history stays private -``` - -```python [Python] -# User runs: "Update price oracle with my private trading data" -trading_data = load_protecteddata() # User's protected trading history -average_price = calculate_weighted_average(trading_data) -update_oracle_contract(average_price) -# → Oracle updated with real data, trading history stays private -``` - -::: - -### Automated Transactions iApp - -This iApp automates monthly payments using protected payment details, so -financial information remains private. - -::: code-group - -```js [Node.js] -// User runs: "Automate payments every month" -const paymentInfo = loadProtectedData(); // User's payment details -for (let month = 0; month < 12; month++) { - processPayment(paymentInfo); -} -// → Payments processed, payment details stay private -``` - -```python [Python] -# User runs: "Automate payments every month" -payment_info = load_protecteddata() # User's payment details -for month in range(12): - process_payment(payment_info) -# → Payments processed, payment details stay private -``` - -::: - diff --git a/src/guides/build-iapp/debugging.md b/src/guides/build-iapp/debugging.md index 17e9c5a2..aad98af2 100644 --- a/src/guides/build-iapp/debugging.md +++ b/src/guides/build-iapp/debugging.md @@ -171,5 +171,5 @@ Continue improving your iApp: - **[Inputs and Outputs](/guides/build-iapp/inputs-and-outputs)** - Handle data in TEE -- **[How to Get and Decrypt Results](/guides/build-iapp/how-to-get-and-decrypt-results)** - +- **[How to Get and Decrypt Results](/guides/build-iapp/download-and-decrypt-results)** - Retrieve results diff --git a/src/guides/build-iapp/how-to-get-and-decrypt-results.md b/src/guides/build-iapp/download-and-decrypt-results.md similarity index 76% rename from src/guides/build-iapp/how-to-get-and-decrypt-results.md rename to src/guides/build-iapp/download-and-decrypt-results.md index f56bef05..64bdc61e 100644 --- a/src/guides/build-iapp/how-to-get-and-decrypt-results.md +++ b/src/guides/build-iapp/download-and-decrypt-results.md @@ -3,7 +3,7 @@ title: How to Get and Decrypt Results description: Download and decrypt iApp execution results from completed tasks --- -# 📦 How to Get and Decrypt Results +# 📦 Download and Decrypt Results **When an iApp execution completes, you need to retrieve and decrypt the results.** This guide shows you how to download task results and decrypt them to @@ -40,36 +40,11 @@ Deal (agreement between parties) - 📁 **Results contain** all files from `IEXEC_OUT` directory - ⚡ **Available immediately** after task completion -## Downloading Results +## Download & Decrypt Results -### Using iExec SDK CLI - -**Get task information and download**: - -```bash -# Check task status and get result info -iexec task show - -# Download encrypted result -iexec task show --download my-result - -# Extract downloaded files -unzip my-result.zip -d my-result/ -ls my-result/ -``` - -**Get task ID from deal**: - -```bash -# If you only have the deal ID -iexec deal show - -# Lists all tasks in the deal with their IDs -``` - -### Using DataProtector SDK - -**Integrated download and decryption**: +DataProtector provides methods to download and decrypt results from completed +tasks. You can view the `taskId` in your +[iExec Explorer](https://explorer.iex.ec/). ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; @@ -77,7 +52,7 @@ import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; const web3Provider = getWeb3Provider('PRIVATE_KEY'); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); // ---cut--- -// Get result from completed task +// Get result from a completed task const result = await dataProtectorCore.getResultFromCompletedTask({ taskId: '0x123abc...', // Your task ID }); @@ -85,51 +60,12 @@ const result = await dataProtectorCore.getResultFromCompletedTask({ console.log('Result downloaded and decrypted:', result); ``` -## Decrypting Results +::: tip Info -### Automatic Decryption with DataProtector - -**The easiest way** - decryption happens automatically: - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; +The `processProtectedData` method will create a task and automatically download +and decrypt the result. -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Execute and get results in one flow -const processResponse = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', - app: '0x456def...', -}); - -console.log('Task ID:', processResponse.taskId); - -// Get decrypted result -const result = await dataProtectorCore.getResultFromCompletedTask({ - taskId: processResponse.taskId, -}); - -// Result is automatically decrypted ArrayBuffer -const resultText = new TextDecoder().decode(result.result); -console.log('Decrypted result:', resultText); -``` - -### Manual Decryption with CLI - -**If you downloaded manually**: - -```bash -# Download the encrypted result -iexec task show --download my-result - -# Decrypt using your wallet (must be the beneficiary) -iexec result decrypt my-result.zip --force - -# Extract decrypted files -unzip decrypted-result.zip -d final-result/ -cat final-result/result.txt -``` +::: ## Result File Structure diff --git a/src/guides/build-iapp/inputs-and-outputs.md b/src/guides/build-iapp/inputs-and-outputs.md index 1012a2e6..056476b7 100644 --- a/src/guides/build-iapp/inputs-and-outputs.md +++ b/src/guides/build-iapp/inputs-and-outputs.md @@ -618,7 +618,7 @@ save_report(report) Once your iApp completes execution, users can retrieve and decrypt the results: → **Learn how users get results**: Check our -[How to Get and Decrypt Results](/guides/build-iapp/how-to-get-and-decrypt-results) +[How to Get and Decrypt Results](/guides/build-iapp/download-and-decrypt-results) guide for the complete user workflow. ## What's Next? @@ -631,7 +631,7 @@ Continue building with these guides: Control who can use your iApp - **[Debugging Your iApp](/guides/build-iapp/debugging)** - Troubleshoot execution issues -- **[How to Get and Decrypt Results](/guides/build-iapp/how-to-get-and-decrypt-results)** - +- **[How to Get and Decrypt Results](/guides/build-iapp/download-and-decrypt-results)** - User-side result handling ### Technical Deep Dive diff --git a/src/guides/manage-data/manage-access.md b/src/guides/manage-data/manage-access.md index 7b37b486..8f2ecde1 100644 --- a/src/guides/manage-data/manage-access.md +++ b/src/guides/manage-data/manage-access.md @@ -79,27 +79,6 @@ for detailed formatting instructions. ::: -### Debug Mode Option - -Debug mode lets you test with debug iApp during development. As "debug" iApp -don't have the same security standards, we recommend using this mode only during -iApp development. - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- - -const protectedData = await dataProtectorCore.protectData({ - data: { - email: 'test@example.com', - }, - allowDebug: true, // [!code focus] -}); -``` - ## Grant Access By default, your protected data is private. To let others use it, you need to diff --git a/src/guides/use-iapp/add-inputs-to-execution.md b/src/guides/use-iapp/add-inputs-to-execution.md index eb6d321e..3d88eb68 100644 --- a/src/guides/use-iapp/add-inputs-to-execution.md +++ b/src/guides/use-iapp/add-inputs-to-execution.md @@ -20,74 +20,11 @@ iExec supports several types of inputs for iApp executions: 3. **Secrets**: Sensitive data like API keys stored securely 4. **Protected Data**: Encrypted data processed within the TEE -## Method 1: Adding Command-Line Arguments +## Adding Command-Line Arguments Command-line arguments are passed as a string to the iApp and are visible on the blockchain. -### Using SDK Library - -```ts twoslash -import { IExec, utils } from 'iexec'; - -const ethProvider = utils.getSignerFromPrivateKey( - 'bellecour', // blockchain node URL - 'PRIVATE_KEY' -); -const iexec = new IExec({ - ethProvider, -}); -// ---cut--- -// Basic arguments -const requestorderToSign = await iexec.order.createRequestorder({ - app: '0x456def...', - category: 0, - appmaxprice: 10, - workerpool: '0xa5de76...', // ENS address for iExec's debug workerpool - params: 'arg1 arg2 arg3', // Command-line arguments - // Other parameters have default values -}); -const requestOrder = await iexec.order.signRequestorder(requestorderToSign); - -// Fetch app orders -const appOrders = await iexec.orderbook.fetchAppOrderbook( - '0x456def...' // Filter by specific app -); -if (appOrders.orders.length === 0) { - throw new Error('No app orders found for the specified app'); -} - -// Fetch workerpool orders -const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ - workerpool: '0xa5de76...', // Filter by specific workerpool -}); -if (workerpoolOrders.orders.length === 0) { - throw new Error('No workerpool orders found for the specified workerpool'); -} - -// Execute the task -const taskId = await iexec.order.matchOrders({ - requestorder: requestOrder, - apporder: appOrders.orders[0].order, - workerpoolorder: workerpoolOrders.orders[0].order, -}); -``` - -### Using SDK CLI - -```bash -# Basic arguments -iexec app run 0x456def... --protectedData 0x123abc... --args "arg1 arg2" - -# Complex arguments with spaces -iexec app run 0x456def... --protectedData 0x123abc... --args "--input-file data.csv --output-format json" - -# Arguments with quotes (escape properly) -iexec app run 0x456def... --protectedData 0x123abc... --args "--message \"Hello World\" --config '{\"key\": \"value\"}'" -``` - -### Using DataProtector - ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; @@ -102,79 +39,11 @@ const result = await dataProtectorCore.processProtectedData({ }); ``` -## Method 2: Adding Input Files +## Adding Input Files Input files are URLs to public files that the iApp can download during execution. -### Using SDK Library - -```ts twoslash -import { IExec, utils } from 'iexec'; - -const ethProvider = utils.getSignerFromPrivateKey( - 'bellecour', // blockchain node URL - 'PRIVATE_KEY' -); -const iexec = new IExec({ - ethProvider, -}); -// ---cut--- -// Single input file -const requestorderToSign = await iexec.order.createRequestorder({ - app: '0x456def...', - category: 0, // Required: category for the request - appmaxprice: 10, - workerpool: '0xa5de76...', // ENS address for iExec's debug workerpool - params: { - iexec_input_files: [ - 'https://example.com/config.json', - 'https://example.com/template.html', - 'https://example.com/data.csv', - ], - }, -}); -const requestOrder = await iexec.order.signRequestorder(requestorderToSign); - -// Fetch app orders -const appOrders = await iexec.orderbook.fetchAppOrderbook( - '0x456def...' // Filter by specific app -); -if (appOrders.orders.length === 0) { - throw new Error('No app orders found for the specified app'); -} - -// Fetch workerpool orders -const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ - workerpool: '0xa5de76...', // Filter by specific workerpool -}); -if (workerpoolOrders.orders.length === 0) { - throw new Error('No workerpool orders found for the specified workerpool'); -} - -// Execute the task -const taskId = await iexec.order.matchOrders({ - requestorder: requestOrder, - apporder: appOrders.orders[0].order, - workerpoolorder: workerpoolOrders.orders[0].order, -}); -``` - -### Using SDK CLI - -```bash -# Single input file -iexec app run 0x456def... --protectedData 0x123abc... --inputFiles "https://example.com/config.json" - -# Multiple input files (comma-separated) -iexec app run 0x456def... --protectedData 0x123abc... --inputFiles "https://example.com/config.json,https://example.com/template.html" - -# Multiple input files (space-separated) -iexec app run 0x456def... --protectedData 0x123abc... --inputFiles "https://example.com/config.json" --inputFiles "https://example.com/template.html" -``` - -### Using DataProtector - ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; @@ -192,76 +61,11 @@ const result = await dataProtectorCore.processProtectedData({ }); ``` -## Method 3: Adding Secrets +## Adding Secrets Secrets are sensitive data like API keys, passwords, or tokens that are stored securely and made available to the iApp as environment variables. -### Using SDK Library - -```ts twoslash [Browser] -// @errors: 2345 2739 7053 2339 -import { IExec, utils } from 'iexec'; - -const ethProvider = utils.getSignerFromPrivateKey( - 'bellecour', // blockchain node URL - 'PRIVATE_KEY' -); -const iexec = new IExec({ - ethProvider, -}); -// ---cut--- -// Basic secrets -const requestorderToSign = await iexec.order.createRequestorder({ - app: '0x456def...', - category: 0, // Required: category for the request - appmaxprice: 10, - workerpool: '0xa5de76...', // ENS address for iExec's debug workerpool - params: { - iexec_secrets: { - 1: 'api-key-12345', - 2: 'database-password', - }, - }, -}); -const requestOrder = await iexec.order.signRequestorder(requestorderToSign); - -// Fetch app orders -const appOrders = await iexec.orderbook.fetchAppOrderbook( - '0x456def...' // Filter by specific app -); -if (appOrders.orders.length === 0) { - throw new Error('No app orders found for the specified app'); -} - -// Fetch workerpool orders -const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ - workerpool: '0xa5de76...', // Filter by specific workerpool -}); -if (workerpoolOrders.orders.length === 0) { - throw new Error('No workerpool orders found for the specified workerpool'); -} - -// Execute the task -const taskId = await iexec.order.matchOrders({ - requestorder: requestOrder, - apporder: appOrders.orders[0].order, - workerpoolorder: workerpoolOrders.orders[0].order, -}); -``` - -### Using SDK CLI - -```bash -# Note: CLI doesn't support secrets directly for security reasons -# Use the SDK for secret management - -# Alternative: Use environment variables (less secure) -export IEXEC_SECRET_1="api-key-12345" -export IEXEC_SECRET_2="database-password" -iexec app run 0x456def... --protectedData 0x123abc... -``` - ### Using DataProtector ```ts twoslash @@ -281,7 +85,7 @@ const result = await dataProtectorCore.processProtectedData({ }); ``` -## Method 4: Specifying File Paths in Protected Data +## Specifying File Paths in Protected Data When working with protected data that contains multiple files, you can specify which file to process. @@ -308,26 +112,6 @@ const taskResult = await dataProtectorCore.getResultFromCompletedTask({ }); ``` -You can combine different types of inputs for complex executions. - -## How Secrets Work in iApp - -Inside the iApp, secrets are available as environment variables: - -```python -# Python iApp example -import os - -api_key = os.environ.get('IEXEC_SECRET_1') # 'api-key-12345' -db_password = os.environ.get('IEXEC_SECRET_2') # 'database-password' -``` - -```javascript -// JavaScript iApp example -const apiKey = process.env.IEXEC_SECRET_1; // 'api-key-12345' -const dbPassword = process.env.IEXEC_SECRET_2; // 'database-password' -``` - ## Next Steps Now that you understand how to add inputs to iApp executions: diff --git a/src/guides/use-iapp/different-ways-to-execute.md b/src/guides/use-iapp/different-ways-to-execute.md index bd9f25dc..eb549b19 100644 --- a/src/guides/use-iapp/different-ways-to-execute.md +++ b/src/guides/use-iapp/different-ways-to-execute.md @@ -9,75 +9,7 @@ There are multiple ways to execute iApp on the iExec network. This guide covers the basic execution methods. For advanced features like protected data, arguments, and input files, see the dedicated guides. -::: tip ENS Addresses - -**ENS (Ethereum Name Service)** is a naming system for Ethereum addresses that -allows you to use human-readable names instead of long hexadecimal addresses. -For example, instead of using `0x1234567890abcdef...`, you can use -`debug-v8-learn.main.pools.iexec.eth`. - -In the examples below, we use `debug-v8-learn.main.pools.iexec.eth` which is -iExec's official debug workerpool ENS address. This workerpool is specifically -designed for testing and development purposes on the Bellecour testnet. - -::: - -## Method 1: Using the iExec SDK Library - -The iExec SDK provides a modular JavaScript interface for executing iApp. - -```ts twoslash -import { IExec, utils } from 'iexec'; - -const ethProvider = utils.getSignerFromPrivateKey( - 'bellecour', // blockchain node URL - 'PRIVATE_KEY' -); -const iexec = new IExec({ - ethProvider, -}); -// ---cut--- -// Create & Sign a request order -const requestorderToSign = await iexec.order.createRequestorder({ - app: '0x456def...', // The iApp address - category: 0, -}); -const requestOrder = await iexec.order.signRequestorder(requestorderToSign); - -// Fetch app orders -const appOrders = await iexec.orderbook.fetchAppOrderbook( - '0x456def...' // Filter by specific app -); -if (appOrders.orders.length === 0) { - throw new Error('No app orders found for the specified app'); -} - -// Fetch workerpool orders -const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ - workerpool: '0xa5de76...', // Filter by specific workerpool -}); -if (workerpoolOrders.orders.length === 0) { - throw new Error('No workerpool orders found for the specified workerpool'); -} - -// Execute the task -const taskId = await iexec.order.matchOrders({ - requestorder: requestOrder, - apporder: appOrders.orders[0].order, - workerpoolorder: workerpoolOrders.orders[0].order, -}); -``` - -## Method 2: Using the iExec CLI - -The iExec CLI is perfect for quick executions and automation scripts. - -```bash -# Execute an iApp -iexec app run 0x456def... -``` - -## Method 3: Using the iApp Generator CLI +## Using the iApp Generator CLI The iApp Generator CLI provides a streamlined way to execute iApp, especially for developers who have built their own iApp. @@ -99,12 +31,6 @@ iapp run 0x456def... iapp test ``` -## When to Use Each Method - -- **iExec Library**: For JavaScript applications and web3 integration -- **iExec CLI**: For quick testing and automation scripts -- **iApp Generator CLI**: For developers who have built their own iApp - ## Next Steps - Learn how to diff --git a/src/guides/use-iapp/getting-started.md b/src/guides/use-iapp/getting-started.md index c6be7e09..38a3a9ef 100644 --- a/src/guides/use-iapp/getting-started.md +++ b/src/guides/use-iapp/getting-started.md @@ -8,34 +8,33 @@ description: Learn the basics of finding and executing iApp on the iExec network Welcome to secure, privacy-preserving computation! This guide shows you how to use iApp on the iExec confidential computing network. -## Prerequisites +### Prerequisites -Before you begin, make sure you have: +Before getting started, ensure that you have the following installed on your +system: -- A Web3 wallet (MetaMask, WalletConnect, etc.) -- Some RLC tokens for paying computation fees (or access to free vouchers - through learning programs) - - [Learn about RLC tokens](/get-started/overview/rlc) and - [how to bridge them](/get-started/tooling-and-explorers/bridge) -- Basic understanding of blockchain transactions -- iExec SDK installed +\- [**Node.js**](https://nodejs.org/en/) version 18 or higher + +\- [**NPM**](https://docs.npmjs.com/) (Node.js package manager) + +### Installation ::: code-group ```sh [npm] -npm install -g iexec +npm install @iexec/dataprotector ``` ```sh [yarn] -yarn global add iexec +yarn add @iexec/dataprotector ``` ```sh [pnpm] -pnpm add -g iexec +pnpm add @iexec/dataprotector ``` ```sh [bun] -bun add -g iexec +bun add @iexec/dataprotector ``` ::: @@ -81,15 +80,3 @@ For step-by-step instructions, check out these guides: to provide data and parameters to iApp - **[How to Pay for Executions](/guides/use-iapp/how-to-pay-executions)** - Understanding costs and payment options - -## Quick Start - -Ready to jump in? Follow the execution guides for detailed instructions on how -to use iApp. - - diff --git a/src/guides/use-iapp/use-iapp-with-protected-data.md b/src/guides/use-iapp/use-iapp-with-protected-data.md index 2bdb23a0..fb597265 100644 --- a/src/guides/use-iapp/use-iapp-with-protected-data.md +++ b/src/guides/use-iapp/use-iapp-with-protected-data.md @@ -49,49 +49,6 @@ const { address: protectedDataAddress } = await dataProtectorCore.protectData({ }); ``` -### Protecting Different Data Types - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Protect contact list for email applications -const { address: contactListAddress } = await dataProtectorCore.protectData({ - name: 'Email Contact List', - data: { - contacts: { - '0x123abc...': 'john@example.com', - '0x456def...': 'jane@example.com', - '0x789ghi...': 'bob@example.com', - }, - }, -}); - -// Protect trading data for oracle applications -const { address: tradingDataAddress } = await dataProtectorCore.protectData({ - name: 'Trading History', - data: { - trades: { - '2024-01-01': { price: 50000, volume: 100 }, - '2024-01-02': { price: 51000, volume: 150 }, - '2024-01-03': { price: 49000, volume: 200 }, - }, - }, -}); - -// Protect financial data for payment applications -const { address: paymentDataAddress } = await dataProtectorCore.protectData({ - name: 'Payment Information', - data: { - bankAccount: '1234567890', - routingNumber: '987654321', - accountHolder: 'John Doe', - }, -}); -``` - ## Step 2: Grant Access to iApp iApp need explicit authorization to access your protected data. @@ -134,8 +91,6 @@ const grantedAccessList = await dataProtectorCore.getGrantedAccess({ Once access is granted, you can execute the iApp with your protected data. -### Using DataProtector - ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; @@ -149,78 +104,11 @@ const result = await dataProtectorCore.processProtectedData({ }); ``` -### Using SDK Library - -```ts twoslash -import { IExec, utils } from 'iexec'; - -const ethProvider = utils.getSignerFromPrivateKey( - 'bellecour', // blockchain node URL - 'PRIVATE_KEY' -); -const iexec = new IExec({ - ethProvider, -}); -const protectedDataAddress = '0x123abc...'; -// ---cut--- -// Create & Sign a request order with protected data -const requestorderToSign = await iexec.order.createRequestorder({ - app: '0x456def...', // The iApp address - category: 0, - appmaxprice: 10, // Maximum price in nRLC - dataset: protectedDataAddress, // Protected data address - datasetmaxprice: 5, // Maximum price for dataset access - workerpool: '0xa5de76...', // ENS address for iExec's debug workerpool -}); -const requestOrder = await iexec.order.signRequestorder(requestorderToSign); - -// Fetch app orders -const appOrders = await iexec.orderbook.fetchAppOrderbook( - '0x456def...' // Filter by specific app -); -if (appOrders.orders.length === 0) { - throw new Error('No app orders found for the specified app'); -} - -// Fetch protected data orders -const datasetOrders = await iexec.orderbook.fetchDatasetOrderbook( - protectedDataAddress // Filter by specific dataset -); -if (datasetOrders.orders.length === 0) { - throw new Error( - 'No protectedData orders found for the specified protectedData' - ); -} - -// Fetch workerpool orders -const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ - workerpool: '0xa5de76...', // Filter by specific workerpool -}); -if (workerpoolOrders.orders.length === 0) { - throw new Error('No workerpool orders found for the specified workerpool'); -} - -// Execute the task -const taskId = await iexec.order.matchOrders({ - requestorder: requestOrder, - apporder: appOrders.orders[0].order, - datasetorder: datasetOrders.orders[0].order, - workerpoolorder: workerpoolOrders.orders[0].order, -}); -``` - -### Using iExec CLI with Protected Data - -```bash -# Execute with protected data -iexec app run 0x456def... --dataset 0x123abc... -``` - ## Step 4: Retrieve Results -After execution completes, retrieve the results from the task. - -### Using DataProtector +This step is optional. Indeed, `processProtectedData` will automatically +download and decrypt the results for you. Nevertheless, if you want to retrieve +results from a completed task, you can do so as follows: ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; @@ -236,221 +124,6 @@ const taskResult = await dataProtectorCore.getResultFromCompletedTask({ }); ``` -### Using iExec CLI - -```bash -# Get the task ID from the execution result -TASK_ID="0x7ac398..." - -# Retrieve the result -iexec task show $TASK_ID - -# Retrieve a specific file from the result -iexec task show $TASK_ID --path "computed.json" -``` - -## Real-World Examples - -### Example 1: Data Analysis System - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// 1. Protect sensitive dataset -const { address: datasetAddress } = await dataProtectorCore.protectData({ - name: 'Customer Analytics Data', - data: { - customers: { - '0': { id: 1, purchases: 1500, category: 'premium' }, - '1': { id: 2, purchases: 800, category: 'standard' }, - '2': { id: 3, purchases: 2200, category: 'premium' }, - }, - }, -}); - -// 2. Grant access to analytics iApp -await dataProtectorCore.grantAccess({ - protectedData: datasetAddress, - authorizedApp: '0xanalytics...', // Analytics iApp address - authorizedUser: '0x789abc...', - pricePerAccess: 3, - numberOfAccess: 50, -}); - -// 3. Execute data analysis -const analysisResult = await dataProtectorCore.processProtectedData({ - protectedData: datasetAddress, - app: '0xanalytics...', - args: '--analyze-customer-segments --output-format json', - appMaxPrice: 10, -}); -``` - -### Example 2: Oracle Price Update - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// 1. Protect trading data -const { address: tradingDataAddress } = await dataProtectorCore.protectData({ - name: 'Trading Data', - data: { - trades: { - '2024-01-01': { price: 50000, volume: 100 }, - '2024-01-02': { price: 51000, volume: 150 }, - }, - }, -}); - -// 2. Grant access to oracle iApp -await dataProtectorCore.grantAccess({ - protectedData: tradingDataAddress, - authorizedApp: '0xoracle...', // Oracle iApp address - authorizedUser: '0x789abc...', - pricePerAccess: 5, - numberOfAccess: 100, -}); - -// 3. Execute oracle update -const oracleResult = await dataProtectorCore.processProtectedData({ - protectedData: tradingDataAddress, - app: '0xoracle...', - args: '--update-price-feed --asset ETH', - appMaxPrice: 10, -}); -``` - -### Example 3: Automated Payment Processing - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// 1. Protect payment data -const { address: paymentDataAddress } = await dataProtectorCore.protectData({ - name: 'Payment Data', - data: { - bankAccount: '1234567890', - routingNumber: '987654321', - accountHolder: 'John Doe', - monthlyAmount: 1000, - }, -}); - -// 2. Grant access to payment iApp -await dataProtectorCore.grantAccess({ - protectedData: paymentDataAddress, - authorizedApp: '0xpayment...', // Payment iApp address - authorizedUser: '0x789abc...', - pricePerAccess: 2, - numberOfAccess: 12, // Monthly payments -}); - -// 3. Execute payment processing -const paymentResult = await dataProtectorCore.processProtectedData({ - protectedData: paymentDataAddress, - app: '0xpayment...', - args: '--process-monthly-payment', - secrets: { - 1: 'bank-api-key', - }, - appMaxPrice: 8, -}); -``` - -## Best Practices - -### 1. Always Grant Access Before Execution - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -const protectedDataAddress = '0x123abc...'; -// ---cut--- -// Grant access first -await dataProtectorCore.grantAccess({ - protectedData: protectedDataAddress, - authorizedApp: '0x456def...', - authorizedUser: '0x789abc...', - pricePerAccess: 5, - numberOfAccess: 10, -}); - -const result = await dataProtectorCore.processProtectedData({ - protectedData: protectedDataAddress, - app: '0x456def...', - appMaxPrice: 10, -}); -``` - -### 2. Monitor Access Usage - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Check access usage regularly -const grantedAccess = await dataProtectorCore.getGrantedAccess({ - protectedData: '0x123abc...', - authorizedApp: '0x456def...', - authorizedUser: '0x789abc...', -}); - -console.log('Remaining access:', grantedAccess.count); -``` - -### 3. Use Appropriate Price Limits - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Set reasonable price limits -const result = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', - app: '0x456def...', - appMaxPrice: 10, // Set appropriate limit -}); -``` - -### 4. Handle Results Properly - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Store task ID and retrieve results later -const result = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', - app: '0x456def...', - appMaxPrice: 10, -}); - -// Store task ID for later retrieval -const taskId = result.taskId; - -// Later, retrieve the result -const taskResult = await dataProtectorCore.getResultFromCompletedTask({ - taskId: taskId, -}); -``` - ## Next Steps Now that you understand how to use iApp with protected data: diff --git a/src/modules/helloWorld/ProtectData.vue b/src/modules/helloWorld/ProtectData.vue index d442bb1d..8e6000c2 100644 --- a/src/modules/helloWorld/ProtectData.vue +++ b/src/modules/helloWorld/ProtectData.vue @@ -19,13 +19,7 @@

You will sign three things:

  1. A transaction to create the protected data
    2. -
  2. - A message signature to prove your identity to the production SMS -
    3. -
  3. - A message signature to prove your identity to the debug SMS (this - signature is only required during this Hello World tutorial) -
    4. +
  4. A message signature to prove your identity to the SMS
@@ -189,7 +183,6 @@ async function protectData() { secretText: contentToProtect.value, }, name: 'helloWorld', - allowDebug: true, }); console.log('createdProtectedData', createdProtectedData); diff --git a/src/references/dataProtector/dataProtectorCore/protectData.md b/src/references/dataProtector/dataProtectorCore/protectData.md index 973f233c..528f47fc 100644 --- a/src/references/dataProtector/dataProtectorCore/protectData.md +++ b/src/references/dataProtector/dataProtectorCore/protectData.md @@ -236,34 +236,6 @@ const protectedData = await dataProtectorCore.protectData({ }); ``` -### allowDebug - -**Type:** `boolean` -**Default:** `false` - -Allow using the protected data in TEE debug apps. - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -const protectedData = await dataProtectorCore.protectData({ - name: 'myEmail', - data: { - email: 'example@gmail.com', - }, - allowDebug: true, // [!code focus] -}); -``` - -::: tip - -This param is for development only. - -::: - ### onStatusUpdate **Type:** `OnStatusUpdateFn` diff --git a/src/references/iapp-generator.md b/src/references/iapp-generator.md index c653c8b3..0b22b79a 100644 --- a/src/references/iapp-generator.md +++ b/src/references/iapp-generator.md @@ -17,13 +17,6 @@ confidential computing setup. **iApp Generator** builds confidential applications. Your code runs in Intel SGX/TDX secure enclaves where data stays private during processing. -### What you get - -- **Project scaffolding** - Complete setup, ready to deploy -- **Local testing** - Debug in simulation mode before going live -- **Simple deployment** - One command deploys to TEE workers -- **Data integration** - Works with encrypted datasets out of the box - ### What iApp Generator Provides - ✅ **Project scaffolding** - Complete iApp structure ready to deploy @@ -53,7 +46,7 @@ Once you've built your first iApp, level up with these practical guides: execution issues - **[App Access Control and Pricing](/guides/build-iapp/manage-access)** - Control who can use your iApp -- **[How to Get and Decrypt Results](/guides/build-iapp/how-to-get-and-decrypt-results)** - +- **[How to Get and Decrypt Results](/guides/build-iapp/download-and-decrypt-results)** - Retrieve and use outputs ### 3. **Explore Advanced Features** diff --git a/src/references/iapp-generator/building-your-iexec-app.md b/src/references/iapp-generator/building-your-iexec-app.md index f3314326..f8bdf98a 100644 --- a/src/references/iapp-generator/building-your-iexec-app.md +++ b/src/references/iapp-generator/building-your-iexec-app.md @@ -68,19 +68,10 @@ Follow the prompts to specify: - **Project name** – Creates a folder for your project files. - **Language** – Choose between JavaScript, Python, etc. -- **Project mode** – Choose Basic (Hello-World setup) or Advanced (full debug - capabilities). +- **Project mode** – Choose Basic (Hello-World setup) or Advanced mode. ### ⚙ Configure -::: info - -We are going to create and test our iApp locally. In **debug mode**, you can -quickly iterate and troubleshoot your code. Logs and output files are available -for debugging, helping you refine your app before moving to production. - -::: - You'll set up: - **Arguments (Args)** – Public parameters for your iApp. @@ -186,7 +177,7 @@ discontinuity. ### 🚀 Next Steps -Your iApp is now running in **debug mode** on iExec! +Your iApp is now running on iExec! Once your application is **stable** and **functional**, you can: diff --git a/src/references/iapp-generator/getting-started.md b/src/references/iapp-generator/getting-started.md index 6d381e56..9614cc5a 100644 --- a/src/references/iapp-generator/getting-started.md +++ b/src/references/iapp-generator/getting-started.md @@ -11,11 +11,27 @@ description: Before using the iApp Generator, make sure you have: -\- [**Node.js**](https://nodejs.org/en/) version 20 or higher - -\- **Docker / Docker hub account** - -\- **Docker Buildx** _(for macOS users, check AMD64 compatibility)_ +
+
+
+ 📦 Node.js v20+ +
+ Download → +
+
+
+ 🐳 Docker installed +
+ Download → +
+ +
+
+ 🐳 DockerHub Account +
+ Sign Up → +
+
::: tip 🔍 Verify Docker Compatibility From 7ca2d4bef65123fa7a6f7f9159dc7930cd5dfa88 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Mon, 18 Aug 2025 19:50:29 +0200 Subject: [PATCH 02/17] chore: Remove outdated CLI examples and batch operation section from payment execution guide - Deleted sections on using CLI with RLC and vouchers, as well as the batch operations example to streamline the documentation. - Focused on enhancing clarity and relevance of payment methods in the guide. --- src/guides/use-iapp/how-to-pay-executions.md | 52 -------------------- 1 file changed, 52 deletions(-) diff --git a/src/guides/use-iapp/how-to-pay-executions.md b/src/guides/use-iapp/how-to-pay-executions.md index e3d0fcbe..a9d1cb79 100644 --- a/src/guides/use-iapp/how-to-pay-executions.md +++ b/src/guides/use-iapp/how-to-pay-executions.md @@ -73,19 +73,6 @@ const result = await dataProtectorCore.processProtectedData({ }); ``` -### Using CLI with RLC - -```bash -# Execute with RLC payment -iexec app run 0x456def... --protectedData 0xa0c15e... - -# Check your balance -iexec account show - -# Deposit RLC -iexec account deposit 100 -``` - ## Method 2: Paying with Vouchers Vouchers are pre-funded payment instruments that simplify the payment process @@ -150,16 +137,6 @@ be used in combination with `useVoucher: true`. ::: -#### CLI with Vouchers - -```bash -# Use your own voucher -iexec app run 0x456def... --protectedData 0xa0c15e... --useVoucher - -# Use someone else's voucher -iexec app run 0x456def... --protectedData 0xa0c15e... --useVoucher --voucherOwner 0x5714eB... -``` - ## Understanding Pricing ### Cost Components @@ -263,35 +240,6 @@ const result = await dataProtectorCore.processProtectedData({ }); ``` -### 4. Batch Operations - -Group multiple executions to optimize costs: - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Execute multiple tasks efficiently -const tasks = [ - { protectedData: '0x123abc...', app: '0x456def...' }, - { protectedData: '0x124abc...', app: '0x456def...' }, -]; - -const results = await Promise.all( - tasks.map((task) => - dataProtectorCore.processProtectedData({ - ...task, - dataMaxPrice: 5, - appMaxPrice: 3, - workerpoolMaxPrice: 2, - useVoucher: true, - }) - ) -); -``` - ## Payment Troubleshooting ### Insufficient Balance From bee1b91f5a59101d826cdb391c350cd42d3368e0 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Mon, 18 Aug 2025 22:59:32 +0200 Subject: [PATCH 03/17] refactor: Update iApp execution guides and remove outdated content - Renamed and reorganized sections in the sidebar for clarity, replacing 'Different Ways to Execute an iApp' with 'Run iApp' and 'Use iApp with Protected Data' with 'Run iApp with Inputs'. - Updated links in the 'Getting Started' guide to reflect the new structure. - Added new guides for 'Run an iApp' and 'Run iApp with Inputs', detailing execution methods and input handling. - Removed the outdated 'Use iApp with Protected Data' guide to streamline documentation. --- .vitepress/sidebar.ts | 12 +- README.md | 1 + .../use-iapp/add-inputs-to-execution.md | 124 ---- .../use-iapp/different-ways-to-execute.md | 40 -- src/guides/use-iapp/getting-started.md | 10 +- src/guides/use-iapp/how-to-pay-executions.md | 6 +- src/guides/use-iapp/run-iapp-with-inputs.md | 626 ++++++++++++++++++ src/guides/use-iapp/run-iapp.md | 256 +++++++ .../use-iapp/use-iapp-with-protected-data.md | 135 ---- 9 files changed, 893 insertions(+), 317 deletions(-) delete mode 100644 src/guides/use-iapp/add-inputs-to-execution.md delete mode 100644 src/guides/use-iapp/different-ways-to-execute.md create mode 100644 src/guides/use-iapp/run-iapp-with-inputs.md create mode 100644 src/guides/use-iapp/run-iapp.md delete mode 100644 src/guides/use-iapp/use-iapp-with-protected-data.md diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index 87e2e559..44e42851 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -241,16 +241,12 @@ export function getSidebar() { link: '/guides/use-iapp/getting-started', }, { - text: 'Different Ways to Execute an iApp', - link: '/guides/use-iapp/different-ways-to-execute', + text: 'Run iApp', + link: '/guides/use-iapp/run-iapp', }, { - text: 'Use iApp with Protected Data', - link: '/guides/use-iapp/use-iapp-with-protected-data', - }, - { - text: 'Add Inputs to the Execution', - link: '/guides/use-iapp/add-inputs-to-execution', + text: 'Run iApp with Inputs', + link: '/guides/use-iapp/run-iapp-with-inputs', }, { text: 'How to Pay the Executions', diff --git a/README.md b/README.md index 7fd53bf4..72e617d0 100644 --- a/README.md +++ b/README.md @@ -252,3 +252,4 @@ for input parameters: - Talk about ENS on Bellecour(it's not supported on arbitrum) - Rework Advanced iApp building guides. (from "old" protocol doc) - Rework src\get-started\protocol\oracle.md (transfer to guide or rewrite) +- Talk about iApp secret diff --git a/src/guides/use-iapp/add-inputs-to-execution.md b/src/guides/use-iapp/add-inputs-to-execution.md deleted file mode 100644 index 3d88eb68..00000000 --- a/src/guides/use-iapp/add-inputs-to-execution.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Add Inputs to iApp Execution -description: - Learn how to provide arguments, files, secrets, and other inputs to iApp - executions ---- - -# 📥 Add Inputs to iApp Execution - -iApp can accept various types of inputs to customize their behavior and provide -necessary data for processing. This guide covers all the different ways to add -inputs to your iApp executions using various iExec tools and SDK. - -## Types of Inputs - -iExec supports several types of inputs for iApp executions: - -1. **Arguments**: Command-line arguments passed to the application -2. **Input Files**: URLs to public files that the app can download -3. **Secrets**: Sensitive data like API keys stored securely -4. **Protected Data**: Encrypted data processed within the TEE - -## Adding Command-Line Arguments - -Command-line arguments are passed as a string to the iApp and are visible on the -blockchain. - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Process protected data with arguments -const result = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', - app: '0x456def...', - args: '--input-path data/input.csv --output-format json --verbose', -}); -``` - -## Adding Input Files - -Input files are URLs to public files that the iApp can download during -execution. - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Process protected data with input files -const result = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', - app: '0x456def...', - inputFiles: [ - 'https://raw.githubusercontent.com/user/repo/main/config.json', - 'https://example.com/public-data.csv', - ], -}); -``` - -## Adding Secrets - -Secrets are sensitive data like API keys, passwords, or tokens that are stored -securely and made available to the iApp as environment variables. - -### Using DataProtector - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Process protected data with secrets -const result = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', - app: '0x456def...', - secrets: { - 1: 'openai-api-key', - 2: 'database-password', - }, -}); -``` - -## Specifying File Paths in Protected Data - -When working with protected data that contains multiple files, you can specify -which file to process. - -### Using DataProtector - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Process protected data with specific path -const result = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', - app: '0x456def...', - path: 'data/input.csv', -}); - -// Get result with specific path -const taskResult = await dataProtectorCore.getResultFromCompletedTask({ - taskId: '0x7ac398...', - path: 'output/analysis.json', -}); -``` - -## Next Steps - -Now that you understand how to add inputs to iApp executions: - -- Learn about - [Using iApp with Protected Data](/guides/use-iapp/use-iapp-with-protected-data) -- Explore - [Different Ways to Execute](/guides/use-iapp/different-ways-to-execute) iApp -- Check out our - [How to Pay for Executions](/guides/use-iapp/how-to-pay-executions) guide diff --git a/src/guides/use-iapp/different-ways-to-execute.md b/src/guides/use-iapp/different-ways-to-execute.md deleted file mode 100644 index eb549b19..00000000 --- a/src/guides/use-iapp/different-ways-to-execute.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Different Ways to Execute iApp -description: Learn about various methods for executing iApp on the iExec network ---- - -# ⚡ Different Ways to Execute iApp - -There are multiple ways to execute iApp on the iExec network. This guide covers -the basic execution methods. For advanced features like protected data, -arguments, and input files, see the dedicated guides. - -## Using the iApp Generator CLI - -The iApp Generator CLI provides a streamlined way to execute iApp, especially -for developers who have built their own iApp. - -> **Note**: For installation instructions, see the -> [iApp Generator Getting Started guide](/references/iapp-generator/getting-started). - -### Basic Execution - -```bash -# Execute a deployed iApp -iapp run 0x456def... -``` - -### Testing Before Execution - -```bash -# Test the iApp locally first -iapp test -``` - -## Next Steps - -- Learn how to - [use iApp with protected data](/guides/use-iapp/use-iapp-with-protected-data) -- Discover how to - [add inputs to execution](/guides/use-iapp/add-inputs-to-execution) -- Understand [how to pay for executions](/guides/use-iapp/how-to-pay-executions) diff --git a/src/guides/use-iapp/getting-started.md b/src/guides/use-iapp/getting-started.md index 38a3a9ef..050d08ab 100644 --- a/src/guides/use-iapp/getting-started.md +++ b/src/guides/use-iapp/getting-started.md @@ -72,11 +72,9 @@ section. For step-by-step instructions, check out these guides: -- **[Different Ways to Execute](/guides/use-iapp/different-ways-to-execute)** - - iExec CLI, lib, and other execution methods -- **[Use iApp with Protected Data](/guides/use-iapp/use-iapp-with-protected-data)** - - Working with sensitive data securely -- **[Add Inputs to Execution](/guides/use-iapp/add-inputs-to-execution)** - How - to provide data and parameters to iApp +- **[Run iApp](/guides/use-iapp/run-iapp)** - iExec CLI, lib, and other + execution methods +- **[Run iApp with Inputs](/guides/use-iapp/run-iapp-with-inputs)** - How to + provide data and parameters to iApp - **[How to Pay for Executions](/guides/use-iapp/how-to-pay-executions)** - Understanding costs and payment options diff --git a/src/guides/use-iapp/how-to-pay-executions.md b/src/guides/use-iapp/how-to-pay-executions.md index a9d1cb79..bba62495 100644 --- a/src/guides/use-iapp/how-to-pay-executions.md +++ b/src/guides/use-iapp/how-to-pay-executions.md @@ -438,10 +438,8 @@ const executeWithPaymentRetry = async (params: any, maxRetries = 3) => { Now that you understand payment methods: -- Learn about - [Adding Inputs to Execution](/guides/use-iapp/add-inputs-to-execution) -- Explore - [Using iApp with Protected Data](/guides/use-iapp/use-iapp-with-protected-data) +- Learn about [Run iApp with Inputs](/guides/use-iapp/run-iapp-with-inputs) +- Explore [Getting Started with iApp](/guides/use-iapp/getting-started) - Review the pricing information above for detailed cost analysis diff --git a/src/guides/use-iapp/run-iapp.md b/src/guides/use-iapp/run-iapp.md new file mode 100644 index 00000000..9534625f --- /dev/null +++ b/src/guides/use-iapp/run-iapp.md @@ -0,0 +1,256 @@ +--- +title: Run an iApp +description: + Learn about various methods for executing iApp on the iExec network, including + CLI and SDK approaches +--- + +# ⚡ Run an iApp + +There are multiple ways to execute an iApp on the iExec network. An iApp can be: + +- **Self-sufficient** - Basic execution without additional inputs +- **Data-dependent** - Requires protected data, secrets, input files, or + command-line arguments + +This guide covers the basic execution methods. For advanced features like +protected data, arguments, and input files, see the dedicated guides. + +## Using the iApp Generator CLI + +The iApp Generator CLI provides a streamlined way to execute iApp, especially +for developers who have built their own iApp. + +> **Note**: For installation instructions, see the +> [iApp Generator Getting Started guide](/references/iapp-generator/getting-started). + + + + + +## Next Steps + +- Discover how to + [run an iApp with inputs](/guides/use-iapp/run-iapp-with-inputs) +- Understand [how to pay for executions](/guides/use-iapp/how-to-pay-executions) + + diff --git a/src/guides/use-iapp/use-iapp-with-protected-data.md b/src/guides/use-iapp/use-iapp-with-protected-data.md deleted file mode 100644 index fb597265..00000000 --- a/src/guides/use-iapp/use-iapp-with-protected-data.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Use iApp with Protected Data -description: - Learn how to securely process protected data using iApp on the iExec network ---- - -# 🔒 Use iApp with Protected Data - -Protected data is the cornerstone of privacy-preserving computation on iExec. -This guide shows you how to use iApp with protected data, from granting access -to processing and retrieving results. - -## Understanding Protected Data and iApp - -Protected data is encrypted information that can only be processed by authorized -iApp within Trusted Execution Environments (TEEs). The data remains confidential -throughout the entire computation process. - -### The Workflow - -1. **Protect Your Data**: Encrypt sensitive information using the Data Protector -2. **Grant Access**: Authorize specific iApp to process your data -3. **Execute iApp**: Run the iApp with your protected data -4. **Retrieve Results**: Get the computation results while data remains private - -## Step 1: Protect Your Data - -Before using an iApp, you need to protect your sensitive data. - -### Basic Data Protection - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Protect your data -const { address: protectedDataAddress } = await dataProtectorCore.protectData({ - name: 'My Sensitive Data', - data: { - email: 'user@example.com', - apiKey: 'secret-api-key-12345', - preferences: { - theme: 'dark', - notifications: true, - }, - }, -}); -``` - -## Step 2: Grant Access to iApp - -iApp need explicit authorization to access your protected data. - -### Grant Access to a Specific iApp - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Grant access to an iApp -const grantedAccess = await dataProtectorCore.grantAccess({ - protectedData: '0x123abc...', - authorizedApp: '0x456def...', // The iApp address - authorizedUser: '0x789abc...', // Your wallet address - pricePerAccess: 5, // Price per access in nRLC - numberOfAccess: 10, // Number of allowed accesses -}); -``` - -### Check Granted Access - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Check what access you've granted -const grantedAccessList = await dataProtectorCore.getGrantedAccess({ - protectedData: '0x123abc...', - authorizedApp: '0x456def...', - authorizedUser: '0x789abc...', -}); -``` - -## Step 3: Execute iApp with Protected Data - -Once access is granted, you can execute the iApp with your protected data. - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// Execute iApp with protected data -const result = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', - app: '0x456def...', // The iApp address -}); -``` - -## Step 4: Retrieve Results - -This step is optional. Indeed, `processProtectedData` will automatically -download and decrypt the results for you. Nevertheless, if you want to retrieve -results from a completed task, you can do so as follows: - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -const taskId = '0x7ac398...'; - -// ---cut--- -// Retrieve the result -const taskResult = await dataProtectorCore.getResultFromCompletedTask({ - taskId: taskId, -}); -``` - -## Next Steps - -Now that you understand how to use iApp with protected data: - -- Learn about - [Different Ways to Execute](/guides/use-iapp/different-ways-to-execute) iApp -- Explore [How to Pay for Executions](/guides/use-iapp/how-to-pay-executions) -- Check out our - [Add Inputs to Execution](/guides/use-iapp/add-inputs-to-execution) guide From 1c8d83f786b44354a6c32e600587810d61f2662b Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Tue, 19 Aug 2025 08:18:31 +0200 Subject: [PATCH 04/17] refactor: Improve formatting and clarity in iApp execution guide - Enhanced readability by breaking long lines into multiple lines in the 'Choosing Between Toolkit' section. - Maintained the content integrity while improving the overall presentation of the guide. --- src/guides/use-iapp/run-iapp-with-inputs.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/guides/use-iapp/run-iapp-with-inputs.md b/src/guides/use-iapp/run-iapp-with-inputs.md index 15e886ff..f8a71fd5 100644 --- a/src/guides/use-iapp/run-iapp-with-inputs.md +++ b/src/guides/use-iapp/run-iapp-with-inputs.md @@ -14,9 +14,13 @@ DataProtector turnkey toolkit. ## Choosing Between Toolkit -**DataProtector SDK Toolkit**: Always requires protected data. Best for Node.js/frontend projects and production environments. Offers programmatic control, integration, error handling, and batch operations. +**DataProtector SDK Toolkit**: Always requires protected data. Best for +Node.js/frontend projects and production environments. Offers programmatic +control, integration, error handling, and batch operations. -**iApp Generator CLI Toolkit**: No protected data required to run an iApp. Perfect for testing, development, and quick prototyping. Provides immediate execution without coding. +**iApp Generator CLI Toolkit**: No protected data required to run an iApp. +Perfect for testing, development, and quick prototyping. Provides immediate +execution without coding. ## Possible of Inputs From 889b38267417c61879b12d2c3ff61512ba6b73fe Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Tue, 19 Aug 2025 11:08:44 +0200 Subject: [PATCH 05/17] docs: Enhance iApp execution guide with structured methods and code examples - Added a new section outlining when to use each execution method: iApp Generator CLI, iExec Library, and iExec CLI. - Introduced detailed code examples for using the iExec SDK Library and iExec CLI for executing iApps. - Improved overall organization and clarity of the guide to assist users in selecting the appropriate execution method. --- src/guides/use-iapp/run-iapp.md | 63 ++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/src/guides/use-iapp/run-iapp.md b/src/guides/use-iapp/run-iapp.md index 9534625f..6999435d 100644 --- a/src/guides/use-iapp/run-iapp.md +++ b/src/guides/use-iapp/run-iapp.md @@ -16,7 +16,13 @@ There are multiple ways to execute an iApp on the iExec network. An iApp can be: This guide covers the basic execution methods. For advanced features like protected data, arguments, and input files, see the dedicated guides. -## Using the iApp Generator CLI +## When to Use Each Method + +- **iApp Generator CLI**: For developers who have built their own iApp +- **iExec Library**: For JavaScript applications and web3 integration +- **iExec CLI**: For quick testing and automation scripts + +## Method 1: Using the iApp Generator CLI The iApp Generator CLI provides a streamlined way to execute iApp, especially for developers who have built their own iApp. @@ -50,6 +56,61 @@ for developers who have built their own iApp. /> +## Method 2: Using the iExec SDK Library + +The iExec SDK provides a modular JavaScript interface for executing iApp. + +```ts twoslash +import { IExec, utils } from 'iexec'; + +const ethProvider = utils.getSignerFromPrivateKey( + 'bellecour', // blockchain node URL + 'PRIVATE_KEY' +); +const iexec = new IExec({ + ethProvider, +}); +// ---cut--- +// Create & Sign a request order +const requestorderToSign = await iexec.order.createRequestorder({ + app: '0x456def...', // The iApp address + category: 0, +}); +const requestOrder = await iexec.order.signRequestorder(requestorderToSign); + +// Fetch app orders +const appOrders = await iexec.orderbook.fetchAppOrderbook( + '0x456def...' // Filter by specific app +); +if (appOrders.orders.length === 0) { + throw new Error('No app orders found for the specified app'); +} + +// Fetch workerpool orders +const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ + workerpool: '0xa5de76...', // Filter by specific workerpool +}); +if (workerpoolOrders.orders.length === 0) { + throw new Error('No workerpool orders found for the specified workerpool'); +} + +// Execute the task +const taskId = await iexec.order.matchOrders({ + requestorder: requestOrder, + apporder: appOrders.orders[0].order, + workerpoolorder: workerpoolOrders.orders[0].order, +}); +``` + +## Method 3: Using the iExec CLI + +The iExec CLI is perfect for quick executions and automation scripts. + +```bash +# Execute an iApp +iexec app run 0x456def... +``` + ## Next Steps - Discover how to From 638787138509370ca72e8fce61186cedc566e51f Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Tue, 19 Aug 2025 11:35:57 +0200 Subject: [PATCH 06/17] docs: Update iApp guide titles for consistency and clarity --- src/guides/build-iapp/build-&-deploy.md | 2 +- src/guides/use-iapp/run-iapp.md | 10 ---------- 2 files changed, 1 insertion(+), 11 deletions(-) diff --git a/src/guides/build-iapp/build-&-deploy.md b/src/guides/build-iapp/build-&-deploy.md index 459bbe3e..db3d97ae 100644 --- a/src/guides/build-iapp/build-&-deploy.md +++ b/src/guides/build-iapp/build-&-deploy.md @@ -4,7 +4,7 @@ description: How to create a confidential iExec application and deploy it on iExec protocol --- -# Create and Deploy an iApp +# Build and Deploy an iApp iApp (iExec Applications) are decentralized applications that run on the iExec network. They use confidential computing to ensure data privacy and security diff --git a/src/guides/use-iapp/run-iapp.md b/src/guides/use-iapp/run-iapp.md index 6999435d..296a7e22 100644 --- a/src/guides/use-iapp/run-iapp.md +++ b/src/guides/use-iapp/run-iapp.md @@ -20,7 +20,6 @@ protected data, arguments, and input files, see the dedicated guides. - **iApp Generator CLI**: For developers who have built their own iApp - **iExec Library**: For JavaScript applications and web3 integration -- **iExec CLI**: For quick testing and automation scripts ## Method 1: Using the iApp Generator CLI @@ -102,15 +101,6 @@ const taskId = await iexec.order.matchOrders({ }); ``` -## Method 3: Using the iExec CLI - -The iExec CLI is perfect for quick executions and automation scripts. - -```bash -# Execute an iApp -iexec app run 0x456def... -``` - ## Next Steps - Discover how to From b9d6d4162df432b4b8f8dd633d19ef670f21b54f Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Tue, 19 Aug 2025 12:29:06 +0200 Subject: [PATCH 07/17] docs: Update iApp guides to reflect new testing and deployment structure - Renamed 'Build and Deploy' to 'Build and Test' in navigation and sidebar for consistency. - Added a new guide for 'Build and Test an iApp' detailing the creation and testing process. - Introduced a new guide for 'Deploy and Run an iApp' covering deployment methods and execution on the iExec network. - Updated links in existing documentation to align with the new guide structure. --- .vitepress/config.ts | 2 +- .vitepress/sidebar.ts | 8 +- src/get-started/overview/what-is-iexec.md | 2 +- .../{build-&-deploy.md => build-&-test.md} | 172 +------ src/guides/build-iapp/deploy-&-run.md | 454 ++++++++++++++++++ src/index.md | 2 +- 6 files changed, 469 insertions(+), 171 deletions(-) rename src/guides/build-iapp/{build-&-deploy.md => build-&-test.md} (63%) create mode 100644 src/guides/build-iapp/deploy-&-run.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 8714f543..b893e811 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -101,7 +101,7 @@ export default withMermaid( // https://vitepress.dev/reference/default-theme-config nav: [ { text: 'Get Started', link: '/get-started/welcome' }, - { text: 'Guides', link: '/guides/build-iapp/build-&-deploy' }, + { text: 'Guides', link: '/guides/build-iapp/build-&-test' }, { text: 'References', link: '/references/dataProtector' }, { component: 'ChainSelector', diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index 44e42851..ee93d804 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -166,8 +166,12 @@ export function getSidebar() { text: 'BUILD YOUR iAPP', items: [ { - text: 'Build and Deploy', - link: '/guides/build-iapp/build-&-deploy', + text: 'Build and Test', + link: '/guides/build-iapp/build-&-test', + }, + { + text: 'Deploy and Run', + link: '/guides/build-iapp/deploy-&-run', }, { text: 'Manage Access', diff --git a/src/get-started/overview/what-is-iexec.md b/src/get-started/overview/what-is-iexec.md index bd416f56..a88710ee 100644 --- a/src/get-started/overview/what-is-iexec.md +++ b/src/get-started/overview/what-is-iexec.md @@ -10,7 +10,7 @@ description: iExec is a **decentralized confidential computing toolkit** that helps developers build privacy-preserving applications. -## The Protocol (Simple Version) +## SpeedRun The Protocol ### Step 1: Protect Data diff --git a/src/guides/build-iapp/build-&-deploy.md b/src/guides/build-iapp/build-&-test.md similarity index 63% rename from src/guides/build-iapp/build-&-deploy.md rename to src/guides/build-iapp/build-&-test.md index db3d97ae..2e96bb3c 100644 --- a/src/guides/build-iapp/build-&-deploy.md +++ b/src/guides/build-iapp/build-&-test.md @@ -4,7 +4,7 @@ description: How to create a confidential iExec application and deploy it on iExec protocol --- -# Build and Deploy an iApp +# Build and Test an iApp iApp (iExec Applications) are decentralized applications that run on the iExec network. They use confidential computing to ensure data privacy and security @@ -237,171 +237,11 @@ specify your app version, and push both standard and TEE-compatible images: /> - diff --git a/src/guides/build-iapp/deploy-&-run.md b/src/guides/build-iapp/deploy-&-run.md new file mode 100644 index 00000000..4367d151 --- /dev/null +++ b/src/guides/build-iapp/deploy-&-run.md @@ -0,0 +1,454 @@ +--- +title: Run an iApp +description: + Learn about various methods for executing iApp on the iExec network, including + CLI and SDK approaches +--- + +# Deploy and Run an iApp + +After your tests pass and the package is built, you can deploy your iApp to a +supported network. During deployment, you'll enter your DockerHub credentials, +specify your app version, and push both standard and TEE-compatible images: + + + + + +# ⚡ Run an iApp + +There are multiple ways to execute an iApp on the iExec network. An iApp can be: + +- **Self-sufficient** - Basic execution without additional inputs +- **Data-dependent** - Requires protected data, secrets, input files, or + command-line arguments + +This guide covers the basic execution methods. For advanced features like +protected data, arguments, and input files, see the dedicated guides. + +## Using the iApp Generator Toolkit + +The iApp Generator CLI provides a streamlined way to execute iApp, especially +for developers who have built their own iApp. + +> **Note**: For installation instructions, see the +> [iApp Generator Getting Started guide](/references/iapp-generator/getting-started). + + + + + +## Next Steps + +- Discover how to + [run an iApp with inputs](/guides/use-iapp/run-iapp-with-inputs) +- Understand [how to pay for executions](/guides/use-iapp/how-to-pay-executions) + + diff --git a/src/index.md b/src/index.md index dbd9dbb9..100648f1 100644 --- a/src/index.md +++ b/src/index.md @@ -31,7 +31,7 @@ features: details: iApp Generator builds confidential applications that run in secure TEEs. Custom confidentiality integration without managing infrastructure. - link: /guides/build-iapp/build-&-deploy + link: /guides/build-iapp/build-&-test - icon: ⚡ title: Use iApp details: From 0ce89134f33c93d309c6e8803756013084fc9f93 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Tue, 19 Aug 2025 12:39:49 +0200 Subject: [PATCH 08/17] docs: Revise iApp deployment and execution guides for clarity and structure - Removed outdated deployment examples from the 'Build and Test' guide to streamline content. - Enhanced the 'Deploy and Run' guide with a clearer introduction and restructured sections for better flow. - Updated headings for consistency and improved readability throughout the documentation. --- src/guides/build-iapp/build-&-test.md | 32 --------------------------- src/guides/build-iapp/deploy-&-run.md | 11 +++++---- 2 files changed, 5 insertions(+), 38 deletions(-) diff --git a/src/guides/build-iapp/build-&-test.md b/src/guides/build-iapp/build-&-test.md index 2e96bb3c..8b05bf5e 100644 --- a/src/guides/build-iapp/build-&-test.md +++ b/src/guides/build-iapp/build-&-test.md @@ -205,38 +205,6 @@ The CLI will build a Docker image, run your app, and show you the results: :autoRestart="true" /> -## Deployment - -After your tests pass and the package is built, you can deploy your iApp to a -supported network. During deployment, you'll enter your DockerHub credentials, -specify your app version, and push both standard and TEE-compatible images: - - - - - ## Next Steps - When everything is ready diff --git a/src/guides/build-iapp/deploy-&-run.md b/src/guides/build-iapp/deploy-&-run.md index 4367d151..a18af1bc 100644 --- a/src/guides/build-iapp/deploy-&-run.md +++ b/src/guides/build-iapp/deploy-&-run.md @@ -7,6 +7,10 @@ description: # Deploy and Run an iApp +It's time to run your iApp! After building and testing, you'll need to deploy it to a supported network and then execute it. + +## Deploy your iApp + After your tests pass and the package is built, you can deploy your iApp to a supported network. During deployment, you'll enter your DockerHub credentials, specify your app version, and push both standard and TEE-compatible images: @@ -37,7 +41,7 @@ specify your app version, and push both standard and TEE-compatible images: /> -# ⚡ Run an iApp +## Run your iApp There are multiple ways to execute an iApp on the iExec network. An iApp can be: @@ -45,11 +49,6 @@ There are multiple ways to execute an iApp on the iExec network. An iApp can be: - **Data-dependent** - Requires protected data, secrets, input files, or command-line arguments -This guide covers the basic execution methods. For advanced features like -protected data, arguments, and input files, see the dedicated guides. - -## Using the iApp Generator Toolkit - The iApp Generator CLI provides a streamlined way to execute iApp, especially for developers who have built their own iApp. From 9e254399930ee33a806014e26d3d3f8f7370169c Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Tue, 19 Aug 2025 12:51:51 +0200 Subject: [PATCH 09/17] docs: Update iApp guides for improved clarity and consistency --- src/guides/build-iapp/build-&-test.md | 4 ++-- src/guides/build-iapp/deploy-&-run.md | 5 ++--- src/guides/build-iapp/manage-access.md | 6 +++--- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/src/guides/build-iapp/build-&-test.md b/src/guides/build-iapp/build-&-test.md index 8b05bf5e..37a2063d 100644 --- a/src/guides/build-iapp/build-&-test.md +++ b/src/guides/build-iapp/build-&-test.md @@ -1,7 +1,7 @@ --- -title: Create and Deploy an iApp +title: Build and Test an iApp description: - How to create a confidential iExec application and deploy it on iExec protocol + Learn how to build, test, and package your iExec application using the iApp Generator CLI tool --- # Build and Test an iApp diff --git a/src/guides/build-iapp/deploy-&-run.md b/src/guides/build-iapp/deploy-&-run.md index a18af1bc..f6ccfafe 100644 --- a/src/guides/build-iapp/deploy-&-run.md +++ b/src/guides/build-iapp/deploy-&-run.md @@ -1,8 +1,7 @@ --- -title: Run an iApp +title: Deploy and Run an iApp description: - Learn about various methods for executing iApp on the iExec network, including - CLI and SDK approaches + Deploy your iApp to supported networks and learn how to execute it using the iApp Generator CLI --- # Deploy and Run an iApp diff --git a/src/guides/build-iapp/manage-access.md b/src/guides/build-iapp/manage-access.md index a325c2a5..9d18e8c1 100644 --- a/src/guides/build-iapp/manage-access.md +++ b/src/guides/build-iapp/manage-access.md @@ -118,13 +118,13 @@ iexec wallet import ::: tip iApp Generator Users -If you used iApp Generator, you already have an `iexecconfig.json` file with a +If you used iApp Generator, you already have an `iapp.config.json` file with a generated private key. You can use this existing private key to initialize your wallet: ```bash -# Extract the private key from your `iexecconfig.json` -iexec wallet import +# Extract the private key from your `iapp.config.json` +iexec wallet import ``` ::: From d523212a4732b7079dd5686e177debd73ee43e58 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Tue, 19 Aug 2025 13:11:00 +0200 Subject: [PATCH 10/17] docs: Enhance 'Deploy and Run' guide with deployment and run tracking details - Added sections explaining the creation of `deployments.json` and `runs.json` files for tracking deployments and runs on the iExec network. - Included JSON examples to illustrate the structure of the tracking files. - Updated next steps to guide users on managing access and debugging techniques. --- src/guides/build-iapp/deploy-&-run.md | 38 ++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/src/guides/build-iapp/deploy-&-run.md b/src/guides/build-iapp/deploy-&-run.md index f6ccfafe..fa0cd335 100644 --- a/src/guides/build-iapp/deploy-&-run.md +++ b/src/guides/build-iapp/deploy-&-run.md @@ -40,6 +40,22 @@ specify your app version, and push both standard and TEE-compatible images: /> +Now that your iApp has been deployed on the iExec protocol, you can navigate to the `cache` folder to see your deployments saved. A file named `deployments.json` in the folder corresponding to your target network will be created containing each deployment made on this network. These files will help you easily track each deployment per network. + +Here is an example: + +```json +[ + { + "sconifiedImage": "robiniexec/iapp:0.0.1-tee-scone-5.9.1-v16-debug-5aea8b4aa71d", + "appContractAddress": "0x9665136c599ec361C8eE627eC4F35A23fBa94897", + "owner": "0xbabE8270aC9857Af3aaC06877888F1939FbeC578", + "date": "2025-08-12T13:16:18.252Z" + }, + ... +] +``` + ## Run your iApp There are multiple ways to execute an iApp on the iExec network. An iApp can be: @@ -80,11 +96,27 @@ for developers who have built their own iApp. /> +Now that you have run your iApp on the iExec protocol, you can navigate to the `cache` folder to see your runs saved. A file named `runs.json` in the folder corresponding to your target network will be created containing each run made on this network. These files will help you easily track each run per network. Use the [iExec Explorer](/guides/tooling-and-explorers/iexec-explorer) to retrieve more data about your tasks. + +Here is an example: + +```json +[ + { + "iAppAddress": "0x9665136c599ec361C8eE627eC4F35A23fBa94897", + "dealid": "0x26d758de1be51697c33fa606cd0c5243082a6e675a4463b106d71fde2893280f", + "taskid": "0x1a58dd6018b30b022eb35be53ad9374eb630925458d14643a1dfd9c686b964d8", + "txHash": "0x6f14eac6933c609fb6d3e6b2bbd18c373c6dc99c7d7fd22036d5a20f847c5e42", + "date": "2025-08-18T18:30:03.711Z" + }, + ... +] +``` + ## Next Steps -- Discover how to - [run an iApp with inputs](/guides/use-iapp/run-iapp-with-inputs) -- Understand [how to pay for executions](/guides/use-iapp/how-to-pay-executions) +- Learn how to [manage access to your iApp](/guides/build-iapp/manage-access) +- Discover [debugging techniques](/guides/build-iapp/debugging) for troubleshooting diff --git a/src/guides/use-iapp/run-iapp-without-ProtectedData.md b/src/guides/use-iapp/run-iapp-without-ProtectedData.md new file mode 100644 index 00000000..7e93ce74 --- /dev/null +++ b/src/guides/use-iapp/run-iapp-without-ProtectedData.md @@ -0,0 +1,187 @@ +--- +title: Run iApp without ProtectedData +description: + Learn how to run iApp with basic inputs like command-line arguments, public files, and secrets using the iexec SDK +--- + +# 📥 Run iApp without a ProtectedData + +When an iApp requires additional data or parameters to function, you can provide +various types of inputs to customize its behavior and enable processing. This +guide covers all the different ways to run an iApp with inputs using the +DataProtector turnkey toolkit. + +## Possible Inputs + +iExec supports several types of inputs for iApp executions: + +1. **Arguments**: Command-line arguments passed to the application +2. **Input Files**: URLs to public files that the app can download +3. **Secrets**: Sensitive data like API keys stored securely + +## Adding Command-Line Arguments + +Command-line arguments are passed as a string to the iApp and are visible on the +blockchain. + +```ts twoslash +import { IExec, utils } from 'iexec'; + +const ethProvider = utils.getSignerFromPrivateKey( + 'bellecour', // blockchain node URL + 'PRIVATE_KEY' +); +const iexec = new IExec({ + ethProvider, +}); +// ---cut--- +// Basic arguments +const requestorderToSign = await iexec.order.createRequestorder({ + app: '0x456def...', + category: 0, + appmaxprice: 10, + workerpool: '0xa5de76...', // ENS address for iExec's debug workerpool + params: 'arg1 arg2 arg3', // Command-line arguments + // Other parameters have default values +}); +const requestOrder = await iexec.order.signRequestorder(requestorderToSign); + +// Fetch app orders +const appOrders = await iexec.orderbook.fetchAppOrderbook( + '0x456def...' // Filter by specific app +); +if (appOrders.orders.length === 0) { + throw new Error('No app orders found for the specified app'); +} + +// Fetch workerpool orders +const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ + workerpool: '0xa5de76...', // Filter by specific workerpool +}); +if (workerpoolOrders.orders.length === 0) { + throw new Error('No workerpool orders found for the specified workerpool'); +} + +// Execute the task +const taskId = await iexec.order.matchOrders({ + requestorder: requestOrder, + apporder: appOrders.orders[0].order, + workerpoolorder: workerpoolOrders.orders[0].order, +}); +``` + +## Adding Input Files + +Input files are URLs to public files that the iApp can download during +execution. + +```ts twoslash +import { IExec, utils } from 'iexec'; + +const ethProvider = utils.getSignerFromPrivateKey( + 'bellecour', // blockchain node URL + 'PRIVATE_KEY' +); +const iexec = new IExec({ + ethProvider, +}); +// ---cut--- +// Single input file +const requestorderToSign = await iexec.order.createRequestorder({ + app: '0x456def...', + category: 0, // Required: category for the request + appmaxprice: 10, + workerpool: '0xa5de76...', // ENS address for iExec's debug workerpool + params: { + iexec_input_files: [ + 'https://example.com/config.json', + 'https://example.com/template.html', + 'https://example.com/data.csv', + ], + }, +}); +const requestOrder = await iexec.order.signRequestorder(requestorderToSign); + +// Fetch app orders +const appOrders = await iexec.orderbook.fetchAppOrderbook( + '0x456def...' // Filter by specific app +); +if (appOrders.orders.length === 0) { + throw new Error('No app orders found for the specified app'); +} + +// Fetch workerpool orders +const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ + workerpool: '0xa5de76...', // Filter by specific workerpool +}); +if (workerpoolOrders.orders.length === 0) { + throw new Error('No workerpool orders found for the specified workerpool'); +} + +// Execute the task +const taskId = await iexec.order.matchOrders({ + requestorder: requestOrder, + apporder: appOrders.orders[0].order, + workerpoolorder: workerpoolOrders.orders[0].order, +}); +``` + +## Adding Secrets + +Secrets are sensitive data like API keys, passwords, or tokens that are stored +securely and made available to the iApp as environment variables. + +```ts twoslash [Browser] +// @errors: 2345 2739 7053 2339 +import { IExec, utils } from 'iexec'; + +const ethProvider = utils.getSignerFromPrivateKey( + 'bellecour', // blockchain node URL + 'PRIVATE_KEY' +); +const iexec = new IExec({ + ethProvider, +}); +// ---cut--- +// Basic secrets +const requestorderToSign = await iexec.order.createRequestorder({ + app: '0x456def...', + category: 0, // Required: category for the request + appmaxprice: 10, + workerpool: '0xa5de76...', // ENS address for iExec's debug workerpool + params: { + iexec_secrets: { + 1: 'api-key-12345', + 2: 'database-password', + }, + }, +}); +const requestOrder = await iexec.order.signRequestorder(requestorderToSign); + +// Fetch app orders +const appOrders = await iexec.orderbook.fetchAppOrderbook( + '0x456def...' // Filter by specific app +); +if (appOrders.orders.length === 0) { + throw new Error('No app orders found for the specified app'); +} + +// Fetch workerpool orders +const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ + workerpool: '0xa5de76...', // Filter by specific workerpool +}); +if (workerpoolOrders.orders.length === 0) { + throw new Error('No workerpool orders found for the specified workerpool'); +} + +// Execute the task +const taskId = await iexec.order.matchOrders({ + requestorder: requestOrder, + apporder: appOrders.orders[0].order, + workerpoolorder: workerpoolOrders.orders[0].order, +}); +``` + +## Next Steps + +Now that you understand how to add inputs to iApp executions: diff --git a/src/guides/use-iapp/run-iapp.md b/src/guides/use-iapp/run-iapp.md deleted file mode 100644 index 296a7e22..00000000 --- a/src/guides/use-iapp/run-iapp.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -title: Run an iApp -description: - Learn about various methods for executing iApp on the iExec network, including - CLI and SDK approaches ---- - -# ⚡ Run an iApp - -There are multiple ways to execute an iApp on the iExec network. An iApp can be: - -- **Self-sufficient** - Basic execution without additional inputs -- **Data-dependent** - Requires protected data, secrets, input files, or - command-line arguments - -This guide covers the basic execution methods. For advanced features like -protected data, arguments, and input files, see the dedicated guides. - -## When to Use Each Method - -- **iApp Generator CLI**: For developers who have built their own iApp -- **iExec Library**: For JavaScript applications and web3 integration - -## Method 1: Using the iApp Generator CLI - -The iApp Generator CLI provides a streamlined way to execute iApp, especially -for developers who have built their own iApp. - -> **Note**: For installation instructions, see the -> [iApp Generator Getting Started guide](/references/iapp-generator/getting-started). - - - - - -## Method 2: Using the iExec SDK Library - -The iExec SDK provides a modular JavaScript interface for executing iApp. - -```ts twoslash -import { IExec, utils } from 'iexec'; - -const ethProvider = utils.getSignerFromPrivateKey( - 'bellecour', // blockchain node URL - 'PRIVATE_KEY' -); -const iexec = new IExec({ - ethProvider, -}); -// ---cut--- -// Create & Sign a request order -const requestorderToSign = await iexec.order.createRequestorder({ - app: '0x456def...', // The iApp address - category: 0, -}); -const requestOrder = await iexec.order.signRequestorder(requestorderToSign); - -// Fetch app orders -const appOrders = await iexec.orderbook.fetchAppOrderbook( - '0x456def...' // Filter by specific app -); -if (appOrders.orders.length === 0) { - throw new Error('No app orders found for the specified app'); -} - -// Fetch workerpool orders -const workerpoolOrders = await iexec.orderbook.fetchWorkerpoolOrderbook({ - workerpool: '0xa5de76...', // Filter by specific workerpool -}); -if (workerpoolOrders.orders.length === 0) { - throw new Error('No workerpool orders found for the specified workerpool'); -} - -// Execute the task -const taskId = await iexec.order.matchOrders({ - requestorder: requestOrder, - apporder: appOrders.orders[0].order, - workerpoolorder: workerpoolOrders.orders[0].order, -}); -``` - -## Next Steps - -- Discover how to - [run an iApp with inputs](/guides/use-iapp/run-iapp-with-inputs) -- Understand [how to pay for executions](/guides/use-iapp/how-to-pay-executions) - - From 1f58f63a65e5cc1d51abe6b4cc6b776378f79d1c Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Tue, 19 Aug 2025 14:30:00 +0200 Subject: [PATCH 12/17] docs: Update iApp guides for improved navigation and clarity --- .vitepress/sidebar.ts | 12 +- .../protocol/tee/intel-sgx-technology.md | 2 +- .../advanced/access-confidential-assets.md | 4 +- .../advanced/quick-start-for-developers.md | 1 - .../advanced/sgx-encrypted-dataset.md | 2 - .../build-iapp/advanced/your-first-app.md | 10 - src/guides/build-iapp/build-&-test.md | 2 +- src/guides/build-iapp/debugging.md | 2 +- src/guides/build-iapp/deploy-&-run.md | 4 +- .../download-and-decrypt-results.md | 250 ------------------ src/guides/build-iapp/inputs-and-outputs.md | 6 +- src/guides/use-iapp/getting-started.md | 13 +- src/guides/use-iapp/how-to-pay-executions.md | 3 +- .../use-iapp/run-iapp-with-ProtectedData.md | 3 +- .../run-iapp-without-ProtectedData.md | 3 +- src/references/iapp-generator.md | 6 +- 16 files changed, 28 insertions(+), 295 deletions(-) delete mode 100644 src/guides/build-iapp/download-and-decrypt-results.md diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index ee93d804..984ff8f8 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -185,10 +185,6 @@ export function getSidebar() { text: 'Using TDX', link: '/guides/build-iapp/using-tdx', }, - { - text: 'Download and Decrypt Results', - link: '/guides/build-iapp/download-and-decrypt-results', - }, { text: 'Debugging', link: '/guides/build-iapp/debugging', @@ -245,12 +241,12 @@ export function getSidebar() { link: '/guides/use-iapp/getting-started', }, { - text: 'Run iApp', - link: '/guides/use-iapp/run-iapp', + text: 'Run iApp without ProtectedData', + link: '/guides/use-iapp/run-iapp-without-ProtectedData', }, { - text: 'Run iApp with Inputs', - link: '/guides/use-iapp/run-iapp-with-inputs', + text: 'Run iApp with ProtectedData', + link: '/guides/use-iapp/run-iapp-with-ProtectedData', }, { text: 'How to Pay the Executions', diff --git a/src/get-started/protocol/tee/intel-sgx-technology.md b/src/get-started/protocol/tee/intel-sgx-technology.md index 62ab37ff..bd508f78 100644 --- a/src/get-started/protocol/tee/intel-sgx-technology.md +++ b/src/get-started/protocol/tee/intel-sgx-technology.md @@ -79,6 +79,6 @@ The environment you are about to use is a "develop" environment: - where configurations and secrets might be inspected (debug enclaves) When your developer discovery journey is complete, please reach the -[production section](/guides/build-iapp/build-&-deploy#go-to-production). +[production section](/guides/build-iapp/build-&-test#go-to-production). ::: diff --git a/src/guides/build-iapp/advanced/access-confidential-assets.md b/src/guides/build-iapp/advanced/access-confidential-assets.md index 7d705204..4a245b95 100644 --- a/src/guides/build-iapp/advanced/access-confidential-assets.md +++ b/src/guides/build-iapp/advanced/access-confidential-assets.md @@ -18,7 +18,7 @@ indeed whitelisted for it. The SMS currently supports 3 types of secrets: -1. [Application developer secret](/guides/build-iapp/build-&-deploy#application-developer-secret): +1. [Application developer secret](/guides/build-iapp/build-&-test#application-developer-secret): This secret is directly accessible from the application as an environment variable. It is owned by the developer of the application. It can be any kind of data (API key, private key, token, ..) as long as it respects the size @@ -58,6 +58,4 @@ graph TD You now understand how these three kinds of confidential assets work on iExec, you can go one step further by learning how to manipulate them: -- [Attach a secret to your app](/guides/build-iapp/build-&-deploy#application-developer-secret) -- [Access requester secrets](/guides/build-iapp/inputs-and-outputs#access-requester-secrets) - [Access a confidential dataset](sgx-encrypted-dataset.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 08a45b38..2c3564bf 100644 --- a/src/guides/build-iapp/advanced/quick-start-for-developers.md +++ b/src/guides/build-iapp/advanced/quick-start-for-developers.md @@ -344,4 +344,3 @@ You are now familiar with the following key iExec concepts for developers: Continue with these guides: - [Learn how to build your first application running on iExec](your-first-app.md) -- [Learn how to manage your apporders](/guides/build-iapp/build-&-deploy#manage-your-apporders) diff --git a/src/guides/build-iapp/advanced/sgx-encrypted-dataset.md b/src/guides/build-iapp/advanced/sgx-encrypted-dataset.md index eee484e9..c4e84288 100644 --- a/src/guides/build-iapp/advanced/sgx-encrypted-dataset.md +++ b/src/guides/build-iapp/advanced/sgx-encrypted-dataset.md @@ -363,6 +363,4 @@ an encrypted dataset in a Confidential Computing application. To go further, check out how to: -- [Attach a secret to your app](/guides/build-iapp/build-&-deploy#application-developer-secret) -- [Access requester secrets](/guides/build-iapp/inputs-and-outputs#access-requester-secrets) - [Protect the result](end-to-end-encryption.md) diff --git a/src/guides/build-iapp/advanced/your-first-app.md b/src/guides/build-iapp/advanced/your-first-app.md index 824b15bf..e3dd5a8e 100644 --- a/src/guides/build-iapp/advanced/your-first-app.md +++ b/src/guides/build-iapp/advanced/your-first-app.md @@ -413,13 +413,3 @@ iExec: - using docker to package your app with all its dependencies - testing an iExec app locally - publishing on dockerhub - -Resources: - -- A list of iExec applications with their Docker images can be found at - [https://github.com/iExecBlockchainComputing/iexec-apps](https://github.com/iExecBlockchainComputing/iexec-apps) - -Continue with these articles: - -- [Confidential app](/guides/build-iapp/build-&-deploy#confidential-app) -- [Learn how to manage your apporders](/guides/build-iapp/build-&-deploy#manage-your-apporders) diff --git a/src/guides/build-iapp/build-&-test.md b/src/guides/build-iapp/build-&-test.md index e61d1eb8..cec884c1 100644 --- a/src/guides/build-iapp/build-&-test.md +++ b/src/guides/build-iapp/build-&-test.md @@ -209,7 +209,7 @@ The CLI will build a Docker image, run your app, and show you the results: ## Next Steps - When everything is ready - [deploy and run your iApp](../use-iapp/run-iapp-with-inputs) + [deploy and run your iApp](../use-iapp/run-iapp-with-ProtectedData) diff --git a/src/guides/use-iapp/how-to-pay/how-to-pay-for-web3mail.md b/src/guides/use-iapp/how-to-pay/how-to-pay-for-web3mail.md deleted file mode 100644 index 599832b1..00000000 --- a/src/guides/use-iapp/how-to-pay/how-to-pay-for-web3mail.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: How to Pay for Web3Mail -description: - Learn how to pay for Web3Mail's confidential computing power using vouchers - and RLC for secure, blockchain-based email communication. ---- - -# How to Pay for Web3Mail - -[Web3Mail](/references/web3mail) offers secure, blockchain-based communication -by encrypting emails and protecting user privacy. - -The `sendEmail` function uses iExec's protocol to encrypt and send messages, -ensuring secure and decentralized email exchanges. - -This guide shows how to pay for Web3Mail using **vouchers** and -****. - -## Using Vouchers for Web3Mail - -### Step 1: Obtain a Voucher - -- **Acquire Vouchers**: Obtain vouchers through the - [iExec Builder Dashboard](https://builder.iex.ec/). Note that the number of - Web3Mail executions and the expiration time of each voucher is restricted - based on its validity period. Refer to - [pricing documentation](https://www.iex.ec/voucher) for more information. -- **Support**: For specific limitations related to your voucher, please contact - iExec Support. - -### Step 2: Use the Builder Dashboard - - - Builder dashboard screenshot - - -The iExec Builder Dashboard manages vouchers and resources with an intuitive -interface for: - -- **Claiming Vouchers**: Builders can claim vouchers during the BUILD and EARN - stages. -- **Top-Up Vouchers**: Future updates will allow direct top-ups via the - dashboard. Currently, builders are redirected to Discord. -- **Checking Voucher Balance**: Track your voucher balance and usage history. - -🧙🏼 [Go here](https://builder.iex.ec/) - -### Step 3: Grant Allowance (If Necessary) - -Use `iexec.account.approve(voucherAddress)` to authorize the voucher smart -contract to debit your account if the voucher balance is insufficient. This -ensures that if the voucher alone doesn't cover the execution cost, the -remaining balance is automatically deducted from your account. - -For additional information on using for fallback payment in -Web3Mail, refer to the **Using with Web3Mail** section. - -### Step 4: Execute Web3Mail's SendEmail Function - -When using a voucher for payment, set the `useVoucher` parameter to `true`: - -```ts twoslash -import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const web3mail = new IExecWeb3mail(web3Provider); -// ---cut--- -const sendEmail = await web3mail.sendEmail({ - protectedData: '0x123abc...', - emailSubject: 'My email subject', - emailContent: 'My email content', - useVoucher: true, // [!code focus] -}); -``` - -## Using for Web3Mail - -If you choose to use to cover the computational cost of Web3Mail -(or if you need to cover data access costs such as retrieving the recipient's -email address), follow these steps: - -### Install the iExec SDK - -To manage RLC tokens, developers must use the iExec SDK, which offers all the -necessary tools for interacting with the iExec platform. This includes -depositing, withdrawing, and checking balances of RLC and - -- In your JS/TS project, run `npm install iexec` -- Instantiate the iExec SDK (see the - [doc](https://github.com/iExecBlockchainComputing/iexec-sdk/blob/master/docs/README.md#quick-start)) - -```javascript -import { IExec } from 'iexec'; -// Connect to injected provider -const iexec = new IExec({ ethProvider: window.ethereum }); -``` - -### Purchase RLC - -Obtain RLC tokens from a supported cryptocurrency exchange. For detailed -information on how to buy RLC tokens, see our -[RLC Token guide](/get-started/overview/rlc) which covers all available DEX and -CEX options. - -For detailed instructions on how to bridge RLC tokens between networks, see our -[Bridge guide](/get-started/tooling-and-explorers/bridge) which covers all -supported networks and bridging methods. - -### Deposit - -Deposit the into your iExec account using the command: - -```javascript -iexec.account.deposit(RLC_amount); -``` - -This converts into sRLC, used as proof of funds for task -execution. - -### Check sRLC Balance - -Use the command below to check your balance: - -```javascript -iexec.account.show(); -``` - -### Execute sendEmail - -Set the `useVoucher` parameter to `false` when using Web3Mail's sendEmail -function to pay with : - -```ts twoslash -import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const web3mail = new IExecWeb3mail(web3Provider); -// ---cut--- -const sendEmail = await web3mail.sendEmail({ - protectedData: '0x123abc...', - emailSubject: 'My email subject', - emailContent: 'My email content', - useVoucher: false, // [!code focus] -}); -``` - -### Withdraw sRLC (If Desired) - -Convert sRLC back to and withdraw to your wallet using: - -```javascript -iexec.account.withdraw(RLC_amount); -``` - - diff --git a/src/guides/use-iapp/how-to-pay/how-to-pay-for-web3telegram.md b/src/guides/use-iapp/how-to-pay/how-to-pay-for-web3telegram.md deleted file mode 100644 index e9a9d098..00000000 --- a/src/guides/use-iapp/how-to-pay/how-to-pay-for-web3telegram.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: How to Pay for Web3Telegram -description: - Learn how to pay for Web3Telegram's confidential computing power using - vouchers and RLC for secure, blockchain-based email communication. ---- - -# How to Pay for Web3Telegram - -[Web3Telegram](/references/web3telegram) offers secure, blockchain-based -communication by encrypting messages and protecting user privacy. - -The `sendTelegram` function uses iExec's protocol to encrypt and send messages, -ensuring secure and decentralized email exchanges. - -This guide shows how to pay for Web3Telegram using **vouchers** and -****. - -## Using Vouchers for Web3Telegram - -### Step 1: Obtain a Voucher - -- **Acquire Vouchers**: Obtain vouchers through the - [iExec Builder Dashboard](https://builder.iex.ec/). Note that the number of - Web3Telegram executions and the expiration time of each voucher is restricted - based on its validity period. Refer to - [pricing documentation](https://www.iex.ec/voucher) for more information. -- **Support**: For specific limitations related to your voucher, please contact - iExec Support. - -### Step 2: Use the Builder Dashboard - - - Builder dashboard screenshot - - -The iExec Builder Dashboard manages vouchers and resources with an intuitive -interface for: - -- **Claiming Vouchers**: Builders can claim vouchers during the BUILD and EARN - stages. -- **Top-Up Vouchers**: Future updates will allow direct top-ups via the - dashboard. Currently, builders are redirected to Discord. -- **Checking Voucher Balance**: Track your voucher balance and usage history. - -🧙🏼 [Go here](https://builder.iex.ec/) - -### Step 3: Grant Allowance (If Necessary) - -Use `iexec.account.approve(voucherAddress)` to authorize the voucher smart -contract to debit your account if the voucher balance is insufficient. This -ensures that if the voucher alone doesn't cover the execution cost, the -remaining balance is automatically deducted from your account. - -For additional information on using for fallback payment in -Web3Telegram, refer to the **Using with Web3Telegram** section. - -### Step 4: Execute Web3Telegram's `sendTelegram` Function - -When using a voucher for payment, set the `useVoucher` parameter to `true`: - -```ts twoslash -import { IExecWeb3telegram, getWeb3Provider } from '@iexec/web3telegram'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const web3telegram = new IExecWeb3telegram(web3Provider); -// ---cut--- - -const sendTelegram = await web3telegram.sendTelegram({ - protectedData: '0x123abc...', - telegramContent: 'My telegram message content', - senderName: 'Awesome project team', - label: 'some-custom-id', - workerpoolAddressOrEns: 'prod-v8-bellecour.main.pools.iexec.eth', - dataMaxPrice: 42, - appMaxPrice: 42, - workerpoolMaxPrice: 42, - useVoucher: true, // [!code focus] -}); -``` - -## Using for Web3Telegram - -If you choose to use to cover the computational cost of -Web3Telegram (or if you need to cover data access costs such as retrieving the -recipient's Chat Id), follow these steps: - -### Install the iExec SDK - -To manage RLC tokens, developers must use the iExec SDK, which offers all the -necessary tools for interacting with the iExec platform. This includes -depositing, withdrawing, and checking balances of RLC and - -- In your JS/TS project, run `npm install iexec` -- Instantiate the iExec SDK (see the - [doc](https://github.com/iExecBlockchainComputing/iexec-sdk/blob/master/docs/README.md#quick-start)) - -```javascript -import { IExec } from 'iexec'; -// Connect to injected provider -const iexec = new IExec({ ethProvider: window.ethereum }); -``` - -### Purchase RLC - -Obtain RLC tokens from a supported cryptocurrency exchange. For detailed -information on how to buy RLC tokens, see our -[RLC Token guide](/get-started/overview/rlc) which covers all available DEX and -CEX options. - -For detailed instructions on how to bridge RLC tokens between networks, see our -[Bridge guide](/get-started/tooling-and-explorers/bridge) which covers all -supported networks and bridging methods. - -### Deposit - -Deposit the into your iExec account using the command: - -```javascript -iexec.account.deposit(RLC_amount); -``` - -This converts into sRLC, used as proof of funds for task -execution. - -### Check sRLC Balance - -Use the command below to check your balance: - -```javascript -iexec.account.show(); -``` - -### Execute `sendTelegram` - -Set the `useVoucher` parameter to `false` when using Web3Telegram's sendTelegram -function to pay with : - -```ts twoslash -import { IExecWeb3telegram, getWeb3Provider } from '@iexec/web3telegram'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const web3telegram = new IExecWeb3telegram(web3Provider); -// ---cut--- - -const sendTelegram = await web3telegram.sendTelegram({ - protectedData: '0x123abc...', - telegramContent: 'My telegram message content', - senderName: 'Awesome project team', - label: 'some-custom-id', - workerpoolAddressOrEns: 'prod-v8-bellecour.main.pools.iexec.eth', - dataMaxPrice: 42, - appMaxPrice: 42, - workerpoolMaxPrice: 42, - useVoucher: false, // [!code focus] -}); -``` - -### Withdraw sRLC (If Desired) - -Convert sRLC back to and withdraw to your wallet using: - -```javascript -iexec.account.withdraw(RLC_amount); -``` - - diff --git a/src/guides/use-iapp/how-to-pay/pricing-considerations.md b/src/guides/use-iapp/how-to-pay/pricing-considerations.md deleted file mode 100644 index 09587a20..00000000 --- a/src/guides/use-iapp/how-to-pay/pricing-considerations.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Pricing Considerations -description: Pricing considerations ---- - -# Pricing Considerations - -This page is under development. - - diff --git a/src/guides/use-iapp/how-to-pay/voucher.md b/src/guides/use-iapp/how-to-pay/voucher.md deleted file mode 100644 index cf1c7822..00000000 --- a/src/guides/use-iapp/how-to-pay/voucher.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Voucher Guide -description: Voucher Guide ---- - -# Voucher Guide - -This page is under development. - - diff --git a/src/guides/use-iapp/run-iapp-with-ProtectedData.md b/src/guides/use-iapp/run-iapp-with-ProtectedData.md index 7fa99f17..479f228c 100644 --- a/src/guides/use-iapp/run-iapp-with-ProtectedData.md +++ b/src/guides/use-iapp/run-iapp-with-ProtectedData.md @@ -113,10 +113,3 @@ const result = await dataProtectorCore.processProtectedData({ }, }); ``` - -## Next Steps - -Now that you understand how to add inputs to iApp executions: - -- Check out our - [How to Pay for Executions](/guides/use-iapp/how-to-pay-executions) guide diff --git a/src/guides/use-iapp/run-iapp-without-ProtectedData.md b/src/guides/use-iapp/run-iapp-without-ProtectedData.md index 4a569032..f568f619 100644 --- a/src/guides/use-iapp/run-iapp-without-ProtectedData.md +++ b/src/guides/use-iapp/run-iapp-without-ProtectedData.md @@ -176,7 +176,3 @@ const taskId = await iexec.order.matchOrders({ workerpoolorder: workerpoolOrders.orders[0].order, }); ``` - -## Next Steps - -Now that you understand how to add inputs to iApp executions: diff --git a/src/references/sdk.md b/src/references/sdk.md index 54ee6c83..f56f75db 100644 --- a/src/references/sdk.md +++ b/src/references/sdk.md @@ -9,8 +9,72 @@ The iExec SDK is a [CLI](#command-line-interface) and a [JS library](#javascripttypescript-library) that allows easy interactions with iExec decentralized marketplace in order to run off-chain computations. -iExec SDK is available on [npm](https://www.npmjs.com/package/iexec) and -[GitHub](https://github.com/iExecBlockchainComputing/iexec-sdk) +## Overview + +### Prerequisites + +Before getting started, ensure that you have the following installed on your +system: + +\- [**Node.js**](https://nodejs.org/en/) version 18 or higher + +\- [**NPM**](https://docs.npmjs.com/) (Node.js package manager) + +### Installation + +::: code-group + +```sh [npm] +npm install @iexec/dataprotector +``` + +```sh [yarn] +yarn add @iexec/dataprotector +``` + +```sh [pnpm] +pnpm add @iexec/dataprotector +``` + +```sh [bun] +bun add @iexec/dataprotector +``` + +::: + +### Instantiate SDK + +::: code-group + +```ts twoslash [Browser] +declare global { + interface Window { + ethereum: any; + } +} +// ---cut--- +import { IExec } from 'iexec'; + +// Connect to injected provider +const iexec = new IExec({ ethProvider: window.ethereum }); +``` + +```ts twoslash [NodeJS] +import { IExec, utils } from 'iexec'; + +const ethProvider = utils.getSignerFromPrivateKey( + 'http://localhost:8545', // blockchain node URL + 'YOUR_PRIVATE_KEY' +); +const iexec = new IExec({ + ethProvider, +}); +``` + +::: + +For comprehensive documentation and advanced usage examples, see the +[iExec SDK GitHub repository](https://github.com/iExecBlockchainComputing/iexec-sdk/blob/master/docs/README.md). ## Command Line Interface diff --git a/src/references/web3mail/methods/sendEmail.md b/src/references/web3mail/methods/sendEmail.md index 39d3cdfc..4eefbaa3 100644 --- a/src/references/web3mail/methods/sendEmail.md +++ b/src/references/web3mail/methods/sendEmail.md @@ -23,7 +23,7 @@ documentation for more details. For executing the `sendEmail` method with a voucher or , refer to the dedicated section in the documentation under -"[How to Pay for web3mail](/guides/use-iapp/how-to-pay/how-to-pay-for-web3mail)". +"[How to Pay for Executions](/guides/use-iapp/how-to-pay-executions.md)". ::: diff --git a/src/references/web3telegram/methods/sendTelegram.md b/src/references/web3telegram/methods/sendTelegram.md index c14135ac..6b9e1450 100644 --- a/src/references/web3telegram/methods/sendTelegram.md +++ b/src/references/web3telegram/methods/sendTelegram.md @@ -23,7 +23,7 @@ documentation for more details. For executing the `sendTelegram` method with a voucher or , refer to the dedicated section in the documentation under -"[How to Pay for web3telegram](/guides/use-iapp/how-to-pay/how-to-pay-for-web3telegram)". +"[How to Pay for Executions](/guides/use-iapp/how-to-pay-executions.md)". ::: From 013d9eafe2f343db95616cba758839d18d04f623 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Wed, 20 Aug 2025 09:36:37 +0200 Subject: [PATCH 17/17] fix: update voucher usage and clarify price parameters in payment guide --- src/guides/use-iapp/how-to-pay-executions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/guides/use-iapp/how-to-pay-executions.md b/src/guides/use-iapp/how-to-pay-executions.md index fe215210..ec96ffbc 100644 --- a/src/guides/use-iapp/how-to-pay-executions.md +++ b/src/guides/use-iapp/how-to-pay-executions.md @@ -120,7 +120,7 @@ const sendEmail = await web3mail.sendEmail({ protectedData: '0x123abc...', emailSubject: 'My email subject', emailContent: 'My email content', - useVoucher: false, // [!code focus] + useVoucher: true, // [!code focus] }); ``` @@ -223,8 +223,8 @@ const result = await dataProtectorCore.processProtectedData({ ::: info -All price parameters are in **nRLC** (nano RLC). The default value for all price -parameters is `0`, which means no maximum price limit is set. +All price parameters are in nRLC (nano RLC). The default value for all price +parameters is 0, which means only free resources are accepted. :::