Skip to content

Commit 8bbd70c

Browse files
64ix64ix
committed
build iapp section guides
Content for some guides about how to build an iApp - Orders Management - Inputs and Outputs - Get and Decrypt the results - How to debug - How to use TDX Content is not verified, due to lack of time
1 parent 2776454 commit 8bbd70c

File tree

9 files changed

+1842
-56
lines changed

9 files changed

+1842
-56
lines changed

‎.vitepress/sidebar.ts‎

Lines changed: 5 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -361,39 +361,28 @@ export function getSidebar() {
361361
},
362362
{
363363
text: '📖  Guides',
364+
link: '/build_iapp/guides',
364365
collapsed: true,
365366
items: [
366367
{
367-
text: 'Manage Your iApps',
368-
link: '/build_iapp/iapp-generator/manage-iapps',
369-
},
370-
{
371-
text: 'Orders (how they work, how to manage them)',
368+
text: 'App Access Control and Pricing',
372369
link: '/build_iapp/guides/orders',
373370
},
374371
{
375-
text: 'Inputs and Outputs (types, differences, formats)',
372+
text: 'Inputs and Outputs',
376373
link: '/build_iapp/guides/inputs-and-outputs',
377374
},
378375
{
379376
text: 'Debugging Your iApp',
380377
link: '/build_iapp/guides/debugging-your-iapp',
381378
},
382-
{
383-
text: 'Using TDX (Trusted Execution) [EXPERIMENTAL]',
384-
link: '/build_iapp/guides/using-tdx-experimental',
385-
},
386379
{
387380
text: 'How to Get and Decrypt Results',
388381
link: '/build_iapp/guides/how-to-get-and-decrypt-results',
389382
},
390383
{
391-
text: 'AI Frameworks',
392-
link: '/build_iapp/iapp-generator/ai-frameworks',
393-
},
394-
{
395-
text: 'Other Emerging Trends',
396-
link: '/build_iapp/guides/other-emerging-trends',
384+
text: 'Using TDX (Experimental)',
385+
link: '/build_iapp/guides/using-tdx-experimental',
397386
},
398387
],
399388
},

‎build_iapp/guides.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: iApp Building Guides
3+
description:
4+
Step-by-step guides for building, deploying, and managing your privacy-first
5+
iApps
6+
---
7+
8+
# 📖 iApp Building Guides
9+
10+
**Master iApp development from code to production** with these comprehensive
11+
step-by-step guides. Each guide focuses on a specific aspect of building
12+
privacy-preserving applications with iExec.
13+
14+
## Essential Guides
15+
16+
### 💰 [App Access Control and Pricing](/build_iapp/guides/orders)
17+
18+
**Control who can use your iApp and monetize it.** Learn how to create app
19+
orders to make your iApp accessible while defining pricing and access
20+
restrictions.
21+
22+
- Create and manage app orders with iExec SDK
23+
- Configure pricing, volume limits, and restrictions
24+
- Understand TEE requirements and workerpool restrictions
25+
- Common monetization patterns and use cases
26+
27+
---
28+
29+
### 📥📤 [Inputs and Outputs](/build_iapp/guides/inputs-and-outputs)
30+
31+
**Handle data flow in your iApp's TEE environment.** Master the different input
32+
types and learn how to generate proper outputs that users can retrieve.
33+
34+
- 4 input types: Args, Input Files, Requester Secrets, Protected Data
35+
- Access methods via environment variables and file system
36+
- TEE memory constraints and best practices
37+
- Output structure with mandatory `computed.json`
38+
39+
---
40+
41+
### 🐛 [Debugging Your iApp](/build_iapp/guides/debugging-your-iapp)
42+
43+
**Troubleshoot and optimize your iApp execution in the TEE environment.** Master
44+
debugging techniques and best practices for reliable iApp development.
45+
46+
- Task execution lifecycle and monitoring
47+
- iExec Explorer and CLI debugging tools
48+
- Common issues: timeouts, memory limits, input/output problems
49+
- Best practices: input validation, error handling, performance optimization
50+
51+
---
52+
53+
### 📦 [How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results)
54+
55+
**Download and decrypt iApp execution results from completed tasks.** Learn the
56+
complete workflow for retrieving and using iApp outputs.
57+
58+
- Deal → Task → Result structure and accessibility
59+
- Download methods: iExec CLI and DataProtector SDK
60+
- Automatic vs manual decryption workflows
61+
- Integration patterns for React and Node.js applications
62+
63+
---
64+
65+
### 🛡️ [Using TDX (Experimental)](/build_iapp/guides/using-tdx-experimental)
66+
67+
**Enable Intel TDX for enhanced TEE security - experimental feature only.**
68+
Understand how to activate TDX and when to use it.
69+
70+
- How to enable TDX in iApp Generator deployment and execution
71+
- SGX vs TDX differences and compatibility requirements
72+
- Protected data compatibility considerations
73+
- Production warnings and experimental limitations
74+
75+
## Quick Navigation
76+
77+
::: tip What You'll Learn These guides cover the complete journey from iApp
78+
development to production deployment, user access management, and result
79+
handling. :::
80+
81+
### By Development Stage
82+
83+
- **🚀 Just built your iApp?** →
84+
[App Access Control and Pricing](/build_iapp/guides/orders)
85+
- **🔧 Handling data flow?** →
86+
[Inputs and Outputs](/build_iapp/guides/inputs-and-outputs)
87+
- **🐛 Having issues?** →
88+
[Debugging Your iApp](/build_iapp/guides/debugging-your-iapp)
89+
- **📦 Need results?** →
90+
[How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results)
91+
92+
### By User Type
93+
94+
**iApp Developer**: You build the privacy-preserving application
95+
→ [Inputs and Outputs](/build_iapp/guides/inputs-and-outputs) +
96+
[Debugging](/build_iapp/guides/debugging-your-iapp)
97+
98+
**App Owner**: You deploy and monetize the iApp
99+
→ [App Access Control and Pricing](/build_iapp/guides/orders)
100+
101+
**End User Guide**: Your users need to retrieve results
102+
→ [How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results)
103+
104+
## Development Workflow
105+
106+
### 1. **Build Your iApp**
107+
108+
Start with [iApp Generator](/build_iapp/iapp-generator) to create your
109+
privacy-preserving application.
110+
111+
### 2. **Handle Data Flow**
112+
113+
Use the [Inputs and Outputs](/build_iapp/guides/inputs-and-outputs) guide to
114+
properly access different input types and generate results.
115+
116+
### 3. **Debug and Test**
117+
118+
Follow the [Debugging](/build_iapp/guides/debugging-your-iapp) guide to
119+
troubleshoot issues and optimize performance.
120+
121+
### 4. **Control Access**
122+
123+
Implement [App Access Control and Pricing](/build_iapp/guides/orders) to make
124+
your iApp accessible with proper monetization.
125+
126+
### 5. **User Experience**
127+
128+
Implement [Result Retrieval](/build_iapp/guides/how-to-get-and-decrypt-results)
129+
to provide users with seamless access to iApp outputs.
130+
131+
## Additional Resources
132+
133+
### 📚 **iApp Generator**
134+
135+
- [What Is an iApp?](/build_iapp/iapp-generator/what-is-iapp) - Core concepts
136+
and overview
137+
- [Getting Started](/build_iapp/iapp-generator/getting-started) - Your first
138+
iApp in 15 minutes
139+
- [Building Your iApp](/build_iapp/iapp-generator/building-your-iexec-app) -
140+
Complete development guide
141+
142+
### 🎯 **Real Examples**
143+
144+
- [Hello World Tutorial](/overview/helloWorld) - End-to-end iApp development
145+
- [AI Use Cases](/overview/use-cases/ai) - AI-powered privacy applications
146+
147+
### 🔧 **Advanced Topics**
148+
149+
- [SDK Deep Dive](/deep_dive/sdk) - Advanced SDK concepts and usage
150+
- [Workers & Workerpools](/deep_dive/workers) - Understanding the execution
151+
infrastructure
152+
153+
---
154+
155+
**Ready to build privacy-first applications?** Pick the guide that matches your
156+
current development stage and start building! 🚀

‎build_iapp/guides/debugging-your-iapp.md‎

Lines changed: 164 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,170 @@
11
---
22
title: Debugging Your iApp
3-
description: Déboguer votre iApp
3+
description:
4+
Troubleshoot and optimize your iApp execution in the TEE environment
45
---
56

6-
# Debugging Your iApp
7+
# 🐛 Debugging Your iApp
78

8-
Cette page est en cours de développement.
9+
**When your iApp doesn't work as expected, debugging in the TEE environment
10+
requires specific techniques.** This guide helps you identify issues and
11+
optimize your iApp's performance.
912

10-
<!-- TODO: Ajouter le guide de débogage -->
13+
## Task Execution Lifecycle
14+
15+
Understanding how your task progresses through the iExec network:
16+
17+
### Key Stages
18+
19+
1. **Deal Creation** - Orders matched, funds locked
20+
2. **Task Initialization** - Workers selected for execution
21+
3. **iApp Execution** - Your code runs inside TEE
22+
4. **Result Processing** - Results encrypted and uploaded
23+
5. **Task Completion** - Results available for download
24+
25+
**Most failures happen during stages 2-4**
26+
27+
## Monitoring Your Tasks
28+
29+
### iExec Explorer
30+
31+
Track your tasks at [explorer.iex.ec](https://explorer.iex.ec):
32+
33+
- Search by `taskId` or deal ID
34+
- Check status: `PENDING` → `ACTIVE` → `COMPLETED/FAILED`
35+
- View error messages if execution fails
36+
37+
### Status in Code
38+
39+
```typescript
40+
const response = await dataProtectorCore.processProtectedData({
41+
protectedData: '0x123abc...',
42+
app: '0x456def...',
43+
onStatusUpdate: ({ title, isDone }) => {
44+
console.log(`Status: ${title} - Done: ${isDone}`);
45+
},
46+
});
47+
```
48+
49+
## Debug Commands
50+
51+
### Local Testing
52+
53+
```bash
54+
# Test your iApp locally
55+
iapp test --args "model=bert threshold=0.8"
56+
iapp test --secrets "key1=value1,key2=value2"
57+
58+
# Mock protected data for testing
59+
iapp mock protectedData
60+
iapp test --protectedData "mock_name"
61+
```
62+
63+
### Remote Debugging
64+
65+
```bash
66+
# Deploy and run
67+
iapp deploy
68+
iapp run <iapp-address>
69+
70+
# Debug failed executions
71+
iapp debug <taskId>
72+
```
73+
74+
### Task Information
75+
76+
```bash
77+
# View task details
78+
iexec task show <taskId>
79+
80+
# Download results (if completed)
81+
iexec task show <taskId> --download
82+
```
83+
84+
## Common Issues
85+
86+
### ⏱️ **Task Timeout**
87+
88+
- **Cause**: Code takes too long to execute
89+
- **Solution**: Optimize algorithms, reduce input sizes, use appropriate task
90+
category
91+
92+
### 💾 **Memory Issues**
93+
94+
- **Cause**: Loading large files, memory leaks, TEE constraints
95+
- **Solution**: Process data in chunks, use streaming, optimize memory usage
96+
97+
### 📁 **Input/Output Problems**
98+
99+
- **Cause**: Wrong file paths, missing `computed.json`
100+
- **Solution**: Always create `computed.json`, verify environment variables
101+
102+
```python
103+
# Always create computed.json
104+
import json, os
105+
computed = {"deterministic-output-path": f"{os.environ['IEXEC_OUT']}/result.json"}
106+
with open(f"{os.environ['IEXEC_OUT']}/computed.json", 'w') as f:
107+
json.dump(computed, f)
108+
```
109+
110+
## Best Practices
111+
112+
### 🔍 **Input Validation**
113+
114+
```python
115+
import os, sys
116+
117+
# Check required environment variables
118+
if not os.environ.get('IEXEC_IN') or not os.environ.get('IEXEC_OUT'):
119+
print("ERROR: Missing IEXEC_IN or IEXEC_OUT")
120+
sys.exit(1)
121+
122+
# Validate arguments
123+
if len(sys.argv) < 2:
124+
print("ERROR: Missing required arguments")
125+
sys.exit(1)
126+
```
127+
128+
### 📝 **Clear Error Messages**
129+
130+
```python
131+
try:
132+
# Your processing logic
133+
result = process_data(data)
134+
except Exception as e:
135+
print(f"ERROR: Processing failed: {str(e)}")
136+
sys.exit(1)
137+
```
138+
139+
### 🔒 **Safe File Operations**
140+
141+
```python
142+
import os, json
143+
144+
# Always ensure output directory exists
145+
iexec_out = os.environ['IEXEC_OUT']
146+
os.makedirs(iexec_out, exist_ok=True)
147+
148+
# Write results safely
149+
try:
150+
with open(f"{iexec_out}/result.json", 'w') as f:
151+
json.dump(result_data, f)
152+
except Exception as e:
153+
print(f"ERROR: Failed to write results: {e}")
154+
sys.exit(1)
155+
```
156+
157+
## What's Next?
158+
159+
Continue improving your iApps:
160+
161+
- **[Inputs and Outputs](/build_iapp/guides/inputs-and-outputs)** - Handle data
162+
in TEE
163+
- **[How to Get and Decrypt Results](/build_iapp/guides/how-to-get-and-decrypt-results)** -
164+
Retrieve results
165+
166+
---
167+
168+
**TL;DR**: Use Explorer to track tasks → Test locally with `iapp test` → Debug
169+
remote issues with `iapp debug` → Always validate inputs and create
170+
`computed.json`! 🚀

0 commit comments

Comments
 (0)