nova-app-builder

构建和部署 Nova 平台应用程序（Sparsity Nova / sparsity.cloud 上的 TEE 应用程序）。当用户想要创建 Nova 应用程序、编写 enclave 应用程序代码、将其构建到 Docker 映像并将其部署到 Nova 平台以获得实时运行的 URL 时使用。处理完整的生命周期：脚手架、代码、构建、推送、部署、验证运行。触发“为我构建一个 Nova 应用程序”、“部署到 Nova 平台”、“在 sparsity.cloud 上创建 TEE 应用程序”、“我想在 Nova 上运行一个 enclave 应用程序”等请求。

## 概述（中文）

构建和部署 Nova 平台应用程序（Sparsity Nova / sparsity.cloud 上的 TEE 应用程序）。当用户想要创建 Nova 应用程序、编写 enclave 应用程序代码、将其构建到 Docker 映像并将其部署到 Nova 平台以获得实时运行的 URL 时使用。处理完整的生命周期：脚手架、代码、构建、推送、部署、验证运行。触发“为我构建一个 Nova 应用程序”、“部署到 Nova 平台”、“在 sparsity.cloud 上创建 TEE 应用程序”、“我想在 Nova 上运行一个 enclave 应用程序”等请求。

## 原文

# 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