diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index 315595b0..0f48d5a6 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -348,15 +348,14 @@ export function getSidebar() { { text: 'โ“ What Is an iApp?', link: '/build-iapp/what-is-iapp' }, { text: '๐Ÿ“– Guides', - link: '/build-iapp/guides', items: [ { - text: 'Manage Your iApps', - link: '/build-iapp/guides/manage-iapps', + text: 'Build and Deploy your iApps', + link: '/build-iapp/guides/build-&-deploy-iapp', }, { - text: 'Orders (how they work, how to manage them)', - link: '/build-iapp/guides/orders', + text: 'Manage your iApps', + link: '/build-iapp/guides/manage-iapp', }, { text: 'Inputs and Outputs (types, differences, formats)', @@ -374,20 +373,11 @@ export function getSidebar() { text: 'How to Get and Decrypt Results', link: '/build-iapp/guides/how-to-get-and-decrypt-results', }, - { - text: 'AI Frameworks', - link: '/build-iapp/guides/ai-frameworks', - }, - { - text: 'Other Emerging Trends', - link: '/build-iapp/guides/other-emerging-trends', - }, ], }, { text: '๐Ÿค– iApp Generator', link: '/build-iapp/iapp-generator', - collapsed: true, items: [ { text: 'Getting Started', @@ -397,20 +387,8 @@ export function getSidebar() { text: 'Building Your iApp', link: '/build-iapp/iapp-generator/building-your-iexec-app', }, - { - text: 'References', - link: '/build-iapp/iapp-generator/references', - }, - { - text: 'Advanced Creation', - link: '/build-iapp/iapp-generator/advanced-creation', - }, ], }, - { - text: '๐Ÿ”ง Protocol-Level Guides', - link: '/build-iapp/iapp-generator/protocol-level-guides', - }, ], }, ], diff --git a/src/build-iapp/guides/ai-frameworks.md b/src/build-iapp/guides/ai-frameworks.md deleted file mode 100644 index c00dd07f..00000000 --- a/src/build-iapp/guides/ai-frameworks.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: AI Frameworks -description: AI Frameworks for iApps ---- - -# AI Frameworks - -This page is under development. - - diff --git a/src/build-iapp/guides/build-&-deploy-iapp.md b/src/build-iapp/guides/build-&-deploy-iapp.md new file mode 100644 index 00000000..27697166 --- /dev/null +++ b/src/build-iapp/guides/build-&-deploy-iapp.md @@ -0,0 +1,115 @@ +--- +title: Build and Deploy an iApp? +description: + How to build an confidential iexec application and deploy it on iexec protocol +--- + +## iApp Generator: Your Development Tool + +Bootstrap TEE-compatible applications in minutes without any hardcoding skills, +iApp Generator handles all the low-level complexity for you. + +- **Access to TEEs easily** - No need to dive into low-level requirements, build + iApps that connect to TEEs in minutes. +- **Check and deploy iApps quickly** - iApp Generator checks that your iApp + complies with the iExec Framework and streamlines its deployment. +- **Select your project mode & language** - Get started with either a basic or + advanced setup, depending on your experience with the iExec framework. You can + use Python or JavaScriptโ€”whichever you prefer! + +```bash +# Create your iApp (Python or Node.js supported) +iapp init my-privacy-app +cd my-privacy-app + +# Develop and test locally (simulates TEE environment) +iapp test +# Deploy to the network +iapp deploy +``` + +
+

Note: iApp Generator currently supports Python and Node.js, but iApps can be built in any language that runs in Docker.

+
+ +## Real Examples + +Here are some real-world examples of iApps to help you understand how they work +in practice. + +**Email Notification iApp** + +This iApp lets you send updates to your contacts without ever seeing their email +addresses, privacy is preserved by design. + +::: code-group + +```python [Python] +# User runs: "Send updates to my contacts about my project" +contacts = load_protecteddata() # User's protected contact list +for contact in contacts: + send_email(contact, project_update_message) +# โ†’ Emails sent directly, you never see the addresses +``` + +```js [Node.js] +/* User runs: "Send updates to my contacts about my project" */ +const contacts = loadProtectedData(); // User's protected contact list +contacts.forEach((contact) => { + sendEmail(contact, projectUpdateMessage); +}); +// โ†’ Emails sent directly, you never see the addresses +``` + +::: + +**Oracle Update iApp** + +This iApp securely updates a price oracle using private trading data, ensuring +sensitive information stays confidential. + +::: code-group + +```python [Python] +# User runs: "Update price oracle with my private trading data" +trading_data = load_protecteddata() # User's protected trading history +average_price = calculate_weighted_average(trading_data) +update_oracle_contract(average_price) +# โ†’ Oracle updated with real data, trading history stays private +``` + +```js [Node.js] +/* User runs: "Update price oracle with my private trading data" */ +const tradingData = loadProtectedData(); // User's protected trading history +const averagePrice = calculateWeightedAverage(tradingData); +updateOracleContract(averagePrice); +// โ†’ Oracle updated with real data, trading history stays private +``` + +::: + +**Automated Transactions iApp** + +This iApp automates monthly payments using protected payment details, so +financial information remains private. + +::: code-group + +```python [Python] +# User runs: "Automate payments every month" +payment_info = load_protecteddata() # User's payment details +for month in range(12): + process_payment(payment_info) +# โ†’ Payments processed, payment details stay private +``` + +```js [Node.js] +/* User runs: "Automate payments every month" */ +const paymentInfo = loadProtectedData(); // User's payment details +for (let month = 0; month < 12; month++) { + processPayment(paymentInfo); +} +// โ†’ Payments processed, payment details stay private +``` + +::: diff --git a/src/build-iapp/guides/debugging-your-iapp.md b/src/build-iapp/guides/debugging-your-iapp.md index 57aed3bf..96815a3f 100644 --- a/src/build-iapp/guides/debugging-your-iapp.md +++ b/src/build-iapp/guides/debugging-your-iapp.md @@ -1,10 +1,175 @@ --- title: Debugging Your iApp -description: Debugging Your iApp +description: + Troubleshoot and optimize your iApp execution in the TEE environment --- -# Debugging Your iApp +# ๐Ÿ› Debugging Your iApp -This page is under development. +**When your iApp doesn't work as expected, debugging in the TEE environment +requires specific techniques.** This guide helps you identify issues and +optimize your iApp's performance. - +## Task Execution Lifecycle + +Understanding how your task progresses through the iExec network: + +### Key Stages + +1. **Deal Creation** - Orders matched, funds locked +2. **Task Initialization** - Workers selected for execution +3. **iApp Execution** - Your code runs inside TEE +4. **Result Processing** - Results encrypted and uploaded +5. **Task Completion** - Results available for download + +**Most failures happen during stages 2-4** + +## Monitoring Your Tasks + +### iExec Explorer + +Track your tasks at [explorer.iex.ec](https://explorer.iex.ec): + +- Search by `taskId` or deal ID +- Check status: `PENDING` โ†’ `ACTIVE` โ†’ `COMPLETED/FAILED` +- View error messages if execution fails + +### Status in Code + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +const response = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + onStatusUpdate: ({ title, isDone }) => { + console.log(`Status: ${title} - Done: ${isDone}`); + }, +}); +``` + +## Debug Commands + +### Local Testing + +```bash +# Test your iApp locally +iapp test --args "model=bert threshold=0.8" +iapp test --secrets "key1=value1,key2=value2" + +# Mock protected data for testing +iapp mock protectedData +iapp test --protectedData "mock_name" +``` + +### Remote Debugging + +```bash +# Deploy and run +iapp deploy +iapp run + +# Debug failed executions +iapp debug +``` + +### Task Information + +```bash +# View task details +iexec task show + +# Download results (if completed) +iexec task show --download +``` + +## Common Issues + +### โฑ๏ธ **Task Timeout** + +- **Cause**: Code takes too long to execute +- **Solution**: Optimize algorithms, reduce input sizes, use appropriate task + category + +### ๐Ÿ’พ **Memory Issues** + +- **Cause**: Loading large files, memory leaks, TEE constraints +- **Solution**: Process data in chunks, use streaming, optimize memory usage + +### ๐Ÿ“ **Input/Output Problems** + +- **Cause**: Wrong file paths, missing `computed.json` +- **Solution**: Always create `computed.json`, verify environment variables + +```python +# Always create computed.json +import json, os +computed = {"deterministic-output-path": f"{os.environ['IEXEC_OUT']}/result.json"} +with open(f"{os.environ['IEXEC_OUT']}/computed.json", 'w') as f: + json.dump(computed, f) +``` + +### โš ๏ธ **Dataset type unmatching** + +- **Cause**: The dataset type specified in the frontend (protectData) does not + match with the dataset type specified in the iApp +- **Solution**: Check both dataset types + +## Best Practices + +### ๐Ÿ” **Input Validation** + +```python +import os, sys + +# Check required environment variables +if not os.environ.get('IEXEC_IN') or not os.environ.get('IEXEC_OUT'): + print("ERROR: Missing IEXEC_IN or IEXEC_OUT") + sys.exit(1) + +# Validate arguments +if len(sys.argv) < 2: + print("ERROR: Missing required arguments") + sys.exit(1) +``` + +### ๐Ÿ“ **Clear Error Messages** + +```python +try: + # Your processing logic + result = process_data(data) +except Exception as e: + print(f"ERROR: Processing failed: {str(e)}") + sys.exit(1) +``` + +### ๐Ÿ”’ **Safe File Operations** + +```python +import os, json + +# Always ensure output directory exists +iexec_out = os.environ['IEXEC_OUT'] +os.makedirs(iexec_out, exist_ok=True) + +# Write results safely +try: + with open(f"{iexec_out}/result.json", 'w') as f: + json.dump(result_data, f) +except Exception as e: + print(f"ERROR: Failed to write results: {e}") + sys.exit(1) +``` + +## What's Next? + +Continue improving your iApps: + +- **[Inputs and Outputs](/build_iapp/guides/inputs-and-outputs)** - Handle data + in TEE +- **[How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results)** - + Retrieve results diff --git a/src/build-iapp/guides/how-to-get-and-decrypt-results.md b/src/build-iapp/guides/how-to-get-and-decrypt-results.md index 514e5134..90fbbd18 100644 --- a/src/build-iapp/guides/how-to-get-and-decrypt-results.md +++ b/src/build-iapp/guides/how-to-get-and-decrypt-results.md @@ -1,10 +1,314 @@ --- title: How to Get and Decrypt Results -description: How to get and decrypt results +description: Download and decrypt iApp execution results from completed tasks --- -# How to Get and Decrypt Results +# ๐Ÿ“ฆ How to Get and Decrypt Results -This page is under development. +**When an iApp execution completes, you need to retrieve and decrypt the +results.** This guide shows you how to download task results and decrypt them to +access the actual output files. - +Understanding the result retrieval process is essential for building +user-friendly applications with iExec. + +## Understanding Results Structure + +### Deal โ†’ Task โ†’ Result Flow + +**Every execution follows this hierarchy**: + +``` +Deal (agreement between parties) +โ”œโ”€โ”€ Task 1 (individual execution instance) +โ”‚ โ””โ”€โ”€ Result (encrypted output files) +โ”œโ”€โ”€ Task 2 +โ”‚ โ””โ”€โ”€ Result +โ””โ”€โ”€ ... +``` + +- **Deal**: Contains one or more tasks from your execution request +- **Task**: Individual computation instance with unique `taskId` +- **Result**: Encrypted ZIP file containing your iApp's output files + +### Result Accessibility + +**Results are publicly downloadable** but may be encrypted: + +- โœ… **Anyone can download** the result file from IPFS +- ๐Ÿ”’ **Only authorized parties can decrypt** the contents +- ๐Ÿ“ **Results contain** all files from `IEXEC_OUT` directory +- โšก **Available immediately** after task completion + +## Downloading Results + +### Using iExec SDK CLI + +**Get task information and download**: + +```bash +# Check task status and get result info +iexec task show + +# Download encrypted result +iexec task show --download my-result + +# Extract downloaded files +unzip my-result.zip -d my-result/ +ls my-result/ +``` + +**Get task ID from deal**: + +```bash +# If you only have the deal ID +iexec deal show + +# Lists all tasks in the deal with their IDs +``` + +### Using DataProtector SDK + +**Integrated download and decryption**: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// Get result from completed task +const result = await dataProtectorCore.getResultFromCompletedTask({ + taskId: '0x123abc...', // Your task ID +}); + +console.log('Result downloaded and decrypted:', result); +``` + +## Decrypting Results + +### Automatic Decryption with DataProtector + +**The easiest way** - decryption happens automatically: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// Execute and get results in one flow +const processResponse = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', +}); + +console.log('Task ID:', processResponse.taskId); + +// Get decrypted result +const result = await dataProtectorCore.getResultFromCompletedTask({ + taskId: processResponse.taskId, +}); + +// Result is automatically decrypted ArrayBuffer +const resultText = new TextDecoder().decode(result.result); +console.log('Decrypted result:', resultText); +``` + +### Manual Decryption with CLI + +**If you downloaded manually**: + +```bash +# Download the encrypted result +iexec task show --download my-result + +# Decrypt using your wallet (must be the beneficiary) +iexec result decrypt my-result.zip --force + +# Extract decrypted files +unzip decrypted-result.zip -d final-result/ +cat final-result/result.txt +``` + +## Result File Structure + +### What's Inside a Result + +**Typical result contents**: + +``` +result.zip +โ”œโ”€โ”€ computed.json # Mandatory metadata file +โ”œโ”€โ”€ result.txt # Your main output +โ”œโ”€โ”€ analysis.json # Additional outputs +โ”œโ”€โ”€ logs.txt # Optional logs +โ””โ”€โ”€ metadata.json # Optional metadata +``` + +### computed.json Structure + +**Always present in every result**: + +```json +{ + "deterministic-output-path": "/iexec_out/result.txt", + "execution-timestamp": "2024-01-15T10:30:00Z", + "app-version": "1.0.0" +} +``` + +**Key fields**: + +- `deterministic-output-path`: Main result file path +- `execution-timestamp`: When the computation completed +- Custom fields added by your iApp + +## Common Patterns + +### React Application Example + +**Integrate result retrieval in your frontend**: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +async function downloadResult(taskId: string) { + try { + const resultResponse = await dataProtectorCore.getResultFromCompletedTask({ + taskId, + }); + + // Convert to text or JSON based on your result format + const resultText = new TextDecoder().decode(resultResponse.result); + const resultJson = JSON.parse(resultText); + + return resultJson; + } catch (error) { + console.error('Failed to download result:', error); + throw error; + } +} + +// Usage example +const taskId = '0x123abc...'; +const result = await downloadResult(taskId); +console.log('Analysis Result:', result); +``` + +### Node.js Backend Example + +**Server-side result processing**: + +```javascript +const { + IExecDataProtectorCore, + getWeb3Provider, +} = require('@iexec/dataprotector'); + +async function processTaskResult(taskId) { + const web3Provider = getWeb3Provider(process.env.PRIVATE_KEY); + const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + + try { + // Get the result + const resultBuffer = await dataProtectorCore.getResultFromCompletedTask({ + taskId, + }); + + // Parse the result based on your format + const resultText = new TextDecoder().decode(resultBuffer); + + // If your result is JSON + const analysisResult = JSON.parse(resultText); + + // Store in database, send notifications, etc. + await saveToDatabase(taskId, analysisResult); + await notifyUser(analysisResult); + + return analysisResult; + } catch (error) { + console.error('Result processing failed:', error); + throw error; + } +} +``` + +## Troubleshooting + +### Common Issues + +**โŒ "Task not completed"** + +``` +Error: Task is still running +``` + +**Solution**: Wait for task completion or check status with +`iexec task show ` + +**โŒ "Decryption failed"** + +``` +Error: Failed to decrypt result +``` + +**Solutions**: + +- Ensure you're using the correct wallet (beneficiary) +- Check if result was actually encrypted +- Verify task completed successfully + +**โŒ "Result not found"** + +``` +Error: Result not available +``` + +**Solutions**: + +- Check task status - it might have failed +- Verify the task ID is correct +- Wait for result upload to complete + +### Checking Task Status + +**Before downloading, verify completion**: + +```bash +# Check if task is completed +iexec task show + +# Look for status: "COMPLETED" +# And result information in the output +``` + +### Result Encryption Status + +**Not all results are encrypted**: + +- ๐Ÿ”’ **Encrypted**: When `beneficiary` is set in the request +- ๐Ÿ“‚ **Plain**: When no beneficiary specified (public results) +- โœ… **DataProtector handles both** automatically + +## What's Next? + +**You can now retrieve and decrypt iApp results!** + +Integrate result handling into your applications: + +- **[Inputs and Outputs](/build_iapp/guides/inputs-and-outputs)** - Understand + what your iApp can output +- **[Debugging Your iApp](/build_iapp/guides/debugging-your-iapp)** - + Troubleshoot execution issues +- **[App Access Control and Pricing](/build_iapp/guides/orders)** - Control who + can run your iApp + +### Advanced Topics + +- **[DataProtector SDK](/manage_data/dataProtector)** - Complete SDK + documentation +- **[SDK Deep Dive](/deep_dive/sdk)** - Advanced result handling techniques diff --git a/src/build-iapp/guides/inputs-and-outputs.md b/src/build-iapp/guides/inputs-and-outputs.md index b0bbeddc..9ae58597 100644 --- a/src/build-iapp/guides/inputs-and-outputs.md +++ b/src/build-iapp/guides/inputs-and-outputs.md @@ -1,10 +1,641 @@ --- -title: Inputs and Outputs (types, differences, formats) -description: Types, differences, and formats of inputs and outputs +title: Inputs and Outputs +description: + Understand the different input types and output formats for iApps in the TEE + environment --- -# Inputs and Outputs (types, differences, formats) +# ๐Ÿ“ฅ๐Ÿ“ค Inputs and Outputs -This page is under development. +**Your iApp runs inside a secure TEE environment with access to different types +of inputs.** Understanding what data you can access, how to access it, and when +to use each type is crucial for building effective privacy-preserving +applications. - +This guide covers all input types available to your iApp and how to generate +proper outputs that users can retrieve and decrypt. + +## Development vs User Execution + +**Two perspectives on inputs:** + +- ๐Ÿ”ง **As a developer** (using iApp Generator): You write code to access inputs + from the TEE environment +- ๐Ÿ‘ค **As a user** (using DataProtector): You provide inputs when executing the + iApp via `processProtectedData()` + +This guide shows both perspectives for each input type. + +## Input Types Overview + +When your iApp executes in the TEE, it can access four different types of +inputs: + +| Input Type | Visibility | Use Case | Access Method | +| --------------------- | ----------- | ------------------------ | ---------------------- | +| **Args** | Public | Configuration parameters | Command line arguments | +| **Input Files** | Public URLs | Large datasets, models | Download from URLs | +| **Requester Secrets** | Private | API keys, credentials | Environment variables | +| **Protected Data** | Encrypted | User's sensitive data | File system in TEE | + +## 1. Arguments (Args) + +**What they are:** Public parameters passed to your iApp during execution. + +**When to use:** Configuration settings, model parameters, processing options - +anything that doesn't need to be secret. + +::: danger + +Security Warning Args are **completely public** and visible on the blockchain +explorer. Never pass sensitive information through args. + +::: + +### How to Access Args + +In your iApp Generator project, args are passed as command-line arguments: + +::: code-group + +```python [Python] +import sys + +# Access args from command line +args = sys.argv[1:] # Skip first arg (script name) + +# Example: iapp run myapp --args "model=bert threshold=0.8" +if len(args) >= 2: + model_name = args[0] # "model=bert" + threshold = args[1] # "threshold=0.8" +``` + +```javascript [JavaScript] +// Access args from command line +const args = process.argv.slice(2); // Skip node and script name + +// Example: iapp run myapp --args "model=bert threshold=0.8" +if (args.length >= 2) { + const modelName = args[0]; // "model=bert" + const threshold = args[1]; // "threshold=0.8" +} +``` + +::: + +### How Users Provide Args + +Users pass args through the DataProtector `processProtectedData()` call: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// User provides args when executing your iApp +const response = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + args: 'model=sentiment-bert temperature=0.7 format=json', // Public arguments +}); +``` + +### Example Use Cases + +- Model configuration: `"model=sentiment-bert temperature=0.7"` +- Processing options: `"format=json output_size=small"` +- Analysis parameters: `"start_date=2024-01-01 end_date=2024-12-31"` + +## 2. Input Files + +**What they are:** Files downloaded from public URLs during iApp execution. + +**When to use:** Large datasets, ML models, reference files that don't contain +sensitive information. + +### How to Access Input Files + +Files are downloaded to the `IEXEC_INPUT_FILES_FOLDER` directory: + +::: code-group + +```python [Python] +import os + +# Get the input files directory +input_dir = os.environ.get('IEXEC_INPUT_FILES_FOLDER', './input') + +# List all downloaded files +for filename in os.listdir(input_dir): + file_path = os.path.join(input_dir, filename) + + # Process your file + with open(file_path, 'r') as f: + content = f.read() + print(f"Loaded file: {filename}") +``` + +```javascript [JavaScript] +const fs = require('fs'); +const path = require('path'); + +// Get the input files directory +const inputDir = process.env.IEXEC_INPUT_FILES_FOLDER || './input'; + +// List all downloaded files +fs.readdirSync(inputDir).forEach((filename) => { + const filePath = path.join(inputDir, filename); + + // Process your file + const content = fs.readFileSync(filePath, 'utf8'); + console.log(`Loaded file: ${filename}`); +}); +``` + +::: + +### How Users Provide Input Files + +Users specify input files when executing your iApp: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// User provides input files via DataProtector +const response = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', + app: '0x456def...', + inputFiles: [ + 'https://example.com/sentiment-model.pkl', + 'https://myapp.com/config.json', + ], +}); +``` + +### Example Use Cases + +- ML model files: `"https://example.com/sentiment-model.pkl"` +- Reference datasets: `"https://data.gov/reference-corpus.csv"` +- Configuration files: `"https://myapp.com/config.json"` + +### Limits and Best Practices + +- **File size**: Limited by TEE enclave memory (typically several GB max) +- **Memory constraint**: Files are loaded into enclave memory - large files may + cause out-of-memory errors +- **Format**: Any format (binary, text, compressed) +- **URLs**: Must be direct download links (not web pages) +- **Security**: Files are public - don't use for sensitive data +- **Best practice**: Keep input files under 1-2GB for reliable execution + +## 3. Requester Secrets + +**What they are:** Confidential credentials provided by the user running your +iApp. + +**When to use:** API keys, database credentials, authentication tokens that the +user needs to provide. + +### How to Access Requester Secrets + +Secrets are available as environment variables with the pattern +`IEXEC_REQUESTER_SECRET_`: + +::: code-group + +```python [Python] +import os + +# Access requester secrets by index +api_key = os.environ.get('IEXEC_REQUESTER_SECRET_1') +db_password = os.environ.get('IEXEC_REQUESTER_SECRET_2') + +if api_key: + # Use the API key for external service calls + headers = {'Authorization': f'Bearer {api_key}'} + # Make API calls... +else: + print("No API key provided") +``` + +```javascript [JavaScript] +// Access requester secrets by index +const apiKey = process.env.IEXEC_REQUESTER_SECRET_1; +const dbPassword = process.env.IEXEC_REQUESTER_SECRET_2; + +if (apiKey) { + // Use the API key for external service calls + const headers = { Authorization: `Bearer ${apiKey}` }; + // Make API calls... +} else { + console.log('No API key provided'); +} +``` + +::: + +### How Users Provide Inputs + +Users provide all inputs when executing your iApp via DataProtector: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// Example: User executes your iApp with all input types +const processProtectedDataResponse = + await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', // Protected data address + app: '0x456def...', // Your iApp address + args: 'model=bert threshold=0.8', // Public arguments + inputFiles: [ + // Public input files + 'https://example.com/model.pkl', + 'https://example.com/config.json', + ], + secrets: { + // Requester secrets + 1: 'sk-1234567890abcdef', // API key + 2: 'mydbpassword123', // DB password + }, + }); +``` + +## 4. Protected Data + +**What it is:** Encrypted user data that's only decrypted inside your TEE +environment. + +**When to use:** Processing user's sensitive information like personal data, +financial records, health data. + +### How to Access Protected Data + +Protected data is available in the `IEXEC_IN` directory as decrypted files: + +::: code-group + +```python [Python] +import os +import json + +# Get the input directory +iexec_in = os.environ['IEXEC_IN'] + +# Protected data is decrypted and available as files +try: + # For single protected data + with open(f"{iexec_in}/protectedData", 'r') as f: + data = json.load(f) + + # Access user's sensitive data + user_email = data.get('email') + user_preferences = data.get('preferences') + + print(f"Processing data for user: {user_email}") + +except FileNotFoundError: + print("No protected data provided") +``` + +```javascript [JavaScript] +const fs = require('fs'); +const path = require('path'); + +// Get the input directory +const iexecIn = process.env.IEXEC_IN; + +try { + // Protected data is decrypted and available as files + const dataPath = path.join(iexecIn, 'protectedData'); + const data = JSON.parse(fs.readFileSync(dataPath, 'utf8')); + + // Access user's sensitive data + const userEmail = data.email; + const userPreferences = data.preferences; + + console.log(`Processing data for user: ${userEmail}`); +} catch (error) { + console.log('No protected data provided'); +} +``` + +::: + +### How Users Provide Protected Data + +Users specify the protected data address when executing your iApp: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// User provides their protected data for processing +const response = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', // Address of their protected data + app: '0x456def...', // Your iApp address +}); +``` + +### Working with Multiple Protected Datasets + +When multiple datasets are provided, they're available as separate files: + +::: code-group + +```python [Python] +import os + +iexec_in = os.environ['IEXEC_IN'] + +# List all available protected datasets +for filename in os.listdir(iexec_in): + if filename.startswith('dataset_'): + with open(f"{iexec_in}/{filename}", 'r') as f: + dataset = json.load(f) + print(f"Processing dataset: {filename}") +``` + +::: + +### Memory Limitations + +::: warning + +TEE Memory Constraints Protected data is decrypted and loaded into TEE enclave +memory. Very large datasets (>1-2GB) may cause out-of-memory errors. Consider +data preprocessing or chunking for large datasets. + +::: + +## Creating Outputs + +Your iApp must generate outputs in the `IEXEC_OUT` directory. **Every iApp must +create a `computed.json` file** with metadata about the computation. + +### Basic Output Structure + +::: code-group + +```python [Python] +import os +import json + +# Get output directory +iexec_out = os.environ['IEXEC_OUT'] + +# Create your result file +result_data = { + "analysis": "positive sentiment", + "confidence": 0.92, + "processed_at": "2024-01-15T10:30:00Z" +} + +# Save main result +with open(f"{iexec_out}/result.json", 'w') as f: + json.dump(result_data, f) + +# REQUIRED: Create computed.json metadata +computed_metadata = { + "deterministic-output-path": f"{iexec_out}/result.json", + "execution-timestamp": "2024-01-15T10:30:00Z", + "app-version": "1.0.0" +} + +with open(f"{iexec_out}/computed.json", 'w') as f: + json.dump(computed_metadata, f) +``` + +```javascript [JavaScript] +const fs = require('fs'); +const path = require('path'); + +// Get output directory +const iexecOut = process.env.IEXEC_OUT; + +// Create your result file +const resultData = { + analysis: 'positive sentiment', + confidence: 0.92, + processed_at: '2024-01-15T10:30:00Z', +}; + +// Save main result +fs.writeFileSync( + path.join(iexecOut, 'result.json'), + JSON.stringify(resultData, null, 2) +); + +// REQUIRED: Create computed.json metadata +const computedMetadata = { + 'deterministic-output-path': path.join(iexecOut, 'result.json'), + 'execution-timestamp': '2024-01-15T10:30:00Z', + 'app-version': '1.0.0', +}; + +fs.writeFileSync( + path.join(iexecOut, 'computed.json'), + JSON.stringify(computedMetadata, null, 2) +); +``` + +::: + +### Output Best Practices + +1. **Always create `computed.json`** - This is mandatory +2. **Use descriptive filenames** - `analysis_result.json` vs `output.txt` +3. **Include metadata** - Timestamps, versions, parameters used +4. **Structure your data** - Use JSON for structured results +5. **Keep files reasonable** - Large outputs increase retrieval time and may hit + memory limits +6. **Memory awareness** - TEE enclave memory is limited, avoid generating + multi-GB outputs + +### Example: Multi-file Output + +```python +import os +import json + +iexec_out = os.environ['IEXEC_OUT'] + +# Create multiple output files +summary = {"total_processed": 1000, "success_rate": 0.95} +with open(f"{iexec_out}/summary.json", 'w') as f: + json.dump(summary, f) + +# Create a detailed report +with open(f"{iexec_out}/detailed_report.txt", 'w') as f: + f.write("Detailed analysis results...\n") + +# Create visualization data +chart_data = {"labels": ["A", "B", "C"], "values": [10, 20, 30]} +with open(f"{iexec_out}/chart_data.json", 'w') as f: + json.dump(chart_data, f) + +# Required metadata file +computed = { + "deterministic-output-path": f"{iexec_out}/summary.json", + "additional-files": [ + f"{iexec_out}/detailed_report.txt", + f"{iexec_out}/chart_data.json" + ] +} +with open(f"{iexec_out}/computed.json", 'w') as f: + json.dump(computed, f) +``` + +## Testing Inputs Locally + +Use iApp Generator to test different input types: + +```bash +# Test with different input types +iapp test --args "model=bert threshold=0.8" # Test with arguments +iapp test --inputFiles "https://example.com/data.json" # Test with input files +iapp test --secrets "key1=value1,key2=value2" # Test with secrets + +# Mock protected data for testing +iapp mock protectedData # Generate sample protected data + +# Test your iApp locally with mocked protected data +iapp test --protectedData "mock_name" +``` + +## Common Patterns + +### ๐Ÿ” **Data Analysis iApp** + +**User execution (DataProtector):** + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// User runs your data analysis iApp +const response = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', // Their business data + app: '0x456def...', // Your analysis iApp + args: 'analysis_type=sentiment period=monthly', + secrets: { 1: 'api-key-for-external-service' }, +}); +``` + +**Your iApp code (Python):** + +```python +# Access inputs in your iApp +args = sys.argv[1:] # Processing parameters +api_key = os.environ.get('IEXEC_REQUESTER_SECRET_1') # User's API access +protected_data = load_protected_data() # User's sensitive data + +# Process and output results +results = analyze_data(protected_data, args, api_key) +save_results(results) +``` + +### ๐Ÿค– **AI Model iApp** + +**User execution (DataProtector):** + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// User runs your AI model with their data +const response = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', // Their personal data + app: '0x456def...', // Your AI model iApp + inputFiles: ['https://example.com/model-weights.pkl'], + args: 'model_type=classification confidence_threshold=0.8', +}); +``` + +**Your iApp code (Python):** + +```python +# Load model from input files +model = load_model_from_inputs() + +# Get user data to process +user_data = load_protected_data() + +# Run inference +predictions = model.predict(user_data) + +# Return encrypted results +save_encrypted_results(predictions) +``` + +### ๐Ÿ“Š **Report Generator iApp** + +**User execution (DataProtector):** + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// User generates a report from their business data +const response = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', // Their business data + app: '0x456def...', // Your report generator iApp + args: 'report_type=quarterly format=pdf include_charts=true', + inputFiles: ['https://example.com/company-template.xlsx'], +}); +``` + +**Your iApp code (Python):** + +```python +# Get configuration from args +report_type = get_arg('type', default='summary') + +# Access user's business data +business_data = load_protected_data() + +# Generate report +report = generate_report(business_data, report_type) +save_report(report) +``` + +## Output Retrieval + +Once your iApp completes execution, users can retrieve and decrypt the results: + +โ†’ **Learn how users get results**: Check our +[How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results) +guide for the complete user workflow. + +## What's Next? + +**You now understand all input types and output requirements!** + +Continue building with these guides: + +- **[App Access Control and Pricing](/build_iapp/guides/orders)** - Control who + can use your iApp +- **[Debugging Your iApp](/build_iapp/guides/debugging-your-iapp)** - + Troubleshoot execution issues +- **[How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results)** - + User-side result handling + +### Technical Deep Dive + +- **[SDK Deep Dive](/deep_dive/sdk)** - Advanced SDK concepts +- **[Application I/O Protocol Docs](https://protocol.docs.iex.ec/for-developers/application-io)** - + Low-level protocol details diff --git a/src/build-iapp/guides/manage-iapp.md b/src/build-iapp/guides/manage-iapp.md new file mode 100644 index 00000000..18b36ca3 --- /dev/null +++ b/src/build-iapp/guides/manage-iapp.md @@ -0,0 +1,347 @@ +--- +title: App Access Control and Pricing +description: Control who can use your iApp and set pricing with app orders +--- + +# ๐Ÿ’ฐ App Access Control and Pricing + +**Orders control who can use your iApp and under what conditions.** Once your +iApp is deployed with iApp Generator, you need to create app orders to make it +accessible to users and define your governance rules. + +Think of orders as **usage contracts** - they define pricing, access +restrictions, and execution conditions for your application. + +## What is an Order? + +An **app order** is a signed contract that defines the usage conditions for your +iApp: + +- **Price per execution** (in nRLC) +- **Number of authorized uses** +- **Access restrictions** (specific users, workerpools) +- **TEE configuration** (for confidential applications) + +::: tip + +Currently, order management is not yet available in iApp Generator. This guide +shows you how to use the iExec SDK CLI to create and manage your app orders. + +For complete SDK documentation, check the +[iExec SDK GitHub repository](https://github.com/iExecBlockchainComputing/iexec-sdk). + +::: + +## How Orders Work + +Here's the simplified process: + +1. **You create an app order** with your conditions (price, restrictions, etc.) +2. **You sign the order** with your wallet +3. **You publish the order** on the iExec marketplace +4. **Users can discover** and execute your iApp according to your conditions +5. **You automatically receive** payment in RLC for each execution + +``` +Deployed iApp + Signed App Order = Application accessible on iExec +``` + +## App Order Example + +Here's an example app order for a sentiment analysis iApp: + +```json +{ + "app": "0x123abc...", // Your iApp address + "appprice": "1000000000", // 1 RLC per execution + "volume": "100", // 100 authorized uses + "tag": "0x0000000000000000000000000000000000000000000000000000000000000003", // TEE required + "datasetrestrict": "0x0000000000000000000000000000000000000000", + "workerpoolrestrict": "0x0000000000000000000000000000000000000000", + "requesterrestrict": "0x0000000000000000000000000000000000000000" +} +``` + +## Creating an App Order from an iApp Generator Project + +### Step 1: Install the iExec SDK + +Since iApp Generator doesn't handle orders yet, you need to use the iExec SDK +CLI: + +::: code-group + +```bash [npm] +npm install -g iexec +``` + +```bash [yarn] +yarn global add iexec +``` + +::: + +Verify the installation: + +```bash +iexec --version +iexec --help +``` + +### Step 2: Configure your iExec Project + +In your iApp Generator project folder, initialize the iExec configuration: + +```bash +# In your iApp Generator project folder +iexec init --skip-wallet +``` + +This creates the necessary configuration files: + +- `iexec.json` - Project configuration +- `chain.json` - Blockchain configuration + +### Step 3: Configure your Wallet + +If you don't have an iExec wallet yet: + +```bash +iexec wallet create +``` + +Or import an existing wallet: + +```bash +iexec wallet import +``` + +::: tip iApp Generator Users + +If you used iApp Generator, you already have an `iexecconfig.json` file with a +generated private key. You can use this existing private key to initialize your +wallet: + +```bash +# Extract the private key from your iexecconfig.json +iexec wallet import +``` + +::: + +Check your wallet: + +```bash +iexec wallet show +``` + +### Step 4: Create the App Order + +Initialize the app order: + +```bash +iexec order init --app +``` + +This adds an `apporder` section to your `iexec.json`. Edit the parameters +according to your needs: + +```json +{ + "apporder": { + "app": "0xYourAppAddress", + "appprice": "1000000000", + "volume": "100", + "tag": "0x0000000000000000000000000000000000000000000000000000000000000003", + "datasetrestrict": "0x0000000000000000000000000000000000000000", + "workerpoolrestrict": "0x0000000000000000000000000000000000000000", + "requesterrestrict": "0x0000000000000000000000000000000000000000" + } +} +``` + +### Step 5: Sign and Publish the Order + +Sign your app order with your wallet: + +```bash +iexec order sign --app +``` + +Publish the order on the marketplace: + +```bash +iexec order publish --app +``` + +Your iApp is now accessible according to the conditions you defined! + +## App Order Parameters + +Here's the detailed description of each parameter: + +### `app` + +**Description:** Ethereum address of your deployed iApp + +**Example:** `"0x123abc456def..."` + +### `appprice` + +**Description:** Price to charge per execution (in nano RLC - nRLC) + +**Common values:** + +- `"0"` - Free +- `"1000000000"` - 1 RLC per execution +- `"500000000"` - 0.5 RLC per execution + +::: tip + +1 RLC = 1,000,000,000 nRLC (10^9) + +::: + +### `volume` + +**Description:** Number of authorized executions (decrements with each use) + +**Examples:** + +- `"1"` - Single use +- `"100"` - Limited campaign +- `"10000"` - Virtually unlimited usage + +### `tag` + +**Description:** Specifies the required execution environment + +**Supported values:** + +| Value | Description | +| -------------------------------------------------------------------- | -------------------- | +| `0x0000000000000000000000000000000000000000000000000000000000000000` | Standard execution | +| `0x0000000000000000000000000000000000000000000000000000000000000003` | TEE required (Scone) | + +### Access Restrictions + +All restrictions use `0x0000000000000000000000000000000000000000` to indicate +"no restriction". + +#### `datasetrestrict` + +**Description:** Restrict usage to a specific dataset + +**Typical usage:** `"0x0000000000000000000000000000000000000000"` (no +restriction) + +#### `workerpoolrestrict` + +**Description:** Restrict execution to a specific workerpool + +**Example:** `"prod-v8-bellecour.main.pools.iexec.eth"` for the main workerpool + +#### `requesterrestrict` + +**Description:** Restrict usage to a specific user + +**Typical usage:** `"0x0000000000000000000000000000000000000000"` (open to all) + +## Managing Orders + +### View Published Orders + +Check active orders for your app: + +```bash +iexec orderbook app +``` + +### Modify an Order + +To change conditions, create a new order with new parameters. + +### Cancel an Order + +Remove an order from the marketplace: + +```bash +iexec order unpublish --app +``` + +Completely invalidate an order: + +```bash +iexec order cancel --app +``` + +## Common Use Cases + +### ๐Ÿ†“ **Free and Open App** + +```json +{ + "appprice": "0", + "volume": "10000", + "tag": "0x0000000000000000000000000000000000000000000000000000000000000000" +} +``` + +### ๐Ÿ’ฐ **Paid App (1 RLC per use)** + +```json +{ + "appprice": "1000000000", + "volume": "1000", + "tag": "0x0000000000000000000000000000000000000000000000000000000000000003" +} +``` + +### ๐Ÿ”’ **Private App (specific user only)** + +```json +{ + "appprice": "0", + "volume": "50", + "requesterrestrict": "0xSpecificUserAddress" +} +``` + +### ๐Ÿ›ก๏ธ **Confidential App (TEE required)** + +```json +{ + "appprice": "2000000000", + "volume": "500", + "tag": "0x0000000000000000000000000000000000000000000000000000000000000003" +} +``` + +## What's Next? + +**Your iApp is now accessible with custom conditions!** + +Next steps: + +- **Monitor executions**: Track usage with `iexec task show` +- **Adjust pricing**: Create new orders based on demand +- **Manage revenue**: Check your earnings with `iexec account show` + +### Explore More iExec Guides + +- **[Input and Outputs](/build_iapp/guides/inputs-and-outputs)** - Handle data + in your iApps +- **[Getting and Decrypting Results](/build_iapp/guides/how-to-get-and-decrypt-results)** - + Process execution results +- **[Debugging Your iApp](/build_iapp/guides/debugging-your-iapp)** - + Troubleshoot your applications +- **[Using TDX (Experimental)](/build_iapp/guides/using-tdx-experimental)** - + Advanced TEE features + +### Technical Deep Dive + +- **[SDK Deep Dive](/deep_dive/sdk)** - Advanced SDK concepts and usage +- **[iExec SDK Documentation](https://github.com/iExecBlockchainComputing/iexec-sdk)** - + Complete CLI reference +- **[Official Orders Documentation](https://protocol.docs.iex.ec/for-developers/advanced/manage-your-apporders)** - + Protocol-level order management diff --git a/src/build-iapp/guides/manage-iapps.md b/src/build-iapp/guides/manage-iapps.md deleted file mode 100644 index 7eab360f..00000000 --- a/src/build-iapp/guides/manage-iapps.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Manage iApps -description: Manage Your iApps ---- - -# Manage Your iApps - -This page is under development. - - diff --git a/src/build-iapp/guides/orders.md b/src/build-iapp/guides/orders.md deleted file mode 100644 index 43648154..00000000 --- a/src/build-iapp/guides/orders.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Orders (how they work, how to manage them) -description: How orders work and how to manage them ---- - -# Orders (how they work, how to manage them) - -This page is under development. - - diff --git a/src/build-iapp/guides/other-emerging-trends.md b/src/build-iapp/guides/other-emerging-trends.md deleted file mode 100644 index 015175a7..00000000 --- a/src/build-iapp/guides/other-emerging-trends.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Other Emerging Trends (to be added) -description: Other emerging trends to be added ---- - -# Other Emerging Trends (to be added) - -This page is under development. - - diff --git a/src/build-iapp/guides/using-tdx-experimental.md b/src/build-iapp/guides/using-tdx-experimental.md index 5a183e4d..64774d37 100644 --- a/src/build-iapp/guides/using-tdx-experimental.md +++ b/src/build-iapp/guides/using-tdx-experimental.md @@ -1,10 +1,192 @@ --- -title: Using TDX (Trusted Execution) [EXPERIMENTAL] -description: Using TDX (Trusted Execution) [EXPERIMENTAL] +title: Using TDX (Experimental) +description: + Enable Intel TDX for enhanced TEE security in iApps - experimental feature --- -# Using TDX (Trusted Execution) [EXPERIMENTAL] +# ๐Ÿ›ก๏ธ Using TDX (Experimental) -This page is under development. +:::danger โš ๏ธ EXPERIMENTAL FEATURE - +**TDX support is currently experimental and should NOT be used in production.** +This feature is provided for testing and development purposes only. Expect +instabilities, limited compatibility, and potential outages. + +::: + +**Intel TDX (Trust Domain Extensions) is the next generation of TEE +technology.** This guide shows you how to enable TDX in your iApps and +understand the differences from the default SGX implementation. + +## What is TDX? + +**TDX (Trust Domain Extensions)** is Intel's newer confidential computing +technology, different from the default SGX implementation. + +### SGX vs TDX Differences + +**SGX (Current Default)**: + +- โœ… **Production ready** and stable +- โœ… **Widely supported** by iExec workers +- โŒ **Memory limitations** in TEE environment + +**TDX (Experimental)**: + +- โœ… **Potentially better** for memory-intensive workloads +- โŒ **Experimental** and unstable +- โŒ **Limited worker availability** +- โŒ **Not production ready** + +| Feature | Intel SGX | Intel TDX | +| ------------------------ | ----------------------------------------------------------------------------------- | -------------------------------------------- | +| Release Year | 2015 | 2023 | +| Enclave Scope | Application level | Virtual machine level | +| Code Adaptation Required | Yes - needs redesign of app's logic | No - supports lift-and-shift of full systems | +| Memory Size | Limited | Extensive (multi-GB+) | +| Integration Complexity | Higher (more dev work) | Lower (VM legacy code) | +| Best Fit For | Lightweight, high-assurance modules (e.g. wallets, crypto key ops, small AI models) | Heavier AI workloads, legacy apps, databases | + +## Enabling TDX in iApp Generator + +### Environment Variable Method + +**Enable TDX for deployment and execution**: + +```bash +# Set the experimental flag +export EXPERIMENTAL_TDX_APP=true + +# Deploy and run with TDX +iapp deploy +iapp run +``` + +:::warning Environment Variable Declaration + +The syntax for setting environment variables differs between operating systems: + +- **Mac/Linux**: `export EXPERIMENTAL_TDX_APP=true` +- **Windows**: `set EXPERIMENTAL_TDX_APP=true` + +::: + +### Per-Command Method + +**Enable TDX for specific commands**: + +```bash +# Deploy TDX-enabled iApp +EXPERIMENTAL_TDX_APP=true iapp deploy + +# Run with TDX +EXPERIMENTAL_TDX_APP=true iapp run + +# Debug TDX execution +EXPERIMENTAL_TDX_APP=true iapp debug +``` + +### Verification + +**Check if TDX is enabled**: + +```bash +# Your deployed iApp should show TDX-related tags +iexec app show +``` + +### + +โš ๏ธ **To use** the iExec DataProtector SDK with TDX support, you must configure +the SDK with the right SMS endpoint. + +```jsx +const dataProtector = new IExecDataProtector(web3Provider, { + iexecOptions: { + smsURL: 'https://sms.labs.iex.ec', + }, +}); +``` + +โš ๏ธ**You need** to change the default worker pool in your protected Data +declaration + +```jsx +await dataProtector.core.processProtectedData({ + protectedData: protectedData.address, + workerpool: 'tdx-labs.pools.iexec.eth', + app: '0x1919ceb0c6e60f3B497936308B58F9a6aDf071eC', +}); +``` + +## Protected Data Compatibility + +:::warning Protected Data Requirements + +**TDX iApps may require TDX-compatible protected data.** Check compatibility +before using protected data with TDX iApps. + +::: + +**Important**: The exact process for creating TDX-compatible protected data may +differ from standard protected data creation. Consult the latest DataProtector +documentation for TDX-specific requirements. + +## Development Workflow + +### 1. **Local Testing** + +```bash +# Test locally (same as regular iApps) +iapp test --protectedData "mock_name" + +# TDX only affects remote deployment/execution +``` + +### 2. **Deployment** + +```bash +# Deploy TDX iApp +EXPERIMENTAL_TDX_APP=true iapp deploy +``` + +### 3. **Execution** + +```bash +# Run with TDX +EXPERIMENTAL_TDX_APP=true iapp run +``` + +## Current Limitations + +:::danger Production Warnings + +- **๐Ÿšซ NOT for production use** +- **๐Ÿšซ Limited worker availability** +- **๐Ÿšซ Unstable execution** environment +- **๐Ÿšซ Breaking changes** without notice + +::: + +## When to Use TDX + +**Consider TDX only for**: + +- ๐Ÿ”ฌ **Research/development** purposes +- ๐Ÿงช **Testing future capabilities** + +**Use SGX for**: + +- ๐Ÿš€ **All production applications** +- โšก **Reliable execution** requirements + +## What's Next? + +**For production applications, use the standard SGX guides**: + +- **[Debugging Your iApp](/build_iapp/guides/debugging-your-iapp)** - + Troubleshoot execution issues +- **[Inputs and Outputs](/build_iapp/guides/inputs-and-outputs)** - Handle data + in TEE environment +- **[App Access Control and Pricing](/build_iapp/guides/orders)** - Deploy + production-ready iApps diff --git a/src/build-iapp/iapp-generator.md b/src/build-iapp/iapp-generator.md index 36767edc..03b6bcb6 100644 --- a/src/build-iapp/iapp-generator.md +++ b/src/build-iapp/iapp-generator.md @@ -1,10 +1,111 @@ ---- -title: iApp Generator -description: iApp Generator ---- - # ๐Ÿค– iApp Generator -This page is under development. +**Build privacy-first applications that run in secure TEE environments.** iApp +Generator is your complete toolkit for creating, testing, and deploying +confidential iApps on the iExec network. + +Transform your ideas into production-ready privacy-preserving applications in +minutes, not months. + +## What is iApp Generator? + +**iApp Generator** is a CLI tool that simplifies building **iExec Applications +(iApps)** - applications that run inside **Trusted Execution Environments +(TEE)** for maximum privacy and security. + +### What You Can Build + +- **AI models** that process sensitive data privately +- **Data analysis** tools that protect user information +- **Custom algorithms** with confidential inputs and outputs +- **Privacy-preserving services** for Web3 applications + +### What iApp Generator Provides + +- โœ… **Project scaffolding** - Complete iApp structure ready to deploy +- โœ… **Local testing** - Debug and iterate quickly in simulation mode +- โœ… **One-click deployment** - Deploy to TEE workers with a single command +- โœ… **Input/output handling** - Seamless integration with protected data + +## Quick Start Path + +### 1. **Learn the Concepts** + +Start here to understand what iApps are and how they work: + +- **[What Is an iApp?](/build_iapp/iapp-generator/what-is-iapp)** - Core + concepts and TEE overview +- **[Getting Started](/build_iapp/iapp-generator/getting-started)** - Your first + iApp in 15 minutes +- **[Building Your iApp](/build_iapp/iapp-generator/building-your-iexec-app)** - + Complete development guide + +### 2. **Master the Development Workflow** + +Once you've built your first iApp, level up with these practical guides: + +- **[Inputs and Outputs](/build_iapp/guides/inputs-and-outputs)** - Handle data + flow in TEE environment +- **[Debugging Your iApp](/build_iapp/guides/debugging-your-iapp)** - + Troubleshoot execution issues +- **[App Access Control and Pricing](/build_iapp/guides/orders)** - Control who + can use your iApp +- **[How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results)** - + Retrieve and use outputs + +### 3. **Explore Advanced Features** + +Ready for production? Dive into specialized topics: + +- **[Using TDX (Experimental)](/build_iapp/guides/using-tdx-experimental)** - + Next-gen TEE technology +- **[Complete Guides Overview](/build_iapp/guides)** - All development guides in + one place + +## Why Choose iApp Generator? + +### ๐Ÿ”’ **Privacy by Design** + +Your applications run in hardware-secured enclaves where even the infrastructure +provider can't access your data or code. + +### โšก **Developer-Friendly** + +Focus on your application logic while iApp Generator handles the complex TEE +setup, deployment, and execution infrastructure. + +### ๐ŸŒ **Decentralized Infrastructure** + +Deploy on a global network of TEE-enabled workers without managing servers or +cloud infrastructure. + +### ๐Ÿ”ง **Complete Toolkit** + +From local development to production deployment, everything you need is included +in one CLI tool. + +## Ready to Build? + +**Start with the basics** and work your way up to advanced privacy-preserving +applications: + +::: tip Quick Path + +1. **[Getting Started](/build_iapp/iapp-generator/getting-started)** - Build + your first iApp (15 minutes) +2. **[Inputs and Outputs](/build_iapp/guides/inputs-and-outputs)** - Handle data + properly +3. **[Debugging](/build_iapp/guides/debugging-your-iapp)** - Fix issues quickly +4. **[App Access Control](/build_iapp/guides/orders)** - Go to production ::: + +### Need Help? + +- **[Complete Guides](/build_iapp/guides)** - All development guides +- **[iExec Discord](https://discord.com/invite/pbt9m98wnU)** - Community support +- **[Protocol Documentation](https://protocol.docs.iex.ec)** - Technical deep + dive + +--- - +**Ready to revolutionize privacy in computing?** Your first privacy-preserving +application is just a few commands away! ๐Ÿš€ diff --git a/src/build-iapp/iapp-generator/advanced-creation.md b/src/build-iapp/iapp-generator/advanced-creation.md index 95d5d9d6..e69de29b 100644 --- a/src/build-iapp/iapp-generator/advanced-creation.md +++ b/src/build-iapp/iapp-generator/advanced-creation.md @@ -1,10 +0,0 @@ ---- -title: Advanced Creation -description: Advanced Creation for iApps ---- - -# Advanced Creation - -This page is under development. - - diff --git a/src/build-iapp/iapp-generator/building-your-iexec-app.md b/src/build-iapp/iapp-generator/building-your-iexec-app.md index d1fd8e6d..e6390790 100644 --- a/src/build-iapp/iapp-generator/building-your-iexec-app.md +++ b/src/build-iapp/iapp-generator/building-your-iexec-app.md @@ -41,10 +41,11 @@ You'll set up: - **Protected Data** โ€“ Encrypted data accessible only inside the TEE. - **App Secret** โ€“ Immutable secret provisioned by the iApp owner. -::: warning ๐Ÿ’ก The Secret Management Service (SMS) securely stores application +::: warning ๐Ÿ’ก -developer secrets. Once set, the App Secret is immutable and cannot be updated. -Use with caution. +The Secret Management Service (SMS) securely stores application developer +secrets. Once set, the App Secret is immutable and cannot be updated. Use with +caution. For more information on **App Secrets**, refer to [Access confidential assets from your app](https://protocol.docs.iex.ec/for-developers/confidential-computing/access-confidential-assets) diff --git a/src/build-iapp/iapp-generator/getting-started.md b/src/build-iapp/iapp-generator/getting-started.md index 0457ac5e..2458db91 100644 --- a/src/build-iapp/iapp-generator/getting-started.md +++ b/src/build-iapp/iapp-generator/getting-started.md @@ -6,7 +6,7 @@ Before using the iApp Generator, make sure you have: \- [**Node.js**](https://nodejs.org/en/) version 20 or higher -\- **Docker** +\- **Docker / Docker hub account** \- **Docker Buildx** _(for macOS users, check AMD64 compatibility)_ diff --git a/src/build-iapp/iapp-generator/protocol-level-guides.md b/src/build-iapp/iapp-generator/protocol-level-guides.md index 5ae81af9..e69de29b 100644 --- a/src/build-iapp/iapp-generator/protocol-level-guides.md +++ b/src/build-iapp/iapp-generator/protocol-level-guides.md @@ -1,10 +0,0 @@ ---- -title: Protocol-Level Guides -description: Protocol-Level Guides for iApp development ---- - -# ๐Ÿ”ง Protocol-Level Guides - -This page is under development. - - diff --git a/src/build-iapp/iapp-generator/references.md b/src/build-iapp/iapp-generator/references.md index 48d1afa2..e69de29b 100644 --- a/src/build-iapp/iapp-generator/references.md +++ b/src/build-iapp/iapp-generator/references.md @@ -1,10 +0,0 @@ ---- -title: References -description: References for iApp development ---- - -# References - -This page is under development. - - diff --git a/src/build-iapp/what-is-iapp.md b/src/build-iapp/what-is-iapp.md index 95ad6c61..ff132374 100644 --- a/src/build-iapp/what-is-iapp.md +++ b/src/build-iapp/what-is-iapp.md @@ -1,10 +1,210 @@ --- -title: What is an iApp ? -description: Explain what is an iApp in iExec protocol ? +title: What Is an iApp? +description: Privacy-first applications that run on decentralized infrastructure --- -# What is an iApp ? +# ๐Ÿš€ What Is an iApp? -This page is under development. +An iExec Application (iApp) is your regular application code (Python script, AI +model, data processor) that can securely process protected data (created by +[DataProtector](/manage-data/dataProtector)) inside a confidential computing +environment called TEE (a Trusted Execution Environment). - +## Why iApps Matter? + +iApps let you process sensitive data while keeping it private and secure. + +Imagine you want to build: + +
+
+
+ ๐Ÿค– + An AI that analyzes personal health data +
+
+ ๐Ÿ“ง + An email tool that needs access to contact lists +
+
+ ๐Ÿ’ฐ + A financial advisor that processes bank statements +
+
+ ๐Ÿ›ก๏ธ + A content filter that reads private messages +
+
+
+ +Users have this data, but they won't give it to your regular app. **With iApps, +they will.** + +## Key Concepts + +
+
+ โœ… +

True Privacy: Users never expose their raw data. Your app processes it privately inside secure enclaves.

+
+
+ โœ… +

Trusted Execution: iExec ensures that your code runs inside a Trusted Execution Environment (TEE), which guarantees that only the specified Docker image is executed in a secure and isolated environment.

+
+
+ โœ… +

Decentralized Infrastructure: No single point of failure. Your app runs across a distributed network of workers.

+
+
+ โœ… +

Zero Trust Architecture: User data is protected by hardware-based TEEs, which keep data confidential and inaccessible to the host, cloud provider, or operating system during execution.

+
+
+ +## How It Works + +Your code runs in a Trusted Execution Environment (TEE), a secure area inside +specific processors (Intel SGX/TDX chipset). Everything that happens there stays +private and protected, even from the operating system. + +An authorized user can trigger an iApp that processes someone's protected data +inside this private environment. The data is used, but never exposed, not even +to the person running the app. + +
+
+
+ 1 + User provides private data +
+
+ 2 + Data is protected with DataProtector +
+
+ 3 + Protected data transferred to Trusted Execution Environment (TEE) +
+
+ 4 + Your iApp runs inside TEE and processes protected data +
+
+ 5 + Confidential computing performed while maintaining privacy +
+
+
+ +
+

Nobody sees the raw data except your code running inside the secure enclave.

+
+ +Your iApp can send emails, update contracts, make transactions, trigger +notifications - anything your code needs to do with the protected data. This +isn't about trust - it's about **mathematical guarantees** that privacy is +preserved. + +## Use Cases + +
+
+
+ ๐Ÿ“ง +

Private Communication

+
+

Users send emails, notifications, or messages using their protected contact lists without exposing recipient information.

+
+ +
+
+ ๐Ÿ”ฎ +

Trustworthy Oracles

+
+

Users contribute real data to oracles while keeping their private information confidential.

+
+ +
+
+ ๐Ÿค– +

Personal AI Assistants

+
+

Users let AI models perform actions based on their private data - trading, scheduling, recommendations...

+
+ +
+
+ โšก +

Automated Actions

+
+

Users let AI models perform actions based on their private data - trading, scheduling, recommendations...

+
+
+ +## โ“ Frequently Asked Questions + +::: details ๐Ÿ“ฆ What can I build with iApps? + +Anything that runs in Docker! AI models, data processing scripts, web scrapers, +image processing, financial calculations, etc. If it runs in a container, it can +be an iApp. + +::: + +::: details โšกHow fast are iApps? + +Initial task scheduling takes a few seconds (depending on the resources the +worker download, congestion etc), then your code runs at normal speed depending +on complexity. + +::: + +::: details ๐Ÿ›ก๏ธ Are iApps really secure? + +Yes! Code runs in Intel SGX or TDX secure enclaves. Even the worker running your +iApp can't see what's happening inside the enclave. + +::: + +::: details ๐Ÿš€ How do I deploy my first iApp? + +Try our [Hello World](/overview/helloWorld) for a quick start, or check the +[iApp Generator](/build-iapp/iapp-generator) section for detailed instructions. + +::: + +::: details ๐Ÿ”ง What programming languages are supported? + +iApps can be built in any language that runs in Docker (Python, JavaScript, R, +Java, Go, etc.). However, **iApp Generator** currently supports only Python and +Node.js for simplified development. + +::: + +## Next Steps + +
+ +
+
+
๐Ÿ“š
+
+ Learn More - iApp Generator: + Complete DataProtector Documentation +
+
+
+
๐Ÿš€
+
+ Getting Started - deploy your first iApp: + DataProtector Quick Start Guide +
+
+
+ +
+ +--- + +**TL;DR**: iApps = Your code + Secure execution + User privacy + Verifiable +results. Cloud computing, but nobody can spy on your stuff. ๐Ÿ”’