zkproofport/proofport-ai
8004 agent identity. Reference application [OpenStoa](https://github.com/zkproofport/openstoa) won 1st place at The Synthesis Hackathon ("Agents That Keep Secrets" track).
Ask AI about zkproofport/proofport-ai
Powered by Claude Β· Grounded in docs
I know everything about zkproofport/proofport-ai. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
nitromode, 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)
- TEE generates X25519 key pair on startup, binds public key to NSM attestation
- Client fetches TEE public key from 402 response, verifies attestation
- Client generates ephemeral X25519 keypair, computes ECDH shared secret, derives AES key via SHA-256
- Client encrypts inputs with AES-256-GCM, sends
{ ephemeralPublicKey, iv, ciphertext, authTag, keyId } - Server passes encrypted envelope to enclave via vsock (blind relay)
- 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:
| Mode | Network | Effect |
|---|---|---|
disabled | None | All requests free |
testnet | Base Sepolia | Require USDC payment (testnet) |
mainnet | Base Mainnet | Require USDC payment (production) |
REST Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/health | GET | Health check + TEE status + payment mode |
/api/v1/prove | POST | x402 single-step proof generation |
/api/v1/guide/:circuit | GET | Dynamic proof generation guide (JSON) |
/mcp | POST | StreamableHTTP MCP endpoint |
/a2a | POST | A2A JSON-RPC endpoint |
/.well-known/agent.json | GET | OASF Agent Card |
/agent-card.json | GET | A2A Agent Card |
/.well-known/mcp.json | GET | MCP discovery |
/docs | GET | Swagger UI |
/openapi.json | GET | OpenAPI spec |
MCP Tools
Available via /mcp (StreamableHTTP) or the local @zkproofport-ai/mcp package (stdio):
| Tool | Purpose |
|---|---|
generate_proof | All-in-one proof generation (x402 payment + E2E encryption auto-detect) |
verify_proof | On-chain proof verification |
get_supported_circuits | List available circuits |
request_challenge | Request 402 challenge (step-by-step flow) |
make_payment | Make x402 USDC payment (step-by-step flow) |
submit_proof | Submit proof inputs (step-by-step flow) |
prepare_inputs | Prepare circuit inputs (step-by-step flow) |
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:
| Method | Purpose |
|---|---|
message/send | Submit proof task (blocking) |
message/stream | Submit proof task (SSE streaming) |
tasks/get | Query task status |
tasks/cancel | Cancel a running task |
tasks/resubscribe | Resubscribe to task events |
Agent Card at /.well-known/agent.json provides ERC-8004 on-chain identity and capability discovery.
TEE Integration (AWS Nitro Enclave)
| Mode | Behavior |
|---|---|
disabled | Standard Linux, no TEE, plaintext allowed |
nitro | AWS Nitro Enclave, hardware attestation, E2E encryption enforced |
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_tokenfrom Google, etc.) - Public Inputs: domain hash, scope
- Nullifier: Yes (privacy, replay prevention)
Contract Addresses
Base Sepolia (Testnet)
| Contract | Address |
|---|---|
| KYC Verifier | 0x0036B61dBFaB8f3CfEEF77dD5D45F7EFBFE2035c |
| Country Verifier | 0xdEe363585926c3c28327Efd1eDd01cf4559738cf |
| ERC-8004 Identity | 0x8004A818BFB912233c491871b3d84c89A494BD9e |
| ERC-8004 Reputation | 0x8004B663056A597Dffe9eCcC1965A193B7388713 |
Base Mainnet (Production)
| Contract | Address |
|---|---|
| ERC-8004 Identity | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 |
| ERC-8004 Reputation | 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 |
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
| Variable | Description |
|---|---|
REDIS_URL | Redis connection string |
BASE_RPC_URL | Base chain RPC endpoint |
CHAIN_RPC_URL | RPC for proof verification |
EAS_GRAPHQL_ENDPOINT | EAS GraphQL endpoint for attestation queries |
PROVER_PRIVATE_KEY | Agent wallet private key (64 hex chars, no 0x) |
PAYMENT_MODE | disabled / testnet / mainnet |
A2A_BASE_URL | Public-facing service URL (for Agent Card) |
Optional
| Variable | Default | Description |
|---|---|---|
PORT | 4002 | Express server port |
NODE_ENV | development | Node environment |
BB_PATH | bb | Barretenberg CLI path |
NARGO_PATH | nargo | Nargo CLI path |
CIRCUITS_DIR | /app/circuits | Circuit artifacts directory |
CIRCUITS_REPO_URL | (GitHub raw URL) | Circuit artifacts download URL |
TEE_MODE | disabled | disabled / nitro |
ENCLAVE_CID | β | Nitro Enclave CID (required when TEE_MODE=nitro) |
ENCLAVE_PORT | 5000 | Nitro Enclave port |
TEE_ATTESTATION | false | Enable attestation verification |
PAYMENT_PAY_TO | β | Operator wallet (required when payment enabled) |
PAYMENT_PROOF_PRICE | $0.10 | Price per proof (USD) |
ERC8004_IDENTITY_ADDRESS | β | ERC-8004 Identity contract |
ERC8004_REPUTATION_ADDRESS | β | ERC-8004 Reputation contract |
GEMINI_API_KEY | β | Gemini API key for chat |
OPENAI_API_KEY | β | OpenAI API key for chat |
PHOENIX_COLLECTOR_ENDPOINT | β | Phoenix OTLP endpoint for tracing |
AGENT_VERSION | 1.0.0 | Agent version string |
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.ymlworkflow (NOTdeploy.ymlwhich 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
| Service | URL | Purpose |
|---|---|---|
| proofport-ai | http://localhost:4002 | Agent server |
| a2a-ui | http://localhost:3001 | A2A web test UI |
| Phoenix | http://localhost:6006 | Trace visualization |
Version Locks
| Tool | Version |
|---|---|
| bb (Barretenberg) | v1.0.0-nightly.20250723 |
| nargo | 1.0.0-beta.8 |
| ethers | ^6.13.0 |
| @modelcontextprotocol/sdk | ^1.0.0 |
| Node.js | 20 LTS |
License
Apache 2.0
