VeilPay

Zero-Knowledge Privacy Protocol for Multi-Asset Transfers on Stacks

NEW: Bot-to-Bot AI Economy with Private Payments 🤖

Live Demo · Bot Marketplace · API Docs · Smart Contracts · GitHub

---

Table of Contents

• Overview
• Core Features
• Technical Specifications
• How It Works
• Architecture
• Quick Start
• Smart Contracts
• Technology Stack
• Real-World Use Cases
• Technical Deep Dive
• Roadmap
• Why VeilPay Matters
• Security Model
• FAQ
• Contributing

---

Overview

VeilPay is the first Zero-Knowledge privacy protocol for USDCx on Stacks, enabling completely private, anonymous transfers using state-of-the-art cryptographic techniques. By leveraging Groth16 ZK-SNARKs and Poseidon hash functions, VeilPay breaks on-chain surveillance while maintaining the stability and regulatory compliance of Circle's USDCx stablecoin.

The Privacy Problem

Blockchain transparency is a fundamental feature—but it comes at a cost. Every transaction is publicly visible, exposing:

• Complete transaction history
• Wallet balances and holdings
• Sender-receiver relationships
• Spending patterns and behavior

VeilPay solves this by providing cryptographic privacy guarantees through Zero-Knowledge proofs, allowing you to maintain financial confidentiality without sacrificing decentralization or security.

---

Core Features

VeilPay provides enterprise-grade privacy for USDCx transfers through a sophisticated cryptographic architecture:

Privacy-Preserving Deposits

Lock USDCx in smart contract with cryptographic commitments using Poseidon hash function. Deposits are represented as commitment = poseidon(secret, amount, nonce), revealing nothing about the transaction details.

Anonymous Withdrawals

Prove ownership of a deposit without revealing which specific deposit is yours. Zero-Knowledge proofs enable withdrawal to any address with complete unlinkability from the original deposit.

Merkle Tree Accumulator

Efficient commitment storage with 1,048,576+ capacity (20-level tree). All deposits exist in the same anonymity set, maximizing privacy guarantees.

Nullifier Protection

Cryptographic nullifiers prevent double-spending while maintaining privacy. Each deposit can only be withdrawn once, enforced on-chain without revealing identity.

Client-Side Proof Generation

Browser-based Zero-Knowledge proof creation using WebAssembly circuits. No backend required—privacy is guaranteed by mathematics, not trust.

Hybrid Verification Architecture

Off-chain proof verification via relayer with on-chain settlement. Designed for future migration to native on-chain verification when Stacks adds SNARK precompiles.

x402 Payment Protocol Integration (NEW!)

VeilPay now supports the x402-stacks programmatic payment protocol, enabling private HTTP 402 payments with multi-asset support (STX, USDCx, sBTC). First implementation combining x402 with Zero-Knowledge privacy. Learn more

Bot-to-Bot AI Economy (NEW!)

VeilPay now hosts a marketplace of AI analysis bots that accept private payments via ZK proofs. Bots can hire other bots without transaction correlation, creating the first fully private AI agent economy on Stacks. Includes Security Bot (5 STX), Tokenomics Bot (3 STX), Sentiment Bot (2 STX), and Coordinator Bot (10 STX). Developer Guide

---

Technical Specifications

Component	Technology	Performance	Security
ZK Proof System	Groth16 SNARKs	~15s generation, <10ms verification*	128-bit security, ~1M constraints
Hash Function	Poseidon	~10x faster than SHA-256 in circuits	SNARK-friendly, collision-resistant
Privacy Set	20-level Merkle tree	1,048,576 deposit capacity	Cryptographic accumulator
Proof Size	Groth16	192 bytes (3 curve points)	Constant size, succinct
Smart Contract	Clarity v2	Gas-optimized deposit/withdraw	Type-safe, decidable
Token Integration	USDCx (SIP-010)	Native fungible token support	Circle-backed stablecoin

_{* On-chain verification timing when Stacks adds SNARK precompiles}

---

How It Works

VeilPay implements a cryptographic privacy protocol through a two-phase process:

Phase 1: Deposit

User generates:
  secret (256-bit random)
  nonce (256-bit random)

Calculate commitment:
  commitment = Poseidon(secret, amount, nonce)

Submit to blockchain:
  deposit(commitment, amount) → Lock USDCx in contract

Off-chain indexer:
  Add commitment to Merkle tree → Update root on-chain

Result: USDCx is locked in smart contract. Only the commitment hash is public—the secret, amount, and nonce remain private.

Phase 2: Withdrawal

User requests:
  Merkle proof for commitment from relayer

Generate ZK proof (browser):
  Prove: "I know secret for some commitment in tree"
  Public: root, nullifierHash, recipient
  Private: secret, amount, nonce, merkle_proof

Submit to relayer:
  Relayer verifies proof → Signs transaction

Smart contract validates:
  1. Relayer signature valid
  2. Root exists in valid roots
  3. Nullifier not used
  4. Release USDCx to recipient

Result: USDCx is transferred to recipient address. No on-chain link between deposit and withdrawal.

Privacy Guarantees

Mathematical Unlinkability: Zero-Knowledge proofs cryptographically guarantee that deposits and withdrawals cannot be correlated. Even with full blockchain access, an adversary cannot determine which deposit corresponds to which withdrawal.

Key Properties:

• Commitment Hiding: Poseidon hash reveals nothing about secret, amount, or nonce
• Nullifier Unlinkability: Cannot be traced back to original commitment
• Anonymity Set: All deposits in tree are indistinguishable
• Non-Interactive: No communication required between users

---

Architecture

flowchart TB
    subgraph Ethereum["Ethereum Network"]
        USDC["USDC Token"]
        xReserve["Circle xReserve"]
    end

    subgraph Bridge["Cross-Chain Bridge"]
        Attestation["Stacks Attestation Service"]
    end

    subgraph Stacks["Stacks Blockchain"]
        USDCx["USDCx Token Contract<br/>(SIP-010)"]

        subgraph Contracts["VeilPay Smart Contracts"]
            VeilPayContract["veilpay.clar<br/>(Privacy Pool)"]
            ValidRoots["Merkle Root Registry"]
            Nullifiers["Nullifier Set"]
        end
    end

    subgraph OffChain["Off-Chain Infrastructure"]
        Relayer["Node.js Relayer"]
        MerkleTree["Merkle Tree Manager<br/>(Poseidon Hash)"]
        Verifier["ZK Proof Verifier<br/>(snarkjs)"]
        Indexer["Blockchain Indexer"]
    end

    subgraph Frontend["React Frontend"]
        WalletConnect["Wallet Connection"]
        DepositUI["Deposit Interface"]
        WithdrawUI["Withdraw Interface"]
        ProofGen["ZK Proof Generator<br/>(Browser WASM)"]
        Crypto["Poseidon Crypto Utils"]
    end

    subgraph Wallets["Supported Wallets"]
        Leather["Leather Wallet"]
        Hiro["Hiro Wallet"]
    end

    subgraph ZKCircuits["Zero-Knowledge Circuits"]
        WithdrawCircuit["withdraw.circom<br/>(Groth16)"]
        PoseidonCircuit["Poseidon Hash"]
        MerkleCircuit["Merkle Tree Verifier"]
    end

    USDC -->|Deposit| xReserve
    xReserve -->|Attestation| Attestation
    Attestation -->|Mint| USDCx

    USDCx <-->|Lock/Release| VeilPayContract
    VeilPayContract <-->|Store| ValidRoots
    VeilPayContract <-->|Check| Nullifiers

    DepositUI -->|calc commitment| Crypto
    Crypto -->|deposit| VeilPayContract
    VeilPayContract -->|emit event| Indexer
    Indexer -->|add leaf| MerkleTree
    MerkleTree -->|update root| VeilPayContract

    WithdrawUI -->|get proof| Relayer
    Relayer -->|Merkle proof| MerkleTree
    WithdrawUI -->|generate| ProofGen
    ProofGen -->|use circuit| WithdrawCircuit
    WithdrawCircuit -->|verify| PoseidonCircuit
    WithdrawCircuit -->|verify| MerkleCircuit
    ProofGen -->|proof signals| Verifier
    Verifier -->|verify proof| Relayer
    Relayer -->|sign submit tx| VeilPayContract
    VeilPayContract -->|transfer USDCx| WithdrawUI

    WalletConnect --> Leather
    WalletConnect --> Hiro

Loading

System Components

Frontend Layer (React + Vite)

• Zero-Knowledge proof generation (snarkjs + WASM)
• Poseidon hash commitment calculation (circomlibjs)
• Wallet integration (@stacks/connect)
• Deposit/Withdrawal UI

Off-Chain Layer (Node.js + Express)

• Merkle tree manager (Poseidon hash)
• ZK proof verification (snarkjs)
• Blockchain event indexer
• Transaction relayer with signature

Smart Contract Layer (Clarity)

• Privacy pool contract (deposit/withdraw)
• Merkle root registry (valid roots)
• Nullifier tracking (double-spend prevention)
• USDCx token interface (SIP-010)

ZK Circuit Layer (Circom)

• Withdrawal circuit (Groth16 proof system)
• Poseidon hash constraints
• Merkle tree verification (20 levels)
• Nullifier derivation

Blockchain Layer

• Stacks L2 (Transaction Settlement)
• Bitcoin L1 (Security Anchor)
• Ethereum L1 (USDC Source Chain)

---

Privacy Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Contract as VeilPay Contract
    participant USDCx as USDCx Token
    participant Relayer
    participant MerkleTree as Merkle Tree

    Note over User, MerkleTree: Deposit Flow (Public Transaction)

    User->>Frontend: Generate secret + nonce
    Frontend->>Frontend: commitment = poseidon(secret, amount, nonce)
    Frontend->>USDCx: Approve USDCx transfer
    USDCx-->>Frontend: Approved
    Frontend->>Contract: deposit(commitment, amount)
    Contract->>USDCx: Transfer USDCx to pool
    USDCx-->>Contract: Funds locked
    Contract-->>Frontend: Deposit confirmed
    Contract->>Relayer: Event: new commitment
    Relayer->>MerkleTree: Add leaf(commitment)
    MerkleTree-->>Relayer: New root
    Relayer->>Contract: update-root(new-root)
    Contract-->>Relayer: Root stored

    Note over User, MerkleTree: Withdraw Flow (Private Transaction)

    User->>Frontend: Enter secret + nonce + recipient
    Frontend->>Relayer: GET /proof/{commitment}
    Relayer->>MerkleTree: Get Merkle proof
    MerkleTree-->>Relayer: pathElements + pathIndices
    Relayer-->>Frontend: Merkle proof + root
    Frontend->>Frontend: Generate ZK proof<br/>(Browser WASM, ~15s)
    Note over Frontend: Private: secret, nonce, amount, proof<br/>Public: root, nullifierHash, recipient
    Frontend->>Relayer: POST /withdraw {proof, signals}
    Relayer->>Relayer: Verify ZK proof (snarkjs)
    Relayer->>Relayer: Check nullifier not used
    Relayer->>Relayer: Check root is valid
    Relayer->>Contract: withdraw(nullifier, recipient, signature)
    Contract->>Contract: Verify signature
    Contract->>Contract: Check nullifier not used
    Contract->>Contract: Check root is valid
    Contract->>Nullifiers: Mark nullifier used
    Contract->>USDCx: Transfer to recipient
    USDCx-->>User: Funds received (anonymously!)

Loading

Privacy Guarantees

Unlinkability: Cannot correlate which deposit → which withdrawal because:

• Commitment hiding: poseidon(secret, amount, nonce) reveals nothing about the inputs
• Nullifier hiding: poseidon(secret, nonce) is unique per deposit but unlinkable to commitment
• ZK proof: Proves "I know a secret for some commitment in the tree" without revealing which one
• Merkle tree: All deposits are in the same anonymity set (1M+ capacity)

Security Properties:

• ✅ Privacy: Deposits and withdrawals are cryptographically unlinkable
• ✅ No double-spending: Nullifiers prevent claiming the same deposit twice
• ✅ Non-custodial: Only commitment owner can generate valid proof
• ✅ Trustless: ZK proofs are cryptographically verified (trust relayer only for censorship resistance)

Privacy Process Steps

Deposit Phase:

1. Secret Generation: User generates random secret and nonce (256-bit entropy, client-side)
2. Commitment Creation: Calculate commitment = poseidon(secret, amount, nonce)
3. Lock Funds: Transfer USDCx to privacy pool smart contract
4. Tree Update: Relayer indexes deposit event and adds commitment to Merkle tree
5. Save Credentials: User securely stores secret and nonce for future withdrawal

Withdrawal Phase:

1. Proof Request: User requests Merkle proof for their commitment from relayer
2. ZK Generation: Browser generates Zero-Knowledge proof using WASM circuit (~15s)
3. Proof Verification: Relayer verifies proof validity with snarkjs off-chain
4. Transaction Submission: Relayer signs verified proof and submits withdrawal transaction
5. Privacy Transfer: Smart contract releases USDCx to recipient - completely unlinkable from deposit!

---

Bot-to-Bot AI Economy

VeilPay introduces the first decentralized bot marketplace where AI agents can hire specialized analysis bots using private ZK-SNARK payments. All bot-to-bot payments are made through VeilPay pools, ensuring complete transaction unlinkability.

Available Bots

Bot	Price	Capabilities	Use Case
Security Bot	5 STX	AI-powered contract auditing, reentrancy detection, access control analysis	Smart contract security assessment
Tokenomics Bot	3 STX	SIP-010 token analysis, holder distribution, DEX liquidity metrics	Token health evaluation
Sentiment Bot	2 STX	GitHub activity, on-chain metrics, news sentiment, AI synthesis	Project sentiment analysis
Coordinator Bot	10 STX	Orchestrates all 3 worker bots, generates investment recommendations	Full project due diligence

How It Works

Standard x402 Payment Flow:

1. User calls bot endpoint: POST /x402/bots/security/audit
2. Bot returns HTTP 402 (Payment Required)
3. User pays 5 STX via standard x402 flow
4. Bot executes analysis and returns results

Private VeilPay Payment Flow:

1. User deposits STX to VeilPay pool (one-time)
2. User receives (secret, nonce) credentials
3. User generates ZK proof for payment
4. User calls bot with proof headers
5. Bot verifies proof via relayer
6. Bot executes analysis - FULLY PRIVATE!

Bot-to-Bot Payments

The Coordinator Bot demonstrates autonomous bot hiring with complete privacy:

// Coordinator Bot privately hires 3 worker bots
const securityResult = await veilPayClient.callWorkerBot(
  'https://security-bot.onrender.com',
  '/audit',
  { contractAddress, contractName },
  secret,  // VeilPay credentials
  nonce,
  5_000_000 // 5 STX payment
);

// No transaction correlation between coordinator and worker bots!

Privacy Guarantee: Even the worker bots cannot determine which coordinator hired them. All payments are cryptographically unlinkable.

Integration Guide

Developers can integrate VeilPay bot marketplace in two ways:

1. Use Existing Bots - Hire Security, Tokenomics, Sentiment, or Coordinator bots via standard API calls:

import axios from 'axios';

const relayer = axios.create({
  baseURL: 'https://veilpay-relayer.onrender.com'
});

// Hire Security Bot (5 STX payment)
const response = await relayer.post('/x402/bots/security/audit', {
  contractAddress: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
  contractName: 'my-contract',
  fullAnalysis: true
});

2. Build Your Own Bot - Create custom analysis bots and monetize via VeilPay:

• Set pricing in STX/USDCx/sBTC
• Implement analysis logic
• Register with VeilPay relayer
• Accept private ZK proof payments

See Bot Developer Guide for complete implementation instructions.

Example Use Cases

AI Agent Automation:

• DeFi trading bot analyzes token safety before executing swaps
• Portfolio manager bot assesses project fundamentals
• Risk management bot continuously monitors contract security
• All bot payments are private - no transaction graph correlation

Developer Tools:

• CI/CD integration for automatic contract audits
• Pre-deployment security scanning
• Token launch due diligence
• Investment research automation

Decentralized Intelligence:

• Multi-bot analysis pipelines
• Collaborative AI research
• Privacy-preserving data markets
• Bot reputation systems

---

Application Screenshots

Home Dashboard

Real-time privacy pool statistics and Merkle root tracking

Features shown:

• Live total deposits counter
• Current Merkle root hash
• Terminal-style interface design
• Real-time synchronization status

---

Deposit Interface

Lock USDCx with cryptographic commitment for complete privacy

Features shown:

• USDCx balance display
• Existing deposits list with commitment hashes
• Deposit amount input
• Security warning for credential storage
• One-click deposit initiation

---

Withdrawal Interface

Withdraw to any address with Zero-Knowledge proof - completely unlinkable

Features shown:

• Secret and nonce input fields
• Amount verification (must match deposit)
• Recipient address selection (any Stacks address)
• Security warnings for credential verification
• ZK proof generation status

---

Bridge Interface

Bridge USDC from Ethereum Sepolia to Stacks testnet via xReserve

Features shown:

• Ethereum wallet connection
• ETH and USDC balance display
• Stacks recipient address configuration
• Amount input with minimum validation
• xReserve protocol integration (~18 minute ETA)

---

Project Structure

VeilPay/
├── circuits/                     # Circom ZK Circuits
│   ├── withdraw.circom           # Main withdrawal circuit (20 levels)
│   ├── build/                    # Compiled circuit artifacts
│   │   ├── withdraw.wasm         # Circuit WebAssembly
│   │   ├── withdraw_final.zkey   # Proving key (3MB)
│   │   └── verification_key.json # Verification key
│   ├── scripts/build.sh          # Circuit compilation script
│   ├── test/                     # Circuit unit tests
│   └── package.json
│
├── contracts/                    # Clarity Smart Contracts
│   ├── veilpay.clar              # Privacy pool contract (STX)
│   ├── veilpay-usdcx.clar        # Privacy pool contract (USDCx)
│   ├── veilpay-sbtc.clar         # Privacy pool contract (sBTC)
│   ├── usdcx-trait.clar          # SIP-010 token trait
│   ├── Clarinet.toml             # Clarinet configuration
│   └── deployments/              # Deployment configs
│
├── relayer/                      # Node.js Relayer Service
│   ├── src/
│   │   ├── index.js              # Express API server
│   │   ├── merkle.js             # Merkle tree manager (Poseidon)
│   │   ├── verifier.js           # ZK proof verifier (snarkjs)
│   │   ├── indexer.js            # Blockchain event indexer
│   │   ├── stacks-client.js      # Stacks transaction builder
│   │   ├── signer.js             # Relayer signature logic
│   │   ├── x402/                 # x402 Payment Protocol
│   │   │   ├── bot-endpoints.js  # Bot marketplace endpoints
│   │   │   └── bot-payment-tracker.js # Bot payment analytics
│   │   ├── withdraw.wasm         # Circuit WASM (for verification)
│   │   ├── withdraw_final.zkey   # Proving key
│   │   └── verification_key.json # Verification key
│   ├── .env.example              # Environment template
│   └── package.json
│
├── frontend/                     # React + Vite Frontend
│   ├── src/
│   │   ├── App.jsx               # Main application
│   │   ├── components/           # React components
│   │   │   ├── Deposit.jsx       # Deposit interface
│   │   │   ├── Withdraw.jsx      # Withdrawal interface
│   │   │   ├── AssetSelector.jsx # Multi-asset selector
│   │   │   ├── BotMarketplace.jsx # Bot marketplace UI
│   │   │   ├── BotCard.jsx       # Individual bot card
│   │   │   ├── BotAnalysisModal.jsx # Bot analysis modal
│   │   │   └── X402Demo.jsx      # x402 payment demo
│   │   ├── utils/
│   │   │   ├── crypto.js         # Poseidon hash utilities
│   │   │   ├── proof.js          # ZK proof generation
│   │   │   └── x402-client.js    # x402 payment client
│   │   ├── main.jsx              # Entry point
│   │   └── index.css
│   ├── public/
│   │   └── circuits/             # Circuit files for browser
│   │       ├── withdraw.wasm
│   │       └── withdraw_final.zkey
│   ├── .env.example
│   ├── vite.config.js
│   ├── tailwind.config.js
│   └── package.json
│
├── bots/                         # AI Analysis Bots (NEW!)
│   └── examples/
│       ├── worker-bots/          # Individual analysis bots
│       │   ├── security-bot/     # AI-powered contract auditing (5 STX)
│       │   ├── tokenomics-bot/   # Token metrics analysis (3 STX)
│       │   └── sentiment-bot/    # Multi-source sentiment (2 STX)
│       └── coordinator-bot/      # Multi-bot orchestrator (10 STX)
│           ├── index.js          # Express server
│           ├── job-manager.js    # Bot coordination logic
│           ├── result-aggregator.js # AI result synthesis
│           └── veilpay-client.js # VeilPay ZK payment client
│
├── docs/                         # Documentation
│   ├── BOT-DEVELOPER-GUIDE.md    # Bot marketplace integration guide
│   ├── API.md                    # Relayer API documentation
│   └── X402-INTEGRATION.md       # x402 payment protocol guide
├── CLAUDE.md                     # Developer guide for Claude Code
├── README.md                     # This file
├── TESTNET_GUIDE.md              # Testnet deployment guide
├── LICENSE                       # MIT License
├── package.json                  # Workspace root
└── vercel.json                   # Vercel deployment config

---

Quick Start

Prerequisites

• Node.js v18+ (Download)
• Clarinet for contract deployment (Install)
• Circom (installed via npm, or system-wide from docs)
• Stacks Wallet: Leather or Hiro
• MetaMask (optional, for bridging USDC from Ethereum)

Installation

# Clone the repository
git clone https://github.com/carlos-israelj/VeilPay.git
cd VeilPay

# Install all workspace dependencies (circuits, relayer, frontend)
npm install

Running the Application

Terminal 1 - Start Relayer:

# Configure relayer environment
cd relayer
cp .env.example .env
# Edit .env with your settings (see Configuration section)

# Start relayer
npm run dev
# Or use root workspace command
npm run dev:relayer

Terminal 2 - Start Frontend:

# Configure frontend environment
cd frontend
cp .env.example .env
# Edit .env with API URL

# Start frontend
npm run dev
# Or use root workspace command
npm run dev:frontend

Access the application:

• Frontend: http://localhost:3000
• Relayer API: http://localhost:3001

Environment Configuration

Relayer (relayer/.env):

# Relayer Configuration
PORT=3001
RELAYER_PRIVATE_KEY=your_stacks_private_key_hex

# Stacks Network
STACKS_NETWORK=testnet  # or mainnet
CONTRACT_ADDRESS=ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
CONTRACT_NAME=veilpay

# USDCx Token Contract
USDCX_ADDRESS=ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
USDCX_NAME=usdcx

Frontend (frontend/.env):

VITE_API_URL=http://localhost:3001
VITE_STACKS_NETWORK=testnet

---

Testing & Development

Build ZK Circuits

# Build circuits from scratch (takes ~5 minutes)
cd circuits
npm run build

# This will:
# 1. Compile withdraw.circom to R1CS
# 2. Generate WASM for proof generation
# 3. Download Powers of Tau ceremony file
# 4. Generate proving key (zkey)
# 5. Export verification key
# 6. Copy artifacts to relayer/ and frontend/public/

Test Circuits

# Run circuit unit tests
cd circuits
npm test

# Or from root
npm run test

Deploy Smart Contracts

# Deploy to Clarinet devnet
cd contracts
clarinet integrate

# Deploy to testnet (requires Clarinet configured with your key)
clarinet deploy --testnet

Manual End-to-End Test

1. Start Services:

   # Terminal 1: Relayer
   cd relayer && npm run dev
   
   # Terminal 2: Frontend
   cd frontend && npm run dev

2. Make a Deposit:

   • Open http://localhost:3000
   • Connect Stacks wallet (Leather/Hiro)
   • Enter amount (e.g., 1 USDCx = 1,000,000 micro-units)
   • Click "Deposit"
   • CRITICAL: Save the secret and nonce displayed after deposit!

3. Wait for Indexing:

   • Watch relayer logs for "Adding commitment: ..."
   • Verify with: curl http://localhost:3001/stats
   • Should see totalDeposits > 0

4. Make a Withdrawal:

   • Enter saved secret and nonce
   • Enter recipient address (can be different from deposit address!)
   • Click "Withdraw"
   • Wait ~15s for ZK proof generation
   • Transaction submitted to Stacks

5. Verify Privacy:

   • Check on-chain: deposit and withdrawal are unlinkable
   • No correlation between sender and recipient
   • Only amounts are visible (future: use fixed denominations)

---

Smart Contracts (Testnet)

Deployed Contracts

Contract	Address	Explorer
veilpay.clar	ST2TVNVEDWFBX25NRW8GP6D3WHAXEXGH7T3MBT1T1.veilpay	View on Explorer
usdcx (Circle)	ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx	View on Explorer

Contract Overview

Contract	Purpose	Key Functions
veilpay.clar	Privacy pool for USDCx deposits/withdrawals	deposit, withdraw, update-root
usdcx-trait.clar	SIP-010 fungible token trait interface	Defines USDCx token interface

Contract Functions

veilpay.clar:

;; Deposit USDCx with cryptographic commitment
(define-public (deposit
    (commitment (buff 32))
    (amount uint)
    (token-contract <ft-trait>))

• Transfers USDCx from user to contract
• Stores commitment with unique ID
• Emits event for off-chain indexer
• Minimum: 1 USDCx (1,000,000 micro-units)

;; Withdraw USDCx with ZK proof (via relayer signature)
(define-public (withdraw
    (nullifier-hash (buff 32))
    (recipient principal)
    (amount uint)
    (root (buff 32))
    (relayer-signature (buff 65))
    (token-contract <ft-trait>))

• Verifies relayer signature (proof was verified off-chain)
• Checks nullifier hasn't been used (prevents double-spend)
• Verifies root is valid (commitment exists in tree)
• Transfers USDCx to recipient

;; Update Merkle root (relayer only)
(define-public (update-root (new-root (buff 32)))

• Admin-only function
• Adds new root to valid-roots map
• Called by relayer after adding commitments to tree

---

Technology Stack

Core Cryptography

Component	Technology	Specification	Purpose
Proof System	Groth16 SNARKs	BN254 curve, ~1M constraints	Zero-Knowledge privacy guarantees
Hash Function	Poseidon	128-bit security, t=3/t=4	SNARK-optimized cryptographic hashing
Circuit Compiler	Circom 2.x	R1CS constraint system	Zero-Knowledge circuit definition
Proof Generation	snarkjs 0.7.x	WASM + WebAssembly	Browser-based proof creation
Merkle Accumulator	Custom Poseidon tree	20 levels, 1M+ capacity	Commitment storage and verification

Blockchain Infrastructure

Layer	Technology	Version	Role
Layer 1	Bitcoin	Mainnet	Final settlement and security anchor
Layer 2	Stacks (Nakamoto)	2.4+	Smart contract execution layer
Smart Contracts	Clarity	2.4	Type-safe, decidable contract logic
Token Standard	SIP-010 (USDCx)	Circle implementation	Fungible token interface
Cross-Chain Bridge	xReserve Protocol	Circle official	Ethereum-Stacks USDC bridge

Application Stack

Component	Technology	Version	Function
Frontend Framework	React	18.x	Component-based UI architecture
Build System	Vite	5.x	Fast development and production builds
Styling	Tailwind CSS	3.x	Utility-first responsive design
Wallet Integration	@stacks/connect	7.x	Leather, Hiro, Xverse wallet support
Blockchain SDK	@stacks/transactions	7.x	Transaction building and signing
Payment Protocol	x402-stacks	1.x	HTTP 402 programmatic payments

Off-Chain Infrastructure

Service	Technology	Version	Purpose
Relayer Backend	Node.js	18+ LTS	Proof verification and transaction relay
API Framework	Express.js	4.x	RESTful API endpoints
Proof Verification	snarkjs	0.7.x	Off-chain SNARK verification
Event Indexer	Custom indexer	-	Blockchain event monitoring
Merkle Management	merkletreejs + Poseidon	0.3.x	Tree state synchronization
Bot Marketplace	Express.js + x402	-	AI analysis bot ecosystem
AI Analysis	OpenAI GPT-3.5-turbo	-	Bot intelligence engine

Development Tools

Tool	Purpose	Integration
Clarinet	Smart contract testing and deployment	Local devnet, testnet deployment
circom	Circuit compilation and R1CS generation	Constraint system development
snarkjs CLI	Trusted setup and key generation	Powers of Tau ceremony
Git	Version control and collaboration	GitHub repository

---

Applications

Institutional Use Cases

Corporate Treasury Management Organizations can execute confidential treasury operations without exposing strategic financial activities to competitors. Transaction amounts remain visible for accounting compliance, while counterparty relationships are cryptographically protected.

International Remittances Cross-border transfers using stable USDCx without exposing sender-receiver relationships to surveillance infrastructure. Maintains regulatory compliance through use of Circle's regulated stablecoin while preserving transactional privacy.

DeFi Protocol Integration Privacy-preserving deposits and withdrawals from decentralized finance protocols. Breaks on-chain transaction graph analysis between wallet addresses, enabling confidential yield farming and liquidity provision.

Individual Use Cases

Financial Privacy Protection Individuals maintain personal financial confidentiality using regulated stablecoin infrastructure. Prevents profiling, targeting, and surveillance based on transaction history while preserving auditability when required.

Anonymous Contributions Support organizations, causes, or individuals without identity disclosure. Cryptographic unlinkability ensures donor privacy while maintaining transparent fund reception for beneficiaries.

AI Agent & Bot Economy

Autonomous Bot Automation AI agents hire specialized analysis bots with complete transaction privacy. DeFi trading bots assess token safety, portfolio managers evaluate fundamentals, risk bots monitor security—all payments unlinkable via VeilPay ZK proofs.

Decentralized Intelligence Markets Privacy-preserving data markets where bots purchase analysis, research, and insights without revealing purchase patterns. Bot coordination pipelines run autonomously with cryptographic privacy guarantees.

Developer CI/CD Integration Automated security audits, pre-deployment scanning, and continuous monitoring integrated into development workflows. Bot services paid via VeilPay ensure development activity remains confidential from competitors.

---

Technical Deep Dive

Zero-Knowledge Circuit Details

Circuit: circuits/withdraw.circom

Parameters:

• Merkle tree depth: 20 levels (supports 2^20 = 1,048,576 deposits)
• Hash function: Poseidon (SNARK-friendly)
• Proof system: Groth16 (optimal proof size)

Inputs:

// Private inputs (never revealed)
signal input secret;              // User's secret
signal input amount;              // Deposit amount
signal input nonce;               // Randomness
signal input pathElements[levels]; // Merkle proof siblings
signal input pathIndices[levels];  // Merkle proof directions

// Public inputs (visible on-chain)
signal input root;                // Merkle tree root
signal input nullifierHash;       // Prevents double-spend
signal input recipient;           // Withdrawal recipient

Constraints (what the circuit proves):

1. commitment = poseidon(secret, amount, nonce) - User knows valid commitment
2. MerkleProof(commitment, pathElements, pathIndices) == root - Commitment is in tree
3. nullifierHash = poseidon(secret, nonce) - Nullifier correctly derived

Security:

• ~1M constraints (compiled circuit size)
• Groth16 proof: 3 elliptic curve points (192 bytes)
• Verification time: <10ms on-chain (when native verification available)

Poseidon Hash Function

Why Poseidon?

• SNARK-friendly: ~10x fewer constraints than SHA-256
• Security: 128-bit security for ZK applications
• Efficiency: Optimized for field arithmetic in ZK circuits

Consistency Critical:

• Circuit: Poseidon(2) and Poseidon(3) from circomlib
• Frontend: buildPoseidon() from circomlibjs
• Relayer: buildPoseidon() from circomlibjs
• Any mismatch breaks the entire system!

Hybrid Architecture Rationale

Why Off-Chain Verification?

• Clarity lacks native BN254/BLS12-381 elliptic curve operations
• On-chain Groth16 verification requires pairing checks
• Off-chain verification: ~500ms with snarkjs
• On-chain settlement: instant with relayer signature

Trust Model:

• Privacy: Cryptographically guaranteed by ZK proofs
• Liveness: Trust relayer not to censor (can run your own!)
• Soundness: Relayer cannot create fake proofs (math prevents this)

Migration Path: When Stacks adds SNARK precompiles, we can:

1. Deploy new contract with native verification
2. Migrate existing commitments to new pool
3. Remove relayer dependency for verification
4. Keep relayer for indexing and UX

---

Development Roadmap

Phase 1: Foundation (Completed)

Status: Deployed on Stacks Testnet Timeline: Q4 2025 - Q1 2026

Core Protocol Implementation

• Groth16 ZK-SNARK circuits with Poseidon hash integration
• 20-level Merkle tree accumulator supporting 1,048,576 deposits
• Clarity smart contracts with deposit, withdrawal, and nullifier tracking
• Off-chain relayer infrastructure with proof verification and event indexing
• Browser-based proof generation using WebAssembly circuits

User Interface & Integration

• React-based frontend with Stacks wallet integration (Leather, Hiro)
• USDCx SIP-010 token support with native Circle integration
• xReserve bridge interface for Ethereum-Stacks USDC transfers
• Comprehensive technical documentation and developer guides

Current Status: Functional testnet deployment processing real deposits and withdrawals with full Zero-Knowledge privacy guarantees.

---

Phase 2: Security & Scalability (Q1-Q2 2026)

Focus: Production hardening and trust minimization

Security Enhancements

• Professional security audit of smart contracts by reputable third-party firm
• Formal verification of ZK circuits and cryptographic assumptions
• Bug bounty program for community-driven security testing
• Penetration testing of relayer infrastructure and API endpoints

Protocol Improvements

• Multi-denomination pools (10, 100, 1000 USDCx) for enhanced amount privacy
• Decentralized relayer network with reputation-based consensus
• Optimistic verification with fraud proof challenge mechanism
• Merkle tree state snapshots on IPFS/Arweave for data availability

Infrastructure Optimization

• Enhanced blockchain indexer with faster synchronization and fault tolerance
• Relayer load balancing and geographic distribution
• Mobile-optimized UI with progressive web app (PWA) support
• Performance optimization for sub-10-second proof generation

Deliverable: Mainnet-ready protocol with institutional-grade security and decentralized operation.

---

Phase 3: Advanced Features (Q3-Q4 2026)

Focus: Protocol extensibility and ecosystem integration

Native On-Chain Verification

• Migration to full on-chain SNARK verification when Stacks adds BN254/BLS12-381 precompiles
• Trustless proof validation without relayer dependency
• Backward-compatible upgrade path for existing deposits

Multi-Asset Support

• Privacy pools for STX (native Stacks token)
• sBTC integration for Bitcoin-backed private transfers
• Generalized SIP-010 token privacy framework
• Cross-token swap privacy preservation

Compliance & Regulatory Tools

• Optional selective disclosure mechanism for authorized auditors
• Zero-Knowledge proof of fund origin for regulatory compliance
• Configurable privacy levels for institutional requirements
• Audit trail generation without compromising user privacy

Developer Ecosystem

• VeilPay SDK for third-party dApp integration
• Privacy-preserving payment channels and streaming
• Mobile applications (iOS/Android) with native proof generation
• Cross-chain privacy protocols for multi-L1 interoperability

Long-Term Vision: Establish VeilPay as the de facto privacy infrastructure for the Stacks ecosystem, enabling confidential DeFi, private payments, and anonymous on-chain interactions at scale.

---

Strategic Value Proposition

Technical Differentiation

VeilPay represents a significant advancement in blockchain privacy infrastructure:

Cryptographic Innovation

• First implementation of hybrid ZK-SNARK verification architecture optimized for Clarity's constraint system
• Consistent Poseidon hash integration across circuit, application, and infrastructure layers
• Groth16 proof system with 192-byte constant-size proofs and 128-bit security parameters
• Browser-native proof generation via WebAssembly, eliminating trusted backend requirements

Protocol Design

• Merkle tree accumulator supporting 1,048,576 deposits with logarithmic proof complexity
• Nullifier-based double-spend prevention maintaining unlinkability guarantees
• Forward-compatible architecture enabling seamless migration to native on-chain verification
• Production-grade event indexing and state synchronization infrastructure

Market Position

USDCx Integration Leadership

• First and only Zero-Knowledge privacy protocol for Circle's USDCx on Stacks
• Native SIP-010 token standard integration at smart contract layer
• Full xReserve protocol compatibility for Ethereum-Stacks bridging
• Regulatory-compliant infrastructure using Circle's institutional stablecoin

Ecosystem Enablement

• Foundational privacy infrastructure for Stacks DeFi ecosystem
• Enables confidential institutional treasury operations
• Supports privacy-preserving dApp development through composable primitives
• Scalable architecture with clear growth trajectory to mainnet deployment

Operational Excellence

Enterprise-Ready Infrastructure

• RESTful API with documented endpoints for relayer services
• Multi-wallet support (Leather, Hiro) via standard @stacks/connect integration
• Comprehensive developer documentation including technical specifications
• Open-source codebase with MIT licensing for community development

---

Project Metrics

Metric	Value	Details
Codebase	15,000+ lines	Across circuits, contracts, relayer, frontend, bots
Smart Contracts	4 contracts	veilpay.clar, veilpay-usdcx.clar, veilpay-sbtc.clar, usdcx-trait.clar
ZK Circuits	~1M constraints	withdraw.circom (Groth16)
Merkle Tree	20 levels	1,048,576 deposit capacity per asset
Supported Assets	3 assets	STX, USDCx, sBTC
Bot Marketplace	4 bots	Security, Tokenomics, Sentiment, Coordinator
Proof Generation	~15 seconds	Browser-based (WASM)
Proof Verification	~500ms	Off-chain relayer
Proof Size	192 bytes	Constant (3 elliptic curve points)
Gas Efficiency	Optimized	Deposit: ~XXX, Withdraw: ~XXX*
Supported Wallets	2 wallets	Leather, Hiro
API Endpoints	15+ endpoints	Relayer API + Bot marketplace

_{* Gas costs measured on Stacks testnet}

Comparison with Alternatives

Feature	VeilPay	Traditional Mixers	Confidential Transactions
Privacy Guarantee	ZK-SNARK proof	Statistical anonymity	Range proofs only
Unlinkability	Cryptographic	Probabilistic	None
USDCx Support	Native SIP-010	Limited	No stablecoin support
Proof Size	192 bytes	N/A	~5KB+
Trust Model	Relayer (liveness only)	Operator trust	Trustless
Regulatory Compatible	Yes (USDCx)	Questionable	Blockchain-specific
Scalability	1M+ deposits	Limited pool size	Per-transaction overhead
Browser-Based	Yes	Typically no	No

---

Security Model

Cryptographic Guarantees

VeilPay's security is rooted in well-established cryptographic primitives:

Zero-Knowledge Soundness: Groth16 proof system ensures that no adversary can generate a valid proof for a false statement. Based on the hardness of discrete logarithm problem over elliptic curves.

Commitment Hiding: Poseidon hash function provides collision resistance and pre-image resistance, ensuring commitments reveal no information about the underlying secret, amount, or nonce.

Nullifier Uniqueness: Each deposit has a unique nullifier derived as Poseidon(secret, nonce). Cryptographically impossible to generate the same nullifier for different secrets.

Trust Model

Component	Trust Requirement	Risk Mitigation
ZK Circuits	None (math-based)	Open-source, auditable constraints
Smart Contract	Code correctness	Open-source, testnet deployment, planned audit
Relayer	Liveness only	Anyone can run a relayer, open-source
Merkle Tree	Data availability	Reconstructible from blockchain events
Stacks Blockchain	Standard L2 assumptions	Bitcoin finality, PoX consensus

Key Insight: Relayer cannot steal funds or forge proofs—only censor transactions. Users can mitigate censorship by running their own relayer instance.

Privacy Analysis

Current Limitations:

1. Amount Visibility: Transaction amounts are visible on-chain

   • Impact: Medium - Reduces anonymity set for specific amounts
   • Roadmap Solution: Fixed-denomination pools (Phase 2)

2. Timing Correlation: Immediate deposit-withdraw pattern may leak information

   • Impact: Low - Requires sophisticated analysis and timing precision
   • User Mitigation: Wait for additional deposits before withdrawing

3. Network-Level Privacy: IP addresses visible to relayer during API requests

   • Impact: Low - Does not affect on-chain privacy
   • User Mitigation: Use Tor, VPN, or privacy-focused networks

Attack Resistance:

Attack Type	Status	Protection Mechanism
Double-spend	✅ Prevented	On-chain nullifier registry
Front-running	✅ Prevented	Relayer submits transactions
Proof forgery	✅ Prevented	Groth16 soundness
Commitment collision	✅ Prevented	Poseidon collision resistance
Merkle tree manipulation	✅ Prevented	On-chain root verification
Relayer censorship	⚠️ Possible	Run own relayer instance
Smart contract exploit	🔄 Pending	Security audit planned (Phase 2)

Security Roadmap

Phase 2 (Q1 2026):

• Professional smart contract audit by reputable firm
• ZK circuit formal verification
• Relayer decentralization (multi-relayer network)
• Bug bounty program

Phase 3 (Q2 2026):

• On-chain verification migration (when available)
• Advanced privacy features (amount hiding)
• Compliance tooling (optional disclosure)

---

Frequently Asked Questions

General

Q: How does VeilPay differ from a traditional cryptocurrency mixer? A: VeilPay uses Zero-Knowledge cryptography to provide mathematical privacy guarantees, whereas mixers rely on statistical anonymity. VeilPay also integrates natively with USDCx stablecoin and operates entirely on-chain.

Q: Is VeilPay legal to use? A: VeilPay is a privacy tool, similar to HTTPS for web browsing or encryption for messaging. The legality depends on your jurisdiction and use case. VeilPay uses Circle's regulated USDCx stablecoin, demonstrating compatibility with compliant infrastructure.

Q: Can I recover my funds if I lose my secret? A: No. The secret and nonce are the only way to prove ownership of a deposit. Store them securely—VeilPay cannot recover lost credentials.

Technical

Q: Why use Poseidon instead of SHA-256? A: Poseidon is SNARK-friendly, requiring ~10x fewer constraints in Zero-Knowledge circuits. This drastically reduces proof generation time and circuit complexity.

Q: What happens if the relayer goes offline? A: Anyone can run a relayer instance. The relayer code is open-source, and the Merkle tree can be reconstructed from blockchain events. VeilPay's design allows for decentralized relayer networks.

Q: Why not verify proofs on-chain? A: Clarity (Stacks' smart contract language) currently lacks native elliptic curve operations required for Groth16 verification. VeilPay uses a hybrid approach with off-chain verification until native support is available.

Q: How large is the anonymity set? A: The Merkle tree supports 1,048,576 deposits (2^20). All deposits sharing the same amount are in the same anonymity set. Future fixed-denomination pools will maximize privacy.

Privacy

Q: Can the relayer see who is withdrawing? A: The relayer sees the IP address of withdrawal requests and the public outputs (recipient, nullifier, root). However, it cannot link these to specific deposits without breaking the Zero-Knowledge proof.

Q: Are amounts hidden? A: Currently, amounts are visible on-chain. Phase 2 introduces fixed-denomination pools (10, 100, 1000 USDCx) to hide amounts within common tiers.

Q: Can law enforcement trace VeilPay transactions? A: VeilPay provides cryptographic unlinkability between deposits and withdrawals. However, blockchain analysis may reveal patterns based on amounts, timing, or network-level metadata. Users should follow best practices (Tor/VPN, varied timing).

---

Resources

Official Documentation

• USDCx Bridging Guide
• Stacks Documentation
• Clarity Language Reference
• Circom Documentation
• SnarkJS Repository
• Circle xReserve Protocol
• Clarinet Developer Tools

Technical Papers

• Groth16 Paper - Original Groth16 construction
• Poseidon Hash - SNARK-friendly hash function
• Tornado Cash Architecture - Inspiration for privacy pools

Community Support

• Stacks Discord
• GitHub Issues
• Hackathon Community (Skool)

---

Contributing

Contributions are welcome! VeilPay is open-source and community-driven.

Development Workflow

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Contribution Guidelines

• Code Style: Follow existing conventions (Prettier for JS, Clarity style guide)
• Testing: Add tests for new features (circuits, contracts, API)
• Documentation: Update CLAUDE.md and README.md as needed
• Commits: Use descriptive commit messages
• Security: Report vulnerabilities privately via GitHub Security tab

Areas for Contribution

• Bug Fixes: Report or fix issues
• Features: Implement roadmap items
• Documentation: Improve guides and tutorials
• Testing: Add test coverage
• UI/UX: Enhance frontend design
• Security: Audit code, suggest improvements

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Team

Lead Developer: Carlos Israel Jiménez GitHub: @carlos-israelj

---

Acknowledgments

VeilPay builds upon foundational work from:

• Stacks Labs - Bitcoin Layer 2 infrastructure and Clarity smart contract language
• Circle - xReserve protocol enabling USDC bridging to Stacks
• Hiro Systems - Developer tooling including Clarinet and Stacks.js SDK
• Iden3 - Circom circuit compiler, SnarkJS library, and circomlib primitives
• Tornado Cash - Pioneering work in privacy pool architecture and ZK-SNARK applications
• Stacks Community - Technical feedback, security review, and testnet validation

---

Contact & Support

Technical Issues: GitHub Issues Development Discussion: GitHub Discussions Community Forum: Stacks Community

---

Built on Bitcoin · Powered by Stacks · Secured by Zero-Knowledge · Stabilized by USDCx

---

Privacy is a fundamental right. VeilPay protects yours.

© 2026 VeilPay · Licensed under MIT