From 7f7713d915871d0a3800db885bd8475a00a7f498 Mon Sep 17 00:00:00 2001 From: aimen-djari Date: Fri, 8 Aug 2025 11:21:28 +0100 Subject: [PATCH 1/8] add intro, getting started and few guides --- .vitepress/sidebar.ts | 14 +- src/use-iapp/getting-started.md | 132 ++- .../guides/add-inputs-to-execution.md | 769 +++++++++++++++++- .../guides/different-ways-to-execute.md | 108 ++- src/use-iapp/guides/find-iapps.md | 108 ++- src/use-iapp/guides/how-to-pay-executions.md | 382 ++++++++- .../guides/use-iapp-with-protected-data.md | 465 ++++++++++- src/use-iapp/introduction.md | 37 +- 8 files changed, 1976 insertions(+), 39 deletions(-) diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index 315595b0..84be3e8a 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -424,20 +424,20 @@ export function getSidebar() { text: '📖 Guides', items: [ { - text: 'Different ways to execute an iApp', - link: '/use-iapp/guides/different-ways-to-execute', + text: 'Find iApps to Use', + link: '/use-iapp/guides/find-iapps', }, { - text: 'Add inputs to the execution', - link: '/use-iapp/guides/add-inputs-to-execution', + text: 'Different ways to execute an iApp', + link: '/use-iapp/guides/different-ways-to-execute', }, { text: 'Use iApp with Protected Data', link: '/use-iapp/guides/use-iapp-with-protected-data', }, { - text: 'Find iApps to Use', - link: '/use-iapp/guides/find-iapps', + text: 'Add inputs to the execution', + link: '/use-iapp/guides/add-inputs-to-execution', }, { text: 'How to pay the executions', @@ -467,7 +467,7 @@ export function getSidebar() { ], }, { - text: '✉ Web3Mail', + text: '📨 Web3Mail', link: '/use-iapp/web3mail', collapsed: true, items: [ diff --git a/src/use-iapp/getting-started.md b/src/use-iapp/getting-started.md index 4000de65..b615cb91 100644 --- a/src/use-iapp/getting-started.md +++ b/src/use-iapp/getting-started.md @@ -1,10 +1,134 @@ --- title: Getting Started with iApps -description: Getting started with iApps +description: Learn the basics of finding and executing iApps on the iExec network --- -# 🚀 Getting Started +# 🚀 Getting Started with iApps -This page is under development. +Welcome to the world of secure, privacy-preserving computation! This guide will walk you through the essential steps to start using iApps on the iExec network. - +## Prerequisites + +Before you begin, make sure you have: + +- A Web3 wallet (MetaMask, WalletConnect, etc.) +- Some RLC tokens for paying computation fees (or access to free vouchers through learning programs) +- Basic understanding of blockchain transactions + +### 🆓 Use Our Stack for Free! + +Good news! You can start using iApps **completely free** through our learning programs: + +- **Learn Web3 Program**: Get free access to our entire stack, including vouchers for iApp executions +- **Free Vouchers**: Pre-funded computation credits provided through learning initiatives +- **No RLC Required**: Start experimenting and building without any upfront costs + +### 💰 Getting Started Without RLC + +Don't have RLC tokens yet? No problem! Our learning programs provide everything you need: + +- **Free Vouchers**: Access to pre-funded computation credits +- **Full Stack Access**: Use all iExec tools and infrastructure at no cost +- **Educational Support**: Learn while you build with our community + +Ready to dive in? Let's get started with finding and executing your first iApp! + +## Step 1: Find Available iApps + +The first step is discovering what iApps are available for your use case. You can find iApps through several methods: + +1. Visit the [iExec Explorer](https://explorer.iex.ec) +2. Navigate to the "Apps" section +3. Browse available applications by category or search by name +4. Check the app's description, requirements, and pricing + +## Step 2: Understand App Requirements + +Before executing an iApp, understand what it needs: + +- **Protected Data**: Some apps require specific types of protected data +- **Input Parameters**: Check if the app needs command-line arguments +- **Input Files**: Some apps require additional files (URLs to public files) +- **Secrets**: Certain apps need requester secrets for API keys, etc. + +## Step 3: Prepare Your Data + +If the iApp requires protected data: + +1. **Protect Your Data**: Use the [Data Protector](/manage-data/dataProtector/dataProtectorCore/protectData) to encrypt your sensitive information +2. **Grant Access**: Ensure the iApp has permission to access your protected data using [grantAccess](/manage-data/dataProtector/dataProtectorCore/grantAccess) + +## Step 4: Execute the iApp + +### Using the DataProtector SDK + +```typescript +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider(window.ethereum); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +// Execute the iApp with protected data +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', // Your protected data address + app: '0x456def...', // The iApp address + args: 'optional arguments', + maxPrice: 10, // Maximum price in nRLC +}); +``` + +### Using the CLI + +```bash +# Execute an iApp with protected data +iexec app run 0x456def... --dataset 0x123abc... --args "your arguments" +``` + +## Step 5: Monitor and Retrieve Results + +After submitting your task: + +1. **Monitor Progress**: Track your task on the [iExec Explorer](https://explorer.iex.ec) +2. **Retrieve Results**: Get your results once the task completes + +### Using the DataProtector SDK + +```typescript +// Retrieve results from a completed task +const taskResult = await dataProtectorCore.getResultFromCompletedTask({ + taskId: '0x7ac398...', // Your task ID +}); +``` + +### Using the CLI + +```bash +# Get task result +iexec task show 0x7ac398... + +# Download task result +iexec task show 0x7ac398... --download +``` + +## Step 6: Understand Costs + +iApp execution costs include: + +- **Application Fee**: Paid to the app developer +- **Data Fee**: Paid to the data owner (if using protected data) +- **Workerpool Fee**: Paid to the computation provider +- **Gas Fees**: Blockchain transaction costs (free on Bellecour sidechain) + +## Next Steps + +Now that you understand the basics: + +- Explore our [Guides](./guides/) for detailed tutorials +- Learn about [Different Ways to Execute](./guides/different-ways-to-execute.md) iApps +- Understand [How to Pay for Executions](./guides/how-to-pay-executions.md) +- Discover how to [Use iApps with Protected Data](./guides/use-iapp-with-protected-data.md) + +## Need Help? + +- Check the [iExec Explorer](https://explorer.iex.ec) for app details +- Visit our [Discord community](https://discord.gg/iexec) for support diff --git a/src/use-iapp/guides/add-inputs-to-execution.md b/src/use-iapp/guides/add-inputs-to-execution.md index 8f1b592b..5848e1fd 100644 --- a/src/use-iapp/guides/add-inputs-to-execution.md +++ b/src/use-iapp/guides/add-inputs-to-execution.md @@ -1,10 +1,769 @@ --- -title: Add inputs to the execution -description: Add inputs to the execution +title: Add Inputs to iApp Execution +description: Learn how to provide arguments, files, secrets, and other inputs to iApp executions --- -# Add inputs to the execution +# 📥 Add Inputs to iApp Execution -This page is under development. +iApps 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 SDKs. - +::: 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. +::: + +## 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 + +## Method 1: Adding Command-Line Arguments + +Command-line arguments are passed as a string to the iApp and are visible on the blockchain. + +### Using SDK Library + +```typescript +import { IExecConfig, IExecOrderModule, IExecOrderbookModule } from '@iexec/sdk'; + +// create the configuration +const config = new IExecConfig({ ethProvider: window.ethereum }); + +// instantiate modules sharing the same configuration +const orderModule = IExecOrderModule.fromConfig(config); +const orderbookModule = IExecOrderbookModule.fromConfig(config); + +// Basic arguments +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + params: 'arg1 arg2 arg3', // Command-line arguments + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], // Select appropriate app order + workerpoolorder: workerpoolOrders[0], // Select appropriate workerpool order +}); + +// Complex arguments with spaces and quotes +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + params: '--input-file data.csv --output-format json --message "Hello World"', + // Other parameters have default values +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + workerpoolorder: workerpoolOrders[0], +}); + +// With protected data +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + dataset: '0x123abc...', // Protected data address + datasetmaxprice: 5, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + params: '--input-path data/input.csv --output-format json --verbose', + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const datasetOrders = await orderbookModule.fetchDatasetOrderbook({ + dataset: '0x123abc...', // Filter by specific dataset +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + datasetorder: datasetOrders[0], // Select appropriate dataset order + workerpoolorder: workerpoolOrders[0], +}); +``` + +### 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 + +```typescript +import { IExecDataProtectorCore } from '@iexec/dataprotector'; + +const dataProtector = new IExecDataProtectorCore(web3Provider); + +// Process protected data with arguments +const result = await dataProtector.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + args: '--input-path data/input.csv --output-format json --verbose', + maxPrice: 10, +}); + + +``` + +## Method 2: Adding Input Files + +Input files are URLs to public files that the iApp can download during execution. + +### Using SDK Library + +```typescript +import { IExecConfig, IExecOrderModule, IExecOrderbookModule } from '@iexec/sdk'; + +// create the configuration +const config = new IExecConfig({ ethProvider: window.ethereum }); + +// instantiate modules sharing the same configuration +const orderModule = IExecOrderModule.fromConfig(config); +const orderbookModule = IExecOrderbookModule.fromConfig(config); + +// Single input file +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + workerpoolorder: workerpoolOrders[0], + inputFiles: ['https://example.com/config.json'], +}); + +// Multiple input files +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + workerpoolorder: workerpoolOrders[0], + inputFiles: [ + 'https://example.com/config.json', + 'https://example.com/template.html', + 'https://example.com/data.csv' + ], +}); + +// With protected data and input files +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + dataset: '0x123abc...', // Protected data address + datasetmaxprice: 5, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const datasetOrders = await orderbookModule.fetchDatasetOrderbook({ + dataset: '0x123abc...', // Filter by specific dataset +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + datasetorder: datasetOrders[0], + workerpoolorder: workerpoolOrders[0], + inputFiles: [ + 'https://raw.githubusercontent.com/user/repo/main/config.json', + 'https://example.com/public-data.csv' + ], +}); +``` + +### 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 + +```typescript +import { IExecDataProtectorCore } from '@iexec/dataprotector'; + +const dataProtector = new IExecDataProtectorCore(web3Provider); + +// Process protected data with input files +const result = await dataProtector.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + inputFiles: [ + 'https://raw.githubusercontent.com/user/repo/main/config.json', + 'https://example.com/public-data.csv' + ], + maxPrice: 10, +}); + + +``` + +## Method 3: 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 + +```typescript +import { IExecConfig, IExecOrderModule, IExecOrderbookModule, IExecSecretsModule } from '@iexec/sdk'; + +// create the configuration +const config = new IExecConfig({ ethProvider: window.ethereum }); + +// instantiate modules sharing the same configuration +const orderModule = IExecOrderModule.fromConfig(config); +const orderbookModule = IExecOrderbookModule.fromConfig(config); +const secretsModule = IExecSecretsModule.fromConfig(config); + +// Basic secrets +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + workerpoolorder: workerpoolOrders[0], + secrets: { + 1: 'api-key-12345', + 2: 'database-password', + }, +}); + +// Multiple secrets +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + workerpoolorder: workerpoolOrders[0], + secrets: { + 1: 'openai-api-key', + 2: 'database-connection-string', + 3: 'jwt-secret', + 4: 'encryption-key', + }, +}); + +// With protected data and secrets +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + dataset: '0x123abc...', // Protected data address + datasetmaxprice: 5, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const datasetOrders = await orderbookModule.fetchDatasetOrderbook({ + dataset: '0x123abc...', // Filter by specific dataset +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + datasetorder: datasetOrders[0], + workerpoolorder: workerpoolOrders[0], + secrets: { + 1: 'openai-api-key', + 2: 'database-password', + }, +}); +``` + +### 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 + +```typescript +import { IExecDataProtectorCore } from '@iexec/dataprotector'; + +const dataProtector = new IExecDataProtectorCore(web3Provider); + +// Process protected data with secrets +const result = await dataProtector.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + secrets: { + 1: 'openai-api-key', + 2: 'database-password', + }, + maxPrice: 10, +}); + +``` + +## Method 4: Specifying File Paths in Protected Data + +When working with protected data that contains multiple files, you can specify which file to process. + +### Using SDK Library + +```typescript +import { IExecConfig, IExecOrderModule, IExecOrderbookModule, IExecResultModule } from '@iexec/sdk'; + +// create the configuration +const config = new IExecConfig({ ethProvider: window.ethereum }); + +// instantiate modules sharing the same configuration +const orderModule = IExecOrderModule.fromConfig(config); +const orderbookModule = IExecOrderbookModule.fromConfig(config); +const resultModule = IExecResultModule.fromConfig(config); + +// Basic path specification (with protected data) +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + dataset: '0x123abc...', // Protected data address + datasetmaxprice: 5, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const datasetOrders = await orderbookModule.fetchDatasetOrderbook({ + dataset: '0x123abc...', // Filter by specific dataset +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + datasetorder: datasetOrders[0], + workerpoolorder: workerpoolOrders[0], + path: 'my-content', // Extract specific file from protected data +}); + +// Complex path examples (with protected data) +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + dataset: '0x123abc...', // Protected data address + datasetmaxprice: 5, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + datasetorder: datasetOrders[0], + workerpoolorder: workerpoolOrders[0], + path: 'data/processed/results.json', +}); + +// Retrieve specific file from task result +const taskResult = await resultModule.getTaskResult({ + taskId: '0x7ac398...', + path: 'computed.json', // Extract specific file from result +}); +``` + +### Using SDK CLI + +```bash +# Basic path specification +iexec app run 0x456def... --protectedData 0x123abc... --path "my-content" + +# Complex path +iexec app run 0x456def... --protectedData 0x123abc... --path "data/processed/results.json" + +# Retrieve result with specific path +iexec task show 0x7ac398... --path "computed.json" +``` + +### Using DataProtector + +```typescript +import { IExecDataProtectorCore } from '@iexec/dataprotector'; + +const dataProtector = new IExecDataProtectorCore(web3Provider); + +// Process protected data with specific path +const result = await dataProtector.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + path: 'data/input.csv', + maxPrice: 10, +}); + +// Get result with specific path +const taskResult = await dataProtector.getResultFromCompletedTask({ + taskId: '0x7ac398...', + path: 'output/analysis.json', +}); +``` + +## Method 5: Combining Multiple Input Types + +You can combine different types of inputs for complex executions. + +### Using SDK Library + +```typescript +import { IExecConfig, IExecOrderModule, IExecOrderbookModule, IExecSecretsModule } from '@iexec/sdk'; + +// create the configuration +const config = new IExecConfig({ ethProvider: window.ethereum }); + +// instantiate modules sharing the same configuration +const orderModule = IExecOrderModule.fromConfig(config); +const orderbookModule = IExecOrderbookModule.fromConfig(config); +const secretsModule = IExecSecretsModule.fromConfig(config); + +// Complete example with all input types +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', + appmaxprice: 10, + dataset: '0x123abc...', // Protected data address + datasetmaxprice: 5, + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + params: '--mode production --output-format json', + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const datasetOrders = await orderbookModule.fetchDatasetOrderbook({ + dataset: '0x123abc...', // Filter by specific dataset +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + datasetorder: datasetOrders[0], + workerpoolorder: workerpoolOrders[0], + inputFiles: [ + 'https://example.com/config.json', + 'https://example.com/template.html' + ], + secrets: { + 1: 'api-key-12345', + 2: 'database-password', + }, + path: 'data/input.csv', +}); +``` + +### Using SDK CLI + +```bash +# Combine multiple input types +iexec app run 0x456def... \ + --protectedData 0x123abc... \ + --args "--mode production --output-format json" \ + --inputFiles "https://example.com/config.json,https://example.com/template.html" \ + --path "data/input.csv" \ + --maxPrice 10 + +# Note: Secrets must be handled via SDK due to CLI limitations +``` + +### Using DataProtector + +```typescript +import { IExecDataProtectorCore } from '@iexec/dataprotector'; + +const dataProtector = new IExecDataProtectorCore(web3Provider); + +// Process protected data with multiple input types +const result = await dataProtector.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + args: '--mode production --output-format json', + inputFiles: [ + 'https://example.com/config.json', + 'https://example.com/template.html' + ], + secrets: { + 1: 'api-key-12345', + 2: 'database-password', + }, + path: 'data/input.csv', + maxPrice: 10, +}); +``` + +## How Secrets Work in iApps + +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' +``` + +## Input Validation and Error Handling + +### Validate Inputs Before Execution + +```typescript +const validateInputs = (params) => { + const errors = []; + + // Validate arguments + if (params.args && params.args.length > 1000) { + errors.push('Arguments too long (max 1000 characters)'); + } + + // Validate input files + if (params.inputFiles) { + params.inputFiles.forEach((url, index) => { + if (!url.startsWith('https://')) { + errors.push(`Input file ${index + 1} must use HTTPS`); + } + }); + } + + // Validate secrets + if (params.secrets) { + Object.keys(params.secrets).forEach(key => { + if (!/^\d+$/.test(key)) { + errors.push('Secret keys must be numeric'); + } + }); + } + + return errors; +}; + +// Use validation +const params = { + protectedData: '0x123abc...', + app: '0x456def...', + args: '--test', + inputFiles: ['https://example.com/file.json'], + secrets: { 1: 'secret' }, + maxPrice: 10, +}; + +const errors = validateInputs(params); +if (errors.length > 0) { + console.error('Validation errors:', errors); + return; +} + +const result = await dataProtectorCore.processProtectedData(params); +``` + +### Handle Input-Related Errors + +```typescript +try { + const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + args: '--invalid-option', + maxPrice: 10, + }); +} catch (error) { + if (error.message.includes('argument')) { + console.log('Invalid arguments provided'); + } else if (error.message.includes('file')) { + console.log('Input file not accessible'); + } else if (error.message.includes('secret')) { + console.log('Secret configuration error'); + } else { + console.log('Execution failed:', error.message); + } +} +``` + +## Best Practices + +### 1. Use Appropriate Input Types + +```typescript +// ✅ Use secrets for sensitive data +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + secrets: { 1: 'api-key' }, // Sensitive data + args: '--mode production', // Non-sensitive configuration + maxPrice: 10, +}); +``` + +### 2. Validate URLs and Files + +```typescript +// ✅ Ensure input files are accessible +const inputFiles = [ + 'https://raw.githubusercontent.com/user/repo/main/config.json', + 'https://example.com/public-data.csv' +]; + +// Test file accessibility before execution +const testFileAccess = async (url) => { + try { + const response = await fetch(url, { method: 'HEAD' }); + return response.ok; + } catch { + return false; + } +}; + +const accessibleFiles = await Promise.all( + inputFiles.map(async (url) => ({ + url, + accessible: await testFileAccess(url) + })) +); + +const validFiles = accessibleFiles + .filter(file => file.accessible) + .map(file => file.url); +``` + +### 3. Use Descriptive Arguments + +```typescript +// ✅ Clear, descriptive arguments +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + args: '--input-format csv --output-format json --verbose --log-level info', + maxPrice: 10, +}); +``` + +### 4. Organize Secrets Logically + +```typescript +// ✅ Logical secret numbering +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + secrets: { + 1: 'primary-api-key', // Main API key + 2: 'backup-api-key', // Backup API key + 3: 'database-password', // Database credentials + 4: 'encryption-key', // Encryption key + }, + maxPrice: 10, +}); +``` + +## Next Steps + +Now that you understand how to add inputs to iApp executions: + +- Learn about [Using iApps with Protected Data](./use-iapp-with-protected-data.md) +- Explore [Different Ways to Execute](./different-ways-to-execute.md) iApps +- Check out our [How to Pay for Executions](./how-to-pay-executions.md) guide diff --git a/src/use-iapp/guides/different-ways-to-execute.md b/src/use-iapp/guides/different-ways-to-execute.md index 28d0e1ff..5dc21a8c 100644 --- a/src/use-iapp/guides/different-ways-to-execute.md +++ b/src/use-iapp/guides/different-ways-to-execute.md @@ -1,10 +1,108 @@ --- -title: Different ways to execute an iApp -description: Different ways to execute an iApp +title: Different Ways to Execute iApps +description: Learn about various methods for executing iApps on the iExec network --- -# Different ways to execute an iApp +# ⚡ Different Ways to Execute iApps -This page is under development. +There are multiple ways to execute iApps 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 iApps. + +```typescript +import { IExecConfig, IExecOrderModule, IExecOrderbookModule } from '@iexec/sdk'; + +// create the configuration +const config = new IExecConfig({ ethProvider: window.ethereum }); + +// instantiate modules sharing the same configuration +const orderModule = IExecOrderModule.fromConfig(config); +const orderbookModule = IExecOrderbookModule.fromConfig(config); + +// Create a request order +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', // The iApp address + appmaxprice: 10, // Maximum price in nRLC + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +// Execute the task +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + workerpoolorder: workerpoolOrders[0], +}); +``` + +## Method 2: Using the iExec CLI + +The iExec CLI is perfect for quick executions and automation scripts. + +### Installation + +```bash +npm install -g @iexec/iexec +``` + +### Basic CLI Execution + +```bash +# Execute an iApp +iexec app run 0x456def... + +# Set maximum price +iexec app run 0x456def... --maxPrice 10 +``` + +## Method 3: Using the iApp Generator CLI + +The iApp Generator CLI provides a streamlined way to execute iApps, especially for developers who have built their own iApps. + +### Installation + +```bash +npm install -g @iexec/iapp +``` + +### Basic Execution + +```bash +# Execute a deployed iApp +iapp run 0x456def... +``` + +### Testing Before Execution + +```bash +# Test the iApp locally first +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 iApps + +## Next Steps + +- Learn how to [use iApps with protected data](./use-iapp-with-protected-data.md) +- Discover how to [add inputs to execution](./add-inputs-to-execution.md) +- Understand [how to pay for executions](./how-to-pay-executions.md) diff --git a/src/use-iapp/guides/find-iapps.md b/src/use-iapp/guides/find-iapps.md index 2353eed1..0e2eeb98 100644 --- a/src/use-iapp/guides/find-iapps.md +++ b/src/use-iapp/guides/find-iapps.md @@ -1,10 +1,110 @@ --- title: Find iApps to Use -description: Find iApps to Use +description: Discover and explore available iApps on the iExec network --- -# Find iApps to Use +# 🔍 Find iApps to Use -This page is under development. +Discovering the right iApp for your needs is the first step toward secure, privacy-preserving computation. Here are several ways to find and explore available iApps on the iExec network. - +## Using the iExec Explorer + +The [iExec Explorer](https://explorer.iex.ec) is the primary tool for discovering iApps. + +### Step-by-Step Discovery + +1. **Visit the Explorer**: Go to [explorer.iex.ec](https://explorer.iex.ec) +2. **Navigate to Apps**: Click on the "Apps" section in the navigation +3. **Search by Name**: Use the search function to find specific applications +4. **View Details**: Click on any app to see detailed information + +### What to Look For + +When evaluating an iApp, check these key details: + +- **Description**: What does the app do? +- **Requirements**: What type of data or inputs does it need? +- **Pricing**: How much does execution cost? +- **Developer**: Who created the app? +- **Usage Statistics**: How often is it used? +- **Orders Availability**: Are there active orders available for execution? + +## Using the iExec CLI + +For developers who prefer command-line tools, the iExec CLI provides programmatic access to app discovery. + +### Installation + +```bash +npm install -g @iexec/iexec +``` + +### Basic Commands + +```bash +# Note: Use the iExec Explorer for discovering applications +# The CLI is primarily for executing applications, not listing them + +# Get detailed information about a specific app (if you have the address) +iexec app show +``` + +## Popular iApp Categories + +### Communication Apps +- **Web3Mail**: Send encrypted emails without seeing recipient addresses +- **Web3Telegram**: Send Telegram messages with protected contact lists + +### Data Processing +- **Content Creator**: Process and deliver content using protected data +- **Data Analytics**: Analyze sensitive datasets without exposing raw data + +### Oracle Services +- **Oracle Factory**: Create and manage price oracles +- **Data Feeds**: Update external systems with private data + +### AI and Machine Learning +- **Model Training**: Train AI models on protected datasets +- **Inference Services**: Run AI inference on sensitive data + +## Evaluating App Quality + +Before using an iApp, consider these factors: + +### Reliability +- **Usage History**: How many times has the app been executed? +- **Success Rate**: What percentage of executions succeed? +- **Developer Reputation**: Is the developer known and trusted? + +### Cost Efficiency +- **Execution Cost**: Is the price reasonable for the computation? +- **Competitive Pricing**: How does it compare to similar apps? + +## Community Resources + +### Discord Community +Join the [iExec Discord](https://discord.gg/iexec) to: +- Ask questions about specific apps +- Get recommendations from other users +- Learn about new apps and updates + +### GitHub Repositories +Many iApp developers share their code on GitHub: +- Review the source code +- Check for recent updates +- Report issues or suggest improvements + +### Documentation +- **App-Specific Docs**: Check if the developer provides detailed documentation +- **Community Guides**: Look for tutorials and guides from the community + +## Next Steps + +Once you've found an iApp that meets your needs: + +1. **Read the Documentation**: Understand how to use the app properly +2. **Check Requirements**: Ensure you have the necessary data and permissions +3. **Test with Small Data**: Start with a small test before processing large datasets +4. **Monitor Execution**: Track your first few executions to ensure everything works as expected + +Ready to execute your first iApp? Check out our [Getting Started Guide](../getting-started.md) for the next steps! diff --git a/src/use-iapp/guides/how-to-pay-executions.md b/src/use-iapp/guides/how-to-pay-executions.md index 0adc35e6..04f393f1 100644 --- a/src/use-iapp/guides/how-to-pay-executions.md +++ b/src/use-iapp/guides/how-to-pay-executions.md @@ -1,10 +1,382 @@ --- -title: How to pay the executions -description: How to pay for executions +title: How to Pay for iApp Executions +description: Learn about payment methods, pricing, and cost management for iApp executions --- -# How to pay the executions +# 💰 How to Pay for iApp Executions -This page is under development. +Understanding how to pay for iApp executions is crucial for using the iExec network effectively. This guide covers all payment methods, pricing structures, and cost management strategies. - +## Payment Methods Overview + +iExec supports multiple payment methods for executing iApps: + +1. **RLC Tokens**: Direct payment using RLC (Request Compute Language) tokens +2. **Vouchers**: Pre-funded vouchers for simplified payment +3. **Mixed Payment**: Combination of RLC and vouchers + +## Method 1: Paying with RLC Tokens + +RLC tokens are the native currency of the iExec network. You need to have RLC in your wallet to pay for executions. + +### Setting Up RLC Payment + +#### Step 1: Get RLC Tokens + +You can obtain RLC tokens from various exchanges: +- **Centralized Exchanges**: Binance, Coinbase, Kraken +- **Decentralized Exchanges**: Uniswap, SushiSwap +- **Direct Purchase**: Through iExec's official channels + +#### Step 2: Transfer to iExec Sidechain + +RLC tokens need to be on the iExec sidechain (Bellecour) for payments: + +```typescript +import { IExecConfig, IExecAccountModule } from '@iexec/sdk'; + +// create the configuration +const config = new IExecConfig({ ethProvider: window.ethereum }); + +// instantiate account module +const accountModule = IExecAccountModule.fromConfig(config); + +// Check your balance +const balance = await accountModule.show(); +console.log('Current balance:', balance); + +// Deposit RLC to the sidechain +await accountModule.deposit(100); // Deposit 100 RLC +``` + +#### Step 3: Execute with RLC Payment + +```typescript +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider(window.ethereum); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +// Execute with RLC payment (default) +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + maxPrice: 10, // Maximum price in nRLC + useVoucher: false, // Explicitly use RLC payment +}); +``` + +### Using CLI with RLC + +```bash +# Execute with RLC payment +iexec app run 0x456def... --protectedData 0x123abc... --maxPrice 10 + +# 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 and can be shared with others. + +### Understanding Vouchers + +Vouchers are ERC-20 tokens that represent pre-funded computation credits on the iExec network. They offer several advantages: + +- **Simplified Payment**: No need to manage RLC transfers +- **Sharing**: Can be shared with team members or users +- **Budget Control**: Set spending limits +- **Automated Top-up**: Can be configured to automatically refill + +### Using Vouchers for Payment + +#### Basic Voucher Usage + +```typescript +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + maxPrice: 10, + useVoucher: true, // Use voucher for payment +}); +``` + +::: tip + +If your voucher doesn't have enough xRLC to cover the deal, the SDK will automatically get the required amount to your iExec account. Ensure that your voucher is authorized to access your iExec account and that your account has sufficient funds for this transfer to proceed. + +::: + +#### Using Someone Else's Voucher + +```typescript +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + maxPrice: 10, + useVoucher: true, + voucherOwner: '0x5714eB...', // Voucher owner's address +}); +``` + +::: warning + +Make sure the voucher's owner has authorized you to use it. This parameter must be used in combination with `useVoucher: true`. + +::: + +#### CLI with Vouchers + +```bash +# Use your own voucher +iexec app run 0x456def... --protectedData 0x123abc... --useVoucher + +# Use someone else's voucher +iexec app run 0x456def... --protectedData 0x123abc... --useVoucher --voucherOwner 0x5714eB... +``` + + + +## Understanding Pricing + +### Cost Components + +iApp execution costs consist of several components: + +1. **Application Fee**: Paid to the app developer +2. **Data Fee**: Paid to the data owner (if using protected data) +3. **Workerpool Fee**: Paid to the computation provider +4. **Gas Fees**: Blockchain transaction costs + +### Setting Maximum Prices + +You can control costs by setting maximum prices for each component: + +```typescript +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + dataMaxPrice: 5, // Maximum amount (in nRLC) to pay the protected data owner + appMaxPrice: 3, // Maximum amount (in nRLC) to pay the iApp provider + workerpoolMaxPrice: 2, // Maximum amount (in nRLC) to pay the workerpool provider +}); +``` + +::: 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. + +::: + + + +## Cost Management Strategies + +### 1. Monitor Your Balance + +Regularly check your RLC balance and voucher status: + +```typescript +// Check RLC balance +const balance = await iexec.account.show(); +console.log('RLC Balance:', balance); + +// Check voucher balance (if applicable) +const voucherBalance = await iexec.voucher.show(); +console.log('Voucher Balance:', voucherBalance); +``` + +### 2. Set Reasonable Price Limits + +Always set maximum prices to avoid unexpected costs: + +```typescript +// Good practice: Set explicit price limits +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + dataMaxPrice: 5, // Maximum for data access + appMaxPrice: 3, // Maximum for app usage + workerpoolMaxPrice: 2, // Maximum for computation +}); +``` + +### 3. Use Vouchers for Regular Usage + +For frequent executions, consider using vouchers: + +```typescript +// Use vouchers for regular operations +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + maxPrice: 10, + useVoucher: true, // Simplify payment process +}); +``` + +### 4. Batch Operations + +Group multiple executions to optimize costs: + +```typescript +// Execute multiple tasks efficiently +const tasks = [ + { protectedData: '0x123abc...', app: '0x456def...' }, + { protectedData: '0x789def...', 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 + +If you encounter insufficient balance errors: + +```typescript +try { + const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + maxPrice: 10, + }); +} catch (error) { + if (error.message.includes('insufficient balance')) { + console.log('Please add more RLC to your account'); + // Check balance and deposit more if needed + const balance = await iexec.account.show(); + console.log('Current balance:', balance); + } +} +``` + +### Voucher Authorization Issues + +If voucher payment fails: + +```typescript +try { + const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + maxPrice: 10, + useVoucher: true, + voucherOwner: '0x5714eB...', + }); +} catch (error) { + if (error.message.includes('voucher')) { + console.log('Voucher authorization failed. Check voucher permissions.'); + } +} +``` + +### Price Too High Errors + +If execution fails due to price constraints: + +```typescript +try { + const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + dataMaxPrice: 2, // Low price limit + appMaxPrice: 1, + workerpoolMaxPrice: 1, + }); +} catch (error) { + if (error.message.includes('price')) { + console.log('Increase price limits or wait for lower prices'); + // Retry with higher prices + const retryResult = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + dataMaxPrice: 8, // Higher price limit + appMaxPrice: 5, + workerpoolMaxPrice: 3, + }); + } +} +``` + +## Best Practices + +### 1. Always Set Price Limits +```typescript +// Never execute without price limits +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + dataMaxPrice: 5, // Always set price limits + appMaxPrice: 3, + workerpoolMaxPrice: 2, +}); +``` + +### 2. Use Vouchers for Production +```typescript +// Use vouchers for production applications +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + maxPrice: 10, + useVoucher: true, // More reliable for production +}); +``` + +### 3. Monitor Costs Regularly +```typescript +// Check costs before and after execution +const balanceBefore = await iexec.account.show(); +const result = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + dataMaxPrice: 5, + appMaxPrice: 3, + workerpoolMaxPrice: 2, +}); +const balanceAfter = await iexec.account.show(); +console.log('Cost:', balanceBefore - balanceAfter); +``` + +### 4. Handle Payment Errors Gracefully +```typescript +const executeWithPaymentRetry = async (params, maxRetries = 3) => { + for (let i = 0; i < maxRetries; i++) { + try { + return await dataProtectorCore.processProtectedData(params); + } catch (error) { + if (error.message.includes('insufficient balance')) { + console.log('Insufficient balance, please add more RLC'); + break; + } + if (i === maxRetries - 1) throw error; + console.log(`Payment retry ${i + 1}/${maxRetries}`); + await new Promise(resolve => setTimeout(resolve, 1000)); + } + } +}; +``` + +## Next Steps + +Now that you understand payment methods: + +- Learn about [Adding Inputs to Execution](./add-inputs-to-execution.md) +- Explore [Using iApps with Protected Data](./use-iapp-with-protected-data.md) +- Check out our [Pricing Considerations](../how-to-pay/pricing-considerations.md) for detailed cost analysis diff --git a/src/use-iapp/guides/use-iapp-with-protected-data.md b/src/use-iapp/guides/use-iapp-with-protected-data.md index 74467330..7655032a 100644 --- a/src/use-iapp/guides/use-iapp-with-protected-data.md +++ b/src/use-iapp/guides/use-iapp-with-protected-data.md @@ -1,10 +1,465 @@ --- -title: Use iApp with Protected Data -description: Use iApp with Protected Data +title: Use iApps with Protected Data +description: Learn how to securely process protected data using iApps on the iExec network --- -# Use iApp with Protected Data +# 🔒 Use iApps with Protected Data -This page is under development. +Protected data is the cornerstone of privacy-preserving computation on iExec. This guide shows you how to use iApps with protected data, from granting access to processing and retrieving results. - +## Understanding Protected Data and iApps + +Protected data is encrypted information that can only be processed by authorized iApps 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 iApps 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 + +```typescript +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider(window.ethereum); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +// 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 + } + }, +}); +``` + +### Protecting Different Data Types + +```typescript +// 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 iApps + +iApps need explicit authorization to access your protected data. + +### Grant Access to a Specific iApp + +```typescript +// Grant access to an iApp +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: protectedDataAddress, + 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 + +```typescript +// Check what access you've granted +const grantedAccessList = await dataProtectorCore.getGrantedAccess({ + protectedData: protectedDataAddress, + authorizedApp: '0x456def...', + authorizedUser: '0x789abc...', +}); + +console.log('Granted access:', grantedAccessList); +``` + +## Step 3: Execute iApp with Protected Data + +Once access is granted, you can execute the iApp with your protected data. + + +### Using DataProtector + +```typescript +// Execute iApp with protected data +const result = await dataProtectorCore.processProtectedData({ + protectedData: protectedDataAddress, + app: '0x456def...', // The iApp address + maxPrice: 10, // Maximum price in nRLC +}); +``` + +### Using SDK Library + +```typescript +import { IExecConfig, IExecOrderModule, IExecOrderbookModule } from '@iexec/sdk'; + +// create the configuration +const config = new IExecConfig({ ethProvider: window.ethereum }); + +// instantiate modules sharing the same configuration +const orderModule = IExecOrderModule.fromConfig(config); +const orderbookModule = IExecOrderbookModule.fromConfig(config); + +// Create a request order with protected data +const requestOrder = await orderModule.createRequestOrder({ + app: '0x456def...', // The iApp address + appmaxprice: 10, // Maximum price in nRLC + dataset: protectedDataAddress, // Protected data address + datasetmaxprice: 5, // Maximum price for dataset access + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool + // Other parameters have default values +}); + +// Fetch matching orders from orderbook with filters +const appOrders = await orderbookModule.fetchAppOrderbook({ + app: '0x456def...', // Filter by specific app +}); +const datasetOrders = await orderbookModule.fetchDatasetOrderbook({ + dataset: protectedDataAddress, // Filter by specific dataset +}); +const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ + workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +}); + +// Execute the task +const taskId = await orderModule.matchOrders({ + requestorder: requestOrder, + apporder: appOrders[0], + datasetorder: datasetOrders[0], + workerpoolorder: workerpoolOrders[0], +}); +``` + +### Using CLI with Protected Data + +```bash +# Execute with protected data +iexec app run 0x456def... --dataset 0x123abc... --maxPrice 10 +``` + +## Step 4: Retrieve Results + +After execution completes, retrieve the results from the task. + + +### Using DataProtector + +```typescript +// Get the task ID from the execution result +const taskId = result.taskId; + +// Retrieve the result +const taskResult = await dataProtectorCore.getResultFromCompletedTask({ + taskId: taskId, +}); + +// Retrieve a specific file from the result +const taskResult = await dataProtectorCore.getResultFromCompletedTask({ + taskId: taskId, + path: 'computed.json', // Extract specific file +}); +``` + +### Using SDK Library + +```typescript +import { IExecConfig, IExecResultModule } from '@iexec/sdk'; + +// create the configuration +const config = new IExecConfig({ ethProvider: window.ethereum }); + +// instantiate result module +const resultModule = IExecResultModule.fromConfig(config); + +// Get the task ID from the execution result +const taskId = result.taskId; // or taskId from SDK library execution + +// Retrieve the result +const taskResult = await resultModule.getTaskResult({ + taskId: taskId, +}); + +// Retrieve a specific file from the result +const specificFile = await resultModule.getTaskResult({ + taskId: taskId, + path: 'computed.json', // Extract specific file +}); +``` + +### Using 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 + +```typescript +// 1. Protect sensitive dataset +const { address: datasetAddress } = await dataProtectorCore.protectData({ + name: 'Customer Analytics Data', + data: { + customers: [ + { id: 1, purchases: 1500, category: 'premium' }, + { id: 2, purchases: 800, category: 'standard' }, + { 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', + maxPrice: 10, +}); +``` + +### Example 2: Oracle Price Update + +```typescript +// 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', + maxPrice: 10, +}); +``` + +### Example 3: Automated Payment Processing + +```typescript +// 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', + }, + maxPrice: 8, +}); +``` + +## Advanced Patterns + +### Pattern 1: Batch Processing + +```typescript +// Process multiple protected datasets +const datasets = [ + { address: '0x123abc...', name: 'Dataset 1' }, + { address: '0x456def...', name: 'Dataset 2' }, + { address: '0x789ghi...', name: 'Dataset 3' }, +]; + +const batchResults = await Promise.all( + datasets.map(dataset => + dataProtectorCore.processProtectedData({ + protectedData: dataset.address, + app: '0x456def...', + args: `--dataset-name ${dataset.name}`, + maxPrice: 10, + }) + ) +); +``` + +### Pattern 2: Result Processing Pipeline + +```typescript +// Process results and use them for further computation +const initialResult = await dataProtectorCore.processProtectedData({ + protectedData: protectedDataAddress, + app: '0x456def...', + maxPrice: 10, +}); + +// Get the result +const taskResult = await dataProtectorCore.getResultFromCompletedTask({ + taskId: initialResult.taskId, +}); + +// Use the result for further processing +const processedData = await processResult(taskResult); + +// Protect the processed data +const { address: newProtectedDataAddress } = await dataProtectorCore.protectData({ + name: 'Processed Data', + data: processedData, +}); +``` + +## Best Practices + +### 1. Always Grant Access Before Execution + +```typescript +// ✅ Good: 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...', + maxPrice: 10, +}); +``` + +### 2. Monitor Access Usage + +```typescript +// Check access usage regularly +const grantedAccess = await dataProtectorCore.getGrantedAccess({ + protectedData: protectedDataAddress, + authorizedApp: '0x456def...', + authorizedUser: '0x789abc...', +}); + +console.log('Remaining access:', grantedAccess.remainingAccess); +console.log('Used access:', grantedAccess.usedAccess); +``` + +### 3. Use Appropriate Price Limits + +```typescript +// Set reasonable price limits +const result = await dataProtectorCore.processProtectedData({ + protectedData: protectedDataAddress, + app: '0x456def...', + maxPrice: 10, // Set appropriate limit +}); +``` + +### 4. Handle Results Properly + +```typescript +// Store task ID and retrieve results later +const result = await dataProtectorCore.processProtectedData({ + protectedData: protectedDataAddress, + app: '0x456def...', + maxPrice: 10, +}); + +// Store task ID for later retrieval +const taskId = result.taskId; +localStorage.setItem('lastTaskId', taskId); + +// Later, retrieve the result +const taskResult = await dataProtectorCore.getResultFromCompletedTask({ + taskId: taskId, +}); +``` + +## Next Steps + +Now that you understand how to use iApps with protected data: + +- Learn about [Different Ways to Execute](./different-ways-to-execute.md) iApps +- Explore [How to Pay for Executions](./how-to-pay-executions.md) +- Check out our [Add Inputs to Execution](./add-inputs-to-execution.md) guide diff --git a/src/use-iapp/introduction.md b/src/use-iapp/introduction.md index b464f422..96c7476c 100644 --- a/src/use-iapp/introduction.md +++ b/src/use-iapp/introduction.md @@ -1,10 +1,39 @@ --- title: Introduction to Using iApps -description: Introduction to using iApps +description: Learn how to use iExec Applications (iApps) to securely process protected data in a privacy-safe environment --- -# 📝 Introduction +# 📝 Introduction to Using iApps -This page is under development. +iExec Applications (iApps) are your gateway to secure, privacy-preserving computation on the iExec network. These applications run inside Trusted Execution Environments (TEEs) like Intel SGX or Intel TDX, ensuring your data remains confidential even during processing. - +## What are iApps? + +iApps are regular applications (Python scripts, AI models, data processors, etc.) that have been adapted to run securely on the iExec network. They can process protected data without ever seeing the raw information, making them perfect for scenarios where data privacy is crucial. + +## Key Benefits + +- **🔒 Privacy-First**: Your data never leaves the secure TEE environment +- **⚡ Trusted Execution**: Applications run in hardware-protected environments +- **🌐 Decentralized**: No single point of failure or control +- **💰 Cost-Effective**: Pay only for the computation you need +- **🔧 Developer-Friendly**: Use familiar programming languages and tools + +## How iApps Work + +1. **Data Protection**: Users protect their sensitive data using the [Data Protector](/manage-data/dataProtector/dataProtectorCore/protectData) +2. **Application Deployment**: Developers deploy their applications to the iExec network +3. **Secure Processing**: iApps process protected data inside TEEs without accessing raw data +4. **Result Delivery**: Only the computation results are returned, keeping original data private + +## Use Cases + +- **Email Notifications**: Send emails without seeing recipient addresses +- **Oracle Updates**: Update price feeds using private trading data +- **Automated Transactions**: Process payments with protected financial data +- **AI Model Training**: Train models on sensitive datasets +- **Data Analytics**: Analyze private data without exposing it + +## Getting Started + +Ready to start using iApps? Check out our [Getting Started Guide](./getting-started.md) to learn how to find, execute, and interact with iApps on the iExec network. From 0b75ae926257ef631807d952c4f142e1dc2f84e8 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Mon, 11 Aug 2025 15:11:32 +0200 Subject: [PATCH 2/8] fix: improve formatting and readability in documentation files --- src/use-iapp/getting-started.md | 44 ++++--- .../guides/add-inputs-to-execution.md | 112 +++++++++++------- .../guides/different-ways-to-execute.md | 30 +++-- src/use-iapp/guides/find-iapps.md | 30 ++++- src/use-iapp/guides/how-to-pay-executions.md | 54 +++++---- .../guides/use-iapp-with-protected-data.md | 48 ++++---- src/use-iapp/introduction.md | 30 +++-- 7 files changed, 230 insertions(+), 118 deletions(-) diff --git a/src/use-iapp/getting-started.md b/src/use-iapp/getting-started.md index b615cb91..2ed57d02 100644 --- a/src/use-iapp/getting-started.md +++ b/src/use-iapp/getting-started.md @@ -1,31 +1,39 @@ --- title: Getting Started with iApps -description: Learn the basics of finding and executing iApps on the iExec network +description: + Learn the basics of finding and executing iApps on the iExec network --- # 🚀 Getting Started with iApps -Welcome to the world of secure, privacy-preserving computation! This guide will walk you through the essential steps to start using iApps on the iExec network. +Welcome to the world of secure, privacy-preserving computation! This guide will +walk you through the essential steps to start using iApps on the iExec network. ## Prerequisites Before you begin, make sure you have: - A Web3 wallet (MetaMask, WalletConnect, etc.) -- Some RLC tokens for paying computation fees (or access to free vouchers through learning programs) +- Some RLC tokens for paying computation fees (or access to free vouchers + through learning programs) - Basic understanding of blockchain transactions ### 🆓 Use Our Stack for Free! -Good news! You can start using iApps **completely free** through our learning programs: +Good news! You can start using iApps **completely free** through our learning +programs: -- **Learn Web3 Program**: Get free access to our entire stack, including vouchers for iApp executions -- **Free Vouchers**: Pre-funded computation credits provided through learning initiatives -- **No RLC Required**: Start experimenting and building without any upfront costs +- **Learn Web3 Program**: Get free access to our entire stack, including + vouchers for iApp executions +- **Free Vouchers**: Pre-funded computation credits provided through learning + initiatives +- **No RLC Required**: Start experimenting and building without any upfront + costs ### 💰 Getting Started Without RLC -Don't have RLC tokens yet? No problem! Our learning programs provide everything you need: +Don't have RLC tokens yet? No problem! Our learning programs provide everything +you need: - **Free Vouchers**: Access to pre-funded computation credits - **Full Stack Access**: Use all iExec tools and infrastructure at no cost @@ -35,7 +43,8 @@ Ready to dive in? Let's get started with finding and executing your first iApp! ## Step 1: Find Available iApps -The first step is discovering what iApps are available for your use case. You can find iApps through several methods: +The first step is discovering what iApps are available for your use case. You +can find iApps through several methods: 1. Visit the [iExec Explorer](https://explorer.iex.ec) 2. Navigate to the "Apps" section @@ -55,8 +64,12 @@ Before executing an iApp, understand what it needs: If the iApp requires protected data: -1. **Protect Your Data**: Use the [Data Protector](/manage-data/dataProtector/dataProtectorCore/protectData) to encrypt your sensitive information -2. **Grant Access**: Ensure the iApp has permission to access your protected data using [grantAccess](/manage-data/dataProtector/dataProtectorCore/grantAccess) +1. **Protect Your Data**: Use the + [Data Protector](/manage-data/dataProtector/dataProtectorCore/protectData) to + encrypt your sensitive information +2. **Grant Access**: Ensure the iApp has permission to access your protected + data using + [grantAccess](/manage-data/dataProtector/dataProtectorCore/grantAccess) ## Step 4: Execute the iApp @@ -88,7 +101,8 @@ iexec app run 0x456def... --dataset 0x123abc... --args "your arguments" After submitting your task: -1. **Monitor Progress**: Track your task on the [iExec Explorer](https://explorer.iex.ec) +1. **Monitor Progress**: Track your task on the + [iExec Explorer](https://explorer.iex.ec) 2. **Retrieve Results**: Get your results once the task completes ### Using the DataProtector SDK @@ -124,9 +138,11 @@ iApp execution costs include: Now that you understand the basics: - Explore our [Guides](./guides/) for detailed tutorials -- Learn about [Different Ways to Execute](./guides/different-ways-to-execute.md) iApps +- Learn about [Different Ways to Execute](./guides/different-ways-to-execute.md) + iApps - Understand [How to Pay for Executions](./guides/how-to-pay-executions.md) -- Discover how to [Use iApps with Protected Data](./guides/use-iapp-with-protected-data.md) +- Discover how to + [Use iApps with Protected Data](./guides/use-iapp-with-protected-data.md) ## Need Help? diff --git a/src/use-iapp/guides/add-inputs-to-execution.md b/src/use-iapp/guides/add-inputs-to-execution.md index 5848e1fd..4de391cb 100644 --- a/src/use-iapp/guides/add-inputs-to-execution.md +++ b/src/use-iapp/guides/add-inputs-to-execution.md @@ -1,17 +1,24 @@ --- title: Add Inputs to iApp Execution -description: Learn how to provide arguments, files, secrets, and other inputs to iApp executions +description: + Learn how to provide arguments, files, secrets, and other inputs to iApp + executions --- # 📥 Add Inputs to iApp Execution -iApps 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 SDKs. +iApps 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 SDKs. -::: 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`. +::: 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. -::: +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. ::: ## Types of Inputs @@ -24,12 +31,17 @@ iExec supports several types of inputs for iApp executions: ## Method 1: Adding Command-Line Arguments -Command-line arguments are passed as a string to the iApp and are visible on the blockchain. +Command-line arguments are passed as a string to the iApp and are visible on the +blockchain. ### Using SDK Library ```typescript -import { IExecConfig, IExecOrderModule, IExecOrderbookModule } from '@iexec/sdk'; +import { + IExecConfig, + IExecOrderModule, + IExecOrderbookModule, +} from '@iexec/sdk'; // create the configuration const config = new IExecConfig({ ethProvider: window.ethereum }); @@ -133,18 +145,21 @@ const result = await dataProtector.processProtectedData({ args: '--input-path data/input.csv --output-format json --verbose', maxPrice: 10, }); - - ``` ## Method 2: Adding Input Files -Input files are URLs to public files that the iApp can download during execution. +Input files are URLs to public files that the iApp can download during +execution. ### Using SDK Library ```typescript -import { IExecConfig, IExecOrderModule, IExecOrderbookModule } from '@iexec/sdk'; +import { + IExecConfig, + IExecOrderModule, + IExecOrderbookModule, +} from '@iexec/sdk'; // create the configuration const config = new IExecConfig({ ethProvider: window.ethereum }); @@ -191,7 +206,7 @@ const taskId = await orderModule.matchOrders({ inputFiles: [ 'https://example.com/config.json', 'https://example.com/template.html', - 'https://example.com/data.csv' + 'https://example.com/data.csv', ], }); @@ -223,7 +238,7 @@ const taskId = await orderModule.matchOrders({ workerpoolorder: workerpoolOrders[0], inputFiles: [ 'https://raw.githubusercontent.com/user/repo/main/config.json', - 'https://example.com/public-data.csv' + 'https://example.com/public-data.csv', ], }); ``` @@ -254,22 +269,26 @@ const result = await dataProtector.processProtectedData({ app: '0x456def...', inputFiles: [ 'https://raw.githubusercontent.com/user/repo/main/config.json', - 'https://example.com/public-data.csv' + 'https://example.com/public-data.csv', ], maxPrice: 10, }); - - ``` ## Method 3: 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. +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 ```typescript -import { IExecConfig, IExecOrderModule, IExecOrderbookModule, IExecSecretsModule } from '@iexec/sdk'; +import { + IExecConfig, + IExecOrderModule, + IExecOrderbookModule, + IExecSecretsModule, +} from '@iexec/sdk'; // create the configuration const config = new IExecConfig({ ethProvider: window.ethereum }); @@ -387,17 +406,22 @@ const result = await dataProtector.processProtectedData({ }, maxPrice: 10, }); - ``` ## Method 4: Specifying File Paths in Protected Data -When working with protected data that contains multiple files, you can specify which file to process. +When working with protected data that contains multiple files, you can specify +which file to process. ### Using SDK Library ```typescript -import { IExecConfig, IExecOrderModule, IExecOrderbookModule, IExecResultModule } from '@iexec/sdk'; +import { + IExecConfig, + IExecOrderModule, + IExecOrderbookModule, + IExecResultModule, +} from '@iexec/sdk'; // create the configuration const config = new IExecConfig({ ethProvider: window.ethereum }); @@ -503,7 +527,12 @@ You can combine different types of inputs for complex executions. ### Using SDK Library ```typescript -import { IExecConfig, IExecOrderModule, IExecOrderbookModule, IExecSecretsModule } from '@iexec/sdk'; +import { + IExecConfig, + IExecOrderModule, + IExecOrderbookModule, + IExecSecretsModule, +} from '@iexec/sdk'; // create the configuration const config = new IExecConfig({ ethProvider: window.ethereum }); @@ -542,7 +571,7 @@ const taskId = await orderModule.matchOrders({ workerpoolorder: workerpoolOrders[0], inputFiles: [ 'https://example.com/config.json', - 'https://example.com/template.html' + 'https://example.com/template.html', ], secrets: { 1: 'api-key-12345', @@ -580,7 +609,7 @@ const result = await dataProtector.processProtectedData({ args: '--mode production --output-format json', inputFiles: [ 'https://example.com/config.json', - 'https://example.com/template.html' + 'https://example.com/template.html', ], secrets: { 1: 'api-key-12345', @@ -605,8 +634,8 @@ 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' +const apiKey = process.env.IEXEC_SECRET_1; // 'api-key-12345' +const dbPassword = process.env.IEXEC_SECRET_2; // 'database-password' ``` ## Input Validation and Error Handling @@ -616,12 +645,12 @@ const dbPassword = process.env.IEXEC_SECRET_2; // 'database-password' ```typescript const validateInputs = (params) => { const errors = []; - + // Validate arguments if (params.args && params.args.length > 1000) { errors.push('Arguments too long (max 1000 characters)'); } - + // Validate input files if (params.inputFiles) { params.inputFiles.forEach((url, index) => { @@ -630,16 +659,16 @@ const validateInputs = (params) => { } }); } - + // Validate secrets if (params.secrets) { - Object.keys(params.secrets).forEach(key => { + Object.keys(params.secrets).forEach((key) => { if (!/^\d+$/.test(key)) { errors.push('Secret keys must be numeric'); } }); } - + return errors; }; @@ -706,7 +735,7 @@ const result = await dataProtectorCore.processProtectedData({ // ✅ Ensure input files are accessible const inputFiles = [ 'https://raw.githubusercontent.com/user/repo/main/config.json', - 'https://example.com/public-data.csv' + 'https://example.com/public-data.csv', ]; // Test file accessibility before execution @@ -722,13 +751,13 @@ const testFileAccess = async (url) => { const accessibleFiles = await Promise.all( inputFiles.map(async (url) => ({ url, - accessible: await testFileAccess(url) + accessible: await testFileAccess(url), })) ); const validFiles = accessibleFiles - .filter(file => file.accessible) - .map(file => file.url); + .filter((file) => file.accessible) + .map((file) => file.url); ``` ### 3. Use Descriptive Arguments @@ -751,10 +780,10 @@ const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', app: '0x456def...', secrets: { - 1: 'primary-api-key', // Main API key - 2: 'backup-api-key', // Backup API key - 3: 'database-password', // Database credentials - 4: 'encryption-key', // Encryption key + 1: 'primary-api-key', // Main API key + 2: 'backup-api-key', // Backup API key + 3: 'database-password', // Database credentials + 4: 'encryption-key', // Encryption key }, maxPrice: 10, }); @@ -764,6 +793,7 @@ const result = await dataProtectorCore.processProtectedData({ Now that you understand how to add inputs to iApp executions: -- Learn about [Using iApps with Protected Data](./use-iapp-with-protected-data.md) +- Learn about + [Using iApps with Protected Data](./use-iapp-with-protected-data.md) - Explore [Different Ways to Execute](./different-ways-to-execute.md) iApps - Check out our [How to Pay for Executions](./how-to-pay-executions.md) guide diff --git a/src/use-iapp/guides/different-ways-to-execute.md b/src/use-iapp/guides/different-ways-to-execute.md index 5dc21a8c..c705b1c4 100644 --- a/src/use-iapp/guides/different-ways-to-execute.md +++ b/src/use-iapp/guides/different-ways-to-execute.md @@ -1,24 +1,34 @@ --- title: Different Ways to Execute iApps -description: Learn about various methods for executing iApps on the iExec network +description: + Learn about various methods for executing iApps on the iExec network --- # ⚡ Different Ways to Execute iApps -There are multiple ways to execute iApps 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. +There are multiple ways to execute iApps 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`. +::: 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. -::: +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 iApps. ```typescript -import { IExecConfig, IExecOrderModule, IExecOrderbookModule } from '@iexec/sdk'; +import { + IExecConfig, + IExecOrderModule, + IExecOrderbookModule, +} from '@iexec/sdk'; // create the configuration const config = new IExecConfig({ ethProvider: window.ethereum }); @@ -73,7 +83,8 @@ iexec app run 0x456def... --maxPrice 10 ## Method 3: Using the iApp Generator CLI -The iApp Generator CLI provides a streamlined way to execute iApps, especially for developers who have built their own iApps. +The iApp Generator CLI provides a streamlined way to execute iApps, especially +for developers who have built their own iApps. ### Installation @@ -103,6 +114,7 @@ iapp test ## Next Steps -- Learn how to [use iApps with protected data](./use-iapp-with-protected-data.md) +- Learn how to + [use iApps with protected data](./use-iapp-with-protected-data.md) - Discover how to [add inputs to execution](./add-inputs-to-execution.md) - Understand [how to pay for executions](./how-to-pay-executions.md) diff --git a/src/use-iapp/guides/find-iapps.md b/src/use-iapp/guides/find-iapps.md index 0e2eeb98..3b1d9f37 100644 --- a/src/use-iapp/guides/find-iapps.md +++ b/src/use-iapp/guides/find-iapps.md @@ -5,11 +5,14 @@ description: Discover and explore available iApps on the iExec network # 🔍 Find iApps to Use -Discovering the right iApp for your needs is the first step toward secure, privacy-preserving computation. Here are several ways to find and explore available iApps on the iExec network. +Discovering the right iApp for your needs is the first step toward secure, +privacy-preserving computation. Here are several ways to find and explore +available iApps on the iExec network. ## Using the iExec Explorer -The [iExec Explorer](https://explorer.iex.ec) is the primary tool for discovering iApps. +The [iExec Explorer](https://explorer.iex.ec) is the primary tool for +discovering iApps. ### Step-by-Step Discovery @@ -31,7 +34,8 @@ When evaluating an iApp, check these key details: ## Using the iExec CLI -For developers who prefer command-line tools, the iExec CLI provides programmatic access to app discovery. +For developers who prefer command-line tools, the iExec CLI provides +programmatic access to app discovery. ### Installation @@ -52,18 +56,22 @@ iexec app show ## Popular iApp Categories ### Communication Apps + - **Web3Mail**: Send encrypted emails without seeing recipient addresses - **Web3Telegram**: Send Telegram messages with protected contact lists ### Data Processing + - **Content Creator**: Process and deliver content using protected data - **Data Analytics**: Analyze sensitive datasets without exposing raw data ### Oracle Services + - **Oracle Factory**: Create and manage price oracles - **Data Feeds**: Update external systems with private data ### AI and Machine Learning + - **Model Training**: Train AI models on protected datasets - **Inference Services**: Run AI inference on sensitive data @@ -72,29 +80,36 @@ iexec app show Before using an iApp, consider these factors: ### Reliability + - **Usage History**: How many times has the app been executed? - **Success Rate**: What percentage of executions succeed? - **Developer Reputation**: Is the developer known and trusted? ### Cost Efficiency + - **Execution Cost**: Is the price reasonable for the computation? - **Competitive Pricing**: How does it compare to similar apps? ## Community Resources ### Discord Community + Join the [iExec Discord](https://discord.gg/iexec) to: + - Ask questions about specific apps - Get recommendations from other users - Learn about new apps and updates ### GitHub Repositories + Many iApp developers share their code on GitHub: + - Review the source code - Check for recent updates - Report issues or suggest improvements ### Documentation + - **App-Specific Docs**: Check if the developer provides detailed documentation - **Community Guides**: Look for tutorials and guides from the community @@ -104,7 +119,10 @@ Once you've found an iApp that meets your needs: 1. **Read the Documentation**: Understand how to use the app properly 2. **Check Requirements**: Ensure you have the necessary data and permissions -3. **Test with Small Data**: Start with a small test before processing large datasets -4. **Monitor Execution**: Track your first few executions to ensure everything works as expected +3. **Test with Small Data**: Start with a small test before processing large + datasets +4. **Monitor Execution**: Track your first few executions to ensure everything + works as expected -Ready to execute your first iApp? Check out our [Getting Started Guide](../getting-started.md) for the next steps! +Ready to execute your first iApp? Check out our +[Getting Started Guide](../getting-started.md) for the next steps! diff --git a/src/use-iapp/guides/how-to-pay-executions.md b/src/use-iapp/guides/how-to-pay-executions.md index 04f393f1..8d1b75ca 100644 --- a/src/use-iapp/guides/how-to-pay-executions.md +++ b/src/use-iapp/guides/how-to-pay-executions.md @@ -1,11 +1,14 @@ --- title: How to Pay for iApp Executions -description: Learn about payment methods, pricing, and cost management for iApp executions +description: + Learn about payment methods, pricing, and cost management for iApp executions --- # 💰 How to Pay for iApp Executions -Understanding how to pay for iApp executions is crucial for using the iExec network effectively. This guide covers all payment methods, pricing structures, and cost management strategies. +Understanding how to pay for iApp executions is crucial for using the iExec +network effectively. This guide covers all payment methods, pricing structures, +and cost management strategies. ## Payment Methods Overview @@ -17,13 +20,15 @@ iExec supports multiple payment methods for executing iApps: ## Method 1: Paying with RLC Tokens -RLC tokens are the native currency of the iExec network. You need to have RLC in your wallet to pay for executions. +RLC tokens are the native currency of the iExec network. You need to have RLC in +your wallet to pay for executions. ### Setting Up RLC Payment #### Step 1: Get RLC Tokens You can obtain RLC tokens from various exchanges: + - **Centralized Exchanges**: Binance, Coinbase, Kraken - **Decentralized Exchanges**: Uniswap, SushiSwap - **Direct Purchase**: Through iExec's official channels @@ -81,11 +86,13 @@ iexec account deposit 100 ## Method 2: Paying with Vouchers -Vouchers are pre-funded payment instruments that simplify the payment process and can be shared with others. +Vouchers are pre-funded payment instruments that simplify the payment process +and can be shared with others. ### Understanding Vouchers -Vouchers are ERC-20 tokens that represent pre-funded computation credits on the iExec network. They offer several advantages: +Vouchers are ERC-20 tokens that represent pre-funded computation credits on the +iExec network. They offer several advantages: - **Simplified Payment**: No need to manage RLC transfers - **Sharing**: Can be shared with team members or users @@ -107,7 +114,10 @@ const result = await dataProtectorCore.processProtectedData({ ::: tip -If your voucher doesn't have enough xRLC to cover the deal, the SDK will automatically get the required amount to your iExec account. Ensure that your voucher is authorized to access your iExec account and that your account has sufficient funds for this transfer to proceed. +If your voucher doesn't have enough xRLC to cover the deal, the SDK will +automatically get the required amount to your iExec account. Ensure that your +voucher is authorized to access your iExec account and that your account has +sufficient funds for this transfer to proceed. ::: @@ -125,7 +135,8 @@ const result = await dataProtectorCore.processProtectedData({ ::: warning -Make sure the voucher's owner has authorized you to use it. This parameter must be used in combination with `useVoucher: true`. +Make sure the voucher's owner has authorized you to use it. This parameter must +be used in combination with `useVoucher: true`. ::: @@ -139,8 +150,6 @@ iexec app run 0x456def... --protectedData 0x123abc... --useVoucher iexec app run 0x456def... --protectedData 0x123abc... --useVoucher --voucherOwner 0x5714eB... ``` - - ## Understanding Pricing ### Cost Components @@ -160,20 +169,19 @@ You can control costs by setting maximum prices for each component: const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', app: '0x456def...', - dataMaxPrice: 5, // Maximum amount (in nRLC) to pay the protected data owner - appMaxPrice: 3, // Maximum amount (in nRLC) to pay the iApp provider + dataMaxPrice: 5, // Maximum amount (in nRLC) to pay the protected data owner + appMaxPrice: 3, // Maximum amount (in nRLC) to pay the iApp provider workerpoolMaxPrice: 2, // Maximum amount (in nRLC) to pay the workerpool provider }); ``` ::: 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 no maximum price limit is set. ::: - - ## Cost Management Strategies ### 1. Monitor Your Balance @@ -199,8 +207,8 @@ Always set maximum prices to avoid unexpected costs: const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', app: '0x456def...', - dataMaxPrice: 5, // Maximum for data access - appMaxPrice: 3, // Maximum for app usage + dataMaxPrice: 5, // Maximum for data access + appMaxPrice: 3, // Maximum for app usage workerpoolMaxPrice: 2, // Maximum for computation }); ``` @@ -231,7 +239,7 @@ const tasks = [ ]; const results = await Promise.all( - tasks.map(task => + tasks.map((task) => dataProtectorCore.processProtectedData({ ...task, dataMaxPrice: 5, @@ -317,18 +325,20 @@ try { ## Best Practices ### 1. Always Set Price Limits + ```typescript // Never execute without price limits const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', app: '0x456def...', - dataMaxPrice: 5, // Always set price limits + dataMaxPrice: 5, // Always set price limits appMaxPrice: 3, workerpoolMaxPrice: 2, }); ``` ### 2. Use Vouchers for Production + ```typescript // Use vouchers for production applications const result = await dataProtectorCore.processProtectedData({ @@ -340,6 +350,7 @@ const result = await dataProtectorCore.processProtectedData({ ``` ### 3. Monitor Costs Regularly + ```typescript // Check costs before and after execution const balanceBefore = await iexec.account.show(); @@ -355,6 +366,7 @@ console.log('Cost:', balanceBefore - balanceAfter); ``` ### 4. Handle Payment Errors Gracefully + ```typescript const executeWithPaymentRetry = async (params, maxRetries = 3) => { for (let i = 0; i < maxRetries; i++) { @@ -367,7 +379,7 @@ const executeWithPaymentRetry = async (params, maxRetries = 3) => { } if (i === maxRetries - 1) throw error; console.log(`Payment retry ${i + 1}/${maxRetries}`); - await new Promise(resolve => setTimeout(resolve, 1000)); + await new Promise((resolve) => setTimeout(resolve, 1000)); } } }; @@ -379,4 +391,6 @@ Now that you understand payment methods: - Learn about [Adding Inputs to Execution](./add-inputs-to-execution.md) - Explore [Using iApps with Protected Data](./use-iapp-with-protected-data.md) -- Check out our [Pricing Considerations](../how-to-pay/pricing-considerations.md) for detailed cost analysis +- Check out our + [Pricing Considerations](../how-to-pay/pricing-considerations.md) for detailed + cost analysis diff --git a/src/use-iapp/guides/use-iapp-with-protected-data.md b/src/use-iapp/guides/use-iapp-with-protected-data.md index 7655032a..7351d9a0 100644 --- a/src/use-iapp/guides/use-iapp-with-protected-data.md +++ b/src/use-iapp/guides/use-iapp-with-protected-data.md @@ -1,15 +1,20 @@ --- title: Use iApps with Protected Data -description: Learn how to securely process protected data using iApps on the iExec network +description: + Learn how to securely process protected data using iApps on the iExec network --- # 🔒 Use iApps with Protected Data -Protected data is the cornerstone of privacy-preserving computation on iExec. This guide shows you how to use iApps with protected data, from granting access to processing and retrieving results. +Protected data is the cornerstone of privacy-preserving computation on iExec. +This guide shows you how to use iApps with protected data, from granting access +to processing and retrieving results. ## Understanding Protected Data and iApps -Protected data is encrypted information that can only be processed by authorized iApps within Trusted Execution Environments (TEEs). The data remains confidential throughout the entire computation process. +Protected data is encrypted information that can only be processed by authorized +iApps within Trusted Execution Environments (TEEs). The data remains +confidential throughout the entire computation process. ### The Workflow @@ -38,8 +43,8 @@ const { address: protectedDataAddress } = await dataProtectorCore.protectData({ apiKey: 'secret-api-key-12345', preferences: { theme: 'dark', - notifications: true - } + notifications: true, + }, }, }); ``` @@ -54,8 +59,8 @@ const { address: contactListAddress } = await dataProtectorCore.protectData({ contacts: { '0x123abc...': 'john@example.com', '0x456def...': 'jane@example.com', - '0x789ghi...': 'bob@example.com' - } + '0x789ghi...': 'bob@example.com', + }, }, }); @@ -66,8 +71,8 @@ const { address: tradingDataAddress } = await dataProtectorCore.protectData({ trades: { '2024-01-01': { price: 50000, volume: 100 }, '2024-01-02': { price: 51000, volume: 150 }, - '2024-01-03': { price: 49000, volume: 200 } - } + '2024-01-03': { price: 49000, volume: 200 }, + }, }, }); @@ -77,7 +82,7 @@ const { address: paymentDataAddress } = await dataProtectorCore.protectData({ data: { bankAccount: '1234567890', routingNumber: '987654321', - accountHolder: 'John Doe' + accountHolder: 'John Doe', }, }); ``` @@ -116,7 +121,6 @@ console.log('Granted access:', grantedAccessList); Once access is granted, you can execute the iApp with your protected data. - ### Using DataProtector ```typescript @@ -131,7 +135,11 @@ const result = await dataProtectorCore.processProtectedData({ ### Using SDK Library ```typescript -import { IExecConfig, IExecOrderModule, IExecOrderbookModule } from '@iexec/sdk'; +import { + IExecConfig, + IExecOrderModule, + IExecOrderbookModule, +} from '@iexec/sdk'; // create the configuration const config = new IExecConfig({ ethProvider: window.ethereum }); @@ -181,7 +189,6 @@ iexec app run 0x456def... --dataset 0x123abc... --maxPrice 10 After execution completes, retrieve the results from the task. - ### Using DataProtector ```typescript @@ -252,7 +259,7 @@ const { address: datasetAddress } = await dataProtectorCore.protectData({ { id: 1, purchases: 1500, category: 'premium' }, { id: 2, purchases: 800, category: 'standard' }, { id: 3, purchases: 2200, category: 'premium' }, - ] + ], }, }); @@ -284,7 +291,7 @@ const { address: tradingDataAddress } = await dataProtectorCore.protectData({ trades: { '2024-01-01': { price: 50000, volume: 100 }, '2024-01-02': { price: 51000, volume: 150 }, - } + }, }, }); @@ -354,7 +361,7 @@ const datasets = [ ]; const batchResults = await Promise.all( - datasets.map(dataset => + datasets.map((dataset) => dataProtectorCore.processProtectedData({ protectedData: dataset.address, app: '0x456def...', @@ -384,10 +391,11 @@ const taskResult = await dataProtectorCore.getResultFromCompletedTask({ const processedData = await processResult(taskResult); // Protect the processed data -const { address: newProtectedDataAddress } = await dataProtectorCore.protectData({ - name: 'Processed Data', - data: processedData, -}); +const { address: newProtectedDataAddress } = + await dataProtectorCore.protectData({ + name: 'Processed Data', + data: processedData, + }); ``` ## Best Practices diff --git a/src/use-iapp/introduction.md b/src/use-iapp/introduction.md index 96c7476c..a683fa30 100644 --- a/src/use-iapp/introduction.md +++ b/src/use-iapp/introduction.md @@ -1,15 +1,23 @@ --- title: Introduction to Using iApps -description: Learn how to use iExec Applications (iApps) to securely process protected data in a privacy-safe environment +description: + Learn how to use iExec Applications (iApps) to securely process protected data + in a privacy-safe environment --- # 📝 Introduction to Using iApps -iExec Applications (iApps) are your gateway to secure, privacy-preserving computation on the iExec network. These applications run inside Trusted Execution Environments (TEEs) like Intel SGX or Intel TDX, ensuring your data remains confidential even during processing. +iExec Applications (iApps) are your gateway to secure, privacy-preserving +computation on the iExec network. These applications run inside Trusted +Execution Environments (TEEs) like Intel SGX or Intel TDX, ensuring your data +remains confidential even during processing. ## What are iApps? -iApps are regular applications (Python scripts, AI models, data processors, etc.) that have been adapted to run securely on the iExec network. They can process protected data without ever seeing the raw information, making them perfect for scenarios where data privacy is crucial. +iApps are regular applications (Python scripts, AI models, data processors, +etc.) that have been adapted to run securely on the iExec network. They can +process protected data without ever seeing the raw information, making them +perfect for scenarios where data privacy is crucial. ## Key Benefits @@ -21,10 +29,14 @@ iApps are regular applications (Python scripts, AI models, data processors, etc. ## How iApps Work -1. **Data Protection**: Users protect their sensitive data using the [Data Protector](/manage-data/dataProtector/dataProtectorCore/protectData) -2. **Application Deployment**: Developers deploy their applications to the iExec network -3. **Secure Processing**: iApps process protected data inside TEEs without accessing raw data -4. **Result Delivery**: Only the computation results are returned, keeping original data private +1. **Data Protection**: Users protect their sensitive data using the + [Data Protector](/manage-data/dataProtector/dataProtectorCore/protectData) +2. **Application Deployment**: Developers deploy their applications to the iExec + network +3. **Secure Processing**: iApps process protected data inside TEEs without + accessing raw data +4. **Result Delivery**: Only the computation results are returned, keeping + original data private ## Use Cases @@ -36,4 +48,6 @@ iApps are regular applications (Python scripts, AI models, data processors, etc. ## Getting Started -Ready to start using iApps? Check out our [Getting Started Guide](./getting-started.md) to learn how to find, execute, and interact with iApps on the iExec network. +Ready to start using iApps? Check out our +[Getting Started Guide](./getting-started.md) to learn how to find, execute, and +interact with iApps on the iExec network. From 4951a3acc02002fc379f25c100e8c61ec5b19035 Mon Sep 17 00:00:00 2001 From: aimen-djari Date: Tue, 12 Aug 2025 23:49:51 +0100 Subject: [PATCH 3/8] make documentation rely more on guides --- src/assets/use-iapp/iexec-actors-diagram.svg | 103 ++++++++++++ src/use-iapp/getting-started.md | 156 +++++------------- .../guides/add-inputs-to-execution.md | 62 +++---- .../guides/different-ways-to-execute.md | 27 +-- src/use-iapp/guides/find-iapps.md | 21 +-- src/use-iapp/guides/how-to-pay-executions.md | 38 ++--- .../guides/use-iapp-with-protected-data.md | 46 +++--- src/use-iapp/introduction.md | 88 +++++----- 8 files changed, 281 insertions(+), 260 deletions(-) create mode 100644 src/assets/use-iapp/iexec-actors-diagram.svg diff --git a/src/assets/use-iapp/iexec-actors-diagram.svg b/src/assets/use-iapp/iexec-actors-diagram.svg new file mode 100644 index 00000000..31fc8b1e --- /dev/null +++ b/src/assets/use-iapp/iexec-actors-diagram.svg @@ -0,0 +1,103 @@ + +

Results

iExec Network

Workerpool

Application & Data

Requester

👤 Requester

📱 iApp

🔐 Protected Data

👨‍💻 iApp Developer

👤 Data Provider

🏭 Workerpool Manager

⚙️ Worker

💰 PoCo

📋 Deal

📤 Results

 \ No newline at end of file diff --git a/src/use-iapp/getting-started.md b/src/use-iapp/getting-started.md index 2ed57d02..3440fdfb 100644 --- a/src/use-iapp/getting-started.md +++ b/src/use-iapp/getting-started.md @@ -6,145 +6,75 @@ description: # 🚀 Getting Started with iApps -Welcome to the world of secure, privacy-preserving computation! This guide will -walk you through the essential steps to start using iApps on the iExec network. +Welcome to the world of secure, privacy-preserving computation! This guide gives you a high-level overview of how to use iApps on the iExec network. ## Prerequisites Before you begin, make sure you have: - A Web3 wallet (MetaMask, WalletConnect, etc.) -- Some RLC tokens for paying computation fees (or access to free vouchers - through learning programs) +- Some RLC tokens for paying computation fees (or access to free vouchers through learning programs) - [Learn about RLC tokens](/overview/rlc) and [how to bridge them](/overview/tooling-and-explorers/bridge) + - **Note**: On Arbitrum, you'll need AETH (Arbitrum ETH) instead of RLC - Basic understanding of blockchain transactions +- iExec SDK installed -### 🆓 Use Our Stack for Free! +::: code-group -Good news! You can start using iApps **completely free** through our learning -programs: - -- **Learn Web3 Program**: Get free access to our entire stack, including - vouchers for iApp executions -- **Free Vouchers**: Pre-funded computation credits provided through learning - initiatives -- **No RLC Required**: Start experimenting and building without any upfront - costs - -### 💰 Getting Started Without RLC - -Don't have RLC tokens yet? No problem! Our learning programs provide everything -you need: - -- **Free Vouchers**: Access to pre-funded computation credits -- **Full Stack Access**: Use all iExec tools and infrastructure at no cost -- **Educational Support**: Learn while you build with our community - -Ready to dive in? Let's get started with finding and executing your first iApp! - -## Step 1: Find Available iApps - -The first step is discovering what iApps are available for your use case. You -can find iApps through several methods: - -1. Visit the [iExec Explorer](https://explorer.iex.ec) -2. Navigate to the "Apps" section -3. Browse available applications by category or search by name -4. Check the app's description, requirements, and pricing - -## Step 2: Understand App Requirements - -Before executing an iApp, understand what it needs: - -- **Protected Data**: Some apps require specific types of protected data -- **Input Parameters**: Check if the app needs command-line arguments -- **Input Files**: Some apps require additional files (URLs to public files) -- **Secrets**: Certain apps need requester secrets for API keys, etc. - -## Step 3: Prepare Your Data - -If the iApp requires protected data: - -1. **Protect Your Data**: Use the - [Data Protector](/manage-data/dataProtector/dataProtectorCore/protectData) to - encrypt your sensitive information -2. **Grant Access**: Ensure the iApp has permission to access your protected - data using - [grantAccess](/manage-data/dataProtector/dataProtectorCore/grantAccess) - -## Step 4: Execute the iApp - -### Using the DataProtector SDK - -```typescript -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider(window.ethereum); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); - -// Execute the iApp with protected data -const result = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', // Your protected data address - app: '0x456def...', // The iApp address - args: 'optional arguments', - maxPrice: 10, // Maximum price in nRLC -}); +```sh [npm] +npm install -g iexec ``` -### Using the CLI +```sh [yarn] +yarn global add iexec +``` -```bash -# Execute an iApp with protected data -iexec app run 0x456def... --dataset 0x123abc... --args "your arguments" +```sh [pnpm] +pnpm add -g iexec ``` -## Step 5: Monitor and Retrieve Results +```sh [bun] +bun add -g iexec +``` -After submitting your task: +::: -1. **Monitor Progress**: Track your task on the - [iExec Explorer](https://explorer.iex.ec) -2. **Retrieve Results**: Get your results once the task completes +Ready to dive in? Let's get started with finding and executing your first iApp! -### Using the DataProtector SDK +## Overview: How to Use iApps -```typescript -// Retrieve results from a completed task -const taskResult = await dataProtectorCore.getResultFromCompletedTask({ - taskId: '0x7ac398...', // Your task ID -}); -``` +Using iApps involves these main steps: -### Using the CLI +1. **Find iApps** - Browse available applications in the [iExec Explorer](/overview/tooling-and-explorers/iexec-explorer) +2. **Prepare Data** - Set up any required protected data or inputs +3. **Execute** - Run the iApp +4. **Get Results** - Retrieve your computation results -```bash -# Get task result -iexec task show 0x7ac398... +### Understanding Orders -# Download task result -iexec task show 0x7ac398... --download -``` +iApps are executed through a marketplace system where different actors publish orders: +- **App orders** - Published by developers with pricing and availability +- **Workerpool orders** - Published by computation providers with capacity and pricing +- **Dataset orders** - Published by data owners with access conditions and pricing -## Step 6: Understand Costs +When you execute an iApp, the system matches your request with available orders from all three categories. For a deeper understanding of how orders work and how to manage them, see the [Manage Orders guide](/build-iapp/guides/manage-access#manage-orders) in the Build iApp section. -iApp execution costs include: +## Detailed Guides -- **Application Fee**: Paid to the app developer -- **Data Fee**: Paid to the data owner (if using protected data) -- **Workerpool Fee**: Paid to the computation provider -- **Gas Fees**: Blockchain transaction costs (free on Bellecour sidechain) +For step-by-step instructions, check out these guides: -## Next Steps +- **[Find iApps](./guides/find-iapps.md)** - How to discover and evaluate available applications +- **[Different Ways to Execute](./guides/different-ways-to-execute.md)** - iExec cli, lib, and other execution methods +- **[Use iApps with Protected Data](./guides/use-iapp-with-protected-data.md)** - Working with sensitive data securely +- **[Add Inputs to Execution](./guides/add-inputs-to-execution.md)** - How to provide data and parameters to iApps +- **[How to Pay for Executions](./guides/how-to-pay-executions.md)** - Understanding costs and payment options -Now that you understand the basics: +## Quick Start -- Explore our [Guides](./guides/) for detailed tutorials -- Learn about [Different Ways to Execute](./guides/different-ways-to-execute.md) - iApps -- Understand [How to Pay for Executions](./guides/how-to-pay-executions.md) -- Discover how to - [Use iApps with Protected Data](./guides/use-iapp-with-protected-data.md) +Ready to jump in? Start with our [Find iApps guide](./guides/find-iapps.md) to discover what's available, then follow the execution guides for detailed instructions. -## Need Help? + diff --git a/src/use-iapp/guides/add-inputs-to-execution.md b/src/use-iapp/guides/add-inputs-to-execution.md index 4de391cb..0f7f14ef 100644 --- a/src/use-iapp/guides/add-inputs-to-execution.md +++ b/src/use-iapp/guides/add-inputs-to-execution.md @@ -11,14 +11,16 @@ iApps 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 SDKs. -::: tip ENS Addresses **ENS (Ethereum Name Service)** is a naming system for +::: 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. ::: +designed for testing and development purposes on the Bellecour testnet. +::: ## Types of Inputs @@ -36,7 +38,7 @@ blockchain. ### Using SDK Library -```typescript +```ts twoslash import { IExecConfig, IExecOrderModule, @@ -49,7 +51,7 @@ const config = new IExecConfig({ ethProvider: window.ethereum }); // instantiate modules sharing the same configuration const orderModule = IExecOrderModule.fromConfig(config); const orderbookModule = IExecOrderbookModule.fromConfig(config); - +// ---cut--- // Basic arguments const requestOrder = await orderModule.createRequestOrder({ app: '0x456def...', @@ -133,11 +135,11 @@ iexec app run 0x456def... --protectedData 0x123abc... --args "--message \"Hello ### Using DataProtector -```typescript +```ts twoslash import { IExecDataProtectorCore } from '@iexec/dataprotector'; const dataProtector = new IExecDataProtectorCore(web3Provider); - +// ---cut--- // Process protected data with arguments const result = await dataProtector.processProtectedData({ protectedData: '0x123abc...', @@ -154,7 +156,7 @@ execution. ### Using SDK Library -```typescript +```ts twoslash import { IExecConfig, IExecOrderModule, @@ -167,7 +169,7 @@ const config = new IExecConfig({ ethProvider: window.ethereum }); // instantiate modules sharing the same configuration const orderModule = IExecOrderModule.fromConfig(config); const orderbookModule = IExecOrderbookModule.fromConfig(config); - +// ---cut--- // Single input file const requestOrder = await orderModule.createRequestOrder({ app: '0x456def...', @@ -227,6 +229,7 @@ const appOrders = await orderbookModule.fetchAppOrderbook({ const datasetOrders = await orderbookModule.fetchDatasetOrderbook({ dataset: '0x123abc...', // Filter by specific dataset }); +``` const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS }); @@ -258,11 +261,11 @@ iexec app run 0x456def... --protectedData 0x123abc... --inputFiles "https://exam ### Using DataProtector -```typescript +```ts twoslash import { IExecDataProtectorCore } from '@iexec/dataprotector'; const dataProtector = new IExecDataProtectorCore(web3Provider); - +// ---cut--- // Process protected data with input files const result = await dataProtector.processProtectedData({ protectedData: '0x123abc...', @@ -282,7 +285,7 @@ securely and made available to the iApp as environment variables. ### Using SDK Library -```typescript +```ts twoslash import { IExecConfig, IExecOrderModule, @@ -297,7 +300,7 @@ const config = new IExecConfig({ ethProvider: window.ethereum }); const orderModule = IExecOrderModule.fromConfig(config); const orderbookModule = IExecOrderbookModule.fromConfig(config); const secretsModule = IExecSecretsModule.fromConfig(config); - +// ---cut--- // Basic secrets const requestOrder = await orderModule.createRequestOrder({ app: '0x456def...', @@ -391,11 +394,11 @@ iexec app run 0x456def... --protectedData 0x123abc... ### Using DataProtector -```typescript +```ts twoslash import { IExecDataProtectorCore } from '@iexec/dataprotector'; const dataProtector = new IExecDataProtectorCore(web3Provider); - +// ---cut--- // Process protected data with secrets const result = await dataProtector.processProtectedData({ protectedData: '0x123abc...', @@ -415,7 +418,7 @@ which file to process. ### Using SDK Library -```typescript +```ts twoslash import { IExecConfig, IExecOrderModule, @@ -430,7 +433,7 @@ const config = new IExecConfig({ ethProvider: window.ethereum }); const orderModule = IExecOrderModule.fromConfig(config); const orderbookModule = IExecOrderbookModule.fromConfig(config); const resultModule = IExecResultModule.fromConfig(config); - +// ---cut--- // Basic path specification (with protected data) const requestOrder = await orderModule.createRequestOrder({ app: '0x456def...', @@ -500,11 +503,11 @@ iexec task show 0x7ac398... --path "computed.json" ### Using DataProtector -```typescript +```ts twoslash import { IExecDataProtectorCore } from '@iexec/dataprotector'; const dataProtector = new IExecDataProtectorCore(web3Provider); - +// ---cut--- // Process protected data with specific path const result = await dataProtector.processProtectedData({ protectedData: '0x123abc...', @@ -526,7 +529,7 @@ You can combine different types of inputs for complex executions. ### Using SDK Library -```typescript +```ts twoslash import { IExecConfig, IExecOrderModule, @@ -541,7 +544,7 @@ const config = new IExecConfig({ ethProvider: window.ethereum }); const orderModule = IExecOrderModule.fromConfig(config); const orderbookModule = IExecOrderbookModule.fromConfig(config); const secretsModule = IExecSecretsModule.fromConfig(config); - +// ---cut--- // Complete example with all input types const requestOrder = await orderModule.createRequestOrder({ app: '0x456def...', @@ -589,19 +592,18 @@ iexec app run 0x456def... \ --protectedData 0x123abc... \ --args "--mode production --output-format json" \ --inputFiles "https://example.com/config.json,https://example.com/template.html" \ - --path "data/input.csv" \ - --maxPrice 10 + --path "data/input.csv" # Note: Secrets must be handled via SDK due to CLI limitations ``` ### Using DataProtector -```typescript +```ts twoslash import { IExecDataProtectorCore } from '@iexec/dataprotector'; const dataProtector = new IExecDataProtectorCore(web3Provider); - +// ---cut--- // Process protected data with multiple input types const result = await dataProtector.processProtectedData({ protectedData: '0x123abc...', @@ -642,7 +644,7 @@ const dbPassword = process.env.IEXEC_SECRET_2; // 'database-password' ### Validate Inputs Before Execution -```typescript +```ts twoslash const validateInputs = (params) => { const errors = []; @@ -693,7 +695,7 @@ const result = await dataProtectorCore.processProtectedData(params); ### Handle Input-Related Errors -```typescript +```ts twoslash try { const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -718,7 +720,7 @@ try { ### 1. Use Appropriate Input Types -```typescript +```ts twoslash // ✅ Use secrets for sensitive data const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -731,7 +733,7 @@ const result = await dataProtectorCore.processProtectedData({ ### 2. Validate URLs and Files -```typescript +```ts twoslash // ✅ Ensure input files are accessible const inputFiles = [ 'https://raw.githubusercontent.com/user/repo/main/config.json', @@ -762,7 +764,7 @@ const validFiles = accessibleFiles ### 3. Use Descriptive Arguments -```typescript +```ts twoslash // ✅ Clear, descriptive arguments const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -774,7 +776,7 @@ const result = await dataProtectorCore.processProtectedData({ ### 4. Organize Secrets Logically -```typescript +```ts twoslash // ✅ Logical secret numbering const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', diff --git a/src/use-iapp/guides/different-ways-to-execute.md b/src/use-iapp/guides/different-ways-to-execute.md index c705b1c4..8dcb7455 100644 --- a/src/use-iapp/guides/different-ways-to-execute.md +++ b/src/use-iapp/guides/different-ways-to-execute.md @@ -10,20 +10,22 @@ There are multiple ways to execute iApps 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 +::: 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. ::: +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 iApps. -```typescript +```ts twoslash import { IExecConfig, IExecOrderModule, @@ -36,7 +38,7 @@ const config = new IExecConfig({ ethProvider: window.ethereum }); // instantiate modules sharing the same configuration const orderModule = IExecOrderModule.fromConfig(config); const orderbookModule = IExecOrderbookModule.fromConfig(config); - +// ---cut--- // Create a request order const requestOrder = await orderModule.createRequestOrder({ app: '0x456def...', // The iApp address @@ -65,20 +67,9 @@ const taskId = await orderModule.matchOrders({ The iExec CLI is perfect for quick executions and automation scripts. -### Installation - -```bash -npm install -g @iexec/iexec -``` - -### Basic CLI Execution - ```bash # Execute an iApp iexec app run 0x456def... - -# Set maximum price -iexec app run 0x456def... --maxPrice 10 ``` ## Method 3: Using the iApp Generator CLI @@ -86,11 +77,7 @@ iexec app run 0x456def... --maxPrice 10 The iApp Generator CLI provides a streamlined way to execute iApps, especially for developers who have built their own iApps. -### Installation - -```bash -npm install -g @iexec/iapp -``` +> **Note**: For installation instructions, see the [iApp Generator Getting Started guide](/build-iapp/iapp-generator/getting-started). ### Basic Execution diff --git a/src/use-iapp/guides/find-iapps.md b/src/use-iapp/guides/find-iapps.md index 3b1d9f37..7c5e6b7c 100644 --- a/src/use-iapp/guides/find-iapps.md +++ b/src/use-iapp/guides/find-iapps.md @@ -11,38 +11,25 @@ available iApps on the iExec network. ## Using the iExec Explorer -The [iExec Explorer](https://explorer.iex.ec) is the primary tool for -discovering iApps. - -### Step-by-Step Discovery - -1. **Visit the Explorer**: Go to [explorer.iex.ec](https://explorer.iex.ec) -2. **Navigate to Apps**: Click on the "Apps" section in the navigation -3. **Search by Name**: Use the search function to find specific applications -4. **View Details**: Click on any app to see detailed information +The [iExec Explorer](/overview/tooling-and-explorers/iexec-explorer) is the primary tool for +discovering iApps. For detailed instructions on how to browse and filter iApps, see the [📱 iApps Listing section](/overview/tooling-and-explorers/iexec-explorer#📱-iapps-listing). ### What to Look For When evaluating an iApp, check these key details: -- **Description**: What does the app do? -- **Requirements**: What type of data or inputs does it need? - **Pricing**: How much does execution cost? - **Developer**: Who created the app? - **Usage Statistics**: How often is it used? - **Orders Availability**: Are there active orders available for execution? +> **Note**: Detailed descriptions and specific requirements are not available in the iExec explorer. You may need to check the developer's documentation, community forums, or contact the developer directly for this information. + ## Using the iExec CLI For developers who prefer command-line tools, the iExec CLI provides programmatic access to app discovery. -### Installation - -```bash -npm install -g @iexec/iexec -``` - ### Basic Commands ```bash diff --git a/src/use-iapp/guides/how-to-pay-executions.md b/src/use-iapp/guides/how-to-pay-executions.md index 8d1b75ca..6c11d1ba 100644 --- a/src/use-iapp/guides/how-to-pay-executions.md +++ b/src/use-iapp/guides/how-to-pay-executions.md @@ -37,7 +37,7 @@ You can obtain RLC tokens from various exchanges: RLC tokens need to be on the iExec sidechain (Bellecour) for payments: -```typescript +```ts twoslash import { IExecConfig, IExecAccountModule } from '@iexec/sdk'; // create the configuration @@ -45,7 +45,7 @@ const config = new IExecConfig({ ethProvider: window.ethereum }); // instantiate account module const accountModule = IExecAccountModule.fromConfig(config); - +// ---cut--- // Check your balance const balance = await accountModule.show(); console.log('Current balance:', balance); @@ -56,12 +56,12 @@ await accountModule.deposit(100); // Deposit 100 RLC #### Step 3: Execute with RLC Payment -```typescript +```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; const web3Provider = getWeb3Provider(window.ethereum); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); - +// ---cut--- // Execute with RLC payment (default) const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -75,7 +75,7 @@ const result = await dataProtectorCore.processProtectedData({ ```bash # Execute with RLC payment -iexec app run 0x456def... --protectedData 0x123abc... --maxPrice 10 +iexec app run 0x456def... --protectedData 0x123abc... # Check your balance iexec account show @@ -103,7 +103,7 @@ iExec network. They offer several advantages: #### Basic Voucher Usage -```typescript +```ts twoslash const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', app: '0x456def...', @@ -123,7 +123,7 @@ sufficient funds for this transfer to proceed. #### Using Someone Else's Voucher -```typescript +```ts twoslash const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', app: '0x456def...', @@ -165,7 +165,7 @@ iApp execution costs consist of several components: You can control costs by setting maximum prices for each component: -```typescript +```ts twoslash const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', app: '0x456def...', @@ -188,7 +188,7 @@ parameters is `0`, which means no maximum price limit is set. Regularly check your RLC balance and voucher status: -```typescript +```ts twoslash // Check RLC balance const balance = await iexec.account.show(); console.log('RLC Balance:', balance); @@ -202,7 +202,7 @@ console.log('Voucher Balance:', voucherBalance); Always set maximum prices to avoid unexpected costs: -```typescript +```ts twoslash // Good practice: Set explicit price limits const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -217,7 +217,7 @@ const result = await dataProtectorCore.processProtectedData({ For frequent executions, consider using vouchers: -```typescript +```ts twoslash // Use vouchers for regular operations const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -231,7 +231,7 @@ const result = await dataProtectorCore.processProtectedData({ Group multiple executions to optimize costs: -```typescript +```ts twoslash // Execute multiple tasks efficiently const tasks = [ { protectedData: '0x123abc...', app: '0x456def...' }, @@ -257,7 +257,7 @@ const results = await Promise.all( If you encounter insufficient balance errors: -```typescript +```ts twoslash try { const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -278,7 +278,7 @@ try { If voucher payment fails: -```typescript +```ts twoslash try { const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -298,7 +298,7 @@ try { If execution fails due to price constraints: -```typescript +```ts twoslash try { const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -326,7 +326,7 @@ try { ### 1. Always Set Price Limits -```typescript +```ts twoslash // Never execute without price limits const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -339,7 +339,7 @@ const result = await dataProtectorCore.processProtectedData({ ### 2. Use Vouchers for Production -```typescript +```ts twoslash // Use vouchers for production applications const result = await dataProtectorCore.processProtectedData({ protectedData: '0x123abc...', @@ -351,7 +351,7 @@ const result = await dataProtectorCore.processProtectedData({ ### 3. Monitor Costs Regularly -```typescript +```ts twoslash // Check costs before and after execution const balanceBefore = await iexec.account.show(); const result = await dataProtectorCore.processProtectedData({ @@ -367,7 +367,7 @@ console.log('Cost:', balanceBefore - balanceAfter); ### 4. Handle Payment Errors Gracefully -```typescript +```ts twoslash const executeWithPaymentRetry = async (params, maxRetries = 3) => { for (let i = 0; i < maxRetries; i++) { try { diff --git a/src/use-iapp/guides/use-iapp-with-protected-data.md b/src/use-iapp/guides/use-iapp-with-protected-data.md index 7351d9a0..f009c9fd 100644 --- a/src/use-iapp/guides/use-iapp-with-protected-data.md +++ b/src/use-iapp/guides/use-iapp-with-protected-data.md @@ -29,12 +29,12 @@ Before using an iApp, you need to protect your sensitive data. ### Basic Data Protection -```typescript +```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; const web3Provider = getWeb3Provider(window.ethereum); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); - +// ---cut--- // Protect your data const { address: protectedDataAddress } = await dataProtectorCore.protectData({ name: 'My Sensitive Data', @@ -51,7 +51,7 @@ const { address: protectedDataAddress } = await dataProtectorCore.protectData({ ### Protecting Different Data Types -```typescript +```ts twoslash // Protect contact list for email applications const { address: contactListAddress } = await dataProtectorCore.protectData({ name: 'Email Contact List', @@ -93,7 +93,7 @@ iApps need explicit authorization to access your protected data. ### Grant Access to a Specific iApp -```typescript +```ts twoslash // Grant access to an iApp const grantedAccess = await dataProtectorCore.grantAccess({ protectedData: protectedDataAddress, @@ -106,7 +106,7 @@ const grantedAccess = await dataProtectorCore.grantAccess({ ### Check Granted Access -```typescript +```ts twoslash // Check what access you've granted const grantedAccessList = await dataProtectorCore.getGrantedAccess({ protectedData: protectedDataAddress, @@ -123,7 +123,7 @@ Once access is granted, you can execute the iApp with your protected data. ### Using DataProtector -```typescript +```ts twoslash // Execute iApp with protected data const result = await dataProtectorCore.processProtectedData({ protectedData: protectedDataAddress, @@ -134,7 +134,7 @@ const result = await dataProtectorCore.processProtectedData({ ### Using SDK Library -```typescript +```ts twoslash import { IExecConfig, IExecOrderModule, @@ -147,7 +147,7 @@ const config = new IExecConfig({ ethProvider: window.ethereum }); // instantiate modules sharing the same configuration const orderModule = IExecOrderModule.fromConfig(config); const orderbookModule = IExecOrderbookModule.fromConfig(config); - +// ---cut--- // Create a request order with protected data const requestOrder = await orderModule.createRequestOrder({ app: '0x456def...', // The iApp address @@ -178,11 +178,11 @@ const taskId = await orderModule.matchOrders({ }); ``` -### Using CLI with Protected Data +### Using iExec CLI with Protected Data ```bash # Execute with protected data -iexec app run 0x456def... --dataset 0x123abc... --maxPrice 10 +iexec app run 0x456def... --dataset 0x123abc... ``` ## Step 4: Retrieve Results @@ -191,7 +191,7 @@ After execution completes, retrieve the results from the task. ### Using DataProtector -```typescript +```ts twoslash // Get the task ID from the execution result const taskId = result.taskId; @@ -209,7 +209,7 @@ const taskResult = await dataProtectorCore.getResultFromCompletedTask({ ### Using SDK Library -```typescript +```ts twoslash import { IExecConfig, IExecResultModule } from '@iexec/sdk'; // create the configuration @@ -217,7 +217,7 @@ const config = new IExecConfig({ ethProvider: window.ethereum }); // instantiate result module const resultModule = IExecResultModule.fromConfig(config); - +// ---cut--- // Get the task ID from the execution result const taskId = result.taskId; // or taskId from SDK library execution @@ -233,7 +233,7 @@ const specificFile = await resultModule.getTaskResult({ }); ``` -### Using CLI +### Using iExec CLI ```bash # Get the task ID from the execution result @@ -250,7 +250,7 @@ iexec task show $TASK_ID --path "computed.json" ### Example 1: Data Analysis System -```typescript +```ts twoslash // 1. Protect sensitive dataset const { address: datasetAddress } = await dataProtectorCore.protectData({ name: 'Customer Analytics Data', @@ -283,7 +283,7 @@ const analysisResult = await dataProtectorCore.processProtectedData({ ### Example 2: Oracle Price Update -```typescript +```ts twoslash // 1. Protect trading data const { address: tradingDataAddress } = await dataProtectorCore.protectData({ name: 'Trading Data', @@ -315,7 +315,7 @@ const oracleResult = await dataProtectorCore.processProtectedData({ ### Example 3: Automated Payment Processing -```typescript +```ts twoslash // 1. Protect payment data const { address: paymentDataAddress } = await dataProtectorCore.protectData({ name: 'Payment Data', @@ -352,7 +352,7 @@ const paymentResult = await dataProtectorCore.processProtectedData({ ### Pattern 1: Batch Processing -```typescript +```ts twoslash // Process multiple protected datasets const datasets = [ { address: '0x123abc...', name: 'Dataset 1' }, @@ -374,7 +374,7 @@ const batchResults = await Promise.all( ### Pattern 2: Result Processing Pipeline -```typescript +```ts twoslash // Process results and use them for further computation const initialResult = await dataProtectorCore.processProtectedData({ protectedData: protectedDataAddress, @@ -402,7 +402,7 @@ const { address: newProtectedDataAddress } = ### 1. Always Grant Access Before Execution -```typescript +```ts twoslash // ✅ Good: Grant access first await dataProtectorCore.grantAccess({ protectedData: protectedDataAddress, @@ -421,7 +421,7 @@ const result = await dataProtectorCore.processProtectedData({ ### 2. Monitor Access Usage -```typescript +```ts twoslash // Check access usage regularly const grantedAccess = await dataProtectorCore.getGrantedAccess({ protectedData: protectedDataAddress, @@ -435,7 +435,7 @@ console.log('Used access:', grantedAccess.usedAccess); ### 3. Use Appropriate Price Limits -```typescript +```ts twoslash // Set reasonable price limits const result = await dataProtectorCore.processProtectedData({ protectedData: protectedDataAddress, @@ -446,7 +446,7 @@ const result = await dataProtectorCore.processProtectedData({ ### 4. Handle Results Properly -```typescript +```ts twoslash // Store task ID and retrieve results later const result = await dataProtectorCore.processProtectedData({ protectedData: protectedDataAddress, diff --git a/src/use-iapp/introduction.md b/src/use-iapp/introduction.md index a683fa30..1440dacd 100644 --- a/src/use-iapp/introduction.md +++ b/src/use-iapp/introduction.md @@ -7,44 +7,56 @@ description: # 📝 Introduction to Using iApps -iExec Applications (iApps) are your gateway to secure, privacy-preserving -computation on the iExec network. These applications run inside Trusted -Execution Environments (TEEs) like Intel SGX or Intel TDX, ensuring your data -remains confidential even during processing. - -## What are iApps? - -iApps are regular applications (Python scripts, AI models, data processors, -etc.) that have been adapted to run securely on the iExec network. They can -process protected data without ever seeing the raw information, making them -perfect for scenarios where data privacy is crucial. - -## Key Benefits - -- **🔒 Privacy-First**: Your data never leaves the secure TEE environment -- **⚡ Trusted Execution**: Applications run in hardware-protected environments -- **🌐 Decentralized**: No single point of failure or control -- **💰 Cost-Effective**: Pay only for the computation you need -- **🔧 Developer-Friendly**: Use familiar programming languages and tools - -## How iApps Work - -1. **Data Protection**: Users protect their sensitive data using the - [Data Protector](/manage-data/dataProtector/dataProtectorCore/protectData) -2. **Application Deployment**: Developers deploy their applications to the iExec - network -3. **Secure Processing**: iApps process protected data inside TEEs without - accessing raw data -4. **Result Delivery**: Only the computation results are returned, keeping - original data private - -## Use Cases - -- **Email Notifications**: Send emails without seeing recipient addresses -- **Oracle Updates**: Update price feeds using private trading data -- **Automated Transactions**: Process payments with protected financial data -- **AI Model Training**: Train models on sensitive datasets -- **Data Analytics**: Analyze private data without exposing it +In the iExec network, multiple actors work together in a coordinated process to ensure secure, decentralized computation. Here's how the ecosystem operates: + +### Key Actors in the Network + +- **👤 Requesters**: Users who need computation performed on protected data +- **🏭 Workerpool Managers**: Operators who manage groups of workers and coordinate task execution +- **⚙️ Workers**: Individual machines that execute the actual computations +- **👨‍💻 iApp Developers**: Developers who create and deploy applications to the iExec marketplace +- **🔐 Data Providers**: Users who own and protect the data being processed + +### Network Assets + +- **📱 iApps**: Applications that process the data securely +- **💾 Data**: Protected information that needs to be processed +- **⚡ Computational Power**: Processing resources provided by workers +- **💰 PoCo**: Proof of Contribution system that matches all actors through marketplace + +### Network Coordination + +The iExec network coordinates all actors through the PoCo (Proof of Contribution) system, which automatically matches requesters with the appropriate applications, data, and computational resources based on availability, requirements, and pricing. + +### Deal Execution Flow + +When a deal is triggered, the following sequence occurs: + +1. **Request Creation**: Requester submits a computation request with parameters +2. **Resource Matching**: PoCo system matches the request with available applications, data, and computational resources +3. **Deal Creation**: When compatible resources are found, a deal is created containing multiple tasks +4. **Task Distribution**: Selected workerpool manager distributes tasks to their workers +5. **Secure Execution**: Workers download the iApp and execute it in TEE environments +6. **Data Processing**: iApp processes protected data without accessing raw content +7. **Result Generation**: Computation results are generated +8. **Result Delivery**: Results are returned to the requester through the network +9. **Payment Settlement**: RLC tokens are distributed to all participants + +### Network Architecture Diagram + +![iExec Network Actors](/assets/use-iapp/iexec-actors-diagram.svg) + +### Detailed Interaction Flow + +1. **Request Submission**: Requester creates a request specifying the iApp, Protected Data, etc. +2. **PoCo Processing**: PoCo system validates the request and matches resources +3. **Deal Creation**: When resources are matched, PoCo creates a deal +4. **Secure Environment Setup**: Workers initialize TEE environments and download the iApp +5. **Data Access**: iApp requests access to protected data through secure channels +6. **Computation**: iApp processes data within the TEE, maintaining privacy +7. **Payment Distribution**: RLC tokens are distributed to all participants based on completed tasks + +This decentralized architecture ensures that no single entity has control over the entire process, while the use of TEEs guarantees that sensitive data remains protected throughout the computation. ## Getting Started From 0f0ab4b37987823d206dc2515017469014833822 Mon Sep 17 00:00:00 2001 From: aimen-djari Date: Tue, 12 Aug 2025 23:55:48 +0100 Subject: [PATCH 4/8] fix format --- src/use-iapp/getting-started.md | 45 +++++++++++----- .../guides/add-inputs-to-execution.md | 31 ++++++----- .../guides/different-ways-to-execute.md | 9 ++-- src/use-iapp/guides/find-iapps.md | 10 ++-- src/use-iapp/introduction.md | 51 +++++++++++++------ 5 files changed, 95 insertions(+), 51 deletions(-) diff --git a/src/use-iapp/getting-started.md b/src/use-iapp/getting-started.md index 3440fdfb..a2a5076d 100644 --- a/src/use-iapp/getting-started.md +++ b/src/use-iapp/getting-started.md @@ -6,14 +6,17 @@ description: # 🚀 Getting Started with iApps -Welcome to the world of secure, privacy-preserving computation! This guide gives you a high-level overview of how to use iApps on the iExec network. +Welcome to the world of secure, privacy-preserving computation! This guide gives +you a high-level overview of how to use iApps on the iExec network. ## Prerequisites Before you begin, make sure you have: - 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](/overview/rlc) and [how to bridge them](/overview/tooling-and-explorers/bridge) +- Some RLC tokens for paying computation fees (or access to free vouchers + through learning programs) - [Learn about RLC tokens](/overview/rlc) and + [how to bridge them](/overview/tooling-and-explorers/bridge) - **Note**: On Arbitrum, you'll need AETH (Arbitrum ETH) instead of RLC - Basic understanding of blockchain transactions - iExec SDK installed @@ -44,33 +47,49 @@ Ready to dive in? Let's get started with finding and executing your first iApp! Using iApps involves these main steps: -1. **Find iApps** - Browse available applications in the [iExec Explorer](/overview/tooling-and-explorers/iexec-explorer) +1. **Find iApps** - Browse available applications in the + [iExec Explorer](/overview/tooling-and-explorers/iexec-explorer) 2. **Prepare Data** - Set up any required protected data or inputs 3. **Execute** - Run the iApp 4. **Get Results** - Retrieve your computation results ### Understanding Orders -iApps are executed through a marketplace system where different actors publish orders: +iApps are executed through a marketplace system where different actors publish +orders: + - **App orders** - Published by developers with pricing and availability -- **Workerpool orders** - Published by computation providers with capacity and pricing -- **Dataset orders** - Published by data owners with access conditions and pricing +- **Workerpool orders** - Published by computation providers with capacity and + pricing +- **Dataset orders** - Published by data owners with access conditions and + pricing -When you execute an iApp, the system matches your request with available orders from all three categories. For a deeper understanding of how orders work and how to manage them, see the [Manage Orders guide](/build-iapp/guides/manage-access#manage-orders) in the Build iApp section. +When you execute an iApp, the system matches your request with available orders +from all three categories. For a deeper understanding of how orders work and how +to manage them, see the +[Manage Orders guide](/build-iapp/guides/manage-access#manage-orders) in the +Build iApp section. ## Detailed Guides For step-by-step instructions, check out these guides: -- **[Find iApps](./guides/find-iapps.md)** - How to discover and evaluate available applications -- **[Different Ways to Execute](./guides/different-ways-to-execute.md)** - iExec cli, lib, and other execution methods -- **[Use iApps with Protected Data](./guides/use-iapp-with-protected-data.md)** - Working with sensitive data securely -- **[Add Inputs to Execution](./guides/add-inputs-to-execution.md)** - How to provide data and parameters to iApps -- **[How to Pay for Executions](./guides/how-to-pay-executions.md)** - Understanding costs and payment options +- **[Find iApps](./guides/find-iapps.md)** - How to discover and evaluate + available applications +- **[Different Ways to Execute](./guides/different-ways-to-execute.md)** - iExec + cli, lib, and other execution methods +- **[Use iApps with Protected Data](./guides/use-iapp-with-protected-data.md)** - + Working with sensitive data securely +- **[Add Inputs to Execution](./guides/add-inputs-to-execution.md)** - How to + provide data and parameters to iApps +- **[How to Pay for Executions](./guides/how-to-pay-executions.md)** - + Understanding costs and payment options ## Quick Start -Ready to jump in? Start with our [Find iApps guide](./guides/find-iapps.md) to discover what's available, then follow the execution guides for detailed instructions. +Ready to jump in? Start with our [Find iApps guide](./guides/find-iapps.md) to +discover what's available, then follow the execution guides for detailed +instructions. diff --git a/src/guides/use-iapp/how-to-pay-executions.md b/src/guides/use-iapp/how-to-pay-executions.md index 6c11d1ba..8cc02532 100644 --- a/src/guides/use-iapp/how-to-pay-executions.md +++ b/src/guides/use-iapp/how-to-pay-executions.md @@ -1,4 +1,4 @@ ---- + 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 f009c9fd..b5a81fd3 100644 --- a/src/guides/use-iapp/use-iapp-with-protected-data.md +++ b/src/guides/use-iapp/use-iapp-with-protected-data.md @@ -32,7 +32,7 @@ Before using an iApp, you need to protect your sensitive data. ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; -const web3Provider = getWeb3Provider(window.ethereum); +const web3Provider = getWeb3Provider('PRIVATE_KEY'); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); // ---cut--- // Protect your data @@ -52,6 +52,11 @@ 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', @@ -94,9 +99,14 @@ iApps 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: protectedDataAddress, + protectedData: '0x123abc...', authorizedApp: '0x456def...', // The iApp address authorizedUser: '0x789abc...', // Your wallet address pricePerAccess: 5, // Price per access in nRLC @@ -107,14 +117,17 @@ const grantedAccess = await dataProtectorCore.grantAccess({ ### 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: protectedDataAddress, + protectedData: '0x123abc...', authorizedApp: '0x456def...', authorizedUser: '0x789abc...', }); - -console.log('Granted access:', grantedAccessList); ``` ## Step 3: Execute iApp with Protected Data @@ -124,57 +137,75 @@ Once access is granted, you can execute the iApp with your protected data. ### Using DataProtector ```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: protectedDataAddress, + protectedData: '0x123abc...', app: '0x456def...', // The iApp address - maxPrice: 10, // Maximum price in nRLC }); ``` ### Using SDK Library ```ts twoslash -import { - IExecConfig, - IExecOrderModule, - IExecOrderbookModule, -} from '@iexec/sdk'; - -// create the configuration -const config = new IExecConfig({ ethProvider: window.ethereum }); - -// instantiate modules sharing the same configuration -const orderModule = IExecOrderModule.fromConfig(config); -const orderbookModule = IExecOrderbookModule.fromConfig(config); +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 a request order with protected data -const requestOrder = await orderModule.createRequestOrder({ +// 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: 'debug-v8-learn.main.pools.iexec.eth', // ENS address for iExec's debug workerpool - // Other parameters have default values + workerpool: '0xa5de76...', // ENS address for iExec's debug workerpool }); +const requestOrder = await iexec.order.signRequestorder(requestorderToSign); -// Fetch matching orders from orderbook with filters -const appOrders = await orderbookModule.fetchAppOrderbook({ - app: '0x456def...', // Filter by specific app -}); -const datasetOrders = await orderbookModule.fetchDatasetOrderbook({ - dataset: protectedDataAddress, // Filter by specific dataset -}); -const workerpoolOrders = await orderbookModule.fetchWorkerpoolOrderbook({ - workerpool: 'debug-v8-learn.main.pools.iexec.eth', // Filter by specific workerpool ENS +// 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 orderModule.matchOrders({ +const taskId = await iexec.order.matchOrders({ requestorder: requestOrder, - apporder: appOrders[0], - datasetorder: datasetOrders[0], - workerpoolorder: workerpoolOrders[0], + apporder: appOrders.orders[0].order, + datasetorder: datasetOrders.orders[0].order, + workerpoolorder: workerpoolOrders.orders[0].order, }); ``` @@ -192,44 +223,16 @@ After execution completes, retrieve the results from the task. ### Using DataProtector ```ts twoslash -// Get the task ID from the execution result -const taskId = result.taskId; - -// Retrieve the result -const taskResult = await dataProtectorCore.getResultFromCompletedTask({ - taskId: taskId, -}); - -// Retrieve a specific file from the result -const taskResult = await dataProtectorCore.getResultFromCompletedTask({ - taskId: taskId, - path: 'computed.json', // Extract specific file -}); -``` - -### Using SDK Library - -```ts twoslash -import { IExecConfig, IExecResultModule } from '@iexec/sdk'; +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; -// create the configuration -const config = new IExecConfig({ ethProvider: window.ethereum }); +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +const taskId = '0x7ac398...' -// instantiate result module -const resultModule = IExecResultModule.fromConfig(config); // ---cut--- -// Get the task ID from the execution result -const taskId = result.taskId; // or taskId from SDK library execution - // Retrieve the result -const taskResult = await resultModule.getTaskResult({ - taskId: taskId, -}); - -// Retrieve a specific file from the result -const specificFile = await resultModule.getTaskResult({ +const taskResult = await dataProtectorCore.getResultFromCompletedTask({ taskId: taskId, - path: 'computed.json', // Extract specific file }); ``` @@ -251,15 +254,20 @@ iexec task show $TASK_ID --path "computed.json" ### 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: [ - { id: 1, purchases: 1500, category: 'premium' }, - { id: 2, purchases: 800, category: 'standard' }, - { id: 3, purchases: 2200, category: 'premium' }, - ], + customers: { + '0': { id: 1, purchases: 1500, category: 'premium' }, + '1': { id: 2, purchases: 800, category: 'standard' }, + '2': { id: 3, purchases: 2200, category: 'premium' }, + }, }, }); @@ -277,13 +285,18 @@ const analysisResult = await dataProtectorCore.processProtectedData({ protectedData: datasetAddress, app: '0xanalytics...', args: '--analyze-customer-segments --output-format json', - maxPrice: 10, + 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', @@ -309,13 +322,18 @@ const oracleResult = await dataProtectorCore.processProtectedData({ protectedData: tradingDataAddress, app: '0xoracle...', args: '--update-price-feed --asset ETH', - maxPrice: 10, + 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', @@ -344,58 +362,8 @@ const paymentResult = await dataProtectorCore.processProtectedData({ secrets: { 1: 'bank-api-key', }, - maxPrice: 8, -}); -``` - -## Advanced Patterns - -### Pattern 1: Batch Processing - -```ts twoslash -// Process multiple protected datasets -const datasets = [ - { address: '0x123abc...', name: 'Dataset 1' }, - { address: '0x456def...', name: 'Dataset 2' }, - { address: '0x789ghi...', name: 'Dataset 3' }, -]; - -const batchResults = await Promise.all( - datasets.map((dataset) => - dataProtectorCore.processProtectedData({ - protectedData: dataset.address, - app: '0x456def...', - args: `--dataset-name ${dataset.name}`, - maxPrice: 10, - }) - ) -); -``` - -### Pattern 2: Result Processing Pipeline - -```ts twoslash -// Process results and use them for further computation -const initialResult = await dataProtectorCore.processProtectedData({ - protectedData: protectedDataAddress, - app: '0x456def...', - maxPrice: 10, -}); - -// Get the result -const taskResult = await dataProtectorCore.getResultFromCompletedTask({ - taskId: initialResult.taskId, + appMaxPrice: 8, }); - -// Use the result for further processing -const processedData = await processResult(taskResult); - -// Protect the processed data -const { address: newProtectedDataAddress } = - await dataProtectorCore.protectData({ - name: 'Processed Data', - data: processedData, - }); ``` ## Best Practices @@ -403,7 +371,13 @@ const { address: newProtectedDataAddress } = ### 1. Always Grant Access Before Execution ```ts twoslash -// ✅ Good: Grant access first +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...', @@ -415,48 +389,61 @@ await dataProtectorCore.grantAccess({ const result = await dataProtectorCore.processProtectedData({ protectedData: protectedDataAddress, app: '0x456def...', - maxPrice: 10, + 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: protectedDataAddress, + protectedData: '0x123abc...', authorizedApp: '0x456def...', authorizedUser: '0x789abc...', }); -console.log('Remaining access:', grantedAccess.remainingAccess); -console.log('Used access:', grantedAccess.usedAccess); +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: protectedDataAddress, + protectedData: '0x123abc...', app: '0x456def...', - maxPrice: 10, // Set appropriate limit + 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: protectedDataAddress, + protectedData: '0x123abc...', app: '0x456def...', - maxPrice: 10, + appMaxPrice: 10, }); // Store task ID for later retrieval const taskId = result.taskId; -localStorage.setItem('lastTaskId', taskId); // Later, retrieve the result const taskResult = await dataProtectorCore.getResultFromCompletedTask({ From 895bdf3e0814892fcc35fc578d1e0efde6751074 Mon Sep 17 00:00:00 2001 From: Le-Caignec Date: Wed, 13 Aug 2025 18:15:50 +0200 Subject: [PATCH 6/8] refactor: remove redundant reference to Find iApps guide and streamline quick start instructions in the getting started documentation --- src/guides/use-iapp/getting-started.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/src/guides/use-iapp/getting-started.md b/src/guides/use-iapp/getting-started.md index 84947418..cb4a028a 100644 --- a/src/guides/use-iapp/getting-started.md +++ b/src/guides/use-iapp/getting-started.md @@ -74,8 +74,6 @@ Build iApp section. For step-by-step instructions, check out these guides: -- **[Find iApps](./find-iapps.md)** - How to discover and evaluate - available applications - **[Different Ways to Execute](./different-ways-to-execute.md)** - iExec cli, lib, and other execution methods - **[Use iApps with Protected Data](./use-iapp-with-protected-data.md)** - @@ -87,9 +85,8 @@ For step-by-step instructions, check out these guides: ## Quick Start -Ready to jump in? Start with our [Find iApps guide](./find-iapps.md) to -discover what's available, then follow the execution guides for detailed -instructions. +Ready to jump in? Follow the execution guides for detailed +instructions on how to use iApps.