Nova App Builder

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

<app-name>/
├── Dockerfile
└── enclave/
    ├── main.py
    ├── odyn.py
    └── requirements.txt

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

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"]}

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}

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

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

# 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

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.

# 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

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

# 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