{"id":48545585,"url":"https://github.com/sparsity-xyz/sparsity-nova-examples","last_synced_at":"2026-04-08T06:30:40.095Z","repository":{"id":323996166,"uuid":"1093941224","full_name":"sparsity-xyz/sparsity-nova-examples","owner":"sparsity-xyz","description":"Reference apps for building verifiable AWS Nitro Enclave applications on Sparsity Nova","archived":false,"fork":false,"pushed_at":"2026-03-18T05:24:29.000Z","size":1981,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-18T18:42:52.460Z","etag":null,"topics":["aws","computation","computing","enclave","enclaver","nitro","nova","sparsity","tee","trust","trustless","verifiable"],"latest_commit_sha":null,"homepage":"https://sparsity.cloud","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","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":"LICENSE","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":"2025-11-11T03:32:59.000Z","updated_at":"2026-03-18T05:24:34.000Z","dependencies_parsed_at":"2026-01-12T10:08:43.683Z","dependency_job_id":null,"html_url":"https://github.com/sparsity-xyz/sparsity-nova-examples","commit_stats":null,"previous_names":["sparsity-xyz/sparsity-nova-examples"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sparsity-xyz/sparsity-nova-examples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fsparsity-nova-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fsparsity-nova-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fsparsity-nova-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fsparsity-nova-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sparsity-xyz","download_url":"https://codeload.github.com/sparsity-xyz/sparsity-nova-examples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparsity-xyz%2Fsparsity-nova-examples/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","computation","computing","enclave","enclaver","nitro","nova","sparsity","tee","trust","trustless","verifiable"],"created_at":"2026-04-08T06:30:39.420Z","updated_at":"2026-04-08T06:30:40.072Z","avatar_url":"https://github.com/sparsity-xyz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sparsity Nova Examples\n\nThis repository contains reference applications for the current Sparsity Nova stack and a practical guide for building enclave applications that match the latest `sparsity-nova-platform` and `capsule-cli` implementations.\n\nThe guidance here is aligned with:\n\n- `sparsity-nova-platform`: control plane, build pipeline, runtime agent, attestation routing, and deployment behavior\n- `capsule-cli`: build/run tooling, Capsule Runtime supervisor, Capsule API, Aux API, S3/KMS/app-wallet/Helios integrations\n\n## How Nova Works Today\n\nIn the current Nova implementation, a production deployment looks like this:\n\n1. You provide a normal Dockerized app.\n2. Nova control plane generates `nova-build.yaml` and a deployment-specific `capsule.yaml`.\n3. Nova App Hub / GitHub Actions builds `Docker -\u003e EIF -\u003e release image`, captures PCRs, and emits a signed `build-attestation.json`.\n4. The runtime agent on EC2 pulls the pre-built image from ECR, verifies the image digest, and starts it with `capsule-cli run`.\n5. The runtime fetches the enclave attestation from the Aux API, configures Caddy, and exposes:\n   - your application on the deployment URL\n   - `POST /.well-known/attestation` on the same hostname\n6. ZK proof generation and on-chain registration happen after the enclave is running.\n\nThe examples in this repo are written for that flow: keep the application code simple and let Capsule APIs exposed through Capsule Runtime provide enclave-native services.\n\n## Current Runtime Model\n\ncapsule-cli builds a release image that contains:\n\n- your app image, amended with `/sbin/capsule-runtime` and `/etc/capsule/capsule.yaml`\n- the generated `application.eif`\n- the Capsule-Shell runtime image that launches Nitro Enclaves with `nitro-cli`\n\nAt runtime:\n\n- `capsule-run` starts the enclave on the host side\n- `capsule-runtime` runs as PID 1 inside the enclave\n- your application runs under Capsule Runtime supervision\n- outbound traffic goes through Capsule Runtime's egress proxy\n- attestation, signing, encryption, storage, and optional KMS/app-wallet features are exposed through Capsule APIs served by Capsule Runtime\n\n### Network Surfaces\n\n| Surface | Inside Enclave | Public in Normal Nova Deployments | Notes |\n|---------|----------------|-----------------------------------|-------|\n| App ingress | app-defined port (for example `8000`) | Yes | Published by runtime and routed by Caddy |\n| Primary API | `127.0.0.1:18000` | No | Full `/v1/*` API; loopback-only in normal deployments |\n| Aux API | `127.0.0.1:18001` | Indirectly | Runtime maps a host attestation port to `18001` and routes `/.well-known/attestation*` there |\n| Helios RPC | `127.0.0.1:18545+` | No | Public only in Nova's special mockup service |\n\nImportant current behavior from `sparsity-nova-platform`:\n\n- the runtime publishes exactly two ports for normal apps:\n  - host app port -\u003e enclave app port\n  - host attestation port -\u003e enclave Aux API port `18001`\n- `/.well-known/attestation*` is routed by Caddy to that host attestation port\n- the Primary API (`18000`) is not exposed publicly for normal production apps\n\n## What You Build\n\n### 1. A Normal Docker Image\n\nYour application can use any language or framework as long as it runs in a container and listens on a known port.\n\n```dockerfile\nFROM python:3.11-slim\n\nWORKDIR /app\nCOPY . .\nRUN pip install -r requirements.txt\n\n# This is an app-level convention, not something Capsule injects automatically.\nENV IN_ENCLAVE=false\n\nEXPOSE 8000\nCMD [\"python\", \"app.py\"]\n```\n\n### 2. A `capsule.yaml`\n\nFor Nova deployments, the control plane generates the authoritative manifest from app settings. The committed example manifests in this repo are useful for local runs, but Nova production behavior is defined by the generated manifest.\n\nA typical Nova-generated manifest looks like this:\n\n```yaml\nversion: v1\nname: my-app\ntarget: nova-apps/my-app:v1\n\nsources:\n  app: my-app:v1\n\ndefaults:\n  cpu_count: 2\n  memory_mb: 4096\n\ningress:\n  - listen_port: 8000\n  - listen_port: 18001\n\negress:\n  allow:\n    - api.openai.com\n    - \"**.amazonaws.com\"\n    - 169.254.169.254\n\napi:\n  listen_port: 18000\n\naux_api:\n  listen_port: 18001\n\nstorage:\n  s3:\n    enabled: true\n    bucket: my-app-storage\n    prefix: apps/my-app/\n    region: us-west-1\n\nkms_integration:\n  enabled: true\n  use_app_wallet: true\n  kms_app_id: 49\n  nova_app_registry: \"0x...\"\n\nhelios_rpc:\n  enabled: true\n  chains:\n    - name: L2-base-sepolia\n      network_id: \"84532\"\n      kind: opstack\n      network: base-sepolia\n      execution_rpc: https://sepolia.base.org\n      local_rpc_port: 18545\n```\n\nKey points:\n\n- `api.listen_port` enables the full Capsule API on `127.0.0.1:18000`\n- `aux_api.listen_port` enables the restricted attestation surface on `127.0.0.1:18001`\n- Nova normally adds the app port and `18001` to `ingress`\n- S3, KMS, app-wallet, and Helios are optional and manifest-driven\n- if you use AWS SDK flows that rely on IMDS, allow `169.254.169.254` in `egress`\n\n### 3. A `nova-build.yaml`\n\nNova also generates `nova-build.yaml` when a build is triggered:\n\n```yaml\nname: \"my-app\"\nversion: \"v1\"\nrepo: \"https://github.com/you/my-app\"\nref: \"main\"\nbuild:\n  directory: \"enclave\"\n  dockerfile: \"Dockerfile\"\nmetadata:\n  description: \"My enclave application\"\n```\n\nThis config drives the build pipeline that produces the release image and build provenance.\n\n## Current Capsule API Surface\n\nInside the enclave, Capsule Runtime serves localhost-only Capsule APIs. The full API lives on the Primary API port; the public attestation path used by Nova is backed by the Aux API.\n\n### Core Endpoints\n\n| Endpoint | Method | Current Behavior |\n|----------|--------|------------------|\n| `/v1/eth/address` | `GET` | Returns enclave Ethereum address and public key |\n| `/v1/eth/sign` | `POST` | EIP-191 personal-sign; can optionally include attestation |\n| `/v1/eth/sign-tx` | `POST` | Signs EIP-1559 transactions |\n| `/v1/random` | `GET` | Returns 32 bytes from NSM-backed randomness |\n| `/v1/attestation` | `POST` | Returns raw CBOR attestation bytes; not JSON |\n| `/v1/encryption/public_key` | `GET` | Returns the enclave P-384 public key |\n| `/v1/encryption/encrypt` | `POST` | Encrypts a response to a client |\n| `/v1/encryption/decrypt` | `POST` | Decrypts client payloads |\n\n### Optional Storage / KMS Endpoints\n\n| Endpoint Group | Availability | Notes |\n|----------------|--------------|-------|\n| `/v1/s3/*` | `storage.s3.enabled=true` | Base64 object storage API backed by S3 |\n| `/v1/kms/*` | `kms_integration.enabled=true` | Registry-backed key derivation and KV APIs |\n| `/v1/app-wallet/*` | `kms_integration.use_app_wallet=true` | App-wallet identity and signing APIs |\n\n### Attestation Rules That Matter\n\n- `POST /v1/attestation` returns raw CBOR bytes with content type `application/cbor`\n- `nonce` is optional\n- `public_key` is optional; if omitted, Capsule Runtime uses the enclave encryption public key\n- `user_data` must be a JSON object when provided\n- Capsule Runtime injects `eth_addr` into `user_data`\n- if app-wallet material is available, Capsule Runtime also injects `app_wallet`\n\n## Public Attestation vs Internal Attestation\n\nThis distinction matters because older docs in this repo blurred the two:\n\n- inside the enclave, your app can call `POST http://127.0.0.1:18000/v1/attestation`\n- outside the enclave, Nova exposes `POST /.well-known/attestation`\n- in current Nova runtime, `/.well-known/attestation` is not your app's responsibility in production; Caddy routes it to the Aux API port that the runtime published\n\nSome examples in this repo still implement `/.well-known/attestation` in app code for local development convenience. Treat that as a dev shim, not as the production Nova routing model.\n\n## Outbound Networking: Current Constraint\n\nNitro Enclaves do not have direct outbound network access. In the current Capsule implementation:\n\n- Capsule Runtime provides an HTTP(S) egress proxy inside the enclave\n- Capsule Runtime sets `http_proxy`, `https_proxy`, `HTTP_PROXY`, `HTTPS_PROXY`, `no_proxy`, and `NO_PROXY` for your app when egress is enabled\n- your HTTP client library must respect proxy settings, or you must configure a proxy explicitly\n\nDo not assume that \"normal networking\" always works unchanged inside the enclave. This is a common failure mode, especially with libraries that ignore proxy environment variables by default.\n\n## Local Development\n\nThe examples in this repo commonly use an app-level `IN_ENCLAVE` convention:\n\n```python\nimport os\n\nIN_ENCLAVE = os.getenv(\"IN_ENCLAVE\", \"false\").lower() == \"true\"\nCAPSULE_RUNTIME_BASE_URL = \"http://127.0.0.1:18000\" if IN_ENCLAVE else \"http://capsule-runtime.sparsity.cloud:18000\"\n```\n\nImportant caveats from the current Capsule docs:\n\n- `IN_ENCLAVE` is not injected automatically by Capsule\n- the external mock service is a convenience endpoint, not the authoritative implementation\n- you should verify important behavior against the real Capsule code or a real enclave deployment\n\n### Current Mock Endpoints Used by Examples\n\nNova currently operates a special mockup service that backs `capsule-runtime.sparsity.cloud`. It is useful for lightweight development loops and exposes:\n\n- Primary API: `http://capsule-runtime.sparsity.cloud:18000`\n- Aux API: `http://capsule-runtime.sparsity.cloud:18001`\n- Helios RPC presets: `http://capsule-runtime.sparsity.cloud:18545` through `:18553`\n\nTreat this as a development convenience. It is not version-locked to the Capsule repo.\n\n## Build Provenance in the Current Platform\n\nNova's current build pipeline records provenance in `build-attestation.json`, including:\n\n- source repository, ref, commit, directory, and Dockerfile\n- PCR0 / PCR1 / PCR2 from the built EIF\n- build timestamp and GitHub run metadata\n\nThe build attestation is signed with Sigstore/cosign, stored off-chain, and referenced by hash/URL in the platform flow. Runtime then deploys the pre-built image and verifies its digest before launch.\n\n## Reference Implementations in This Repo\n\n| Example | Why It Matters |\n|---------|----------------|\n| [hello-world-tee](./hello-world-tee) | Smallest identity + attestation example |\n| [echo-vault](./echo-vault) | Best end-to-end backend reference; uses S3 persistence and Helios RPC |\n| [secured-chat-bot](./secured-chat-bot) | Best reference for browser-to-enclave encryption with P-384 ECDH |\n| [oracles/rng-oracle](./oracles/rng-oracle) | On-chain randomness flow with enclave signing |\n| [oracles/price-oracle](./oracles/price-oracle) | External API verification and signing patterns |\n\nFor the most complete Python helper wrapper in this repo, start with:\n\n- [`echo-vault/enclave/capsule_runtime.py`](./echo-vault/enclave/capsule_runtime.py)\n\n## Quick Start\n\n### Run an Example Locally\n\n```bash\ncd echo-vault/enclave\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nIN_ENCLAVE=false python -m uvicorn app:app --host 0.0.0.0 --port 8000\n```\n\nFor frontend-backed examples, start the frontend separately if the example README says so.\n\n### Deploy Through Nova\n\nThe current production path is:\n\n1. push your app repo with a normal Dockerfile\n2. create the app in Nova Portal\n3. configure advanced settings that determine generated `nova-build.yaml` and `capsule.yaml`\n4. trigger a build\n5. enroll the resulting version if on-chain registration is enabled\n6. deploy the enrolled version\n7. verify the app URL and `POST /.well-known/attestation`\n\n## Related Reading\n\n- [Capsule API](https://github.com/sparsity-xyz/nova-enclave-capsule/blob/main/docs/capsule-api.md)\n- [Capsule Manifest Reference](https://github.com/sparsity-xyz/nova-enclave-capsule/blob/main/docs/capsule.yaml)\n- [Capsule Architecture](https://github.com/sparsity-xyz/nova-enclave-capsule/blob/main/docs/capsule-architecture.md)\n- [Nova Build Attestation](https://github.com/sparsity-xyz/sparsity-nova-platform/blob/main/docs/build-attestation.md)\n- [Nova Runtime Port Exposure Flow](https://github.com/sparsity-xyz/sparsity-nova-platform/blob/main/docs/runtime-port-exposure-flow.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparsity-xyz%2Fsparsity-nova-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsparsity-xyz%2Fsparsity-nova-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparsity-xyz%2Fsparsity-nova-examples/lists"}