Skip to content

theyuvan/PrivOTC

Repository files navigation

PrivOTC — Human-Verified Confidential OTC Trading Protocol

Chainlink CRE + Groq AI + World ID + ZK-SNARKs + Tenderly Virtual TestNets

License: MIT Chainlink CRE Tenderly World ID

🎯 What is PrivOTC?

PrivOTC is a privacy-first OTC trading platform that combines AI-powered matching, confidential compute, and zero-knowledge proofs to enable institutional-grade peer-to-peer trading without compromising user privacy.

🔑 Key Innovation

Traditional OTC platforms expose sensitive trading data (balances, order books, pricing strategies) to operators and counterparties. PrivOTC solves this by running the entire matching engine inside Chainlink's Trusted Execution Environment (TEE) with AI-powered compatibility evaluation using Groq's LLaMA 3.1 70B model — all while maintaining complete confidentiality.

✨ Core Features

  • 🤖 AI-Powered Matching — Groq LLaMA 3.1 70B evaluates trade compatibility inside TEE
  • 🔒 Confidential Orderbook — All orders encrypted in Chainlink CRE's TEE
  • 🧮 Zero-Knowledge Proofs — Prove fund ownership without revealing balances
  • 🌍 Sybil Resistance — World ID ensures one trade per human
  • Atomic Settlement — On-chain execution only when matched
  • 🧪 Tenderly Testing — Virtual TestNets for safe contract testing

📺 Demo Video

▶️ Watch 5-Minute Demo

Showcases end-to-end workflow: World ID verification → ZK proof generation → AI matching in TEE → On-chain settlement


📺 Pitch Deck

▶️ View

📚 Detailed Technical Documentation

For in-depth technical details on each integration, see our comprehensive guides:

🔗 Integration Guides

Document Description Topics Covered
📘 How We Use CRE Complete Chainlink Runtime Environment integration HTTPCapability, CronCapability, ConfidentialHTTPClient, EVMClient, Runtime.report(), AI-in-TEE architecture
🌍 How We Use World ID World ID proof-of-personhood implementation IDKit integration, nullifier deduplication, sybil resistance, ZK proof verification
🧪 How We Use Tenderly Tenderly Virtual TestNets deployment & testing Contract deployment, transaction debugging, gas profiling, CRE integration

📖 Additional Resources


🏗️ System Architecture

High-Level Flow

graph TB
    subgraph Frontend["🌐 Frontend (Next.js)"]
        A[User Interface]
        B[World ID Verification]
        C[ZK Proof Generation]
    end
    
    subgraph CRE["🔐 Chainlink CRE (TEE)"]
        D[Trade Intake Handler]
        E[Groq AI Matching Engine]
        F[Confidential Orderbook]
        G[Settlement Orchestrator]
    end
    
    subgraph Blockchain["⛓️ Tenderly Virtual TestNet"]
        H[ProofVerifier Contract]
        I[EscrowVault Contract]
        J[OTCSettlement Contract]
    end
    
    subgraph External["🤖 External APIs"]
        K[Groq API - LLaMA 3.1 70B]
        L[World ID API]
    end
    
    A -->|Submit Trade| B
    B -->|Verify Human| L
    B -->|Generate ZK Proof| C
    C -->|Send to CRE| D
    D -->|Validate Proofs| H
    D -->|Add to Orderbook| F
    F -->|AI Evaluation| E
    E -->|Call AI| K
    E -->|Find Matches| G
    G -->|Execute Settlement| J
    J -->|Transfer Funds| I
    
    style CRE fill:#1a1a2e,stroke:#16c784,stroke-width:3px
    style K fill:#ff6b6b,stroke:#ee5a6f,stroke-width:2px
    style L fill:#000000,stroke:#ffffff,stroke-width:2px
Loading

Detailed Sequence Diagram

PrivOTC Complete Flow

Complete interaction flow showing all 9 phases of the system


🔗 Chainlink CRE Integration

🎯 CRE Workflow Overview

Location: privotc-cre/my-workflow/privotc-workflow.ts

Our CRE workflow orchestrates:

  1. Blockchain Integration (Tenderly Virtual TestNets)
  2. External API Integration (Groq AI for intelligent matching)
  3. Confidential Compute (TEE for privacy-preserving orderbook)
  4. Multi-chain Settlement (Ethereum & World Chain)

📡 Capabilities Used

CRE Capability Usage Implementation
HTTPCapability Trade intake from frontend Handler 0: handleTradeIntake
CronCapability Automated matching engine Handler 1: handleMatchingEngine (every 30s)
ConfidentialHTTPClient AI API calls in TEE evaluateTradeCompatibilityWithAI()
EVMClient On-chain settlement executeSettlement() with writeReport()
Runtime.report() Transaction signing ECDSA signing for settlement txs

🤖 AI Integration Details

AI Model: Groq LLaMA 3.1 70B Versatile (FREE!)
Purpose: Intelligent trade compatibility evaluation
Privacy: All AI calls happen inside TEE via ConfidentialHTTPClient

// AI Evaluation runs in encrypted TEE
async function evaluateTradeCompatibilityWithAI(
  runtime: Runtime<Config>,
  buy: TradeIntent,
  sell: TradeIntent
): Promise<{ match: boolean; confidence: number; reason: string }> {
  const httpClient = new ConfidentialHTTPClient();
  
  const response = httpClient.sendRequest(runtime, {
    vaultDonSecrets: [],
    request: {
      url: 'https://api.groq.com/openai/v1/chat/completions',
      method: 'POST',
      // ... AI evaluation logic
    }
  }).result();
  
  // Returns: {match: true, confidence: 0.85, reason: "Fair price spread"}
}

AI Decision Example:

🧠 Groq AI Decision: ✅ MATCH (85% confidence)
   Reason: "Price spread is fair (1.5%), orders within 2 minutes, low risk"

🔐 Confidential Orderbook

All trade intents stored in-memory inside TEE:

  • ❌ Never persisted to disk
  • ❌ Never visible to frontend
  • ❌ Never exposed to blockchain
  • ✅ Only matched trades execute on-chain

Code: privotc-workflow.ts#L187-L264


🧪 Tenderly Virtual TestNets Integration

🌐 Deployed Contracts

Tenderly Virtual TestNet: Ethereum Sepolia Fork
Chain ID: 9991
RPC URL: https://virtual.mainnet.eu.rpc.tenderly.co/9b993a3b-a915-4d11-9283-b43800cd39a5

Contract Address Explorer
OTCSettlement 0x41A580044F41C9D6BDe5821A4dF5b664A09cc370 View on Tenderly
EscrowVault 0xB61eC46b61E2B5eAdCB00DEED3EaB87B8f1dbC9f View on Tenderly
ProofVerifier 0x30da6632366698aB59d7BDa01Eb22B7cb474D57C View on Tenderly
BalanceVerifier 0xd76578726b87A5c62FC235C9805De20c12453a43 View on Tenderly

Deployment Details: contracts/deployments/tenderly-ethereum-latest.json

🔍 Transaction History

View all CRE-triggered settlements:

💡 Why Tenderly?

  1. Fast Iteration — Deploy/test contracts without mainnet fees
  2. State Forking — Test against real mainnet state
  3. Unlimited ETH — No faucet restrictions
  4. CRE Integration — Native support for Chainlink workflows
  5. Advanced Debugging — Transaction simulation & traces

📁 Repository Structure

🔗 Chainlink-Related Files

File/Folder Description Lines
privotc-cre/my-workflow/privotc-workflow.ts 🔴 MAIN CRE WORKFLOW — Orchestration layer 1000+
privotc-cre/my-workflow/privotc-config.json CRE configuration (RPC URLs, API keys) 20
privotc-cre/my-workflow/AI_MATCHING_GUIDE.md AI matching documentation 150+
contracts/contracts/OTCSettlement.sol Settlement contract (called by CRE) 200+
contracts/contracts/EscrowVault.sol Escrow management 150+
contracts/contracts/ProofVerifier.sol World ID + ZK verification 100+
frontend/app/api/trade/route.ts Frontend → CRE integration 50+
docs/SEQUENCE_DIAGRAM.md Complete system flow 600+

📂 Complete Structure

privotc/
├── privotc-cre/                    # 🔴 Chainlink CRE Workflows
│   └── my-workflow/
│       ├── privotc-workflow.ts     # Main orchestration logic
│       ├── privotc-config.json     # Configuration
│       ├── package.json            # Dependencies (@chainlink/cre-sdk)
│       └── AI_MATCHING_GUIDE.md    # AI integration docs
│
├── contracts/                      # Smart Contracts (Solidity)
│   ├── contracts/
│   │   ├── OTCSettlement.sol       # Settlement execution
│   │   ├── EscrowVault.sol         # Fund custody
│   │   ├── ProofVerifier.sol       # World ID verification
│   │   └── BalanceVerifier.sol     # ZK proof verification
│   ├── deployments/                # Tenderly deployment records
│   └── scripts/                    # Hardhat deployment scripts
│
├── frontend/                       # Next.js Frontend
│   ├── app/
│   │   ├── trade/                  # Trading interface
│   │   └── api/
│   │       ├── trade/              # CRE HTTP trigger
│   │       └── verify/             # World ID verification
│   └── lib/
│       ├── zkProofGenerator.ts     # ZK-SNARK generation
│       └── chainConfig.ts          # Contract addresses
│
├── zk-circuits/                    # ZK-SNARK Circuits (Circom)
│   ├── balance_proof.circom        # Balance ownership proof
│   └── verification_key.json       # Groth16 VK
│
└── docs/                           # Documentation
    ├── SEQUENCE_DIAGRAM.md         # System flow diagrams
    ├── AI_MATCHING_GUIDE.md        # AI integration guide
    └── sequence-diagram.png        # Visual flow chart

🚀 Getting Started

Prerequisites

  • Node.js 18+
  • Bun (for CRE compilation)
  • Hardhat (for contracts)
  • Circom 2.0+ (for ZK circuits)

1️⃣ Clone Repository

git clone https://github.com/theyuvan/chain.link.git
cd chain.link

2️⃣ Install Dependencies

# CRE Workflow
cd privotc-cre/my-workflow
bun install

# Smart Contracts
cd ../../contracts
npm install

# Frontend
cd ../frontend
npm install

# ZK Circuits
cd ../zk-circuits
npm install

3️⃣ Configure Environment

# CRE Configuration
cd privotc-cre/my-workflow
# Edit privotc-config.json with your:
# - Groq API key (free from console.groq.com)
# - Tenderly RPC URL
# - Contract addresses

# Contracts
cd ../../contracts
cp .env.example .env
# Add Tenderly access token

# Frontend
cd ../frontend
cp .env.example .env.local
# Add World ID app credentials

4️⃣ Run Simulation

# Terminal 1: Start Frontend
cd frontend
npm run dev

# Terminal 2: Simulate CRE Workflow
cd privotc-cre/my-workflow
bun x cre sim . --config privotc-config.json

# Terminal 3: Submit Test Trade
curl -X POST http://localhost:3000/api/trade \
  -H "Content-Type: application/json" \
  -d '{"side":"buy","token":"ETH","amount":"1.0","price":"3200"}'

5️⃣ Deploy to CRE Network

cd privotc-cre/my-workflow
bun x cre workflow deploy . --target privotc-production

🎬 Workflow Execution Demo

Simulation Output

🔍 Processing trade intake (PRODUCTION)...
1️⃣  Validating World ID proof...
✅ World ID proof accepted (nullifier: a1b2c3d4...)
2️⃣  Validating ZK balance proof...
✅ ZK proof structure validated (REAL Groth16 proof)
3️⃣  Adding to confidential orderbook...
✅ Trade intent added | Orderbook depth: 3 buys, 2 sells

🎯 Running matching engine (SIMULATION)...
🔍 Matching 3 buy orders vs 2 sell orders (AI: enabled)
🧠 Groq AI Decision: ✅ MATCH (85% confidence) - Price spread is fair (1.5%), orders within 2 minutes, low risk
   ✅ Match created: 1.5 ETH @ 3200
🧠 Groq AI Decision: ❌ NO MATCH (45% confidence) - Price spread too wide (buyer overpaying by 12%)
   ❌ AI rejected match: Buyer overpaying by 12%
✅ Matching complete: 1 total matches

💱 Executing on-chain settlement for match a1b2c3d4...
   Token: ETH (same-token trade)
   Amount: 1.5 @ 3200
   🚀 Sending settlement transaction to ethereum-testnet-sepolia...
   ✅ Settlement executed on-chain!
      Transaction hash: 0xabcd1234...

Key Metrics

  • Trade Intake: ~500ms (includes World ID + ZK validation)
  • AI Evaluation: ~300ms per trade pair (Groq API)
  • Matching Frequency: Every 30 seconds (configurable)
  • Settlement Time: ~2s (Tenderly Virtual TestNet)

🏆 Innovation Highlights

1. AI in TEE (First of its Kind)

Problem: Traditional AI matching exposes orderbook data to external APIs
Solution: Run Groq AI inside Chainlink TEE using ConfidentialHTTPClient
Result: 100% private AI decisions — orderbook never leaves encrypted environment

2. Zero-Knowledge Balance Proofs

Problem: OTC requires proving funds without revealing exact amounts
Solution: Custom Circom circuit generates Groth16 proofs
Result: Users prove balance >= trade_amount without disclosing balance

3. Sybil Resistance via World ID

Problem: Attackers can spam orders with fake accounts
Solution: World ID ensures one trade per verified human
Result: Nullifier-based deduplication in TEE

4. Multi-Chain Atomic Settlement

Problem: Cross-chain trades require trust in escrow operators
Solution: CRE orchestrates Ethereum + World Chain settlements
Result: Trustless cross-chain swaps via Chainlink's decentralized network


📊 Use Cases Solved

Traditional OTC Problem PrivOTC Solution
🔓 Orderbooks visible to operators 🔒 Encrypted in TEE, invisible to everyone
🤖 Bot manipulation & wash trading 🌍 World ID sybil resistance (one human = one trade)
💸 Counterparty knows your balance 🧮 ZK proofs hide exact amounts
🎲 Manual matching (slow, biased) 🤖 AI-powered matching (fast, fair)
🏦 Centralized escrow (trust required) ⛓️ Smart contract escrow (trustless)
🌐 Single-chain limitation 🔗 Multi-chain via CRE orchestration

🧪 Testing & Validation

CRE Workflow Simulation

# Test HTTP trigger
cd privotc-cre/my-workflow
bun x cre sim . --http-payload '{"worldIdProof":{...},"zkProof":{...},"trade":{...}}'

# Test cron matching
bun x cre sim . --cron

Smart Contract Testing

cd contracts
npm test

Test Coverage:

  • ✅ World ID nullifier deduplication
  • ✅ ZK proof verification (Groth16)
  • ✅ Escrow deposit/release/refund
  • ✅ Settlement replay attack prevention
  • ✅ Multi-token support (ETH, WLD)

Integration Testing

# End-to-end flow on Tenderly
cd scripts
npm run test:integration

Security Considerations

TEE Security

  • All orderbook data encrypted at rest & in transit
  • Memory wiped after workflow execution
  • No persistent storage inside TEE

ZK Proof Security

  • Groth16 proofs (industry standard)
  • Trusted setup using Powers of Tau ceremony
  • Circuit audited for soundness

Smart Contract Security

  • OpenZeppelin contracts (battle-tested)
  • Reentrancy guards on all fund transfers
  • Timeout protection for escrow refunds

🎓 Technical Stack

Component Technology
Orchestration Chainlink Runtime Environment (CRE)
AI Matching Groq API — LLaMA 3.1 70B Versatile
Privacy Zero-Knowledge Proofs (Circom + Groth16)
Sybil Resistance World ID (Orb-verified humans)
Smart Contracts Solidity 0.8.20 + OpenZeppelin
Blockchain Testing Tenderly Virtual TestNets
Frontend Next.js 15 + TypeScript
ZK Library snarkjs 0.7+
HTTP Client CRE ConfidentialHTTPClient (TEE-safe)

👥 Team & Contributions

Developers: @yuvan,@Rohit ,@azar
Hackathon: Chainlink + Tenderly Virtual TestNets Track
Development Time: 3 weeks (Feb 15 - Mar 8, 2026)

Contribution Breakdown

  • 40% CRE Workflows — Confidential matching engine, AI integration, settlement orchestration
  • 25% Smart Contracts — OTC settlement, escrow vault, proof verification
  • 20% ZK Circuits — Balance proof circuit, trusted setup
  • 15% Frontend — World ID integration, ZK proof generation, UI/UX

🌟 Future Roadmap

  • Advanced AI Features — Multi-model ensemble (Claude + GPT-4 + Groq)
  • Cross-Chain Expansion — Support more chains (Arbitrum, Optimism, Polygon)
  • Liquidity Pools — Aggregate liquidity from multiple sources
  • Flash Loan Protection — Integrate Chainlink Price Feeds for manipulation detection
  • Mobile App — World App Mini App for iOS/Android
  • Governance — DAO for parameter tuning (AI threshold, matching frequency)

📄 License

MIT License — See LICENSE for details


🙏 Acknowledgments

  • Chainlink — For CRE Early Access & comprehensive documentation
  • Tenderly — For Virtual TestNets & developer tools
  • Worldcoin — For World ID SDK & staging environment
  • Groq — For FREE ultra-fast LLaMA inference
  • Polygon — For ZK circuit inspirations

📞 Contact & Links


Built with 💚 for Chainlink + Tenderly Hackathon

Privacy-Preserving AI-Powered OTC Trading — Made Possible by Chainlink CRE

📁 Repository Structure

chain.link/
├── privotc-cre/         # Chainlink CRE confidential workflows (TypeScript)
├── frontend/            # Next.js frontend (World ID + ZK proofs)
├── contracts/           # Smart contracts (Solidity)
├── zk-circuits/         # ZK balance proof circuits (Circom)
├── docs/                # System documentation
├── CRE.md              # Chainlink CRE integration guide
├── WORLD_ID.md         # World ID integration guide
├── TENDERLY.md         # Tenderly Virtual TestNets guide
└── README.md           # This file

� Quick Start

1. Clone Repository

git clone https://github.com/theyuvan/chain.link.git
cd chain.link

2. Setup CRE Workflow

cd privotc-cre/my-workflow
npm install
cp .env.example .env
# Edit .env with your configuration
npm run build

3. Setup Frontend

cd ../../frontend
npm install
cp .env.local.example .env.local
# Configure World ID and contract addresses
npm run dev

4. Setup Smart Contracts

cd ../contracts
npm install
cp .env.example .env
# Add Tenderly RPC URL and private key
npx hardhat run scripts/deployTenderly.ts --network tenderly-ethereum

5. Simulate CRE Workflow

cd ../privotc-cre/my-workflow
bun x cre sim . --config privotc-config.json

🔐 Technology Stack

Privacy & Confidential Compute

  • Chainlink CRE — Trusted Execution Environment (TEE)
  • Circom 2.0.0 — ZK circuit language
  • snarkjs — Proof generation/verification
  • Poseidon Hash — Privacy commitments
  • Groq LLaMA 3.1 70B — AI matching inside TEE

Frontend

  • Next.js 15.1.4 — Web framework
  • World ID — Sybil resistance
  • TypeScript — Type safety
  • Tailwind CSS — Styling

Smart Contracts & Testing

  • Solidity 0.8.20 — Contract language
  • Hardhat — Development framework
  • Tenderly Virtual TestNets — Testing environment (Chain ID 9991)

📊 What's Built

1. ZK Balance Proof Circuit

File: zk-circuits/circuits/balanceProof.circom

Proves: "I have ≥ X tokens" without revealing actual balance

Inputs (Private):

  • Wallet address
  • Actual balance
  • Token address
  • Salt

Outputs (Public):

  • Balance sufficient? (yes/no)
  • Wallet commitment (hash)
  • Proof hash (unique ID)

2. CRE Workflows

Handler 0: Trade Intake (HTTP)

  • Validates World ID proof
  • Verifies ZK balance proof
  • Adds to confidential orderbook

Handler 1: Matching Engine (Cron - every 30s)

  • AI-powered compatibility evaluation
  • Finds matching buy/sell orders
  • Only reveals matched pairs
  • Triggers settlement

Handler 2: Frontend Polling (Cron - every 15s)

  • Provides match status updates
  • Returns settlement transaction hashes

Handler 3: Manual Matching (HTTP)

  • Admin-triggered matching
  • For testing and debugging

3. Smart Contracts (Tenderly)

  • OTCSettlement — Atomic trade execution
  • EscrowVault — Fund custody & release
  • ProofVerifier — World ID verification
  • BalanceVerifier — ZK-SNARK verification

📚 Documentation

Document Description
CRE.md Complete Chainlink CRE integration guide
WORLD_ID.md World ID proof-of-personhood implementation
TENDERLY.md Tenderly Virtual TestNets deployment guide
CHAINLINK_INTEGRATION.md All CRE SDK imports and API reference
docs/SEQUENCE_DIAGRAM.md Complete system interaction flow

🔧 Environment Setup

Prerequisites

  • Node.js 18+ (for both zk-circuits and cre)
  • WSL (for Circom compilation)
  • Circom compiler
  • CRE CLI (irm https://cre.chain.link/install.ps1 | iex)

Configuration Files

Create these files:

# CRE workflows environment
privotc-cre/my-workflow/.env

# Frontend environment
frontend/.env.local

# Smart contracts environment
contracts/.env

# Required variables:
# - TENDERLY_RPC_URL
# - GROQ_API_KEY
# - WORLD_ID_APP_ID
# - Contract addresses (after deployment)

🧪 Testing

Quick test:

# Test ZK circuits
cd zk-circuits
npm run compile && npm run setup && npm test

# Test smart contracts
cd ../contracts
npx hardhat test --network tenderly-ethereum

# Simulate CRE workflows
cd ../privotc-cre/my-workflow
bun x cre sim . --config privotc-config.json

🚀 Deployment

CRE Workflow Simulation

cd privotc-cre/my-workflow
bun x cre sim . --config privotc-config.json

Smart Contracts to Tenderly

cd contracts
npx hardhat run scripts/deployTenderly.ts --network tenderly-ethereum

Frontend

cd frontend
npm run build
npm start

🔒 Security Considerations

  1. Never commit .env files — Contains private keys!
  2. Trusted setup — In production, use multi-party ceremony (MPC)
  3. World ID nullifiers — Tracked to prevent double-trading
  4. Proof expiry — ZK proofs expire after 5 minutes
  5. Confidential compute — All workflows run in TEE

📊 Privacy Guarantees

Data Visibility
Wallet address ❌ Hidden (commitment only)
Actual balance ❌ Never revealed
Unmatched orders ❌ Stay in TEE
Trade intent ❌ Encrypted until matched
Matched trades ✅ Public (for settlement)
World ID proof ✅ Verified, nullifier stored

🎯 Success Metrics

Project is successful when:

  • ZK circuits compile and generate valid proofs
  • CRE workflows deploy successfully
  • Frontend integrates with CRE endpoints
  • Real user completes end-to-end trade
  • Privacy properties verified:
    • Balance never revealed
    • Unmatched orders stay private
    • One trade per verified human

🐛 Troubleshooting

Common Issues

"Verification key not found" → Run: cd zk-circuits && npm run setup

"Contract addresses not configured" → Deploy contracts first, then update privotc-cre/my-workflow/privotc-config.json

"CRE simulation failed" → Check CRE installation: bun x cre --version

"World ID validation failed" → Use real proof from World Mini App, check staging credentials

🎓 Learning Resources

📄 License

MIT License — Hackathon Project


Ready to build the future of private trading! 🚀

Start here: CRE.mdWORLD_ID.mdTENDERLY.md

About

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors