nova-app-builder

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 en