proofport-ai

Agent-native ZK proof infrastructure for ZKProofport. A standalone service that generates and verifies zero-knowledge proofs inside an AWS Nitro Enclave with end-to-end encryption — the server acts as a blind relay and never sees proof inputs.

Architecture

Client (AI Agent / SDK)
  │
  │  1. POST /api/v1/prove  →  402 { nonce, price, teePublicKey }
  │  2. Sign EIP-3009 USDC payment
  │  3. Encrypt inputs with TEE X25519 public key (ECIES)
  │  4. POST /api/v1/prove + X-Payment-TX + X-Payment-Nonce + encrypted_payload
  │
  ▼
┌─────────────────────────────────────┐
│  Node.js Server (port 4002)        │
│  ─ Verify USDC payment on-chain    │
│  ─ Blind relay: pass encrypted     │
│    payload to enclave via vsock     │
│  ─ Return proof + TEE attestation  │
└────────────┬────────────────────────┘
             │ vsock
             ▼
┌─────────────────────────────────────┐
│  AWS Nitro Enclave                  │
│  ─ X25519 key pair (bound to NSM)  │
│  ─ Decrypt inputs (AES-256-GCM)    │
│  ─ bb prove (Barretenberg CLI)     │
│  ─ NSM attestation of proof hash   │
└─────────────────────────────────────┘

Key properties:

• E2E encryption — X25519 ECDH + AES-256-GCM. In nitro mode, plaintext inputs are rejected.
• Blind relay — The Node.js host cannot read proof inputs. Only the enclave decrypts.
• x402 payment — Single-step flow: 402 challenge → USDC payment → proof generation. No middleware.
• Hardware attestation — NSM attestation document binds TEE public key to enclave measurement (PCRs).

Directory Structure

proofport-ai/
├── src/
│   ├── index.ts                  # Express server entry (port 4002)
│   ├── logger.ts                 # Pino logger
│   ├── swagger.ts                # OpenAPI spec
│   ├── tracing.ts                # OpenTelemetry tracing
│   ├── a2a/
│   │   ├── agentCard.ts          # /.well-known/agent.json, agent-card.json
│   │   ├── proofportExecutor.ts  # A2A task executor
│   │   └── redisTaskStore.ts     # Redis-backed task persistence
│   ├── chat/
│   │   ├── geminiClient.ts       # Gemini API client
│   │   ├── llmProvider.ts        # LLM provider interface
│   │   ├── multiProvider.ts      # Multi-provider routing
│   │   └── openaiClient.ts       # OpenAI API client
│   ├── circuit/
│   │   └── artifactManager.ts    # Circuit artifact download/cache
│   ├── config/
│   │   ├── index.ts              # Environment config
│   │   ├── circuits.ts           # Circuit metadata
│   │   └── contracts.ts          # Deployed contract addresses
│   ├── identity/
│   │   ├── agentAuth.ts          # Agent JWT authentication
│   │   ├── autoRegister.ts       # ERC-8004 auto-registration
│   │   ├── register.ts           # Identity registration
│   │   └── reputation.ts         # Reputation management
│   ├── input/
│   │   ├── attestationFetcher.ts # EAS GraphQL attestation fetch
│   │   ├── inputBuilder.ts       # Circuit input construction
│   │   └── merkleTree.ts         # Merkle tree builder
│   ├── mcp/
│   │   ├── server.ts             # StreamableHTTP MCP server
│   │   └── stdio.ts              # stdio MCP server (local use)
│   ├── payment/
│   │   └── freeTier.ts           # Payment mode config
│   ├── proof/
│   │   ├── proofRoutes.ts        # x402 single-step proof API
│   │   ├── guideBuilder.ts       # Dynamic proof generation guide
│   │   ├── paymentVerifier.ts    # On-chain USDC payment verification
│   │   ├── sessionManager.ts     # Proof session/nonce management
│   │   └── types.ts
│   ├── prover/
│   │   ├── bbProver.ts           # bb CLI direct prover
│   │   ├── tomlBuilder.ts        # Prover.toml builder
│   │   └── verifier.ts           # On-chain verification (ethers v6)
│   ├── redis/
│   │   ├── client.ts             # Redis client
│   │   ├── cleanupWorker.ts      # Expired data cleanup
│   │   ├── constants.ts          # Redis key prefixes
│   │   ├── proofCache.ts         # Proof result caching
│   │   ├── proofResultStore.ts   # Proof result persistence
│   │   └── rateLimiter.ts        # Rate limiting
│   ├── skills/
│   │   ├── skillHandler.ts       # Skill routing
│   │   └── flowGuidance.ts       # Step-by-step flow guidance
│   ├── tee/
│   │   ├── index.ts              # TEE mode config
│   │   ├── attestation.ts        # NSM attestation validation (COSE Sign1)
│   │   ├── detect.ts             # TEE environment detection
│   │   ├── enclaveBuilder.ts     # Enclave image builder
│   │   ├── enclaveClient.ts      # Nitro Enclave vsock client
│   │   ├── encryption.ts         # AES-256-GCM encryption utilities
│   │   ├── teeKeyExchange.ts     # X25519 ECDH key exchange
│   │   └── validationSubmitter.ts # TEE validation on-chain
│   └── types/
│       └── index.ts
├── packages/
│   ├── sdk/                      # @zkproofport-ai/sdk (npm)
│   └── mcp/                      # @zkproofport-ai/mcp (npm)
├── aws/
│   ├── enclave-server.ts         # TypeScript TEE prover (Nitro Enclave)
│   ├── Dockerfile.enclave        # Enclave image
│   ├── deploy-blue-green.sh      # Zero-downtime deployment
│   ├── boot-active-slot.sh       # Systemd boot script
│   ├── stop-active-slot.sh       # Systemd stop script
│   ├── build-enclave.sh          # Enclave build helper
│   ├── ec2-setup.sh              # EC2 instance setup
│   ├── Caddyfile                 # Reverse proxy config
│   ├── docker-compose.aws.yml    # AWS Docker Compose
│   ├── vsock-bridge.py           # vsock-to-TCP bridge
│   └── systemd/                  # Systemd service files
├── sign-page/                    # Next.js signing page (WalletConnect)
├── tests/
│   ├── e2e/                      # Full E2E tests (REST, MCP, A2A, proof, verify)
│   ├── a2a/                      # A2A unit tests
│   ├── identity/                 # ERC-8004 identity tests
│   ├── integration/              # Integration tests
│   ├── payment/                  # Payment tests
│   ├── tee/                      # TEE tests
│   └── *.test.ts                 # Unit tests
├── docker-compose.yml            # Local dev: server + redis
├── docker-compose.test.yml       # Test stack: + a2a-ui + Phoenix
├── Dockerfile                    # Node.js server image
└── README.md

Quick Start

npm (Development)

npm install
npm run dev          # Hot reload with tsx
npm run build        # Build TypeScript
npm start            # Production
npm test             # Run tests
npm run test:e2e     # E2E tests against Docker stack

Docker Compose (Local)

docker compose up --build     # Start redis + server
docker compose down           # Stop
docker compose down -v        # Reset data

• Port 4002: Node.js server
• Port 6380 (host) → 6379 (container): Redis

E2E Encryption (Blind Relay)

Proof inputs are end-to-end encrypted between the client and the Nitro Enclave. The Node.js server passes the encrypted blob without reading it.

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

Single-step atomic flow — no middleware, no sessions:

POST /api/v1/prove { circuit, inputs }
  ↓
402 { nonce, price, payTo, teePublicKey }
  ↓
Client signs EIP-3009 TransferWithAuthorization (USDC)
  ↓
POST /api/v1/prove { circuit, encrypted_payload }
  + X-Payment-TX: <txHash>
  + X-Payment-Nonce: <nonce>
  ↓
200 { proof, publicInputs, proofWithInputs, attestation, timing, verification }

Payment modes:

REST Endpoints

MCP Tools

Available via /mcp (StreamableHTTP) or the local @zkproofport-ai/mcp package (stdio):

npm Packages

@zkproofport-ai/sdk   — TypeScript SDK for proof generation (ethers v6)
@zkproofport-ai/mcp   — Local MCP server for AI agents (stdio transport)

Install the MCP server for local AI agent usage:

npm install @zkproofport-ai/mcp
npx zkproofport-mcp    # Starts stdio MCP server

Guide System

GET /api/v1/guide/:circuit returns a comprehensive JSON guide for client AI agents to prepare all proof inputs. Includes:

• Step-by-step instructions with code examples
• Constants (attester keys, contract addresses, EAS schema UIDs)
• Formulas (nullifier computation, signal hash, Merkle tree construction)
• Input schema with types and descriptions
• EAS GraphQL query templates

Circuits use aliases: coinbase_kyc → coinbase_attestation, coinbase_country → coinbase_country_attestation, oidc_domain → oidc_domain_attestation.

A2A Protocol

A2A v0.3 JSON-RPC endpoint at POST /a2a:

Agent Card at /.well-known/agent.json provides ERC-8004 on-chain identity and capability discovery.

TEE Integration (AWS Nitro Enclave)

The enclave runs aws/enclave-server.ts (compiled to dist/aws/enclave-server.js) which executes bb prove with --oracle_hash keccak (required for Solidity verifier compatibility). NSM attestation binds the proof hash and TEE public key to the enclave measurement (PCR0/PCR1/PCR2).

Attestation validation chain: AWS Nitro Root CA → Regional → Zonal → Instance → Leaf certificate, verified with COSE ES384 signature.

Supported Circuits

Coinbase KYC (coinbase_attestation)

Proves holder has passed Coinbase KYC verification.

• Aliases: coinbase_kyc, coinbase_attestation
• Public Inputs: address, scope
• Nullifier: Yes (privacy, replay prevention)

Coinbase Country (coinbase_country_attestation)

Proves holder's KYC country matches attestation.

• Aliases: coinbase_country, coinbase_country_attestation
• Public Inputs: address, country, scope
• Nullifier: Yes (privacy, replay prevention)

OIDC Domain (oidc_domain_attestation)

Proves holder owns an email address at a specific domain via OIDC JWT verification.

• Aliases: oidc_domain, oidc_domain_attestation
• Input type: OIDC JWT (id_token from Google, etc.)
• Public Inputs: domain hash, scope
• Nullifier: Yes (privacy, replay prevention)

Contract Addresses

Base Sepolia (Testnet)

Base Mainnet (Production)

ERC-8004 Agent Identity

The agent auto-registers on-chain at startup via the ERC-8004 Identity contract. Reputation score increments after each successful proof generation.

Environment Variables

Required

Optional

Deployment (AWS Nitro Enclave)

proofport-ai deploys to AWS EC2 with Nitro Enclave support. Deployment uses blue-green slot switching for zero downtime.

Blue-Green Deployment

aws/deploy-blue-green.sh

• Two slots: blue (ports 4002/3200) and green (ports 4003/3201)
• Active slot tracked in /opt/proofport-ai/active-slot
• Caddy reload (not restart) switches traffic
• In-flight request drain before switching (up to 660s for proof generation)
• Automatic rollback if new container health check fails

Infrastructure

• Caddy — Reverse proxy with HTTPS (Cloudflare Full SSL)
• systemd — Services: proofport-ai, proofport-ai-redis, proofport-ai-enclave, vsock-bridge
• CloudWatch — Log driver awslogs, 30-day retention
• GitHub Actions — deploy-ai-aws.yml workflow (NOT deploy.yml which is GCP)

Boot / Stop

aws/boot-active-slot.sh    # Start active slot containers
aws/stop-active-slot.sh    # Stop active slot containers

Testing

npm test                # Unit tests
npm run test:e2e        # E2E against Docker stack
npm run test:watch      # Watch mode

A2A Testing (a2a-ui + Phoenix)

docker compose -f docker-compose.yml -f docker-compose.test.yml up --build -d

Version Locks

License

Apache 2.0