nova-app-builder

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

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 )
   
  [  =  ] && 
  [  =  ] &&   &&  1
   15





DEPLOY_ID=$(curl -sX POST  \
  -H  \
  -H  \
  -d  \
  | python3 -c )
 


 ; 
  RESP=$(curl -s  -H )
  STATE=$(  | python3 -c )
   
  [  =  ] && 
  [  =  ] &&   &&  1
   15



curl -s  -H  \
  | python3 -c 

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 "/deployments//status" \
    -H  \
    | python3 -c )
   
  [  =  ] && 
  [  =  ] &&   &&  1
   30



curl -sX POST  \
  -H 

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 when you enter a repo URL. Not needed for direct API usage.

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 and in at app creation

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	Simplest start — identity + attestation only; uses nova_python_sdk/
echo-vault	Best backend reference — S3 persistence + Helios RPC; source of canonical SDK
secured-chat-bot	Best E2E encryption reference — browser-to-enclave P-384 ECDH
rng-oracle	On-chain randomness flow with enclave signing
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 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