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 — 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

⚠️ 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:

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 → 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:

     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

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 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:

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):

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:

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.

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 → 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.

# 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:

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

# 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. 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):

python3 scripts/nova_deploy.py ... --onchain

The script will automatically execute steps 6a–6d and poll until complete.

Manually via API — 4-step sequence:

# 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:

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

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

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

Nova Python SDK: The canonical SDK lives in enclave/nova_python_sdk/ in both 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 or 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, internal_api.md
• Nova Platform Architecture: build-attestation.md, runtime-port-exposure-flow.md