zkproofport/proofport-ai

Agent-native ZK proof infrastructure for ZKProofport, with a TEE-based proving architecture, SDK and local MCP package. Supported Nitro deployments encrypt inputs to the enclave; encryption and hardware-attestation guarantees depend on the selected endpoint and actual returned evidence. GIWA exact-action authorization remains **EXPERIMENTAL on GIWA Sepolia (91342)**.
Architecture
The following diagram describes the Nitro deployment. Endpoints without an attested enclave key receive readable inputs over HTTPS; the current GCP Cloud Run deployments use that mode and do not supply hardware attestation. A valid proof alone is not evidence of enclave execution.
**Key properties:**
- **E2E encryption** — X25519 ECDH + AES-256-GCM. In nitro mode, plaintext inputs are rejected.
- **Blind relay in Nitro mode** — The host forwards enclave-encrypted inputs. This property does not apply to an endpoint accepting plaintext circuit inputs.
- **x402 payment** — Single-step flow: 402 challenge → USDC payment → proof generation. No middleware.
- **Hardware attestation in Nitro mode** — An actual validated NSM document binds the TEE key to enclave measurements (PCRs); do not infer it from proof validity.
Directory Structure
Quick Start
npm (Development)
Docker Compose (Local)
- Port 4002: Node.js server
- Port 6380 (host) → 6379 (container): Redis
E2E Encryption (Blind Relay)
For the supported Nitro deployment, proof inputs are encrypted between the client and the enclave. The host passes the encrypted blob without reading it. This section describes that protocol, not every endpoint.
**Protocol:** X25519 ECDH + AES-256-GCM (ECIES pattern)
1. TEE generates X25519 key pair on startup, binds public key to NSM attestation
2. Client fetches TEE public key from 402 response, verifies attestation
3. Client generates ephemeral X25519 keypair, computes ECDH shared secret, derives AES key via SHA-256
4. Client encrypts inputs with AES-256-GCM, sends { ephemeralPublicKey, iv, ciphertext, authTag, keyId }
5. Server passes encrypted envelope to enclave via vsock (blind relay)
6. Enclave decrypts, generates proof, returns proof + NSM attestation
**Enforcement:** In nitro mode, plaintext inputs are rejected with PLAINTEXT_REJECTED.
x402 Payment Flow
The live 402 challenge determines the offered routes, price, asset, recipient and signing domain. Select a compatible wallet and explicit route, obtain user approval, then sign the exact terms and retry the request using the SDK's payment headers. Do not assume every endpoint is free or that every wallet works on every offered chain.
Callers must validate the live offer rather than substitute a documentation price.
Use max_payment: "0.001" and approved_payment in local MCP, or maxPayment and approvedPayment in the SDK. Exact approved terms include network, scheme, amount (USDC base units), asset, payTo and extra: {name, version, verifyingContract}. The SDK rejects a changed fee, recipient, asset, network or signing domain before signing. Proof payment and any application transaction that relies on the proof require separate approvals.
Base and Base Sepolia use Dexter first and PayAI as a backup. --pay-with key
and --pay-with cdp still choose the buyer's signing wallet; neither selects
the server's facilitator. Provider failover reuses the identical EIP-3009
authorization, including its nonce, amount and recipient. Ethereum direct
settlement keeps its own settlement route.
The server tries each configured facilitator at most once for connection
failures, timeouts, HTTP 429/5xx or malformed responses. Payment rejections
such as insufficient balance, invalid signatures and expired authorizations
stop immediately. Before contacting the backup, the server checks the USDC
authorization state on the selected chain. A pending settlement or an
already consumed authorization is not submitted again. If that state cannot
be established, the API reports settlement_unknown; known pending responses
report settlement_pending, with a transaction hash when available. These
outcomes require reconciliation, not a newly signed payment. This failover
does not implement resumption of a proof request after its settlement response
was lost. Final on-chain payment verification still runs before proof generation.
REST Endpoints
| Endpoint | Method | Purpose |
|----------|--------|---------|
| /health | GET | Health check + TEE status + payment mode |