{"id":48545604,"url":"https://github.com/sparsity-xyz/nova-app-template","last_synced_at":"2026-04-08T06:30:42.293Z","repository":{"id":334874058,"uuid":"1140279930","full_name":"sparsity-xyz/nova-app-template","owner":"sparsity-xyz","description":"nova app template for developers to start with","archived":false,"fork":false,"pushed_at":"2026-03-13T13:46:23.000Z","size":737,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-13T14:42:14.298Z","etag":null,"topics":["aws","enclave","enclaver","nitro","nova","sparsity","tee"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sparsity-xyz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-23T04:04:21.000Z","updated_at":"2026-03-13T13:46:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sparsity-xyz/nova-app-template","commit_stats":null,"previous_names":["sparsity-xyz/nova-app-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sparsity-xyz/nova-app-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fnova-app-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fnova-app-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fnova-app-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fnova-app-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sparsity-xyz","download_url":"https://codeload.github.com/sparsity-xyz/nova-app-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fnova-app-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31544081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","enclave","enclaver","nitro","nova","sparsity","tee"],"created_at":"2026-04-08T06:30:41.641Z","updated_at":"2026-04-08T06:30:42.282Z","avatar_url":"https://github.com/sparsity-xyz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nova App Template\n\n## 1. Introduction\nThis repository is a Nova app example with:\n- FastAPI backend in [`enclave/`](./enclave)\n- Next.js frontend panel in [`frontend/`](./frontend)\n- Example contracts in [`contracts/`](./contracts)\n- Repo `capsule.yaml` template (portal can parse listening port and file-proxy mount config from it)\n\nThe backend includes public endpoints (`/health`, `/status`, `/.well-known/attestation`) and `/api/*` demo endpoints for KMS, app-wallet, S3 storage, mounted directory access, encryption, oracle, and event monitoring.\n\n## 2. Features Included\n- **Attestation + Identity**: Fetch Nitro attestation and TEE wallet identity.\n- **E2E Encryption Demo**: ECDH + AES-GCM request/response flow.\n- **Dual-Chain Defaults**: Auth chain Base Sepolia (`84532`) and business chain Ethereum mainnet (`1`) in template config.\n- **KMS + KV APIs**: `/api/kms/derive`, `/api/kms/kv/get|put|delete`.\n- **App Wallet APIs**: `/api/app-wallet/address|sign|sign-tx`.\n- **S3 Storage APIs**: `/api/storage*` plus `/api/storage/config`.\n- **Mounted Directory APIs**: `/api/filesystem/config|write|read|list`.\n- **Frontend Test Panel**: One-page UI to exercise all demo APIs.\n\n## 3. Deploy on Nova Platform (Current Flow)\n\n### 3.1 Create App\n1. Open **Apps** in Nova portal and click **Create App**.\n2. Fill basic fields (`name`, `repo_url`, optional `description`, `metadata_uri`, `app_contract_addr`).\n3. Configure advanced options in the form (for example app listening port, KMS/App Wallet/S3/Mounted Directory/Helios toggles, chain selection).\n4. Submit. The platform creates an app and assigns `sqid`.\n\n### 3.2 Create Version (Build)\n1. Open the app detail page, then open **Versions**.\n2. Click **+ New Version**.\n3. Submit `git_ref` and semantic `version` (for example `main` and `1.0.0`).\n4. Wait for build status to become `success`.\n\nNotes aligned with control-plane implementation:\n- Repository URL is taken from the app record created in step 3.1.\n- Build input is `git_ref + version`; there is no extra repository field in the build form.\n- Control-plane generates `nova-build.yaml` and `capsule.yaml` in app-hub from app settings before triggering workflow.\n\n### 3.3 Deploy Version\n1. In **Versions**, choose a successful version and click **Deploy this version**.\n2. In deploy modal, choose `region` and `tier` (`standard` or `performance`).\n3. Submit deployment and track state transitions in **Deployments**.\n\nNotes aligned with portal/API:\n- Deploy request fields are `build_id`, `region`, optional `tier`, optional `app_contract_addr`.\n- Current deploy UI has no environment-variable input section.\n\n## 4. Local Development Quick Start\n```bash\n# 1) Start frontend dev server\nmake dev-frontend\n\n# 2) Build frontend static assets for backend serving\nmake build-frontend\n\n# 3) Start backend locally (IN_ENCLAVE=false)\nmake dev-backend\n```\nBackend serves:\n- **API Endpoint:** `http://localhost:8000`\n- **UI Dashboard:** `http://localhost:8000/frontend/`\n\nDefault local chain behavior:\n- Auth chain reads prefer mockup Helios at `http://capsule-runtime.sparsity.cloud:18545`\n- Business chain reads prefer mockup Helios at `http://capsule-runtime.sparsity.cloud:18546`\n- When `IN_ENCLAVE=true`, the same logic switches to enclave-local Helios on `127.0.0.1:18545` and `127.0.0.1:18546`\n\nStartup note:\n- On boot, the backend tries to restore `app_state.json` through Capsule Runtime S3. In local mockup mode this may return no state or fail transiently; the app logs `Starting fresh...` and continues with an empty in-memory state.\n\nPlatform-managed deploy note:\n- Actual platform builds/deployments use control-plane generated app-hub `capsule.yaml` from app settings.\n\n## 5. Using `nova_python_sdk`\n\nThe canonical backend SDK lives in [`enclave/nova_python_sdk/`](./enclave/nova_python_sdk). Because the Docker image copies `enclave/` into the runtime image, backend modules inside [`enclave/`](./enclave) can import it directly:\n\n```python\nfrom nova_python_sdk.capsule_runtime import CapsuleRuntime\nfrom nova_python_sdk.kms_client import NovaKmsClient\nfrom nova_python_sdk.rpc import ChainRpc\n\ncapsule_runtime = CapsuleRuntime()\nkms = NovaKmsClient(endpoint=capsule_runtime.endpoint)\n```\n\nUse each SDK module for one responsibility:\n- [`enclave/nova_python_sdk/capsule_runtime.py`](./enclave/nova_python_sdk/capsule_runtime.py): identity, attestation, encryption, S3, and convenience wrappers around `/v1/kms/*` and `/v1/app-wallet/*`\n- [`enclave/nova_python_sdk/kms_client.py`](./enclave/nova_python_sdk/kms_client.py): preferred thin client for KMS and app-wallet flows in request/response handlers\n- [`enclave/nova_python_sdk/rpc.py`](./enclave/nova_python_sdk/rpc.py): shared RPC transport and environment switching; keep app-specific contract logic in [`enclave/chain.py`](./enclave/chain.py)\n- [`enclave/nova_python_sdk/env.py`](./enclave/nova_python_sdk/env.py): shared `IN_ENCLAVE` and endpoint resolution helpers\n\nRuntime endpoint precedence:\n- Capsule API: `CAPSULE_RUNTIME_API_BASE_URL` -\u003e `CAPSULE_RUNTIME_ENDPOINT` -\u003e `http://127.0.0.1:18000` when `IN_ENCLAVE=true` -\u003e `http://capsule-runtime.sparsity.cloud:18000` otherwise\n- Business chain RPC: `ETHEREUM_MAINNET_RPC_URL` -\u003e `BUSINESS_CHAIN_RPC_URL` -\u003e `http://127.0.0.1:18546` when `IN_ENCLAVE=true` -\u003e `http://capsule-runtime.sparsity.cloud:18546` otherwise\n- Auth chain RPC: `NOVA_AUTH_CHAIN_RPC_URL` -\u003e `AUTH_CHAIN_RPC_URL` -\u003e `http://127.0.0.1:18545` when `IN_ENCLAVE=true` -\u003e `http://capsule-runtime.sparsity.cloud:18545` otherwise\n\nRecommended template pattern:\n1. Create one shared `CapsuleRuntime()` instance in [`enclave/app.py`](./enclave/app.py).\n2. In route modules, build `NovaKmsClient(endpoint=capsule_runtime.endpoint)` when you need `/v1/kms/*` or `/v1/app-wallet/*`.\n3. In [`enclave/chain.py`](./enclave/chain.py), build shared chain clients with `ChainRpc` and keep ABI selectors, contract read helpers, and transaction builders there.\n\n## 6. Module Learning Map (Functionality + APIs + Implementation)\n\nThis section is intended for developers who want to **learn and reuse** each module.\n\n### 6.1 Identify \u0026 Attestation\n- **What it demonstrates**\n  - Connecting to an enclave (via registry or direct URL)\n  - Fetching and decoding AWS Nitro attestation\n  - Displaying enclave identity (wallet + TEE pubkey)\n- **App APIs used**\n  - `GET /status`\n  - `POST /.well-known/attestation`\n  - `GET /api/encryption/public_key`\n- **Capsule APIs involved**\n  - `GET /v1/eth/address`\n  - `POST /v1/attestation`\n  - `GET /v1/encryption/public_key`\n- **Implementation entry points**\n  - Frontend: [`frontend/src/app/page.tsx`](./frontend/src/app/page.tsx) (`identity` tab + connection panel)\n  - Frontend crypto transport: [`frontend/src/lib/crypto.ts`](./frontend/src/lib/crypto.ts)\n  - Registry integration: [`frontend/src/lib/registry.ts`](./frontend/src/lib/registry.ts)\n  - Backend routes: [`enclave/routes.py`](./enclave/routes.py)\n\n### 6.2 Hardware Entropy\n- **What it demonstrates**\n  - Hardware-backed random source from Nitro Secure Module\n- **App APIs used**\n  - `GET /api/random`\n- **Capsule APIs involved**\n  - `GET /v1/random`\n- **Implementation entry points**\n  - Frontend: [`frontend/src/app/page.tsx`](./frontend/src/app/page.tsx) (`hardware-entropy` tab)\n  - Backend handler: [`enclave/routes.py`](./enclave/routes.py) (`/api/random`)\n\n### 6.3 Secure Echo (End-to-End Encrypted Request)\n- **What it demonstrates**\n  - Client-side request encryption and enclave-side decryption\n  - Encrypted response return path\n- **App APIs used**\n  - `POST /api/echo`\n- **Capsule APIs involved**\n  - `POST /v1/encryption/encrypt`\n  - `POST /v1/encryption/decrypt`\n  - `GET /v1/encryption/public_key`\n- **Implementation entry points**\n  - Frontend: [`frontend/src/app/page.tsx`](./frontend/src/app/page.tsx) (`secure-echo` tab)\n  - Crypto helper: [`frontend/src/lib/crypto.ts`](./frontend/src/lib/crypto.ts)\n  - Backend handler: [`enclave/routes.py`](./enclave/routes.py) (`/api/echo`)\n\n### 6.4 S3 Storage (single module, encryption-aware)\n- **What it demonstrates**\n  - Put/Get/List/Delete object-style app data\n  - Runtime inspection of current S3 encryption mode\n- **App APIs used**\n  - `POST /api/storage`\n  - `GET /api/storage/{key}`\n  - `GET /api/storage`\n  - `DELETE /api/storage/{key}`\n  - `GET /api/storage/config`\n- **Capsule APIs involved**\n  - `POST /v1/s3/put`\n  - `POST /v1/s3/get`\n  - `POST /v1/s3/list`\n  - `POST /v1/s3/delete`\n- **Implementation entry points**\n  - Frontend: [`frontend/src/app/page.tsx`](./frontend/src/app/page.tsx) (`storage` tab)\n  - Backend handlers: [`enclave/routes.py`](./enclave/routes.py) (`/api/storage*` and `/api/storage/config`)\n  - Runtime config: [`capsule.yaml`](./capsule.yaml) (`storage.s3.*`, `storage.s3.encryption.mode`)\n\n### 6.5 Mounted Directory\n- **What it demonstrates**\n  - Mounting a host-backed loopback image into the enclave\n  - Reading and writing regular files with normal filesystem APIs\n  - Inspecting mount status and available capacity\n- **App APIs used**\n  - `GET /api/filesystem/config`\n  - `POST /api/filesystem/write`\n  - `GET /api/filesystem/read`\n  - `GET /api/filesystem/list`\n- **Capsule runtime bindings involved**\n  - Hostfs mount defined under `storage.mounts[]`\n  - Runtime binding via `capsule-cli run --mount \u003cname\u003e=\u003chost_state_dir\u003e`\n- **Implementation entry points**\n  - Frontend: [`frontend/src/app/page.tsx`](./frontend/src/app/page.tsx) (`filesystem` tab)\n  - Backend handlers: [`enclave/routes.py`](./enclave/routes.py) (`/api/filesystem/*`)\n  - Runtime config: [`capsule.yaml`](./capsule.yaml) (`storage.mounts`)\n\n### 6.6 KMS Demo\n- **What it demonstrates**\n  - Deterministic key derivation\n  - KMS-backed key/value operations (put/get/delete + TTL)\n- **App APIs used**\n  - `POST /api/kms/derive`\n  - `POST /api/kms/kv/put`\n  - `POST /api/kms/kv/get`\n  - `POST /api/kms/kv/delete`\n- **Capsule APIs involved**\n  - `POST /v1/kms/derive`\n  - `POST /v1/kms/kv/put`\n  - `POST /v1/kms/kv/get`\n  - `POST /v1/kms/kv/delete`\n- **Implementation entry points**\n  - Frontend: [`frontend/src/app/page.tsx`](./frontend/src/app/page.tsx) (`kms-demo` tab)\n  - Backend handlers: [`enclave/routes.py`](./enclave/routes.py) (`/api/kms/*`)\n  - Canonical SDK: [`enclave/nova_python_sdk/kms_client.py`](./enclave/nova_python_sdk/kms_client.py)\n\n### 6.7 App Wallet Sign\n- **What it demonstrates**\n  - Querying app-specific wallet address\n  - EIP-191 message signing via app wallet\n- **App APIs used**\n  - `GET /api/app-wallet/address`\n  - `POST /api/app-wallet/sign`\n  - `POST /api/app-wallet/sign-tx` (backend supports tx signing)\n- **Capsule APIs involved**\n  - `GET /v1/app-wallet/address`\n  - `POST /v1/app-wallet/sign`\n  - `POST /v1/app-wallet/sign-tx`\n- **Implementation entry points**\n  - Frontend: [`frontend/src/app/page.tsx`](./frontend/src/app/page.tsx) (`app-wallet` tab)\n  - Backend handlers: [`enclave/routes.py`](./enclave/routes.py) (`/api/app-wallet/*`)\n  - Wallet SDK: [`enclave/nova_python_sdk/kms_client.py`](./enclave/nova_python_sdk/kms_client.py)\n\n### 6.8 Oracle Demo (Internet → Chain)\n- **What it demonstrates**\n  - Fetching external market data in enclave\n  - Building/signing/submitting chain updates\n  - Periodic scheduler + API trigger\n- **App APIs used**\n  - `POST /api/oracle/update-now`\n  - `GET /status` (for cron counters)\n  - `GET /api/events/oracle` and related event monitoring routes\n- **Implementation entry points**\n  - Frontend: [`frontend/src/app/page.tsx`](./frontend/src/app/page.tsx) (`oracle` tab)\n  - Backend routes: [`enclave/routes.py`](./enclave/routes.py) (`/api/oracle/*`, `/api/events/*`)\n  - Scheduler tasks: [`enclave/tasks.py`](./enclave/tasks.py)\n  - App-specific chain logic: [`enclave/chain.py`](./enclave/chain.py)\n  - Shared RPC SDK: [`enclave/nova_python_sdk/rpc.py`](./enclave/nova_python_sdk/rpc.py)\n\n## 7. Reuse Guide (How to build your own module)\n\nFor any new feature, follow this template pattern:\n\n1. **Add backend endpoint** in [`enclave/routes.py`](./enclave/routes.py).\n2. **Reuse the canonical SDK first** from [`enclave/nova_python_sdk/`](./enclave/nova_python_sdk) for Capsule Runtime, KMS, app-wallet, and shared RPC logic.\n3. **Keep app-specific blockchain logic** in [`enclave/chain.py`](./enclave/chain.py) instead of pushing business helpers into the shared SDK.\n4. **Expose a frontend card/tab** in [`frontend/src/app/page.tsx`](./frontend/src/app/page.tsx).\n5. **Document required runtime config** in [`capsule.yaml`](./capsule.yaml) and constants in [`enclave/config.py`](./enclave/config.py).\n6. **Optionally add periodic execution** in [`enclave/tasks.py`](./enclave/tasks.py) if the feature needs background jobs.\n\nThis keeps every capability consistent: UI demo → app API → Capsule API or runtime binding → reproducible config.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparsity-xyz%2Fnova-app-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsparsity-xyz%2Fnova-app-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparsity-xyz%2Fnova-app-template/lists"}