ZK API Usage Credits

Anonymous API access with ZK proofs. Deposit ETH once, make unlimited anonymous requests to any API service with no identity tracking or request linking.

TS implementation of the ZK API Usage Credits: LLMs and Beyond proposal by Davide Crapis & Vitalik Buterin.

Workflow

1. Deposit ETH to smart contract with anonymous identity commitment
2. Generate ZK proof of solvency for each API request
3. Request any API service anonymously with proof and nullifier (Claude API example included)
4. Receive refund ticket for unused credits
5. Redeem accumulated refunds on-chain

Install

pnpm install
forge install
cp .env.template .env.local

Test

Unit tests

pnpm test

End-to-end tests

pnpm test:e2e

Integration tests

Make sure Anvil is running (in a separated tab):

anvil

Same for the API (in a separated tab too):

pnpm start:dev

Make test scripts executable (first time only):

chmod +x scripts/test-complete-flow.sh
chmod +x scripts/test-double-spend.sh
chmod +x scripts/test-invalid-proofs.sh
chmod +x scripts/test-refund-redemption.sh

Then run:

pnpm test:zk

Or run individual ZK tests:

bash scripts/test-complete-flow.sh      # Complete deposit → API → refund flow
bash scripts/test-double-spend.sh       # Double-spend prevention
bash scripts/test-invalid-proofs.sh     # Invalid proof rejection
bash scripts/test-refund-redemption.sh  # On-chain refund redemption

Run

Local Development

# Generate TLS certificates
mkdir -p secrets
openssl req -x509 -newkey rsa:4096 \
  -keyout secrets/tls.key \
  -out secrets/tls.cert \
  -days 365 -nodes \
  -subj "/CN=localhost"

# Generate EdDSA keypair (optional - auto-generates if not set)
pnpm ts-node scripts/generate-admin-keypair.ts

# Start server
pnpm start:dev

API available at https://localhost:3000

Production Deployment

The application supports multiple deployment strategies:

🏠 Basic Ubuntu VPS (no TEE):

NODE_ENV=production
OPERATOR_PRIVATE_KEY=0x...  # EdDSA key for refund signatures
pnpm start:prod

🔐 Phala TEE:

NODE_ENV=production
# Phala injects encrypted secrets automatically

See PHALA_CONFIG.md

☁️ Cloud with KMS (AWS/GCP/Azure):

NODE_ENV=production
KMS_URL=https://kms.example.com/secrets
# Fetches OPERATOR_PRIVATE_KEY from KMS using TEE attestation

See TEE_SETUP.md

Secret Management: The OPERATOR_PRIVATE_KEY is never stored on disk. It's loaded into memory via SecretsService which supports environment variables, Phala encrypted secrets, or KMS with TEE attestation. See SQLITE3.md for details.

Docs

• API_REFERENCE.md - REST API endpoints and request/response formats
• ZK.md - Zero-Knowledge circuits and cryptographic proofs
• OVERVIEW.md - System architecture and design
• LOCAL_SETUP.md - Development setup without Docker
• DOCKER.md - Docker development environment
• TEE_SETUP.md - Production deployment to TEE (AMD SEV-SNP, Intel TDX, AWS Nitro, Phala)
• PHALA_CONFIG.md - Phala Cloud configuration
• TESTING_GUIDE.md - Test procedures and verification scripts
• TRUSTED_SETUP_CEREMONY.md - Powers of Tau ceremony for ZK circuits
• SQLITE3.md - Persistent storage and privacy design
• MLKEM.md - Post-quantum encryption implementation
• SIWE.md - Sign-In with Ethereum integration

Credits

Inspired by the Ethresear.ch proposal ZK API Usage Credits: LLMs and Beyond by Davide Crapis & Vitalik Buterin

Based on the Wulong API template by W3HC: https://github.com/w3hc/wulong

License

LGPL-3.0

Contact

Julien Béranger (GitHub)

• Element: @julienbrg:matrix.org
• Farcaster: julien-
• Telegram: @julienbrg