> For the complete documentation index, see [llms.txt](https://docs.cortensor.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortensor.network/technical-architecture/data-management/private-encrypted-inference.md).

# Private / Encrypted Inference

> Draft / WIP – this document captures the current plan for private / encrypted inference on Cortensor, starting with dedicated sessions and evolving toward SDK-native Web3 flows and, ultimately, TEE-backed confidential execution.
>
> It complements the main architecture docs:
>
> * Technical: `technical-architecture/data-management/private-encrypted-inference`
> * Phase roadmap: `roadmap/testnet-phase-3`

***

### 1. Goals & Scope

The private / encrypted inference roadmap is designed to:

* Let users encrypt prompts and results end-to-end for selected workflows.
* Keep router & miners blind to plaintext wherever possible, while still routing correctly.
* Start with config-driven dedicated sessions and gradually extend to:
  * Ephemeral / pooled nodes (dynamic assignment)
  * A unified key-issuance engine
  * SDK-native Web3 integration (wallet-based auth + policy)
  * TEE-backed confidential execution (Nitro / TDX) as the highest-assurance mode

We talk about “versions” in terms of the privacy/key system, not the router API:

* **V0** – dedicated sessions, router-managed allowlist + key derivation (env-based).
* **V0.5** – move allowlist to onchain contract, router becomes contract-enforced.
* **V1** – ephemeral / pooled node support (assignment-aware keys).
* **V2** – unified engine for all session types (pluggable policies).
* **V3** – SDK-native Web3 private inference (wallet + policy).
* **V4** – TEE-backed private inference (Nitro / TDX nodes as final privacy layer).

All versions assume **offchain payload v2** for encrypted content (so rotation/backfill is possible).

***

### 2. V0 – Dedicated Sessions, Router-Managed Policy & Key Issuance

#### 2.1 What V0 Supports

V0 focuses on **dedicated-node sessions** where the router knows the full path (User ↔ Router ↔ Miner) and can safely manage encryption keys.

New auth endpoints (concept):

* `POST /api/v1/auth/payload_enc_key/session`\
  → issue a session-level encryption key derived from `session_id`.
* `POST /api/v1/auth/payload_enc_key/task`\
  → issue a task-level encryption key derived from `session_id + task_id`.

Auth flow:

1. Caller sends:
   * `address` (EOA)
   * `signature` over canonical scope string
   * `scope` fields:
     * Session endpoint signs the string: `"session_id"`
     * Task endpoint signs the string: `"session_id:task_id"`
2. Router:
   * Verifies the signature with `verify_addr_str_message(scope_string)`.
   * Checks `address` against `ENCRYPTION_ALLOWED_LIST` (V0 policy source).
   * If authorized, derives a `payload_enc_key` deterministically from:
     * `ENCRYPTION_SEED`
     * Scope (for example `"101"` or `"101:9001"`).
3. Router returns:
   * `payload_enc_key` (or a wrapped form)
   * `scope` / `scope_type` (session or task)
   * `key_version` (see keyring below)

Apps use this key to encrypt/decrypt payloads client-side; the router only sees encrypted blobs + metadata and routes them like any other payload.

#### 2.2 Deterministic Key Derivation

Current prototype (short-term acceptable):

* `payload_key = SHA256(ENCRYPTION_SEED + ":" + scope)`

Longer term, prefer **HKDF** with explicit versioning:

* `payload_key_vN = HKDF(seed_vN, info = "cts:v0:" + scope)`

Key properties:

* Deterministic for the router (given seed + scope).
* Not guessable from `session_id` / `task_id` alone.
* Security depends on strength of `ENCRYPTION_SEED_vN`:
  * Use at least 32 bytes of high-entropy random.
  * Rotate if exposed or suspected compromised.

#### 2.3 Encrypted Payload Metadata (Offchain v2)

Encrypted payloads follow an offchain payload v2 pattern with explicit metadata, for example:

```
{
  "alg": "aes-256-gcm",
  "scope_type": "session",      // or "task"
  "session_id": 101,
  "task_id": 9001,
  "key_version": "v3",
  "nonce": "base64-encoded",
  "tag": "base64-encoded",
  "ciphertext": "base64-encoded",
  "created_at": "2026-03-01T12:34:56Z"
}
```

Rules:

* Router does not see plaintext; it only uses:
  * `session_id` / `task_id`
  * `scope_type`
  * `key_version`
* All encrypted prompts/results must use this v2 metadata format.
* Plaintext may be kept separately only in trusted tooling during backfill/rotation.

***

### 3. V0 Key Rotation Model (Critical)

We must never run the network on a single long-lived seed.

#### 3.1 Keyring Model

Router keeps a **keyring**:

* `active_version = vN`
* `legacy_versions = [vN-1, vN-2, ...]` (decrypt-only)

Behavior:

* Issuance:
  * `/auth/payload_enc_key/*` always derives keys with active `ENCRYPTION_SEED_vN`.
  * Response includes `key_version = "vN"`.
* Encryption client-side:
  * Clients persist `key_version` inside the encrypted payload metadata.
* Decryption:
  * Router first uses `key_version` from metadata.
  * Only if needed, fall back to range mapping or legacy assumptions for migration.

#### 3.2 Backfill & Retirement

For offchain v2 payloads:

1. Background worker:
   * Reads ciphertext with legacy `key_version`.
   * Decrypts using the corresponding legacy seed.
   * Re-encrypts with active seed/version.
   * Updates stored payload + metadata in-place, so **the offchain payload URN/ID stays the same**.
2. Once SLO window passes and backfill coverage is acceptable:
   * Mark old versions as retired (no decrypt).
   * Optionally purge old ciphertexts or mark them invalid.

#### 3.3 If a Seed is Stolen

If `ENCRYPTION_SEED_vK` is compromised:

* Assume ciphertexts under that version are compromised if attacker can access them.
* Immediate steps:
  * Rotate `active_version` to `vK+1`.
  * Stop issuing keys for `vK`.
  * Revoke affected sessions/leases as needed.
* Recovery options:
  * For offchain v2 payloads:
    * Re-encrypt from trusted source data, or
    * Re-encrypt from ciphertexts decryptable with known-good key material.
  * For onchain:
    * Only store policy + references, never raw secrets or seeds.

***

### 4. V0 Policy – ENCRYPTION\_ALLOWED\_LIST (Dedicated Sessions)

#### 4.1 Env Format

V0 uses an env-based allowlist to control which addresses can request keys for which scopes:

```
ENCRYPTION_SEED="replace-with-strong-random-seed"
ENCRYPTION_ALLOWED_LIST="101:0x1111111111111111111111111111111111111111,0x2222222222222222222222222222222222222222;102:0x3333333333333333333333333333333333333333;101-9001:0x4444444444444444444444444444444444444444,0x5555555555555555555555555555555555555555;202-77:0x6666666666666666666666666666666666666666"
```

Semantics:

* `session_id:addr,addr` → session-level allowlist.
  * Example: `101:0x11...,0x22...` → addresses allowed for session `101`.
* `session_id-task_id:addr,addr` → task-level allowlist.
  * Example: `101-9001:0x44...,0x55...` → addresses allowed for session `101`, task `9001`.

Rules:

* No spaces; addresses must be `0x` + 40 hex chars.
* Router parses this once and uses it to grant/deny key issuance.

This is V0 only and intended for **dedicated-node sessions** where operator and app are known/trusted.

***

### 5. V0.5 – Contract-Backed Allowlist

To move beyond static env-based policy, we introduce **V0.5**:

* Authorization becomes:
  * `signature_valid AND contract_policy_allows(scope, address)`.
* Session-level and task-level grants are stored in an onchain contract.
* Router:
  * Still verifies signatures and derives keys.
  * Queries contract (with caching) for allow/deny decisions.
* Policy updates:
  * Emit events from the contract.
  * Routers subscribe or poll for updates to invalidate caches.

Env allowlist is kept as:

* Emergency override / bootstrap mode.
* Local dev / test environment fallback.

***

### 6. V1 – Ephemeral / Dynamic Node Support

V1 extends private inference to **ephemeral or pooled nodes** (node-pool sessions).

Challenges:

* Miner assignments change over time.
* We can’t rely on static address lists only.

Design points:

1. **Assignment-aware policy**
   * Router confirms that a requesting miner:
     * Is currently assigned to the session/task for this epoch.
     * Has a valid lease or job assignment record.
2. **Replay resistance**
   * Scope string extended for key issuance, for example:
     * `"session:task:epoch:expires_at"`
   * Caller signs this extended scope.
3. **Short-lived grants**
   * Keys for ephemeral sessions/tasks should:
     * Be valid only for short windows (for example, minutes).
     * Align with job assignment lifetimes.

V1 still uses the same keyring, derivation style, and metadata format — the difference is how policy decides who gets keys.

***

### 7. V2 – Unified Key-Issuance Engine

V2 unifies dedicated and ephemeral sessions under a single framework:

* Same auth endpoints:
  * `/api/v1/auth/payload_enc_key/session`
  * `/api/v1/auth/payload_enc_key/task`
* Same signature semantics:
  * Canonical scope strings; explicit `scope_type`.
* Same metadata:
  * `alg`, `scope_type`, `session_id`, `task_id`, `key_version`, `nonce`, `tag`, `ciphertext`, `created_at`.
* Same audit model:
  * Every issuance recorded as an event (who, what scope, which key\_version).

Policy becomes pluggable:

* `EnvAdapter` – env-based allowlist (V0).
* `ContractAclAdapter` – onchain ACL for sessions/tasks (V0.5).
* `AssignmentAdapter` – dynamic assignment info for ephemeral sessions (V1).

Router composes these adapters to compute:

* `authorized = signature_valid AND env_policy_allows(...) AND contract_policy_allows(...) AND assignment_policy_allows(...)`

Encrypted workloads continue to use offchain payload v2 to keep rotation/backfill feasible at scale.

***

### 8. V3 – SDK-Native Private Inference (Web3)

V3 focuses on a Web3 SDK–native experience:

* Web3 client/SDK:
  * Manages wallet-based signing of scope strings.
  * Manages policy registration:
    * Which sessions/tasks require encryption.
    * Which addresses/roles can receive keys.
  * Manages key request + caching flows.
* Router:
  * Remains:
    * Policy enforcement engine.
    * Key issuance service.
  * Does not hold long-lived plaintext DEKs beyond what’s needed to derive them.
* Onchain:
  * Stores transparent policy state and references:
    * Which addresses are allowed.
    * Which sessions/tasks are “private-required”.
  * Never stores raw secrets or seeds.
* 3-party patterns (optional, later):
  * User ↔ Miner ↔ Oracle flow for:
    * Encrypted inference.
    * Verifiable output checking.
  * Converge to envelope encryption:
    * One DEK per session/task.
    * DEK wrapped separately for each authorized recipient.

***

### 9. V4 – TEE-Backed Confidential Inference (Nitro / TDX)

V4 introduces **TEE-backed nodes** as the final, strongest privacy form: even when payloads must be decrypted for model execution, they are only ever decrypted inside a **trusted execution environment** (TEE) such as AWS Nitro Enclaves or Intel TDX.

#### 9.1 Why TEE Nodes Matter

Encrypted payloads + key control protect data in transit and at rest, but at some point, models need plaintext inside RAM to run.

V4 aims to guarantee that:

* Decryption and inference happen only inside a TEE with:
  * Hardware-backed isolation from the host OS/hypervisor.
  * Attestation that proves code + configuration to the router and/or caller.
* Node operators (and cloud providers) cannot inspect plaintext payloads, only resource usage.

This becomes the “final privacy form” for high-sensitivity workloads.

#### 9.2 Initial Target: AWS Nitro Enclaves

Past experience:

* We’ve used **AWS Nitro** and **Intel TDX** for user data privacy projects.
* Nitro is a practical first target because:
  * Once you have a Docker image, it is “one command away” to build a Nitro image.
  * It is straightforward to run a TEE-enabled container on AWS as an enclave.

Initial V4 rollout plan:

* Start with Nitro-enabled miners:
  * Build enclave-compatible images from existing miner containers.
  * Expose a TEE runtime that can:
    * Receive encrypted payloads.
    * Obtain DEKs or wrapped keys only after successful attestation.
    * Run inference locally inside the enclave.
* Later, extend to Intel TDX and other TEE platforms where available.

#### 9.3 Key & Attestation Flow (High-Level)

A typical V4 flow (simplified):

1. Miner node boots a TEE (Nitro/TDX) with a known enclave image.
2. Enclave generates an attestation document describing:
   * Code hash / image hash.
   * Configuration (e.g., models, routes).
3. Router (or a separate attestation service) verifies the attestation:
   * Ensures the enclave matches an allowlisted image/config.
4. For an encrypted job:
   * Router derives or unwraps a DEK for the scope (session/task) as in V2/V3.
   * Router encrypts the DEK to the enclave’s public key (or uses TEE-specific key exchange).
   * Encrypted payload + wrapped DEK are delivered to the enclave.
5. Inside the enclave:
   * Enclave unwraps DEK.
   * Decrypts payload.
   * Runs inference using local models.
   * Optionally re-encrypts results to the user’s key or to a new DEK.
6. Router sees only:
   * TEE attestation claims.
   * Encrypted payloads and results.
   * Metering and success/failure status.

TEE nodes still integrate with:

* Existing keyring versions (`key_version`).
* Offchain payload v2 metadata (same envelope).
* Policy adapters (e.g., only certain sessions/tasks may require TEE execution).

#### 9.4 How V4 Fits the Roadmap

V4 builds on previous versions:

* V0–V2:
  * Define scoped keys, rotation, and metadata.
* V3:
  * Adds Web3 SDK and clean policy registration.
* V4:
  * Uses those same scoped DEKs and policies.
  * Adds a TEE “execution shape” for miners:
    * Some sessions/tasks marked as `privacy_mode = "TEE_REQUIRED"` or similar.
    * Router routes those only to TEE-capable miners.

Over time:

* Nitro-based TEE miners can be the first production path.
* Intel TDX support can be added for on-prem or other cloud vendors.
* Full design doc will extend this section with:
  * Attestation formats.
  * Routing policies.
  * Combined “TEE + encrypted payload” patterns.

***

### 10. Long-Term Rotation & Backfill at Scale

TEE-backed private inference doesn’t remove the need for **operational key hygiene**. Over the long run, Cortensor needs a rotation/backfill story that works at network scale, especially if a seed or key material is suspected to be compromised.

Key considerations:

* **Backfill jobs must preserve offchain URNs/IDs**
  * For most apps, URNs or IDs pointing at offchain payloads (S3 objects, IPFS CIDs behind a pinning layer, etc.) should remain stable.
  * Backfill workers should:
    * Fetch existing ciphertext by URN.
    * Decrypt using the legacy `key_version`.
    * Re-encrypt with the active version.
    * Write back to the same URN / storage key so upstream references do not break.
* **Priority tiers for backfill**
  * Not all encrypted data is equal:
    * “Hot” session/task payloads that agents still need.
    * “Warm” history needed for audits/repairs.
    * “Cold” archives that can be invalidated with lower user impact.
  * Backfill runners should support:
    * Priority queues by namespace / project / app.
    * Configurable SLOs (for example: 95% of hot data re-encrypted within 24h).
* **Compromised-key scenarios**
  * If a seed or specific `key_version` is suspected compromised:
    * Immediately mark that version as “compromised, decrypt-only”.
    * Block new issuance for that version (only decrypt for backfill).
    * Kick off backfill against payloads tagged with that `key_version`.
    * Offer app-level knobs:
      * “Hard invalidate” (refuse to decrypt) for the most sensitive flows.
      * “Best-effort backfill” for less critical archives.
* **Shard-aware backfill**
  * In a multi-router or multi-region world, backfill should be sharded:
    * Each router (or worker pool) handles a subset of URNs or key ranges.
    * Progress tracked via a central index (for example, “encrypted payload index” keyed by `key_version`).
    * Operators can see:
      * How many payloads per key\_version remain.
      * Estimated time to completion.
* **TEE + rotation interplay**
  * When TEE nodes are in use:
    * Backfill workers can optionally run **inside TEEs** as well, so decrypt/re-encrypt never leaves an enclave.
    * A hybrid approach is also possible:
      * Use a privileged “maintenance enclave” with separate attestation + rate limits for rotation jobs.
  * Over time, high-sensitivity tenants may require:
    * “All decrypt/re-encrypt operations must happen within TEE nodes only.”

The main takeaway:

* Keys **will** rotate.
* Some keys **may** become compromised.
* The design assumes:
  * Offchain payload v2 is always re-encryptable in place.
  * URNs/IDs stay stable while the ciphertext behind them gets upgraded.
  * Rotation/backfill is a first-class, observable process — not an afterthought.

***

### 11. Concrete V0 Improvements (Next Work Items)

To harden V0 and prepare for V0.5/V1/V2/V3/V4:

1. Add `key_version` to responses:
   * `/auth/payload_enc_key/session`
   * `/auth/payload_enc_key/task`
2. Require clients to persist `key_version` in encrypted payload metadata.
3. Introduce router keyring env format:
   * `ENCRYPTION_SEED_ACTIVE` and `ENCRYPTION_SEED_LEGACY_*` (or similar).
4. Implement decrypt flow with key\_version-first resolution:
   * Use `key_version` in metadata.
   * Only fall back to legacy/range mapping during migration.
5. Add backfill worker for offchain v2 ciphertext re-encryption to active version (preserving URNs).
6. Enforce that encrypted sessions/tasks must use offchain payload v2 for prompts/results.

***

### 12. Summary

* **V0** gives dedicated-session private inference: router-managed policy, deterministic per-scope keys, and env-based allowlists.
* **V0.5** moves policy into a contract-backed allowlist, with env as emergency fallback.
* **V1** extends privacy to ephemeral / dynamic node pools, with assignment-aware rules and short-lived grants.
* **V2** unifies everything behind a single key-issuance engine and pluggable policy adapters, using the same metadata and audit model.
* **V3** layers on a Web3 SDK–native experience and envelope encryption, turning private inference into a first-class, programmable feature for onchain + offchain apps.
* **V4** adds TEE-backed confidential inference (AWS Nitro / Intel TDX) so that decryption + execution happen only inside hardware-backed enclaves, giving the strongest privacy guarantees for high-sensitivity workloads.
* Across all versions, **key rotation and backfill** are treated as ongoing operational duties:
  * Encrypted payloads live in offchain payload v2.
  * URNs remain stable while ciphertext is upgraded.
  * Compromised keys can be contained via rotation + re-encryption rather than breaking references or rewriting app-level contracts.

This roadmap is intentionally incremental: start with dedicated sessions and env-based allowlists, then steadily layer in contracts, dynamic node pools, unified engines, SDKs, and finally TEE-backed execution — without breaking the core guarantees users expect from private inference on Cortensor.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortensor.network/technical-architecture/data-management/private-encrypted-inference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.