> ARCHITECTURE

System Architecture

Deep dive into ZKPrime's technical architecture and design decisions

System Overview

ZKPrime's architecture consists of multiple layers working together to provide privacy on Solana.

┌──────────────────────────────────────────────────────────────┐
│                     APPLICATION LAYER                        │
│  DApps, Wallets, SDKs (TypeScript/Rust)                     │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                    ZKPRIME SDK LAYER                         │
│  • Proof Generation       • Transaction Builder              │
│  • Key Management         • State Encryption                 │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                  PRIVACY PROTOCOL LAYER                      │
│  • zkSNARK Circuits      • Homomorphic Encryption            │
│  • Commitment Schemes    • Nullifier Management              │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                 SOLANA PROGRAM LAYER                         │
│  • Proof Verifier        • State Manager                     │
│  • Transaction Validator • Token Handler                     │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                    SOLANA BLOCKCHAIN                         │
│  Validators, Consensus, State Storage                        │
└──────────────────────────────────────────────────────────────┘

Core Components

Proof Generator

Generates zkSNARK proofs for transaction validity without revealing details

• Circuit: Groth16 zkSNARK implementation

• Proof time: ~2-5 seconds (client-side)

• Verification: ~5ms on-chain

State Encryptor

Manages encrypted account states using ElGamal encryption

• Encryption: ElGamal on twisted Edwards curve

• Homomorphic operations supported

• Key derivation: BIP-44 compatible

Commitment Pool

Maintains anonymity set through Merkle tree of commitments

• Tree depth: 20 levels (~1M leaves)

• Hash function: Poseidon

• Update frequency: Per transaction

Nullifier Registry

Prevents double-spending through unique nullifiers

• Storage: On-chain Solana account

• Lookup: O(1) with account indexing

• Privacy: No link to original commitment

Network Protocol

Transaction Flow

1.
Client prepares transaction
User specifies recipient, amount, privacy level
2.
Fetch commitment tree
Download Merkle proof for sender's commitment
3.
Generate proof
Create zkSNARK proving valid spend without revealing details
4.
Encrypt output
Create encrypted commitment for recipient
5.
Submit to Solana
Transaction with proof sent to ZKPrime program
6.
On-chain verification
Program verifies proof, checks nullifier, updates state

Data Structures

// Commitment
struct Commitment {
    hash: [u8; 32],        // Poseidon hash
    value: EncryptedValue,  // Encrypted amount
    owner: EncryptedKey,    // Encrypted public key
    timestamp: i64,
}

// Nullifier
struct Nullifier {
    hash: [u8; 32],         // Unique identifier
    spent: bool,            // Double-spend prevention
}

// Transaction
struct PrivateTransaction {
    proof: Groth16Proof,    // zkSNARK proof
    nullifiers: Vec<[u8; 32]>, // Spent commitments
    commitments: Vec<Commitment>, // New outputs
    memo: Option<Vec<u8>>,  // Optional encrypted memo
}

Integration Guide

Integrate ZKPrime into your existing Solana application:

Step 1: Add SDK Dependency

npm install @zkprime/sdk @solana/web3.js

Step 2: Initialize Client

import { ZKPrimeClient } from '@zkprime/sdk';

const zkClient = new ZKPrimeClient({
  rpcUrl: connection.rpcEndpoint,
  network: 'mainnet-beta'
});

Step 3: Wrap Existing Transactions

// Before: Public transaction
await transfer(connection, wallet, recipient, amount);

// After: Private transaction
await zkClient.createPrivateTransfer({
  from: wallet,
  to: recipient,
  amount: amount,
  privacyLevel: 'high'
});

Step 4: Handle Private State

// Query encrypted balance
const encrypted = await zkClient.getEncryptedBalance(
  wallet.publicKey.toString()
);

// Decrypt for display
const balance = await zkClient.decryptBalance(encrypted);
setBalance(balance);

Migration Checklist:

☐ Install ZKPrime SDK
☐ Initialize client with RPC connection
☐ Replace public transfers with private transfers
☐ Update balance queries to use encrypted state
☐ Add key management for decryption
☐ Test on devnet before mainnet deployment

Performance Characteristics

Client-Side

Proof generation:2-5s

Encryption:~50ms

Decryption:~20ms

SDK size:~2.5MB

On-Chain

Proof verification:~5ms

Compute units:~200K

Transaction size:~1.2KB

State overhead:+256 bytes