Architecture Overview

Paraloom is built as a layered architecture with four main layers:

Privacy Layer: zkSNARK proofs and shielded transactions
Consensus Layer: Multi-validator Byzantine fault tolerance
Bridge Layer: Solana integration for deposits/withdrawals
Network Layer: P2P communication using libp2p

Paraloom Architecture

Core Components

1. Privacy Pool

The privacy pool manages the shielded state using:

Merkle Tree: Incremental merkle tree for commitments
Nullifier Set: RocksDB-backed spent nullifiers
Pool State: Total supply and commitment tracking

pub struct ShieldedPool {
    storage: Arc<PrivacyStorage>,
    merkle_tree: IncrementalMerkleTree,
    nullifier_set: HashSet<Nullifier>,
    total_supply: u64,
}

Responsibilities:

Process deposits (add commitments to merkle tree)
Process transfers (verify nullifiers, add new commitments)
Process withdrawals (mark nullifiers as spent)
Maintain merkle root for on-chain verification

2. Consensus Coordinator

Coordinates distributed proof verification across validators:

pub struct WithdrawalVerificationCoordinator {
    pending_verifications: HashMap<String, WithdrawalConsensus>,
    validators: Arc<RwLock<HashMap<NodeId, ValidatorInfo>>>,
    reputation: Arc<ReputationTracker>,
    threshold: ConsensusThreshold,
}

Key Features:

7/10 consensus threshold (70% agreement required)
30-second timeout for verification
Byzantine fault tolerance (tolerates 3/10 malicious validators)
Automatic reputation updates based on verification results

3. Solana Bridge

Manages cross-chain deposits and withdrawals:

Components:

solana/program.rs: Anchor program interface
solana/submitter.rs: Withdrawal transaction submitter
types.rs: Deposit/withdrawal event structures

Program Accounts:

BridgeState: Global bridge configuration
NullifierAccount: Individual nullifier tracking
BridgeVault: PDA holding deposited SOL

4. Network Manager

P2P networking using libp2p:

pub struct NetworkManager {
    swarm: Swarm<Protocol>,
    message_tx: mpsc::UnboundedSender<NetworkMessage>,
    peer_id: PeerId,
}

Features:

Gossipsub for message broadcasting
mDNS for local peer discovery
Request-response for direct communication
Connection pooling and management

Data Flow

Deposit Flow

User Wallet
    │
    ├─► 1. Transfer SOL to Bridge Program
    │
Bridge Program (Solana)
    │
    ├─► 2. Emit Deposit Event
    │
Bridge Listener
    │
    ├─► 3. Process Event
    │
Privacy Pool
    │
    ├─► 4. Add Commitment to Merkle Tree
    │
    └─► 5. Update Merkle Root

Withdrawal Flow

User Request
    │
    ├─► 1. Generate zkSNARK Proof
    │
Consensus Coordinator
    │
    ├─► 2. Broadcast to Validators
    │
Validators (Distributed)
    │
    ├─► 3. Verify Proof Independently
    │
    ├─► 4. Submit Verification Results
    │
Consensus Coordinator
    │
    ├─► 5. Aggregate Results (7/10 threshold)
    │
    ├─► 6. If Consensus: Mark Approved
    │
Bridge Submitter
    │
    ├─► 7. Submit Withdrawal Transaction
    │
Solana Program
    │
    ├─► 8. Verify Proof On-Chain
    │
    ├─► 9. Check Nullifier Not Spent
    │
    └─► 10. Transfer SOL to Recipient

Network Topology

Validator Network

┌──────────────┐
│ Validator 1  │◄────┐
│ (Bootstrap)  │     │
└──────┬───────┘     │
       │             │
       │  Gossipsub  │
       │   Messages  │
       │             │
┌──────▼───────┐     │
│ Validator 2  │◄────┤
└──────┬───────┘     │
       │             │
┌──────▼───────┐     │
│ Validator 3  │◄────┤
└──────┬───────┘     │
       │             │
┌──────▼───────┐     │
│ Validator 4  │◄────┤
└──────┬───────┘     │
       │             │
┌──────▼───────┐     │
│ Validator 5  │◄────┘
└──────────────┘

Discovery:

mDNS for local network
Bootstrap nodes for initial connection
Gossipsub for topic-based messaging

Storage Architecture

RocksDB Column Families

database/
├── merkle_tree       # Merkle tree nodes
│   └── key: position → value: hash
├── nullifier_set     # Spent nullifiers
│   └── key: nullifier → value: timestamp
└── pool_state        # Pool statistics
    └── key: "state" → value: JSON

Project Structure

paraloom-core/
├── programs/paraloom/          # Solana program (Anchor)
├── src/
│   ├── bin/                   # Binary executables
│   ├── privacy/               # Privacy primitives
│   ├── compute/               # Compute layer
│   ├── consensus/             # Validator consensus
│   ├── bridge/                # Solana bridge
│   ├── network/               # P2P networking
│   ├── storage/               # RocksDB storage
│   └── node/                  # Node implementation
├── tests/                     # Integration tests
├── examples/                  # Example applications
├── scripts/                   # Automation scripts
└── docs/                      # Documentation

Architecture

On this page