nova-app-builder

by zfdang

Install this Skill

curl -fsSL -o nova-app-builder.zip https://skill.seembox.com/api/v1/skills/nova-app-builder/download && unzip nova-app-builder.zip

Download nova-app-builder.zip

SKILL.md About

---
name: nova-app-builder
description: "Build and deploy Nova Platform apps (TEE apps on Sparsity Nova / sparsity.cloud). Use when a user wants to create a Nova app, write enclave application code, build it into a Docker image, and deploy it to the Nova Platform to get a live running URL. Handles the full lifecycle: scaffold, code, build, push, deploy, verify running. Triggers on requests like 'build me a Nova app', 'deploy to Nova Platform', 'create a TEE app on sparsity.cloud', 'I want to run an enclave app on Nova'."
---

# Nova App Builder

End-to-end workflow: scaffold → code → push to Git → create app → build → deploy → (on-chain: create app on-chain → enroll version → generate ZK proof → register instance).

## Architecture Overview

Nova apps run inside AWS Nitro Enclaves, managed by **Enclaver** (Sparsity edition) and supervised by **Odyn** (PID 1 inside the enclave). Key concepts:

- **Enclaver**: packages your Docker image into an EIF (Enclave Image File) and manages the enclave lifecycle.
- **Odyn**: supervisor inside the enclave; provides Internal API for signing, attestation, encryption, KMS, S3, and manages networking.
- **Nova Platform**: cloud platform at [sparsity.cloud](https://sparsity.cloud) — builds EIFs from Git, runs enclaves, exposes app URLs.
- **Nova KMS**: distributed key management; enclave apps derive keys via `/v1/kms/derive`.
- **Nova Python SDK**: canonical SDK in `enclave/nova_python_sdk/` — import as `from nova_python_sdk.odyn import Odyn`. Ships in nova-app-template and all examples.

## Two Development Paths

| | Minimal Scaffold | Full Template Fork |
|---|---|---|
| Starting point | `scripts/scaffold.py` | Fork [nova-app-template](https://github.com/sparsity-xyz/nova-app-template) |
| Config | `advanced` field in Platform API handles all config | Same — `advanced` field at app creation; platform generates `enclaver.yaml` |
| `enclaver.yaml` needed? | No — platform generates it | No — platform generates it from `advanced` |
| `enclave/config.py` | N/A | App-level business logic config (contract address, chain IDs, etc.) |
| Features | Minimal: signing, attestation, HTTP | Full: KMS, App Wallet, E2E encryption, S3, Helios, React UI, oracle |
| Best for | Simple or custom apps | Apps needing KMS/wallet/storage/frontend |

> ⚠️ **`enclaver.yaml` and `nova-build.yaml` are generated by Nova Platform** — developers never need to write or provide these files. The control plane generates both from app settings before triggering the build workflow. S3 storage and AWS credentials are fully managed by the platform; developers never touch them.

## Prerequisites (collect from user before starting)

> **Ensure skill is up to date before starting:**
> ```bash
> clawhub update nova-app-builder
> ```
> Older versions are missing `Dockerfile.txt` in the template, causing scaffold to fail.

- **App idea**: What does the app do?
- **Nova account + API key**: Sign up at [sparsity.cloud](https://sparsity.cloud) → Account → API Keys.
- **GitHub repo + GitHub PAT**: Used only to push your app code to GitHub. Nova Platform then builds from the repo URL. The PAT is not passed to Nova Platform.

**GitHub PAT setup**:
  1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Required permissions: **Contents** (Read & Write), **Metadata** (Read)
  3. Push with token:
     ```bash
     git remote set-url origin https://oauth2:${GH_TOKEN}@github.com/<user>/<repo>.git
     git push origin main
     ```

> ⚠️ **Do NOT ask for Docker registry credentials, AWS S3 credentials, or `enclaver.yaml`.**
> Nova Platform handles the Docker build, image registry, and S3/storage provisioning internally.
> Developers never touch AWS credentials or write `enclaver.yaml` — the platform generates it from the `advanced` field.
> The app only calls Internal API endpoints (`/v1/s3/*`) for storage; Odyn handles the rest.

## Full Workflow

### Step 1 — Scaffold the project

```bash
python3 scripts/scaffold.py \
  --name <app-name> \
  --desc "<one-line description>" \
  --port <port> \
  --out <output-dir>
```

> **Port choice**: Any port works. Set it via `advanced.app_listening_port` when creating the app. Must also match `EXPOSE` in your Dockerfile. No requirement to use 8080.

This generates `<output-dir>/<app-name>/` with the following structure:
```
<app-name>/
├── Dockerfile
└── enclave/
    ├── main.py
    ├── odyn.py
    └── requirements.txt
```

> **Note**: The template ships as `Dockerfile.txt` (clawhub cannot distribute extensionless files). `scaffold.py` automatically renames it to `Dockerfile` and substitutes the port. No manual action needed.

**Alternatively, fork [nova-app-template](https://github.com/sparsity-xyz/nova-app-template)** for the full production-ready structure:
```
nova-app-template/
├── Makefile
├── Dockerfile
├── enclaver.yaml          ← reference template only; portal parses listening port from it;
│                            platform generates the real enclaver.yaml from app settings
├── enclave/
│   ├── app.py             ← entry point (not main.py)
│   ├── routes.py          ← FastAPI route handlers
│   ├── config.py          ← app business logic config (chain RPCs, contract address, etc.)
│   ├── chain.py           ← chain interaction helpers (app-specific ABI, contract reads)
│   ├── tasks.py           ← background scheduler (oracle, periodic jobs)
│   ├── nova_python_sdk/   ← canonical Nova SDK (do not modify)
│   │   ├── odyn.py        ← identity, attestation, encryption, S3, KMS/app-wallet wrappers
│   │   ├── kms_client.py  ← thin client for KMS and app-wallet request handlers
│   │   ├── rpc.py         ← shared RPC transport + environment switching
│   │   └── env.py         ← IN_ENCLAVE + endpoint resolution helpers
│   └── requirements.txt
├── frontend/              ← React/Next.js UI (served at /frontend)
└── contracts/             ← example on-chain contracts
```
Features: KMS, App Wallet, E2E encryption, S3 (KMS-encrypted), Helios dual-chain RPC, React dashboard, example contracts, oracle.

### Step 2 — Write the app logic

Edit `enclave/main.py` (scaffold) or `enclave/routes.py` (full template). Key patterns:

**Minimal FastAPI app:**
```python
import os, httpx
from fastapi import FastAPI

app = FastAPI()
IN_ENCLAVE = os.getenv("IN_ENCLAVE", "false").lower() == "true"
ODYN_BASE = "http://localhost:18000" if IN_ENCLAVE else "http://odyn.sparsity.cloud:18000"

@app.get("/api/hello")
def hello():
    r = httpx.get(f"{ODYN_BASE}/v1/eth/address", timeout=10)
    return {"message": "Hello from TEE!", "enclave": r.json()["address"]}
```

> ⚠️ **`IN_ENCLAVE` is NOT injected automatically by Enclaver** — it's an app-level convention. Set it in your Dockerfile as `ENV IN_ENCLAVE=false` for local dev; the platform sets it `true` in production.

**Using the Nova Python SDK** (recommended for full template; copy from [nova-app-template](https://github.com/sparsity-xyz/nova-app-template)):
```python
from nova_python_sdk.odyn import Odyn
from nova_python_sdk.kms_client import NovaKmsClient

odyn = Odyn()  # auto-detects IN_ENCLAVE env var
kms = NovaKmsClient(endpoint=odyn.endpoint)

@app.get("/api/hello")
def hello():
    return {"address": odyn.eth_address(), "random": odyn.get_random_bytes().hex()}

@app.post("/api/sign")
def sign(body: dict):
    return odyn.sign_message(body["message"])

@app.post("/api/store")
def store(body: dict):
    odyn.s3_put(body["key"], body["value"].encode())
    return {"stored": True}
```

**With App Wallet + KMS:**
```python
from nova_python_sdk.kms_client import NovaKmsClient

kms = NovaKmsClient(endpoint=odyn.endpoint)

@app.get("/api/wallet")
def wallet():
    return kms.app_wallet_address()     # {"address": "0x...", "app_id": 0}

@app.post("/api/sign")
def sign(body: dict):
    return kms.app_wallet_sign(body["message"])   # {"signature": "0x..."}

@app.post("/api/sign-tx")
def sign_tx(body: dict):
    return kms.app_wallet_sign_tx(body)  # EIP-1559 transaction signing
```

**SDK module responsibilities:**
- `nova_python_sdk/odyn.py` — identity, attestation, encryption, S3, convenience wrappers around `/v1/kms/*` and `/v1/app-wallet/*`
- `nova_python_sdk/kms_client.py` — preferred thin client for KMS and app-wallet flows in request/response handlers
- `nova_python_sdk/rpc.py` — shared RPC transport + environment switching; keep app-specific contract logic in `enclave/chain.py`
- `nova_python_sdk/env.py` — shared `IN_ENCLAVE` and endpoint resolution helpers

**Runtime endpoint precedence (from `env.py`):**
- Odyn API: `ODYN_API_BASE_URL` → `ODYN_ENDPOINT` → `http://127.0.0.1:18000` (when `IN_ENCLAVE=true`) → `http://odyn.sparsity.cloud:18000` (otherwise)
- Business chain RPC: `ETHEREUM_MAINNET_RPC_URL` → `BUSINESS_CHAIN_RPC_URL` → `http://127.0.0.1:18546` (enclave) → `http://odyn.sparsity.cloud:18546` (otherwise)
- Auth chain RPC: `NOVA_AUTH_CHAIN_RPC_URL` → `AUTH_CHAIN_RPC_URL` → `http://127.0.0.1:18545` (enclave) → `http://odyn.sparsity.cloud:18545` (otherwise)

**Dual-chain topology** (as in the template):
- **Auth/Registry chain**: Base Sepolia (84532) — KMS authorization & app registry
- **Business chain**: Ethereum Mainnet (1) — your business logic

Helios light-client RPC runs locally at `http://127.0.0.1:18545` (Base Sepolia) and `http://127.0.0.1:18546` (Mainnet).

> ⚠️ **Helios RPC ports must be decided before creating the app** — they are set in `advanced.helios_chains[].local_rpc_port` and locked at creation time. Choose values carefully up front.

Rules for enclave code:
- **Odyn calls (localhost)**: `requests` or `httpx` both work — Odyn is local.
- **External outbound HTTP**: must use `httpx` (proxy-aware). Never use `requests` or `urllib` for external calls — they may bypass the egress proxy.
- Persistent state → use `/v1/s3/*` endpoints (or `odyn.s3_put()`); the enclave filesystem is ephemeral.
- Secrets → derive via KMS (`/v1/kms/derive`); never from env vars or hardcoded.
- Test locally: `IN_ENCLAVE=false python3 app.py` (scaffold: `uvicorn main:app --port <port>`). Odyn calls hit the public mock.

**`/.well-known/attestation` routing note:** In production Nova deployments, this endpoint is handled by Caddy routing to the Aux API (port 18001) — **not** your app code. Some examples implement it in app code as a local dev shim. Don't ship that in production.

### Step 3 — Commit & push to Git

Your repo only needs `Dockerfile` + app code. No local Docker build needed — Nova Platform builds from your Git repo directly.

KMS integration is fully handled by the platform — just set `enable_decentralized_kms: true` (and optionally `enable_app_wallet: true`) in `advanced` when creating the app. No contract addresses, app IDs, or manual KMS config needed in your code.

```bash
git add .
git commit -m "Initial Nova app"
git push origin main
```

### Step 4 — Deploy to Nova Platform

The deployment is a **3-step** process: **Create App → Trigger Build → Create Deployment**.

#### Via Portal (recommended for first-time)

**Portal flow (works for both scaffold and full template):**

1. Go to [sparsity.cloud](https://sparsity.cloud) → **Apps** → **Create App**
2. Fill in:
   - **Name**, **Repo URL**, optional Description, `metadata_uri`, `app_contract_addr`
   - Configure **Advanced** settings (port, egress, KMS, App Wallet, S3, Helios toggles, chain selection)
   - Submit → copy the **App sqid**

> The repo URL is stored on the app record and used for all subsequent builds — you don't provide it again at build time.

3. In the App page → **Versions** → **+ New Version**:
   - **Git Ref**: `main` (or tag / commit SHA)
   - **Version**: e.g. `1.0.0`
   - Submit

4. Wait for build status → `success` (platform builds Docker image → EIF → generates PCRs and `build-attestation.json` signed with Sigstore/cosign)

5. In **Versions**, find the successful version → **Deploy this version**:
   - Select **Region**
   - Select **Tier**: `standard` or `performance`
   - Submit

6. Poll until deployment state → `running` → copy the **App URL** (hostname from app detail)

> The deploy modal has no environment-variable input — no env vars or credentials needed.

#### Via API (scripted)

The script will ask interactively whether to run on-chain registration after the app is live. Use `--onchain` to always run it, `--no-onchain` to always skip.

```bash
# Preview config without deploying
python3 scripts/nova_deploy.py \
  --repo https://github.com/you/my-app \
  --name "my-app" \
  --port 8080 \
  --api-key <your-nova-api-key> \
  --dry-run

# Deploy (will prompt for on-chain at the end)
python3 scripts/nova_deploy.py \
  --repo https://github.com/you/my-app \
  --name "my-app" \
  --port 8080 \
  --api-key <your-nova-api-key>

# Deploy + on-chain registration in one shot
python3 scripts/nova_deploy.py \
  --repo https://github.com/you/my-app \
  --name "my-app" \
  --port 8080 \
  --api-key <your-nova-api-key> \
  --onchain
```

Or via raw API:

```bash
BASE="https://sparsity.cloud/api"
TOKEN="<your-api-key>"
REPO="https://github.com/you/my-app"

# 1. Create app — 'advanced' is the only config field needed
SQID=$(curl -sX POST "$BASE/apps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"my-app",
    "repo_url":"'"$REPO"'",
    "description":"optional description",
    "metadata_uri":"",
    "app_contract_addr":"",
    "advanced":{
      "directory":"/",
      "app_listening_port":8080,
      "egress_allow":["**"],
      "enable_decentralized_kms":false,
      "enable_persistent_storage":false,
      "enable_s3_storage":false,
      "enable_s3_kms_encryption":false,
      "enable_ipfs_storage":false,
      "enable_walrus_storage":false,
      "enable_app_wallet":false,
      "enable_helios_rpc":false
    }
  }' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['sqid'])")
echo "App sqid: $SQID"

# 2. Create new version (build) — repo URL comes from app record, not repeated here
BUILD_ID=$(curl -sX POST "$BASE/apps/$SQID/builds" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"git_ref":"main","version":"1.0.0"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "Build ID: $BUILD_ID"

# 3. Poll build
while true; do
  STATUS=$(curl -s "$BASE/builds/$BUILD_ID/status" \
    -H "Authorization: Bearer $TOKEN" \
    | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',''))")
  echo "Build: $STATUS"
  [ "$STATUS" = "success" ] && break
  [ "$STATUS" = "failed" ] && echo "Build failed!" && exit 1
  sleep 15
done

# 4. Deploy this version — specify region and tier
# region options: ap-south-1 (default), us-east-1, us-west-1, eu-west-1
# tier options: standard (2vCPU/5GiB), performance (6vCPU/13GiB)
DEPLOY_ID=$(curl -sX POST "$BASE/apps/$SQID/deployments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"build_id\":$BUILD_ID,\"region\":\"ap-south-1\",\"tier\":\"standard\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "Deployment ID: $DEPLOY_ID"

# 5. Poll deployment
while true; do
  RESP=$(curl -s "$BASE/deployments/$DEPLOY_ID/status" -H "Authorization: Bearer $TOKEN")
  STATE=$(echo $RESP | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('deployment_state',''))")
  echo "Deployment state: $STATE"
  [ "$STATE" = "running" ] && break
  [ "$STATE" = "failed" ] && echo "Deploy failed!" && exit 1
  sleep 15
done

# 6. Get app URL (hostname from detail, or use unified status)
curl -s "$BASE/apps/$SQID/detail" -H "Authorization: Bearer $TOKEN" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['app'].get('hostname',''))"

# Tip: GET /api/apps/{sqid}/status gives the full lifecycle in one call:
# build_status, deployment_state, proof_status, onchain_instance_id, etc.
```

### Step 5 — Verify the live app

```bash
# Health check
curl https://<hostname>/

# Hello endpoint (returns enclave address + signature)
curl https://<hostname>/api/hello

# Attestation (proves it's a real Nitro Enclave) — POST, returns binary CBOR
# In production, /.well-known/attestation is Caddy → Aux API; not app code
curl -sX POST https://<hostname>/.well-known/attestation --output attestation.bin
```

> **Note**: `/api/app-wallet` is only available if you forked [nova-app-template](https://github.com/sparsity-xyz/nova-app-template). The scaffold template includes `/api/hello` instead.

### Step 6 — On-Chain Registration (optional but important for trust)

After the app is running, register it on-chain to establish verifiable trust.

**Using the script** (recommended):
```bash
python3 scripts/nova_deploy.py ... --onchain
```
The script will automatically execute steps 6a–6d and poll until complete.

**Manually via API** — 4-step sequence:

```bash
# 6a. Create app on-chain
curl -sX POST "$BASE/apps/$SQID/create-onchain" \
  -H "Authorization: Bearer $TOKEN"
# Poll: GET /api/apps/{sqid}/status → onchain_app_id is set when done

# 6b. Enroll build version on-chain (PCR measurements → trusted code fingerprint)
curl -sX POST "$BASE/apps/$SQID/builds/$BUILD_ID/enroll" \
  -H "Authorization: Bearer $TOKEN"

# Poll enrollment via build status endpoint
while true; do
  ENROLLED=$(curl -s "$BASE/builds/$BUILD_ID/status" \
    -H "Authorization: Bearer $TOKEN" \
    | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('is_enrolled',''))")
  echo "Enrolled: $ENROLLED"
  [ "$ENROLLED" = "True" ] && break
  sleep 10
done

# 6c. Generate ZK proof (SP1-based)
curl -sX POST "$BASE/zkproof/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"deployment_id\": $DEPLOY_ID}"

# Poll proof via deployment status endpoint (or /zkproof/status/{deployment_id})
while true; do
  PROOF=$(curl -s "$BASE/deployments/$DEPLOY_ID/status" \
    -H "Authorization: Bearer $TOKEN" \
    | python3 -c "import sys,json; print(json.load(sys.stdin).get('proof_status',''))")
  echo "Proof status: $PROOF"
  [ "$PROOF" = "proved" ] && break
  [ "$PROOF" = "failed" ] && echo "Proof failed!" && exit 1
  sleep 30
done

# 6d. Register instance on-chain (manual — auto-registration has been removed)
curl -sX POST "$BASE/apps/$SQID/instance/register" \
  -H "Authorization: Bearer $TOKEN"

# Poll: GET /api/deployments/{id}/status → onchain_instance_id is set when done
# Or use unified: GET /api/apps/{sqid}/status → latest_onchain_instance_id
```

**What each step does:**
- **Create app on-chain**: Registers your app in the Nova App Registry contract (Base Sepolia)
- **Enroll version**: Records the EIF's PCR measurements on-chain — the trusted code fingerprint
- **Generate ZK proof**: Platform generates an SP1 zero-knowledge proof from the enclave's Nitro attestation
- **Register instance**: Verifies the ZK proof on-chain and links the live instance to its enrolled version

After registration, anyone can verify on-chain that this running instance matches the audited build.

## Odyn Internal API Reference

All endpoints are on `http://127.0.0.1:18000` (Primary API — inside enclave only, NOT publicly exposed in production).

**Always-available endpoints:**

| Endpoint | Method | Description |
|---|---|---|
| `/v1/eth/address` | GET | Enclave Ethereum address + public key |
| `/v1/eth/sign` | POST | EIP-191 personal-sign (optionally with attestation) |
| `/v1/eth/sign-tx` | POST | Sign EIP-1559 transactions |
| `/v1/random` | GET | 32 bytes from NSM-backed randomness |
| `/v1/attestation` | POST | Raw CBOR attestation bytes (not JSON) |
| `/v1/encryption/public_key` | GET | Enclave P-384 public key |
| `/v1/encryption/encrypt` | POST | Encrypt response to a client |
| `/v1/encryption/decrypt` | POST | Decrypt client payloads |

**Feature-gated endpoints (set in `advanced` at app creation):**

| Endpoint Group | Gate | Description |
|---|---|---|
| `/v1/s3/*` | `enable_s3_storage: true` | Base64 object storage backed by S3 |
| `/v1/kms/derive` | `enable_decentralized_kms: true` | Deterministic key derivation |
| `/v1/kms/kv/put\|get\|delete` | `enable_decentralized_kms: true` | KMS-backed KV store with optional TTL |
| `/v1/app-wallet/address` | `enable_app_wallet: true` | App-specific wallet address |
| `/v1/app-wallet/sign` | `enable_app_wallet: true` | EIP-191 message signing via app wallet |
| `/v1/app-wallet/sign-tx` | `enable_app_wallet: true` | EIP-1559 transaction signing via app wallet |

**Port exposure in production:**
- Runtime publishes exactly **two ports**: `host app port → enclave app port` and `host attestation port → enclave Aux API port 18001`
- `/.well-known/attestation*` is routed by Caddy to the host attestation port → Aux API (18001)
- **Primary API (18000) is NOT exposed publicly** for normal production apps

**Odyn mock service** (local development):
- Primary API: `http://odyn.sparsity.cloud:18000`
- Aux API: `http://odyn.sparsity.cloud:18001`
- Helios RPC presets: `http://odyn.sparsity.cloud:18545` through `:18553`

## Key Notes

1. **`advanced` is REQUIRED at app creation.** Omitting it will cause the build to fail. Only `advanced` exists — the old `enclaver` field has been removed from the API.
2. **Your repo only needs `Dockerfile` + app code.** The platform handles everything else at build time.
3. **App ID format**: `sqid` (string like `abc123`) — use in all URL paths, not the integer `id`.
4. **Port**: Set via `advanced.app_listening_port`. Must also match `EXPOSE` in Dockerfile. The `enclaver.yaml` in the template repo is a reference; portal reads the listening port from it.
5. **Repo URL is set once at app creation** — not repeated at build time. Build only needs `git_ref` + `version`.
6. **Deploy requires region + tier**: regions are `ap-south-1` (default), `us-east-1`, `us-west-1`, `eu-west-1`. `tier` is `"standard"` (2 vCPU/5 GiB) or `"performance"` (6 vCPU/13 GiB). No env var injection in deploy.
7. **Helios RPC**: Use the canonical port mapping in `references/nova-api.md` — ports are fixed and locked at app creation.
8. **KMS dependency chain**: `enable_app_wallet` or `enable_s3_kms_encryption` implies KMS → implies Helios (with base-sepolia chain) → implies `kms_app_id` + `nova_app_registry`.
9. **KMS/S3 fully managed by platform** — no AWS credentials, no `enclaver.yaml` authoring needed.
10. **No Docker push**: Platform builds from Git.
11. **On-chain steps** (create-onchain → enroll → ZK proof → register) are required for public verifiability, but optional for a functional running app.
12. **Instance registration is now manual** — auto-registration has been removed. Use `POST /api/apps/{app_sqid}/instance/register` after proof is `proved`.
13. **Portal helper APIs** (`clone-repo`, `get-enclaver-config`) are used by the portal UI to auto-fill the listening port from `enclaver.yaml` when you enter a repo URL. Not needed for direct API usage.
14. **Build provenance**: Builds produce a `build-attestation.json` with PCR0/PCR1/PCR2, source repo, commit, GitHub run metadata — signed with Sigstore/cosign and stored off-chain.
15. **`IN_ENCLAVE` is not injected by Enclaver** — set `ENV IN_ENCLAVE=false` in Dockerfile for local dev; production sets it `true`.

## Common Issues

| Symptom | Fix |
|---|---|
| `Dockerfile` missing after scaffold | Run `clawhub update nova-app-builder` then re-scaffold. The template ships as `Dockerfile.txt` and scaffold renames it to `Dockerfile` automatically. |
| App expects `enclaver.yaml` or old config | `enclaver.yaml` is always generated by Nova Platform — developers never provide it. The `advanced` field at app creation drives all platform-level config. Only `enclave/config.py` (app business logic) needs developer attention when using the full template. |
| API endpoint `console.sparsity.cloud` not resolving | Old version of `nova_deploy.py`. Run `clawhub update nova-app-builder`. Correct endpoint is `https://sparsity.cloud/api`. |
| `from odyn import Odyn` fails | Old import path. New SDK is at `nova_python_sdk/`. Use `from nova_python_sdk.odyn import Odyn`. |
| Build stuck in `pending` | Check GitHub Actions in nova build repo; may be queued |
| Build `failed` | Check `error_message` in build response; usually Dockerfile issue |
| Deploy API returns 401 | Regenerate API key at sparsity.cloud |
| App stuck in `provisioning` >10 min | Check app logs via `GET /api/apps/{sqid}/detail` |
| `httpx` request fails inside enclave | Add domain to `advanced.egress_allow`. Note: `"**"` matches domains only — add `"0.0.0.0/0"` for direct IP connections |
| Direct IP connection blocked | `"**"` does NOT cover IPs. Add `"0.0.0.0/0"` (IPv4) and/or `"::/0"` (IPv6) to `egress_allow` |
| S3 fails | Ensure `169.254.169.254` and S3 endpoint are in egress allow list |
| `/v1/kms/*` returns 400 | Ensure `enable_decentralized_kms: true` and `enable_helios_rpc: true` in `advanced` at app creation |
| App Wallet unavailable | Ensure `enable_app_wallet: true` in `advanced` at app creation |
| Proxy not respected for external calls | Use `httpx` for external HTTP calls (proxy-aware). `requests`/`urllib` may bypass the egress proxy. Note: `requests` is fine for internal Odyn calls (localhost). |
| Health check returns 502 | App is starting; wait for enclave to fully boot |
| ZK proof stuck | Check `GET /api/zkproof/status/{deployment_id}` for details |
| `/.well-known/attestation` returning wrong format in prod | In production, this is Caddy → Aux API routing — not app code. Remove app-side shim for production builds. |

## Reference Files

- **`references/odyn-api.md`** — Full Odyn Internal API (signing, encryption, S3, KMS, App Wallet, attestation)
- **`references/nova-api.md`** — Nova Platform REST API (full endpoint reference)

## Nova Examples

| Example | Description |
|---|---|
| [hello-world-tee](https://github.com/sparsity-xyz/sparsity-nova-examples/tree/main/hello-world-tee) | **Simplest start** — identity + attestation only; uses `nova_python_sdk/` |
| [echo-vault](https://github.com/sparsity-xyz/sparsity-nova-examples/tree/main/echo-vault) | **Best backend reference** — S3 persistence + Helios RPC; source of canonical SDK |
| [secured-chat-bot](https://github.com/sparsity-xyz/sparsity-nova-examples/tree/main/secured-chat-bot) | **Best E2E encryption reference** — browser-to-enclave P-384 ECDH |
| [rng-oracle](https://github.com/sparsity-xyz/sparsity-nova-examples/tree/main/oracles/rng-oracle) | On-chain randomness flow with enclave signing |
| [price-oracle](https://github.com/sparsity-xyz/sparsity-nova-examples/tree/main/oracles/price-oracle) | External API verification and signing patterns |

> **Nova Python SDK**: The canonical SDK lives in `enclave/nova_python_sdk/` in both [nova-app-template](https://github.com/sparsity-xyz/nova-app-template) and all examples. Do not modify SDK files — copy the whole directory into your project.

## Key URLs

- Nova Platform: https://sparsity.cloud
- **Nova Platform API docs**: https://sparsity.cloud/api/docs
- **Nova Sales Deck**: https://sparsity.cloud/decks/nova-sales-deck.html
- **Nova Resources**: https://sparsity.cloud/resources/
- Nova Examples: https://github.com/sparsity-xyz/sparsity-nova-examples/
- **Nova Python SDK (canonical)**: `enclave/nova_python_sdk/` in [nova-app-template](https://github.com/sparsity-xyz/nova-app-template) or [echo-vault](https://github.com/sparsity-xyz/sparsity-nova-examples/tree/main/echo-vault)
- Enclaver (Sparsity): https://github.com/sparsity-xyz/enclaver
- Nova App Template: https://github.com/sparsity-xyz/nova-app-template
- Enclaver Docs: [odyn.md](https://github.com/sparsity-xyz/enclaver/blob/sparsity/docs/odyn.md), [internal_api.md](https://github.com/sparsity-xyz/enclaver/blob/sparsity/docs/internal_api.md)
- Nova Platform Architecture: [build-attestation.md](https://github.com/sparsity-xyz/sparsity-nova-platform/blob/main/docs/build-attestation.md), [runtime-port-exposure-flow.md](https://github.com/sparsity-xyz/sparsity-nova-platform/blob/main/docs/runtime-port-exposure-flow.md)

_meta.json Metadata

{
  "ownerId": "kn75ynxa3j63qghnfr97w02xzs81vyrg",
  "publishedAt": 1773101175066,
  "slug": "nova-app-builder",
  "version": "2.3.1"
}