# TEE-ORAM Private RPC — Project Overview

## Purpose

Enable the **Kohaku** wallet to fetch Ethereum state **without revealing which addresses/slots are being read** to any RPC provider, server operator, or network observer.

* **Privacy of queries:** Hide content and access patterns (which keys are touched).
* **Integrity of data:** Return verifiable state (e.g., via `eth_getProof` EIP-1186).
* **Practicality:** Usable on consumer devices without running a full node.

## Background

Most users rely on centralized RPCs. Standard calls (`eth_getBalance`, `eth_call`, `eth_getStorageAt`, `eth_getProof`) leak:

* Queried addresses/slots (content leakage)
* Timing/size patterns (behavioral leakage)
* Network metadata (IP/device)

**TEEs + ORAM** address this:

* **TEE (Intel TDX):** Executes the server logic inside a hardware-isolated enclave so the operator cannot see plaintext queries.
* **ORAM:** Ensures storage access patterns inside the server do not reveal which keys are read.
* **Remote attestation (RA-TLS):** Lets the client verify it is talking to the intended enclave code before establishing a secure session.
* **Traffic shaping:** Constant-rate, padded I/O to blunt timing/size side channels.

This project is a collaboration with **Oblivious Labs** (ORAM + TEE server). We integrate from **Kohaku** so clients can fetch state privately.

## Minimal Architecture

**Components**

1. **Kohaku Client (wallet)**

* Verifies **TDX remote attestation** for the ORAM server.
* Pins the enclave’s TLS/public key and establishes a session (RA-TLS or equivalent).
* Uses a **constant-rate scheduler** that mixes real requests with **dummy bytes** so wire-level traffic appears flat.
* Hooks into `revm`/provider layer with a local cache; only cache misses become real backend reads (outer traffic still constant-rate).

2. **TEE-ORAM Server (Oblivious Labs)**

* Runs inside **Intel TDX**; exposes a JSON-RPC-compatible endpoint at minimum for **`eth_getProof` (EIP-1186)**.
* Uses **ORAM** to serve proofs without leaking which keys/paths were accessed.
* **Batched reads** for throughput; **padded responses** to keep size flat.
* Publishes **attestation evidence + ephemeral TLS key** at startup (RA-TLS).

3. **Ethereum Data Source**

* Reth (or equivalent) feeding authenticated state data to the enclave logic.
* Optionally, client verifies Merkle/Patricia proofs returned by `eth_getProof`.

**Data Flow (happy path)**

1. Kohaku fetches enclave’s attestation + key; verifies **measurement/vendor chain**.
2. Client pins the key and opens a session.
3. Client maintains **fixed-interval I/O** (e.g., every 200 ms), queueing real requests and filling with dummy bytes when idle.
4. Server processes real requests through **ORAM**, aggregates/batches internally.
5. Server returns **padded** responses; client parses and verifies proofs.
6. Cache warms; subsequent calls hit local cache while **wire traffic stays flat**.

**Assumptions / Trust**

* Trust in **Intel TDX** hardware root and the published enclave **measurement**.
* Minimal TCB inside enclave; no plaintext query exposure to operators.
* Side-channel surface reduced but not eliminated; we explicitly address **timing/size** on the wire.

**Non-Goals (for the minimal slice)**

* Browser (JS/WASM) RA-TLS parity (desktop/Node first).
* Full PIR; full Portal Network integration (future work).

## Expected Outcome

* **Functionality:** Kohaku can retrieve Ethereum state (starting with `eth_getProof`) via a TEE-ORAM backend **without revealing** queried keys/slots, and with **verifiable integrity** of results.
* **Privacy Properties:**

* Server operator cannot learn specific queries (**TEE isolation + ORAM**).
* Network observer cannot reliably distinguish active vs idle or infer request size (**constant-rate, padded transport**).
* **Artifacts:**

* **Attested endpoint** (RA-TLS) with published measurement/fingerprint and a **pin-update** procedure.
* Client integration in Kohaku (`revm` provider swap, cache, constant-rate scheduler).
* Minimal **ops guide** (key rotation, attestation verification steps, fallback).
* **Metrics** demonstrating practicality: added latency vs direct RPC, bandwidth overhead under typical workloads, and basic indistinguishability tests on traffic.
* **Constraints (explicit):**

* Higher bandwidth than bursty RPC (mitigated by active-use only shaping and batching).
* Desktop/Node support first; browser path requires a custom handshake or different trust anchors.