diff --git a/.gitignore b/.gitignore index 4ba87273..f8a2fd0e 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ node_modules auto-imports.d.ts components.d.ts +.cursor #mac .DS_Store diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 89cd94f5..865786b5 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -77,7 +77,7 @@ export default defineConfig({ // https://vitepress.dev/reference/default-theme-config nav: [ { text: 'Home', link: '/' }, - { text: 'Overview', link: '/overview/what-we-do' }, + { text: 'Overview', link: '/overview/speedrun-iexec' }, { text: 'Protect Data', link: '/manage_data/guides' }, { text: 'Build iApp', link: '/build_iapp/iapp-generator/what-is-iapp' }, { text: 'Use iApp', link: '/use_iapp/introduction' }, diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index cc4605ef..eff456fb 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -6,7 +6,10 @@ export function getSidebar() { { text: 'OVERVIEW', items: [ - { text: '💡  What We Do', link: '/overview/what-we-do' }, + { + text: '⚡  Speedrun iExec', + link: '/overview/speedrun-iexec', + }, { text: '👋   Hello World', link: '/overview/helloWorld', @@ -358,39 +361,28 @@ export function getSidebar() { }, { text: '📖  Guides', + link: '/build_iapp/guides', collapsed: true, items: [ { - text: 'Manage Your iApps', - link: '/build_iapp/iapp-generator/manage-iapps', - }, - { - text: 'Orders (how they work, how to manage them)', + text: 'App Access Control and Pricing', link: '/build_iapp/guides/orders', }, { - text: 'Inputs and Outputs (types, differences, formats)', + text: 'Inputs and Outputs', link: '/build_iapp/guides/inputs-and-outputs', }, { text: 'Debugging Your iApp', link: '/build_iapp/guides/debugging-your-iapp', }, - { - text: 'Using TDX (Trusted Execution) [EXPERIMENTAL]', - link: '/build_iapp/guides/using-tdx-experimental', - }, { text: 'How to Get and Decrypt Results', link: '/build_iapp/guides/how-to-get-and-decrypt-results', }, { - text: 'AI Frameworks', - link: '/build_iapp/iapp-generator/ai-frameworks', - }, - { - text: 'Other Emerging Trends', - link: '/build_iapp/guides/other-emerging-trends', + text: 'Using TDX (Experimental)', + link: '/build_iapp/guides/using-tdx-experimental', }, ], }, @@ -426,13 +418,9 @@ export function getSidebar() { { text: 'USE AN iAPP', items: [ - { - text: '📝  Introduction', - link: '/use_iapp/introduction', - }, { text: '🚀  Getting Started', - link: '/use_iapp/getting-started', + link: '/use_iapp/introduction', }, { text: '📖  Guides', diff --git a/build_iapp/guides.md b/build_iapp/guides.md new file mode 100644 index 00000000..52b34719 --- /dev/null +++ b/build_iapp/guides.md @@ -0,0 +1,156 @@ +--- +title: iApp Building Guides +description: + Step-by-step guides for building, deploying, and managing your privacy-first + iApps +--- + +# 📖 iApp Building Guides + +**Master iApp development from code to production** with these comprehensive +step-by-step guides. Each guide focuses on a specific aspect of building +privacy-preserving applications with iExec. + +## Essential Guides + +### 💰 [App Access Control and Pricing](/build_iapp/guides/orders) + +**Control who can use your iApp and monetize it.** Learn how to create app +orders to make your iApp accessible while defining pricing and access +restrictions. + +- Create and manage app orders with iExec SDK +- Configure pricing, volume limits, and restrictions +- Understand TEE requirements and workerpool restrictions +- Common monetization patterns and use cases + +--- + +### 📥📤 [Inputs and Outputs](/build_iapp/guides/inputs-and-outputs) + +**Handle data flow in your iApp's TEE environment.** Master the different input +types and learn how to generate proper outputs that users can retrieve. + +- 4 input types: Args, Input Files, Requester Secrets, Protected Data +- Access methods via environment variables and file system +- TEE memory constraints and best practices +- Output structure with mandatory `computed.json` + +--- + +### 🐛 [Debugging Your iApp](/build_iapp/guides/debugging-your-iapp) + +**Troubleshoot and optimize your iApp execution in the TEE environment.** Master +debugging techniques and best practices for reliable iApp development. + +- Task execution lifecycle and monitoring +- iExec Explorer and CLI debugging tools +- Common issues: timeouts, memory limits, input/output problems +- Best practices: input validation, error handling, performance optimization + +--- + +### 📦 [How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results) + +**Download and decrypt iApp execution results from completed tasks.** Learn the +complete workflow for retrieving and using iApp outputs. + +- Deal → Task → Result structure and accessibility +- Download methods: iExec CLI and DataProtector SDK +- Automatic vs manual decryption workflows +- Integration patterns for React and Node.js applications + +--- + +### 🛡️ [Using TDX (Experimental)](/build_iapp/guides/using-tdx-experimental) + +**Enable Intel TDX for enhanced TEE security - experimental feature only.** +Understand how to activate TDX and when to use it. + +- How to enable TDX in iApp Generator deployment and execution +- SGX vs TDX differences and compatibility requirements +- Protected data compatibility considerations +- Production warnings and experimental limitations + +## Quick Navigation + +::: tip What You'll Learn These guides cover the complete journey from iApp +development to production deployment, user access management, and result +handling. ::: + +### By Development Stage + +- **🚀 Just built your iApp?** → + [App Access Control and Pricing](/build_iapp/guides/orders) +- **🔧 Handling data flow?** → + [Inputs and Outputs](/build_iapp/guides/inputs-and-outputs) +- **🐛 Having issues?** → + [Debugging Your iApp](/build_iapp/guides/debugging-your-iapp) +- **📦 Need results?** → + [How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results) + +### By User Type + +**iApp Developer**: You build the privacy-preserving application +→ [Inputs and Outputs](/build_iapp/guides/inputs-and-outputs) + +[Debugging](/build_iapp/guides/debugging-your-iapp) + +**App Owner**: You deploy and monetize the iApp +→ [App Access Control and Pricing](/build_iapp/guides/orders) + +**End User Guide**: Your users need to retrieve results +→ [How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results) + +## Development Workflow + +### 1. **Build Your iApp** + +Start with [iApp Generator](/build_iapp/iapp-generator) to create your +privacy-preserving application. + +### 2. **Handle Data Flow** + +Use the [Inputs and Outputs](/build_iapp/guides/inputs-and-outputs) guide to +properly access different input types and generate results. + +### 3. **Debug and Test** + +Follow the [Debugging](/build_iapp/guides/debugging-your-iapp) guide to +troubleshoot issues and optimize performance. + +### 4. **Control Access** + +Implement [App Access Control and Pricing](/build_iapp/guides/orders) to make +your iApp accessible with proper monetization. + +### 5. **User Experience** + +Implement [Result Retrieval](/build_iapp/guides/how-to-get-and-decrypt-results) +to provide users with seamless access to iApp outputs. + +## Additional Resources + +### 📚 **iApp Generator** + +- [What Is an iApp?](/build_iapp/iapp-generator/what-is-iapp) - Core concepts + and 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 + +### 🎯 **Real Examples** + +- [Hello World Tutorial](/overview/helloWorld) - End-to-end iApp development +- [AI Use Cases](/overview/use-cases/ai) - AI-powered privacy applications + +### 🔧 **Advanced Topics** + +- [SDK Deep Dive](/deep_dive/sdk) - Advanced SDK concepts and usage +- [Workers & Workerpools](/deep_dive/workers) - Understanding the execution + infrastructure + +--- + +**Ready to build privacy-first applications?** Pick the guide that matches your +current development stage and start building! 🚀 diff --git a/build_iapp/guides/debugging-your-iapp.md b/build_iapp/guides/debugging-your-iapp.md index 3743a7b6..cfa2413a 100644 --- a/build_iapp/guides/debugging-your-iapp.md +++ b/build_iapp/guides/debugging-your-iapp.md @@ -1,10 +1,170 @@ --- title: Debugging Your iApp -description: Déboguer votre iApp +description: + Troubleshoot and optimize your iApp execution in the TEE environment --- -# Debugging Your iApp +# 🐛 Debugging Your iApp -Cette page est en cours de développement. +**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 + +```typescript +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) +``` + +## 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 + +--- + +**TL;DR**: Use Explorer to track tasks → Test locally with `iapp test` → Debug +remote issues with `iapp debug` → Always validate inputs and create +`computed.json`! 🚀 diff --git a/build_iapp/guides/how-to-get-and-decrypt-results.md b/build_iapp/guides/how-to-get-and-decrypt-results.md index 7e87ca2c..495aacbd 100644 --- a/build_iapp/guides/how-to-get-and-decrypt-results.md +++ b/build_iapp/guides/how-to-get-and-decrypt-results.md @@ -1,10 +1,332 @@ --- title: How to Get and Decrypt Results -description: Comment obtenir et décrypter les résultats +description: Download and decrypt iApp execution results from completed tasks --- -# How to Get and Decrypt Results +# 📦 How to Get and Decrypt Results -Cette page est en cours de développement. +**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**: + +```typescript +import { IExecDataProtectorCore } from '@iexec/dataprotector'; + +// 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: + +```typescript +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +// 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); +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**: + +```typescript +import { useState } from 'react'; +import { IExecDataProtectorCore } from '@iexec/dataprotector'; + +function ResultRetriever({ taskId }) { + const [result, setResult] = useState(null); + const [loading, setLoading] = useState(false); + + const downloadResult = async () => { + setLoading(true); + try { + const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + const resultBuffer = await dataProtectorCore.getResultFromCompletedTask({ + taskId, + }); + + // Convert to text or JSON based on your result format + const resultText = new TextDecoder().decode(resultBuffer); + const resultJson = JSON.parse(resultText); + + setResult(resultJson); + } catch (error) { + console.error('Failed to download result:', error); + } finally { + setLoading(false); + } + }; + + return ( +
+ + {result && ( +
+

Analysis Result:

+ 
{JSON.stringify(result, null, 2)}
+
+ )} +
+ ); +} +``` + +### 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 + +--- + +**TL;DR**: Use `getResultFromCompletedTask()` for automatic download + +decryption, or `iexec task show --download` + `iexec result decrypt` for manual +CLI workflow! 🚀 diff --git a/build_iapp/guides/inputs-and-outputs.md b/build_iapp/guides/inputs-and-outputs.md index daac3a43..42984193 100644 --- a/build_iapp/guides/inputs-and-outputs.md +++ b/build_iapp/guides/inputs-and-outputs.md @@ -1,10 +1,604 @@ --- -title: Inputs and Outputs (types, differences, formats) -description: Types, différences et formats des entrées et sorties +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 -Cette page est en cours de développement. +**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: + +```typescript +// 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: + +```typescript +// 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: + +```typescript +// 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 Users Provide Protected Data + +Users specify the protected data address when executing your iApp: + +```typescript +// User provides their protected data for processing +const response = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', // Address of their protected data + app: '0x456def...', // Your iApp address +}); +``` + +### 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'); +} +``` + +::: + +### 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):** + +```typescript +// 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):** + +```typescript +// 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):** + +```typescript +// 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 + +--- + +**TL;DR**: 4 input types (Args, Input Files, Requester Secrets, Protected Data) +→ Access via env vars & file system → Always create `computed.json` output → +Users get encrypted ZIP results! 📦 diff --git a/build_iapp/guides/orders.md b/build_iapp/guides/orders.md index 14364476..473106ff 100644 --- a/build_iapp/guides/orders.md +++ b/build_iapp/guides/orders.md @@ -1,10 +1,344 @@ --- -title: Orders (how they work, how to manage them) -description: Comment fonctionnent et gérer les commandes +title: App Access Control and Pricing +description: Control who can use your iApp and set pricing with app orders --- -# Orders (how they work, how to manage them) +# 💰 App Access Control and Pricing -Cette page est en cours de développement. +**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 + +--- + +**TL;DR**: Orders = usage rules for your iApp. Create with iExec CLI → Configure +price and restrictions → Sign and publish → Receive automatic payments! 💰 diff --git a/build_iapp/guides/other-emerging-trends.md b/build_iapp/guides/other-emerging-trends.md deleted file mode 100644 index dc660e46..00000000 --- a/build_iapp/guides/other-emerging-trends.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Other Emerging Trends (to be added) -description: Autres tendances émergentes à ajouter ---- - -# Other Emerging Trends (to be added) - -Cette page est en cours de développement. - - diff --git a/build_iapp/guides/using-tdx-experimental.md b/build_iapp/guides/using-tdx-experimental.md index afa5490f..dcc913cb 100644 --- a/build_iapp/guides/using-tdx-experimental.md +++ b/build_iapp/guides/using-tdx-experimental.md @@ -1,10 +1,150 @@ --- -title: Using TDX (Trusted Execution) [EXPERIMENTAL] -description: Utiliser TDX (Exécution de Confiance) [EXPÉRIMENTAL] +title: Using TDX (Experimental) +description: + Enable Intel TDX for enhanced TEE security in iApps - experimental feature --- -# Using TDX (Trusted Execution) [EXPERIMENTAL] +# 🛡️ Using TDX (Experimental) -Cette page est en cours de développement. +:::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** + +## 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 +``` + +### 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 +``` + +## 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 + +--- + +:::warning Final Reminder **TDX is experimental technology.** Use SGX for all +production workloads. ::: + +**TL;DR**: Add `EXPERIMENTAL_TDX_APP=true` to iApp commands → Expect +instabilities → Not for production! 🧪 diff --git a/build_iapp/iapp-generator.md b/build_iapp/iapp-generator.md index 1abd9265..03b6bcb6 100644 --- a/build_iapp/iapp-generator.md +++ b/build_iapp/iapp-generator.md @@ -1,10 +1,111 @@ ---- -title: iApp Generator -description: Générateur d'iApp ---- - # 🤖 iApp Generator -Cette page est en cours de développement. +**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/build_iapp/iapp-generator/what-is-iapp.md b/build_iapp/iapp-generator/what-is-iapp.md new file mode 100644 index 00000000..40b2bfff --- /dev/null +++ b/build_iapp/iapp-generator/what-is-iapp.md @@ -0,0 +1,216 @@ +--- +title: What Is an iApp? +description: Privacy-first applications that run on decentralized infrastructure +--- + +# 🚀 What Is an iApp? + +**Think about code, but it runs in a privacy-safe environment.** An iApp is just +your regular application code (Python script, AI model, data processor) packaged +to run inside secure enclaves. + +## Why Would You Want This? + +Simple: **to process sensitive data that users won't normally share.** + +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.** + +## How It Works + +Your code runs in a **trusted execution environment** (TEE) - think of it as a +"privacy bubble" that even iExec workers can't peek into. + +Users run your iApp when they want to **use** their Protected Data for +something. Your code gets access to their protected data, performs actions with +it - all without you ever seeing the raw data. + +## iApp Generator: Your Development Tool + +Creating iApps used to be complex. **iApp Generator** simplifies this by: + +- **Simulating TEE environment locally** - Test your code in conditions close to + real execution +- **Handling deployment** - Package and deploy with simple commands +- **Managing dependencies** - Docker containers, environment setup, etc. + +```bash +# Create your iApp (Python or Node.js supported) +iapp init my-sentiment-analyzer +cd my-sentiment-analyzer + +# 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 + +**Email Notification iApp** + +```python +# User runs: "Send updates to my contacts about my project" +contacts = load_protecteddata() # User's protected contact list +for contact in contacts: + send_email(contact, project_update_message) +# → Emails sent directly, you never see the addresses +``` + +**Oracle Update iApp** + +```python +# User runs: "Update price oracle with my private trading data" +trading_data = load_protecteddata() # User's protected trading history +average_price = calculate_weighted_average(trading_data) +update_oracle_contract(average_price) +# → Oracle updated with real data, trading history stays private +``` + +**Automated Transactions iApp** + +```python +# User runs: "Buy tokens when my portfolio meets certain conditions" +portfolio = load_protecteddata() # User's protected portfolio data +if should_buy_tokens(portfolio): + execute_trade(token_address, amount) +# → Trade executed based on private data, portfolio details stay hidden +``` + +## The Trust Model + +Here's why users will actually use your iApp with their private data: + +### What Users See + +- ✅ "This code runs in a secure enclave, not on the developer's servers" +- ✅ "My data gets used privately for actions I want" +- ✅ "Even iExec workers can't see my data during execution" +- ✅ "I can revoke access anytime" + +### What You Get + +- ✅ Users willing to use your services with their sensitive data +- ✅ New business models around privacy-preserving analytics +- ✅ Competitive advantage through privacy guarantees + +### The Technical Reality + +``` +User's Private Data → Encrypted → TEE Environment → Your iApp uses it → Actions Performed +``` + +**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. + +## What This Enables + +### 📧 **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 set up automated workflows that use their private data to trigger actions, +transactions, or updates. + +## ❓ 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 ~30 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. ::: + +## Why This Changes Everything + +### ✅ **True Privacy** + +Users never expose their raw data. Your app processes it privately inside secure +enclaves. + +### ✅ **Verifiable Execution** + +Cryptographic proof that your code ran exactly as intended. No black box +execution. + +### ✅ **Decentralized Infrastructure** + +No single point of failure. Your app runs across a distributed network of +workers. + +### ✅ **Zero Trust Architecture** + +Users don't need to trust you with their data. The protocol guarantees privacy. + +## Start Building + +Ready to build privacy-first applications? + +### 🚀 **Try iApp Generator** + +- [Getting Started](/build_iapp/iapp-generator/getting-started) - Deploy your + first iApp in 15 minutes +- [Building Your iExec App](/build_iapp/iapp-generator/building-your-iexec-app) - + Complete development guide + +### 📖 **Learn with Guides** + +- [Orders](/build_iapp/guides/orders) - How iApp execution works +- [Inputs and Outputs](/build_iapp/guides/inputs-and-outputs) - Handle data flow +- [Debugging Your iApp](/build_iapp/guides/debugging-your-iapp) - Troubleshoot + issues + +### 🎯 **See iApps in Action** + +Real iApps you can use today: + +- [Web3Mail](/use_iapp/web3mail) - Private emailing iApp SDK +- [Web3Telegram](/use_iapp/web3telegram) Private messaging iApp SDK +- [Oracle Factory](/use_iapp/oracle-factory) - Decentralized oracles + +--- + +**TL;DR**: iApps = Your code + Secure execution + User privacy + Verifiable +results. Cloud computing, but nobody can spy on your stuff. 🔒 diff --git a/manage_data/dataProtector/what-is-protected-data.md b/manage_data/dataProtector/what-is-protected-data.md index 53bcdd32..8bae4672 100644 --- a/manage_data/dataProtector/what-is-protected-data.md +++ b/manage_data/dataProtector/what-is-protected-data.md @@ -1,58 +1,179 @@ --- title: What Is Protected Data? -description: Understanding iExec's data protection mechanisms +description: + Data ownership meets privacy - understand how iExec gives you control --- -# ❓ What Is Protected Data? +# 🛡️ What Is Protected Data? -Protected Data is iExec's revolutionary approach to data privacy and ownership. -It allows you to maintain control over your data while enabling computation on -it without exposing the raw information. +**Your data, but with superpowers.** Protected Data is how iExec gives you +blockchain-verified ownership over your information. You control who uses it, +for what purpose, and you can get paid when it creates value. -## Key Concepts +## The Problem -### Data Ownership +Traditional apps treat your data like their property. You upload it, they own +it. You lose control, they make money from it. -- **You own your data**: The original data never leaves your control -- **Granular permissions**: Decide who can access and use your data -- **Revocable access**: Grant and revoke permissions at any time +## The Solution: Blockchain-Verified Ownership -### Privacy-Preserving Computation +Protected Data flips this model. Here's how you protect data: -- **Encrypted processing**: Data is encrypted during computation -- **TEE (Trusted Execution Environment)**: Secure enclaves protect data during - processing -- **Zero-knowledge**: Compute on data without revealing it +```javascript +const protectedData = await dataprotector.protectData({ + name: 'my-contacts.json', + data: { emails: ['user@example.com', ...] } +}); +``` -### Monetization +Now you have **blockchain-verified ownership** of this data. No one can access +it without your explicit permission. -- **Data marketplaces**: Sell access to your protected data -- **Usage tracking**: Monitor how your data is being used -- **Fair compensation**: Get paid for data usage +## Access Control That Actually Works -## How It Works +Traditional permissions: "This app can access your contacts" _(forever, for +anything)_ -1. **Protect**: Encrypt and register your data on the iExec network -2. **Share**: Grant access permissions to specific users or applications -3. **Monitor**: Track usage and maintain control -4. **Monetize**: Earn from your data while keeping it private +Protected Data permissions: "This newsletter app can use my contacts to send +marketing emails, but only during weekdays, and I get 2€ per campaign." -## Use Cases +```javascript +await dataprotector.grantAccess({ + protectedData: protectedData.address, + authorizedApp: '0x123...', // Specific app + authorizedUser: '0xabc...', // Specific user + // Plus pricing, time limits, usage rules... +}); +``` -- **Personal Data**: Health records, financial data, personal preferences -- **Business Intelligence**: Market research, customer analytics, proprietary - datasets -- **AI Training**: Training models without exposing sensitive data -- **Research**: Collaborative research with privacy guarantees +## Privacy-Safe Processing -## Next Steps +When apps use your Protected Data, they process it inside **secure enclaves** +(TEEs). They get the results they need, but your raw data never leaves the +privacy bubble. -Ready to protect your data? Check out: +### How the Technical Magic Works -- [Getting Started with DataProtector](/manage_data/dataProtector/getting-started) -- [DataProtector Guides](/manage_data/guides) +Here's what actually happens under the hood: + +1. **Your data gets encrypted** and stored online (IPFS,Arweave..) +2. **The decryption key** is stored in a secure TEE database +3. **Only authorized TEE workers** can retrieve this key to process your data +4. **Apps run inside these TEE workers** - they can decrypt and use your data, + but only within the secure enclave +5. **Results come back encrypted** to you - the raw data never leaves the TEE + environment + +``` +Your Data (encrypted, online) + Decryption Key (in TEE database) = Processing (only in authorized TEEs) +``` + +This architecture ensures that even iExec workers can't access your raw data - +only the TEE environment can decrypt it for processing, and only when you've +authorized it. + +## What This Enables + +### 📧 **Privacy-First Email Marketing** + +Your users upload their contact lists as Protected Data. Your newsletter app can +send personalized emails without ever seeing the actual email addresses. Users +stay private, you get engagement. + +### 🤖 **Ethical AI Training** + +People contribute personal data (health records, preferences) as Protected Data. +AI models can learn from this data without seeing individual information. Better +AI, fair compensation, zero privacy trade-offs. + +### 🏢 **Confidential Business Intelligence** + +Companies protect their datasets but still collaborate on insights. Research +partners get aggregate results without accessing raw competitive data. +Innovation without information leaks. + +### 💰 **Data Monetization** + +Create marketplaces where data owners set their own terms. "Use my fitness data +for $5/month, health insights only, no advertising." Automatic payments, +programmable rules. + +## ❓ Frequently Asked Questions + +::: details 💰 How much does it cost? It's **free**! No gas fees on iExec's +Bellecour network. You just need a Web3 wallet to sign transactions. ::: + +::: details 📏 What's the maximum dataset size? It depends on your use case +context. For standard cases (contacts, small datasets), no problem. For large +volumes, [contact us](https://iex.ec/contact/) so we can assess if it fits your +needs. ::: + +::: details 💸 Can I monetize my data? Yes! You can sell access to your +Protected Data with flexible pricing, subscriptions, etc. See the +[Manage Data Monetization](/manage_data/guides/manage-data-monetization) guide +for all details. ::: + +::: details 🚀 How do I get started? You need a Web3 wallet (MetaMask, +WalletConnect) and Node.js 16+. Follow +[DataProtector Core](/manage_data/dataProtector/dataProtectorCore) for +installation and first examples. ::: + +::: details 🔒 Is my data really secure? Yes! Your data is encrypted and keys +are stored in secure TEE environments. Even iExec workers can't see your raw +data - only the authorized TEE environment can decrypt it for processing. ::: + +## Why This Changes Everything + +### ✅ **True Ownership** + +Your data is blockchain-verified yours. Not "terms & conditions" yours, actually +yours. + +### ✅ **Privacy by Design** + +Apps get utility without compromising privacy. No more "privacy vs +functionality" trade-offs. + +### ✅ **Programmable Control** + +Set complex rules: "Use my data only for health insights, only on weekdays, only +if I get paid 5€." + +### ✅ **Composable Privacy** + +Any iApp can use your Protected Data (if authorized). Build privacy-first +ecosystems. + +## Start Building + +Ready to give your users data ownership? + +### 🚀 **Try DataProtector** + +- [Getting Started](/manage_data/dataProtector/getting-started) - Protect your + first dataset +- [DataProtector Core](/manage_data/dataProtector/dataProtectorCore) - Full SDK + reference +- [DataProtector Sharing](/manage_data/dataProtector/dataProtectorSharing) - + Monetization features + +### 📖 **Learn with Guides** + +- [Create and Share Access](/manage_data/guides/create-and-share-access) - Basic + workflow +- [Handle Schemas & Dataset Types](/manage_data/guides/handle-schemas-dataset-types) - + Advanced data types +- [Manage Data Monetization](/manage_data/guides/manage-data-monetization) - Get + paid for your data + +### 🎯 **Use in iApps** + +Protected Data works with any iApp: + +- [Web3Mail](/use_iapp/web3mail) - Private email with contact protection +- [Build your own iApp](/build_iapp/iapp-generator) - Custom privacy-first apps --- -_Protect your data, maintain control, and unlock its value with iExec's -DataProtector._ +**TL;DR**: Protected Data = Your data + Your rules + Privacy guarantees. +Finally, data ownership that actually works. 🔒 diff --git a/manage_data/guides.md b/manage_data/guides.md new file mode 100644 index 00000000..43f4f146 --- /dev/null +++ b/manage_data/guides.md @@ -0,0 +1,105 @@ +--- +title: DataProtector Guides +description: + Step-by-step guides for protecting, managing, and monetizing your data with + iExec DataProtector +--- + +# 📖 DataProtector Guides + +**Master data protection, sharing, and monetization** with these comprehensive +step-by-step guides. Each guide focuses on a specific aspect of building with +DataProtector. + +## Essential Guides + +### 🛡️ [Create and Share Access to Protected Data](/manage_data/guides/create-and-share-access) + +**Start here if you're new to DataProtector.** Learn how to protect your data +and control exactly who can access it. + +- Protect data with client-side encryption +- Grant access to specific users and apps +- Set pricing and usage limits +- Debug mode for development + +--- + +### 🏷️ [Handle Schemas and Dataset Types](/manage_data/guides/handle-schemas-dataset-types) + +**Understand how your data structure works with iApps.** Learn about automatic +schema generation and how to use data types effectively. + +- Auto-generated schemas from your JSON data +- Supported data types and format conversion +- Using schemas in iApp development +- Type safety and error handling + +--- + +### 💰 [Manage Data Monetization](/manage_data/guides/manage-data-monetization) + +**Turn your protected data into revenue.** Explore different monetization +strategies from simple pay-per-use to advanced marketplace distribution. + +- Pay-per-use with DataProtector Core +- DataProtector Sharing with collections +- Rental, subscription, and sale models +- Revenue optimization strategies + +## Quick Navigation + +::: tip What You'll Learn These guides cover the complete journey from +protecting your first dataset to building a sustainable data business with +automated monetization. ::: + +### By Use Case + +- **🚀 Just getting started?** → + [Create and Share Access](/manage_data/guides/create-and-share-access) +- **🔧 Building an iApp?** → + [Handle Schemas and Dataset Types](/manage_data/guides/handle-schemas-dataset-types) +- **💡 Want to monetize data?** → + [Manage Data Monetization](/manage_data/guides/manage-data-monetization) + +### By Experience Level + +**Beginner**: Start with data protection basics +→ [Create and Share Access](/manage_data/guides/create-and-share-access) + +**Intermediate**: Learn about data structures and iApp integration +→ [Handle Schemas and Dataset Types](/manage_data/guides/handle-schemas-dataset-types) + +**Advanced**: Explore monetization strategies and business models +→ [Manage Data Monetization](/manage_data/guides/manage-data-monetization) + +## Additional Resources + +### 📚 **SDK Reference** + +- [DataProtector Core SDK](/manage_data/dataProtector/dataProtectorCore) - + Complete method reference +- [DataProtector Sharing SDK](/manage_data/dataProtector/dataProtectorSharing) - + Advanced distribution features +- [Type Definitions](/manage_data/dataProtector/types) - TypeScript interfaces + and types + +### 🎯 **Real Examples** + +- [Content Creator Demo](/overview/use-case-demo/content-creator) - Live example + of data monetization +- [Hello World Tutorial](/overview/helloWorld) - End-to-end walkthrough + +### 🔧 **Advanced Topics** + +- [Apps Whitelist](/manage_data/dataProtector/advanced/apps-whitelist) - Control + which iApps can access data +- [Smart Contract Details](/manage_data/dataProtector/advanced/dps-smart-contract) - + Blockchain implementation +- [Migration Guide](/manage_data/dataProtector/migrate-from-v1) - Upgrade from + v1 to v2 + +--- + +**Ready to start?** Pick the guide that matches your current goal and dive in! +🚀 diff --git a/manage_data/guides/create-and-share-access.md b/manage_data/guides/create-and-share-access.md index 7bcc81e2..b37be722 100644 --- a/manage_data/guides/create-and-share-access.md +++ b/manage_data/guides/create-and-share-access.md @@ -1,10 +1,192 @@ --- title: Create and Share Access to Protected Data -description: Créer et partager l'accès aux données protégées +description: + Learn how to protect data and grant secure access for specific apps and users --- -# Create and Share Access to Protected Data +# 🛡️ Create and Share Access to Protected Data -Cette page est en cours de développement. +**Want to keep your data private while still using it in applications?** Here's +how DataProtector works: first you encrypt your data, then you control exactly +who can access it and when. - +Once data is protected, it's only accessible inside secure enclaves (TEEs) by +the specific people and iApps you authorize. No exceptions. + +## Quick Start + +First, install DataProtector in your project: + +::: code-group + +```bash [npm] +npm install @iexec/dataprotector +``` + +```bash [yarn] +yarn add @iexec/dataprotector +``` + +```bash [pnpm] +pnpm add @iexec/dataprotector +``` + +::: + +## Protect Your Data + +**Here's what happens:** Your data gets encrypted client-side and stored as an +NFT. Only you control who can decrypt and use it. + +```ts +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +const protectedData = await dataProtectorCore.protectData({ + name: 'My Email Contact', + data: { + email: 'alice@example.com', + firstName: 'Alice', + lastName: 'Smith', + }, +}); + +console.log('Protected data address:', protectedData.address); +``` + +### What You Can Protect + +**Data**: Any JSON object with custom keys. Think user profiles, API +credentials, datasets, model parameters - anything you want to keep private but +still use in computations. + +**Supported types**: Strings, numbers, booleans, nested objects, files (convert +to ArrayBuffer first), and arrays (convert to Record format). + +**Limits**: File size depends on your storage choice (IPFS or Arweave). For +large datasets, consider using another IPFS node. + +::: tip Need Help? Check our +[Schema and Dataset Types guide](/manage_data/guides/handle-schemas-dataset-types) +for detailed formatting instructions. ::: + +### Debug Mode Option + +```ts +const protectedData = await dataProtectorCore.protectData({ + data: { email: 'test@example.com' }, + allowDebug: true, // Only for development/testing +}); +``` + +::: warning Debug mode lets you test with debug iApps during development. As +"debug" iApps don't have the same security standards, we recommend using this +mode only during iApp development. ::: + +## Grant Access + +**Here's the key:** The protocol blocks all access to your protected data by +default. You must explicitly grant permission for each app and user combination. + +Once you own protected data, here's how to share access: + +```ts +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: '0x123abc...', // Your protected data address + authorizedApp: '0x456def...', // iApp that can process the data + authorizedUser: '0x789cba...', // User who can trigger the processing + pricePerAccess: 0, // Cost per use (in nRLC) + numberOfAccess: 10, // Maximum number of uses +}); +``` + +### Parameters Explained + +#### `protectedData` + +The address of your protected data (returned when you created it). **You must +own this data** to grant access. + +#### `authorizedApp` + +**What it is**: The iApp address that's allowed to process your data inside the +secure enclave. + +**Why needed**: This ensures only specific, audited applications can access your +data. No random code can touch it. + +**Pro tip**: Use app whitelists for production. Instead of a single app address, +you can specify a whitelist contract that contains multiple approved app +versions. Very useful for when you need to upgrade your iApps, without losing +all the granted access. + +```ts +// Single app +authorizedApp: 'web3mail.apps.iexec.eth'; + +// Or use a whitelist (recommended for production) +authorizedApp: '0x781482C39CcE25546583EaC4957Fb7Bf04C277D2'; // Web3Mail whitelist +``` + +#### `authorizedUser` + +**What it is**: The wallet address that can initiate processing of your data. + +**Why needed**: Even with an authorized app, only specific users can trigger the +computation. This gives you granular control over who uses your data. + +**Don't forget**: Even if you are the owner of the data, you need to authorize +yourself! + +**Special case**: Set to `0x0000000000000000000000000000000000000000` to allow +**any user** to trigger processing (useful for public datasets). + +#### `pricePerAccess` + +**Quick explanation**: How much you charge per data usage (in nano RLC - nRLC). + +Set to `0` for free access, or specify a price to monetize your data +automatically. + +**Example**: `pricePerAccess: 1000000000` = 1 RLC per access + +→ **Want to learn more monetization capabilities?** See our detailed +[Manage Data Monetization guide](/manage_data/guides/manage-data-monetization) + +#### `numberOfAccess` + +**Quick explanation**: Maximum number of times this authorization can be used. + +::: warning Important If someone tries to process your data more times than +allowed, they'll get a "no dataset orders" error. Set this high enough for your +use case. ::: + +**Example values**: + +- `1` - Single use (great for one-time data analysis) +- `100` - Limited campaign (email marketing with usage cap) +- `10000` - Effectively unlimited for most use cases + +## What's Next? + +**You now have protected data with controlled access.** Here are your next +steps: + +- **Process the data**: Use + [processProtectedData](/manage_data/dataProtector/dataProtectorCore/processProtectedData) + to run computations +- **Manage access**: + [Revoke](/manage_data/dataProtector/dataProtectorCore/revokeOneAccess) or + [modify permissions](/manage_data/dataProtector/dataProtectorCore/grantAccess) + anytime +- **Learn data types**: Deep dive into + [schemas and dataset types](/manage_data/guides/handle-schemas-dataset-types) +- **Monetize data**: Explore + [data monetization strategies](/manage_data/guides/manage-data-monetization) + +--- + +**TL;DR**: Protect data → Grant access to specific app + user → Data stays +encrypted except inside authorized secure enclaves. You keep full control. 🔒 diff --git a/manage_data/guides/handle-schemas-dataset-types.md b/manage_data/guides/handle-schemas-dataset-types.md index 19abe9fb..fe04780b 100644 --- a/manage_data/guides/handle-schemas-dataset-types.md +++ b/manage_data/guides/handle-schemas-dataset-types.md @@ -1,10 +1,186 @@ --- title: Handle Schemas and Dataset Types -description: Gérer les schémas et types de datasets +description: + Learn how schemas work in DataProtector and how to use them in your iApps --- -# Handle Schemas and Dataset Types +# 🏷️ Handle Schemas and Dataset Types -Cette page est en cours de développement. +**Schemas are like TypeScript for your protected data.** They define the +structure and types of your data automatically when you protect it, making it +easy for iApps to know what they're working with. - +Think of schemas as **data labels** - they tell iApps "this protected data +contains an email address and a phone number" without revealing the actual +values. + +## How Schemas Work + +When you protect data with DataProtector, the SDK automatically analyzes your +JSON object and generates a schema. **No manual schema definition needed** - +it's all handled for you. + +```ts +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +const protectedData = await dataProtectorCore.protectData({ + name: 'User Contact', + data: { + email: 'alice@example.com', + phoneNumber: '+1234567890', + preferences: { + newsletter: true, + notifications: false, + }, + }, +}); + +// The schema is automatically generated: +console.log(protectedData.schema); +/* Output: +{ + email: 'string', + phoneNumber: 'string', + preferences: { + newsletter: 'bool', + notifications: 'bool' + } +} +*/ +``` + +## Supported Data Types + +The schema automatically detects these types: + +| Type | Description | Example | +| ------------------------------- | -------------- | --------------------- | +| `string` | Text data | `"alice@example.com"` | +| `bool` | Boolean values | `true`, `false` | +| `f64` | Numbers | `42`, `3.14` | +| `i128` | Big integers | `BigInt(123456789)` | +| `application/octet-stream` | Binary data | File contents | +| `image/jpeg`, `image/png`, etc. | Media files | Images, videos | + +::: tip Auto-Detection The SDK automatically detects file types based on +content. No need to specify MIME types manually. ::: + +## Why Schemas Matter + +### 🎯 **For iApp Development** + +Schemas let your iApps validate and process data safely: + +```js +// Inside your iApp +const email = await deserializer.getValue('email', 'string'); +const preferences = await deserializer.getValue( + 'preferences.newsletter', + 'bool' +); +``` + +### 🔍 **For Data Discovery** + +Users can find relevant protected data without seeing the actual content: + +```ts +// Find all protected data with email addresses +const query = { schema: { email: 'string' } }; +// Returns metadata only, no actual emails revealed +``` + +### 🛡️ **For Type Safety** + +Prevents your iApps from processing incompatible data types. + +## Real Examples + +### Simple User Profile + +```ts +const userData = await dataProtectorCore.protectData({ + data: { + email: 'user@example.com', + age: 25, + isSubscribed: true, + }, +}); +// Schema: { email: 'string', age: 'f64', isSubscribed: 'bool' } +``` + +### Nested Contact Information + +```ts +const contactData = await dataProtectorCore.protectData({ + data: { + personal: { + firstName: 'Alice', + lastName: 'Smith', + }, + contact: { + email: 'alice@example.com', + phone: '+1234567890', + }, + preferences: { + marketing: false, + notifications: true, + }, + }, +}); +// Schema reflects the full nested structure +``` + +### File Data + +```ts +import { createArrayBufferFromFile } from '@iexec/dataprotector'; + +const file = document.getElementById('fileInput').files[0]; +const fileBuffer = await createArrayBufferFromFile(file); + +const fileData = await dataProtectorCore.protectData({ + data: { + fileName: file.name, + fileContent: fileBuffer, + uploadDate: Date.now(), + }, +}); +// Schema: { fileName: 'string', fileContent: 'image/jpeg', uploadDate: 'f64' } +``` + +## Using Schemas in iApps + +Once you have protected data with a schema, you'll want to process it inside an +iApp. + +::: warning Type Matching **Your iApp and frontend must use the same field names +and types.** If they don't match, you'll get runtime errors when processing the +data. ::: + +→ **Ready to build an iApp?** Check out our detailed +[Inputs and Outputs guide](/build_iapp/guides/inputs-and-outputs) to learn how +to access schema fields inside your iApp using the deserializer. + +## Next Steps + +**You now understand how schemas work with protected data.** Here's what to +explore next: + +- **Build an iApp**: Check out the + [iApp Generator guide](/build_iapp/iapp-generator) to create your first data + processor +- **Process data**: Learn about + [processProtectedData](/manage_data/dataProtector/dataProtectorCore/processProtectedData) + for running computations +- **See it in action**: Try our [Hello World tutorial](/overview/helloWorld) for + a complete example + +--- + +**TL;DR**: Schemas = auto-generated data labels. Frontend protects data → Schema +describes structure → iApp uses schema to access fields safely. Match your field +names and types between frontend and iApp! 🏷️ diff --git a/manage_data/guides/index.md b/manage_data/guides/index.md deleted file mode 100644 index 602e3f8a..00000000 --- a/manage_data/guides/index.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: DataProtector Guides -description: Step-by-step guides for using iExec DataProtector ---- - -# 📖 DataProtector Guides - -Discover how to protect, share, and monetize your data using iExec's -DataProtector technology through these comprehensive guides. - -## Getting Started Guides - -### 🚀 [Quick Start Guide](/manage_data/dataProtector/getting-started) - -Learn the basics of protecting your first dataset and granting access to others. - -### 🔐 [Understanding Protected Data](/manage_data/dataProtector/what-is-protected-data) - -Deep dive into the concepts behind data protection and privacy-preserving -computation. - -## Core Features Guides - -### 📊 Data Protection - -- [Protect Your Data](/manage_data/dataProtector/dataProtectorCore/protectData) - - Encrypt and register data -- [Retrieve Protected Data](/manage_data/dataProtector/dataProtectorCore/getProtectedData) - - Access your protected datasets -- [Transfer Ownership](/manage_data/dataProtector/dataProtectorCore/transferOwnership) - - Change data ownership - -### 🔑 Access Management - -- [Grant Access](/manage_data/dataProtector/dataProtectorCore/grantAccess) - - Give permissions to users -- [View Granted Access](/manage_data/dataProtector/dataProtectorCore/getGrantedAccess) - - See who has access -- [Revoke Access](/manage_data/dataProtector/dataProtectorCore/revokeAllAccess) - - Remove permissions - -### ⚡ Data Processing - -- [Process Protected Data](/manage_data/dataProtector/dataProtectorCore/processProtectedData) - - Run computations -- [Get Results](/manage_data/dataProtector/dataProtectorCore/getResultFromCompletedTask) - - Retrieve computation outputs - -## Data Sharing & Monetization - -### 📦 Collections - -- [Create Collections](/manage_data/dataProtector/dataProtectorSharing/collection/createCollection) - - Group related datasets -- [Manage Collections](/manage_data/dataProtector/dataProtectorSharing/collection/addToCollection) - - Add/remove data - -### 💰 Monetization Options - -- [Rent Your Data](/manage_data/dataProtector/dataProtectorSharing/renting) - - Time-based access -- [Sell Your Data](/manage_data/dataProtector/dataProtectorSharing/selling) - - Permanent transfers -- [Subscription Model](/manage_data/dataProtector/dataProtectorSharing/subscription) - - Recurring access - -## Advanced Topics - -### 🔧 [Advanced Configuration](/manage_data/dataProtector/advanced/advanced-configuration) - -Customize DataProtector for your specific needs. - -### 🏗️ [Smart Contracts](/manage_data/dataProtector/advanced/dps-smart-contract) - -Understand the underlying blockchain technology. - -### 📱 [App Whitelisting](/manage_data/dataProtector/advanced/apps-whitelist) - -Control which applications can access your data. - -## Migration Guide - -### 🔄 [Migrate from v1 to v2](/manage_data/dataProtector/migrate-from-v1) - -Upgrade from the previous version of DataProtector. - ---- - -_These guides will help you master data protection and unlock the full potential -of your datasets._ diff --git a/manage_data/guides/manage-data-monetization.md b/manage_data/guides/manage-data-monetization.md index d2fc0ac7..765d2967 100644 --- a/manage_data/guides/manage-data-monetization.md +++ b/manage_data/guides/manage-data-monetization.md @@ -1,10 +1,310 @@ --- title: Manage Data Monetization -description: Gérer la monétisation des données +description: + Explore different ways to monetize your protected data with pay-per-use and + DataProtector Sharing --- -# Manage Data Monetization +# 💰 Manage Data Monetization -Cette page est en cours de développement. +**Your protected data can generate revenue automatically.** iExec offers two +main approaches for monetizing your data: simple pay-per-use access and advanced +DataProtector Sharing with multiple distribution models. - +Each approach serves different use cases, from direct data processing to +autonomous smart contract distribution. + +## Two Monetization Approaches + +### 🎯 **Pay-Per-Use (DataProtector Core)** + +Direct access control with simple pricing. You grant access to specific users +and apps, charging per data usage. + +### 🏪 **DataProtector Sharing** + +Advanced distribution features with collections, subscriptions, rentals, and +sales. Users can purchase access autonomously through smart contracts. + +Let's explore both in detail. + +--- + +## Pay-Per-Use (DataProtector Core) + +**How it works**: When you grant access to your protected data, you set a price +per access. Each time someone processes your data, they pay your specified fee +automatically. + +```ts +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); + +// Grant paid access to your data +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: '0x123abc...', // Your data address + authorizedApp: 'email-processor.apps.iexec.eth', + authorizedUser: '0x456def...', // Specific user + pricePerAccess: 5000000000, // 5 RLC per access + numberOfAccess: 100, // Max 100 uses +}); +``` + +### **Use Cases for Pay-Per-Use** + +::: code-group + +```ts [API Access] +// Charge for AI model inference +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: myAIModelAddress, + authorizedApp: 'ai-inference.apps.iexec.eth', + authorizedUser: clientAddress, + pricePerAccess: 1000000000, // 1 RLC per inference + numberOfAccess: 1000, +}); +``` + +```ts [Data Processing] +// Charge for data analysis +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: healthDataAddress, + authorizedApp: 'health-analyzer.apps.iexec.eth', + authorizedUser: researcherAddress, + pricePerAccess: 10000000000, // 10 RLC per analysis + numberOfAccess: 50, +}); +``` + +```ts [Free Access] +// Grant free access (still controlled) +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: publicDatasetAddress, + authorizedApp: 'research.apps.iexec.eth', + authorizedUser: '0x0000000000000000000000000000000000000000', // Any user + pricePerAccess: 0, // Free + numberOfAccess: 10000, +}); +``` + +::: + +### **Pros & Cons of Pay-Per-Use** + +✅ **Advantages**: + +- Simple setup and direct control +- Works with any existing iApp +- You know exactly who has access +- Immediate payment per usage + +❌ **Limitations**: + +- Manual access granting for each user +- Direct relationship required with each consumer +- No automated distribution features + +--- + +## DataProtector Sharing + +**How it works**: Create collections of your protected data and set up +distribution models. Users can discover and purchase access autonomously through +smart contracts. + +::: tip See It Live The +[Content Creator demo](/overview/use-case-demo/content-creator) shows +DataProtector Sharing in action with file monetization. While it uses +content-delivery for file transfers, the same patterns work for any iApp - AI +models, data processing, oracles, etc. ::: + +### **Step 1: Create a Collection** + +```ts +import { + IExecDataProtectorSharing, + getWeb3Provider, +} from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorSharing = new IExecDataProtectorSharing(web3Provider); + +// Create a collection to group your data +const collection = await dataProtectorSharing.createCollection(); +console.log('Collection address:', collection.collectionId); + +// Add your protected data to the collection +await dataProtectorSharing.addToCollection({ + protectedData: '0x123abc...', // Your protected data address + collectionId: collection.collectionId, + addOnlyAppWhitelist: '0x256bcd881c33bdf9df952f2a0148f27d439f2e64', // iExec apps whitelist +}); +``` + +### **Step 2: Choose Your Distribution Model** + +DataProtector Sharing offers four distribution models: + +### 🆓 **Free Access** + +Perfect for building audience, beta testing, or public datasets. + +```ts +// Make data freely available (but still controlled) +await dataProtectorSharing.setProtectedDataToRenting({ + protectedData: '0x123abc...', + price: 0, // Free access + duration: 86400, // 24 hours access +}); +``` + +### 🏠 **Rental Model** + +Users pay once for temporary access to your data. + +```ts +// Set up rental terms +await dataProtectorSharing.setProtectedDataToRenting({ + protectedData: '0x123abc...', + price: 5000000000, // 5 RLC rental fee + duration: 604800, // 7 days access (in seconds) +}); + +// Users can then rent your data +const rental = await dataProtectorSharing.rentProtectedData({ + protectedData: '0x123abc...', + price: 5000000000, + duration: 604800, +}); +``` + +**Perfect for**: + +- Time-limited datasets (event data, seasonal trends) +- Expensive datasets where users need short-term access +- Content that loses value over time + +### 📅 **Subscription Model** + +Users pay for ongoing access to a bundle of data that you can expand over time. + +```ts +// First, set subscription parameters for the collection +await dataProtectorSharing.setSubscriptionParams({ + collectionId: collection.collectionId, + price: 20000000000, // 20 RLC subscription fee + duration: 2592000, // 30 days access +}); + +// Add protected data to the subscription bundle +await dataProtectorSharing.setProtectedDataToSubscription({ + protectedData: '0x123abc...', +}); + +// Add more data to the same subscription +await dataProtectorSharing.setProtectedDataToSubscription({ + protectedData: '0x456def...', // Additional dataset +}); + +// Users subscribe to access all data in the bundle +const subscription = await dataProtectorSharing.subscribeToCollection({ + collectionId: collection.collectionId, + price: 20000000000, + duration: 2592000, +}); +``` + +**Perfect for**: + +- Growing datasets (daily market data, news feeds) +- Educational content series +- Research datasets that expand over time +- SaaS-style data access + +### 💸 **Sale Model** + +Transfer permanent ownership of your data to the buyer. + +```ts +// List data for sale +await dataProtectorSharing.setProtectedDataForSale({ + protectedData: '0x123abc...', + price: 100000000000, // 100 RLC purchase price +}); + +// Buyers can purchase ownership +const purchase = await dataProtectorSharing.buyProtectedData({ + protectedData: '0x123abc...', + price: 100000000000, +}); +``` + +**Perfect for**: + +- Unique datasets or models +- Digital assets and NFT data +- One-time valuable insights +- When you want to exit data ownership + +## Comparison: When to Use What? + +| Feature | Pay-Per-Use | DataProtector Sharing | +| ------------------------- | ---------------------- | ------------------------------------- | +| **Setup Complexity** | Simple | Moderate | +| **Consumer Relationship** | Direct | Smart contract mediated | +| **Payment** | Per processing | Per access period | +| **User Autonomy** | Requires your approval | Self-service | +| **Distribution Models** | One (pay-per-use) | Four (free, rent, subscription, sale) | +| **Best for** | Direct partnerships | Autonomous distribution | + +### 🎯 **Choose Pay-Per-Use when**: + +- You have direct relationships with data consumers +- You want full control over each access grant +- Your data is processed by specific iApps +- Simple pricing model is sufficient + +### 🏪 **Choose DataProtector Sharing when**: + +- You want automated distribution via smart contracts +- Users should purchase access autonomously without your involvement +- You need flexible pricing models (free, rental, subscription) +- You want to build a data business with recurring revenue + +## Real-World Example + +**Want to see data monetization in action?** Check out our **Content Creator +demo** that showcases DataProtector Sharing with real file transfers: + +**[Content Creator Demo](/overview/use-case-demo/content-creator)** - A complete +app demonstrating collections, rentals, and subscriptions for content +monetization. + +::: tip Live Example The Content Creator demo uses a content-delivery iApp for +file transfers, but the same monetization patterns apply to **any iApp and use +case** - AI model inference, data analysis, oracle feeds, Web3Mail, etc. ::: + +## Next Steps + +**Ready to start monetizing your data?** Here are your next steps: + +- **See it in action**: Try the + [Content Creator demo](/overview/use-case-demo/content-creator) to understand + the full flow +- **Start simple**: Begin with + [pay-per-use via grantAccess](/manage_data/guides/create-and-share-access) +- **Explore sharing**: Try + [DataProtector Sharing](/manage_data/dataProtector/dataProtectorSharing) for + automated distribution +- **Build collections**: Learn about + [collection management](/manage_data/dataProtector/dataProtectorSharing/collection) +- **Set up subscriptions**: Implement + [recurring revenue models](/manage_data/dataProtector/dataProtectorSharing/subscription) + +--- + +**TL;DR**: Pay-per-use = Simple direct control. DataProtector Sharing = Smart +contract automation with free/rent/subscription/sale models. Choose based on +your distribution strategy and technical needs. 💰 diff --git a/overview/speedrun-iexec.md b/overview/speedrun-iexec.md new file mode 100644 index 00000000..d0175e6c --- /dev/null +++ b/overview/speedrun-iexec.md @@ -0,0 +1,119 @@ +--- +title: Speedrun iExec +description: + Understand iExec protocol in 3 minutes - privacy-first computing for Web3 +--- + +# ⚡ Speedrun iExec + +**Privacy-first computing protocol.** Your data stays protected, your code runs +in secure enclaves, results come back encrypted. Here's how it works. + +## The Protocol (Simple Version) + +### 🔒 Step 1: Protect Data + +Your sensitive data gets encrypted and stored online. Only you control who can +access it. + +→ **Devtool**: [DataProtector](/manage_data/dataProtector) handles this for you + +### ⚙️ Step 2: Secure Computing (Workers) + +Code runs inside **secure enclaves** (TEEs) on iExec workers. The worker can +access your data to process it, but only within the privacy-safe TEE +environment - your data never leaves the secure bubble. + +### 🚀 Step 3: Run iApps + +You submit a **Task** = "Run this iApp on this protected data". The protocol +finds available workers and executes everything confidentially. + +→ **Devtool**: [iApp Generator](/build_iapp/iapp-generator) helps you create and +deploy iApps + +### 📦 Step 4: Get Results + +Results come back **encrypted to you**. Workers never see raw data, you never +lose control. + +``` +Protected Data + iApp + Worker = Task → Encrypted Result +``` + +## What Each Piece Does + +### 🛡️ **Protected Data** + +Your data, encrypted. You set the rules: "Only these apps can use it, only for +these purposes." + +### 🚀 **iApps** + +Your code, packaged to run on workers. Can be AI models, data processing +scripts, any computation. + +### 🏭 **Workers (Secure Enclaves)** + +Computers that process your data inside privacy-safe TEE environments. They can +access your data to work with it, but the TEE ensures it stays confidential and +tamper-proof. + +### ⚡ **Deals** + +A job request: "Execute iApp X on protected data Y, send results to Z." The +protocol handles the rest. + +## Real Example Walkthrough + +**AI Model Training (Private)** + +1. **Protect**: Medical researchers upload patient data → becomes Protected Data +2. **Deploy**: AI company packages their model → becomes iApp +3. **Execute**: Someone submits Task → "Train model on this data" +4. **Result**: Model gets trained, researcher gets insights, raw data never + leaves enclave + +**Web3 Email** + +1. **Protect**: Users upload email contacts → Protected Data +2. **Execute**: App submits Task → "Send email via Web3Mail iApp" +3. **Result**: Email sent, addresses stay private, sender/receiver authenticated + +## Why This Architecture Rocks + +### ✅ **True Privacy** + +Data processing happens in secure enclaves. Workers can't peek, hackers can't +break in. + +### ✅ **User Ownership** + +Data owners control access programmatically. Revoke permissions anytime. + +### ✅ **Composable** + +Any iApp can use any Protected Data (if authorized). Build once, use everywhere. + +### ✅ **Monetizable** + +Data owners get paid automatically when their data gets used in tasks. + +## Start Building + +Now that you get the protocol, pick your devtools: + +- **📧 Quick Win**: Add [Web3Mail](/use_iapp/web3mail) or + [Web3Telegram](/use_iapp/web3telegram.md) to your project ! (uses the protocol + under the hood) +- **🛡️ Protect Data**: Try [DataProtector](/manage_data/dataProtector) to + encrypt your first dataset +- **🚀 Build iApps**: Create confidential compute with + [iApp Generator](/build_iapp/iapp-generator) +- **👋 Hands-On**: Follow our [Hello World](/overview/helloWorld) to see all + devtools working together + +--- + +**TL;DR**: iExec = Encrypted data + Secure computing + Your code → Private +results. Privacy made easy. diff --git a/overview/what-we-do.md b/overview/what-we-do.md deleted file mode 100644 index 224ef9f4..00000000 --- a/overview/what-we-do.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: What We Do -description: Discover iExec's decentralized computing platform ---- - -# 💡 What We Do - -iExec is a decentralized marketplace for computing resources. We enable -developers to build applications that combine **ownership**, **privacy**, and -**monetization**. - -## Our Mission - -We believe in a future where: - -- Data owners maintain control over their information -- Developers can access powerful computing resources on-demand -- Privacy is preserved through trusted execution environments -- Anyone can monetize their data and computing power - -## Key Technologies - -### Protected Data - -Secure your data while maintaining control over who can access and use it. - -### iApps (iExec Applications) - -Decentralized applications that run on the iExec network, ensuring privacy and -verifiability. - -### Trusted Execution Environments (TEE) - -Computing in secure enclaves that guarantee privacy and integrity. - -## Get Started - -Ready to build with iExec? Check out our -[Hello World guide](/overview/helloWorld) or explore our -[use cases](/overview/use-cases). - ---- - -_This documentation will help you understand and implement iExec's decentralized -computing solutions._ diff --git a/use_iapp/getting-started.md b/use_iapp/getting-started.md deleted file mode 100644 index 4fc88bcd..00000000 --- a/use_iapp/getting-started.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Getting Started with iApps -description: Démarrage avec les iApps ---- - -# 🚀 Getting Started - -Cette page est en cours de développement. - - diff --git a/use_iapp/introduction.md b/use_iapp/introduction.md index 29d3ae97..21ac9430 100644 --- a/use_iapp/introduction.md +++ b/use_iapp/introduction.md @@ -1,10 +1,174 @@ --- -title: Introduction to Using iApps -description: Introduction à l'utilisation des iApps +title: Getting Started with iApps +description: + From iApp to integration - understand tools vs custom iApps and choose your + path --- -# 📝 Introduction +# 🚀 Getting Started with iApps -Cette page est en cours de développement. +**iApps are applications that run inside secure enclaves (TEEs) on the iExec +network.** They can access and process Protected Data while keeping everything +private and verifiable. - +_New to iApps? Check out +[What Is an iApp?](/build_iapp/iapp-generator/what-is-iapp) to understand the +concept first._ + +## How iApp Execution Works + +When someone runs an iApp, here's what happens: + +1. **Task is submitted** to the iExec network with the iApp address and any + input data +2. **TEE worker picks up the task** - only workers with secure enclaves can + execute iApps +3. **iApp runs inside the TEE** - code executes in an isolated, tamper-proof + environment +4. **Results are encrypted** and sent back to the user who initiated the task + +This execution model ensures that even the worker running your iApp can't see +the data being processed. + +## Integration Challenge + +**You want to add privacy-first services to your application.** Whether you need +email functionality, oracle data, or custom privacy-preserving logic, iApps can +power your features without compromising user privacy. + +The question is: **how do you integrate them?** + +## Tools vs Other iApps + +Not all iApps are integrated the same way. There are three main categories: + +### 🛠️ **Tools (Ready-to-Use SDKs)** + +These are our **developer-friendly services** with polished SDKs: + +- **[Web3Mail](/use_iapp/web3mail)** - Private email functionality +- **[Web3Telegram](/use_iapp/web3telegram)** - Secure messaging via Telegram +- **[Oracle Factory](/use_iapp/oracle-factory)** - Decentralized oracle services + +**Why use these?** They come with: + +- ✅ Clean APIs and comprehensive documentation +- ✅ Built-in user flows and UX patterns +- ✅ Payment handling and error management +- ✅ Ready-to-use examples and quick setup + +### 🛡️ **DataProtector (Process Protected Data)** + +If your goal is to **process Protected Data** specifically: + +- **[DataProtector](/manage_data/dataProtector)** - SDK for processing Protected + Data in TEE environments +- Use `processProtectedData()` to run computation on encrypted datasets +- Built-in privacy guarantees and access control + +**Why use this?** When you need to: + +- ✅ Process users' Protected Data with your custom logic +- ✅ Combine multiple Protected Datasets securely +- ✅ Get privacy-preserving analytics results +- ✅ Keep data encrypted throughout the entire process + +### 🚀 **Custom iApps** + +These are **any other iApps** in the ecosystem: + +- Your own iApp that you built and deployed +- Third-party iApps created by other developers +- Specialized services for specific use cases + +**Integration is more manual** - you handle the execution flow, payments, and +user experience yourself. + +## Three Integration Paths + +### Path 1: Using Tool SDKs (Recommended for Tools) + +```javascript +// Clean, purpose-built APIs +import { IExecWeb3mail } from '@iexec/web3mail'; + +const web3mail = new IExecWeb3mail(web3Provider); +await web3mail.sendEmail({ + emailSubject: 'Welcome!', + emailContent: 'Thanks for signing up', + protectedData: userContactData, + contentType: 'text/html', +}); +``` + +### Path 2: Using DataProtector (For Processing Protected Data) + +```javascript +// Process Protected Data directly +import { IExecDataProtector } from '@iexec/dataprotector'; + +const dataprotector = new IExecDataProtector(web3Provider); +const result = await dataprotector.processProtectedData({ + protectedData: userHealthData, + app: 'health-risk-analyzer.eth', + maxPrice: 100, // RLC +}); +``` + +### Path 3: Using iExec SDK (For Custom iApps) + +```javascript +// General-purpose iApp execution +import { IExec } from 'iexec'; + +const iexec = new IExec({ ethProvider: web3Provider }); +const task = await iexec.task.run({ + app: 'your-sentiment-analysis-iapp.eth', + dataset: protectedTweetData, + params: { model: 'bert-sentiment' }, +}); +``` + +## Choose Your Path + +### ✅ **Use Tool SDKs if:** + +- You need email, messaging, or oracle functionality +- You want quick integration with minimal setup +- You prefer polished APIs and documentation +- You want UX patterns already figured out + +**→ Start with [Web3Mail](/use_iapp/web3mail), +[Web3Telegram](/use_iapp/web3telegram), or +[Oracle Factory](/use_iapp/oracle-factory)** + +### ✅ **Use DataProtector if:** + +- You need to process users' Protected Data +- You want built-in privacy guarantees for data processing +- You're building analytics or AI services on encrypted datasets +- You need to combine multiple Protected Datasets securely + +**→ Start with +[DataProtector Core](/manage_data/dataProtector/dataProtectorCore) and +[Protected Data Guide](/manage_data/dataProtector/what-is-protected-data)** + +### ✅ **Use iExec SDK if:** + +- You have a custom iApp (yours or third-party) +- You need specialized functionality not covered by our tools +- You want full control over the integration +- You're building advanced privacy-preserving workflows + +**→ Start with [General iApp Integration](/use_iapp/guides) and +[Payment Handling](/use_iapp/payment)** + +### 💡 **Not sure what you need?** + +Check out our [Hello World](/overview/helloWorld) tutorial to see all approaches +in action. + +--- + +**TL;DR**: Tools = Easy SDKs for common use cases. Custom iApps = Full +flexibility with more integration work. Choose based on your needs! 🎯