aitbc/docs/zk-applications.md

Zero-Knowledge Applications in AITBC

This document describes the Zero-Knowledge (ZK) proof capabilities implemented in the AITBC platform.

Overview

AITBC now supports privacy-preserving operations through ZK-SNARKs, allowing users to prove computations, membership, and other properties without revealing sensitive information.

Available ZK Features

1. Identity Commitments

Create privacy-preserving identity commitments that allow you to prove you're a valid user without revealing your identity.

Endpoint: POST /api/zk/identity/commit

Request:

{
  "salt": "optional_random_string"
}

Response:

{
  "commitment": "hash_of_identity_and_salt",
  "salt": "used_salt",
  "user_id": "user_identifier",
  "created_at": "2025-12-28T17:50:00Z"
}

2. Stealth Addresses

Generate one-time payment addresses for enhanced privacy in transactions.

Endpoint: POST /api/zk/stealth/address

Parameters:

• recipient_public_key (query): The recipient's public key

Response:

{
  "stealth_address": "0x27b224d39bb988620a1447eb4bce6fc629e15331",
  "shared_secret_hash": "b9919ff990cd8793aa587cf5fd800efb997b6dcd...",
  "ephemeral_key": "ca8acd0ae4a9372cdaeef7eb3ac7eb10",
  "view_key": "0x5f7de2cc364f7c8d64ce1051c97a1ba6028f83d9"
}

3. Private Receipt Attestation

Create receipts that prove computation occurred without revealing the actual computation details.

Endpoint: POST /api/zk/receipt/attest

Parameters:

• job_id (query): Identifier of the computation job
• user_address (query): Address of the user requesting computation
• computation_result (query): Hash of the computation result
• privacy_level (query): "basic", "medium", or "maximum"

Response:

{
  "job_id": "job_123",
  "user_address": "0xabcdef",
  "commitment": "a6a8598788c066115dcc8ca35032dc60b89f2e138...",
  "privacy_level": "basic",
  "timestamp": "2025-12-28T17:51:26.758953",
  "verified": true
}

4. Group Membership Proofs

Prove membership in a group (miners, clients, developers) without revealing your identity.

Endpoint: POST /api/zk/membership/verify

Request:

{
  "group_id": "miners",
  "nullifier": "unique_64_char_string",
  "proof": "zk_snark_proof_string"
}

5. Private Bidding

Submit bids to marketplace auctions without revealing the bid amount.

Endpoint: POST /api/zk/marketplace/private-bid

Request:

{
  "auction_id": "auction_123",
  "bid_commitment": "hash_of_bid_and_salt",
  "proof": "proof_that_bid_is_in_valid_range"
}

6. Computation Proofs

Verify that AI computations were performed correctly without revealing the inputs.

Endpoint: POST /api/zk/computation/verify

Request:

{
  "job_id": "job_456",
  "result_hash": "hash_of_computation_result",
  "proof_of_execution": "zk_snark_proof",
  "public_inputs": {}
}

Anonymity Sets

View available anonymity sets for privacy operations:

Endpoint: GET /api/zk/anonymity/sets

Response:

{
  "sets": {
    "miners": {
      "size": 100,
      "description": "Registered GPU miners",
      "type": "merkle_tree"
    },
    "clients": {
      "size": 500,
      "description": "Active clients",
      "type": "merkle_tree"
    },
    "transactions": {
      "size": 1000,
      "description": "Recent transactions",
      "type": "ring_signature"
    }
  },
  "min_anonymity": 3,
  "recommended_sets": ["miners", "clients"]
}

Technical Implementation

Circuit Compilation

The ZK circuits are compiled using:

• Circom: v2.2.3
• Circomlib: For standard circuit components
• SnarkJS: For trusted setup and proof generation

Trusted Setup

A complete trusted setup ceremony has been performed:

1. Powers of Tau ceremony with 2^12 powers
2. Phase 2 preparation for specific circuits
3. Groth16 proving keys generated
4. Verification keys exported

Circuit Files

The following circuit files are deployed:

• receipt_simple_0001.zkey: Proving key for receipt circuit
• receipt_simple.wasm: WASM witness generator
• verification_key.json: Verification key for on-chain verification

Privacy Levels

1. Basic: Hash-based commitments (no ZK-SNARKs)
2. Medium: Simple ZK proofs with limited constraints
3. Maximum: Full ZK-SNARKs with complete privacy

Security Considerations

1. Trusted Setup: The trusted setup was performed with proper entropy and multiple contributions
2. Randomness: All operations use cryptographically secure random number generation
3. Nullifiers: Prevent double-spending and replay attacks
4. Verification: All proofs can be verified on-chain or off-chain

Future Enhancements

1. Additional Circuits: Membership and bid range circuits to be compiled
2. Recursive Proofs: Enable proof composition for complex operations
3. On-Chain Verification: Deploy verification contracts to blockchain
4. Hardware Acceleration: GPU acceleration for proof generation

API Status

Check the current status of ZK features:

Endpoint: GET /api/zk/status

This endpoint returns detailed information about:

• Which ZK features are active
• Circuit compilation status
• Available proof types
• Next steps for implementation

Integration Guide

To integrate ZK proofs in your application:

1. Generate Proof: Use the appropriate endpoint to generate a proof
2. Submit Proof: Include the proof in your transaction or API call
3. Verify Proof: The system will automatically verify the proof
4. Privacy: Your sensitive data remains private throughout the process

Examples

Private Marketplace Bid

// 1. Create bid commitment
const bidAmount = 100;
const salt = generateRandomSalt();
const commitment = hash(bidAmount + salt);

// 2. Generate ZK proof that bid is within range
const proof = await generateBidRangeProof(bidAmount, salt);

// 3. Submit private bid
const response = await fetch('/api/zk/marketplace/private-bid', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    auction_id: 'auction_123',
    bid_commitment: commitment,
    proof: proof
  })
});

Stealth Address Payment

// 1. Generate stealth address for recipient
const response = await fetch(
  '/api/zk/stealth/address?recipient_public_key=0x123...',
  { method: 'POST' }
);

const { stealth_address, view_key } = await response.json();

// 2. Send payment to stealth address
await sendTransaction({
  to: stealth_address,
  amount: 1000
});

// 3. Recipient can view funds using view_key
const balance = await viewStealthAddressBalance(view_key);

Support

For questions about ZK applications:

• Check the API documentation at /docs/
• Review the status endpoint at /api/zk/status
• Examine the circuit source code in apps/zk-circuits/