P2P Decentralized Exchange (DEX) - Complete System Documentation

🎯 System Overview

The P2P Decentralized Exchange is a sophisticated distributed trading system built on Grenache DHT network that enables peer-to-peer order matching without a central authority. The system implements a hybrid consensus mechanism to ensure all peers maintain synchronized order books while handling high-frequency trading operations.

Key Features

• Fully Decentralized: No central authority or single point of failure
• Consensus-Driven: Advanced hybrid consensus algorithm for state synchronization
• Scalable: Supports 1-5 configurable peers with dynamic discovery
• High Performance: Optimized order matching with sub-second consensus completion
• Fault Tolerant: Robust error handling and network partition recovery
• Real-time Synchronization: Live order book updates across all peers

---

🏗️ Architecture Components

graph TB
    subgraph "P2P DEX System Architecture"
        subgraph "Infrastructure Layer"
            DHT1[Grenache DHT Server 1 Port: 30001]
            DHT2[Grenache DHT Server 2 Port: 40001]
        end

        subgraph "Peer Network"
            PA[Peer A RPC + Pub/Sub]
            PB[Peer B RPC + Pub/Sub]
            PC[Peer C RPC + Pub/Sub]
            PD[Peer D RPC + Pub/Sub]
            PE[Peer E RPC + Pub/Sub]
        end

        subgraph "Order Generation"
            REQ[Order Requester Dynamic Peer Discovery]
        end

        subgraph "System Orchestration"
            STARTER[Starter Service Management]
        end
    end

    DHT1 <--> DHT2
    PA <--> DHT1
    PB <--> DHT1
    PC <--> DHT1
    PD <--> DHT1
    PE <--> DHT1

    REQ --> PA
    REQ --> PB
    REQ --> PC
    REQ --> PD
    REQ --> PE

    STARTER --> DHT1
    STARTER --> DHT2
    STARTER --> PA
    STARTER --> PB
    STARTER --> PC
    STARTER --> PD
    STARTER --> PE
    STARTER --> REQ

Loading

System Components Overview

Component	Purpose	Key Features
Grenache DHT Servers	Distributed hash table for peer discovery	Fault-tolerant networking, automatic peer registration
Peer Nodes	Trading participants with local order books	RPC servers, Pub/Sub communication, consensus participation
Order Requester	Test order generation and distribution	Dynamic peer discovery, health monitoring, configurable load
Starter	System orchestration and lifecycle management	Multi-service coordination, parameter configuration

---

🔍 Core Components Deep Dive

1. Peer Node Architecture (src/peer.js)

graph TB
    subgraph "Peer Internal Architecture"
        subgraph "Communication Layer"
            RPC[RPC Server Order Reception]
            PUB[Publisher Order Broadcasting]
            SUB[Subscriber Order Reception]
        end

        subgraph "Processing Layer"
            OQ[Order Queue Sequential Processing]
            BQ[Broadcast Queue Timed Broadcasting]
        end

        subgraph "Business Logic"
            OB[Order Book Matching Engine]
            OS[Orderbook State Fingerprinting]
        end

        subgraph "Consensus Layer"
            CM[Consensus Manager State Synchronization]
        end

        subgraph "Infrastructure"
            LOG[Logger File + Console]
        end
    end

    RPC --> OQ
    SUB --> OQ
    OQ --> OB
    OB --> BQ
    BQ --> PUB
    OB --> OS
    OS --> CM
    CM --> BQ

    LOG -.-> OQ
    LOG -.-> OB
    LOG -.-> CM
    LOG -.-> BQ

Loading

Key Methods and Responsibilities:

PeerFactory Class:

• constructor(peerId): Initialize peer with unique ID and channels
• start(): Launch all peer services and establish network connections
• setupRPCServer(): Configure incoming order handling
• setupPubSub(): Initialize order broadcasting and subscription
• handleIncomingOrder(order): Process orders from external sources
• processOrderInQueue(order): Sequential order processing with duplicate detection
• broadcastOrder(order): Distribute orders to peer network
• checkConsensusNeeded(): Trigger consensus at order checkpoints (every 3 orders)
• startConsensusTimer(): Backup consensus trigger (15-second intervals)
• startConsensusRound(): Initiate distributed consensus process

2. Order Book Engine (src/Components/orderbook.js)

graph LR
    subgraph "Order Book Matching Engine"
        INCOMING[Incoming Order]

        INCOMING --> TYPE{Order Type?}

        TYPE -->|BUY| MBUY[Match Buy Order]
        TYPE -->|SELL| MSELL[Match Sell Order]

        MBUY --> SCAN1[Scan Sell Orders Price ≤ Buy Price]
        MSELL --> SCAN2[Scan Buy Orders Price ≥ Sell Price]

        SCAN1 --> MATCH1{Match Found?}
        SCAN2 --> MATCH2{Match Found?}

        MATCH1 -->|Yes| TRADE1[Execute Trade FIFO Within Price]
        MATCH2 -->|Yes| TRADE2[Execute Trade FIFO Within Price]

        MATCH1 -->|No| ADD1[Add to Buy Book]
        MATCH2 -->|No| ADD2[Add to Sell Book]

        TRADE1 --> REMAINING1{Quantity Remaining?}
        TRADE2 --> REMAINING2{Quantity Remaining?}

        REMAINING1 -->|Yes| ADD1
        REMAINING2 -->|Yes| ADD2

        REMAINING1 -->|No| COMPLETE[Order Complete]
        REMAINING2 -->|No| COMPLETE

        ADD1 --> SORT1[Sort by Price/Time]
        ADD2 --> SORT2[Sort by Price/Time]
    end

Loading

Core Methods:

• addOrder(order): Main entry point for order processing
• matchBuyOrder(incoming): Price-time priority matching for buy orders
• matchSellOrder(incoming): Price-time priority matching for sell orders
• executeTrade(buy, sell, qty): Trade execution and logging
• buySort(a, b): Descending price, FIFO timestamp sorting
• sellSort(a, b): Ascending price, FIFO timestamp sorting
• createFingerprint(): Generate state hash for consensus
• getOrderBookData(): Export state for synchronization

3. Consensus Manager (src/Components/consensusManager.js)

sequenceDiagram
    participant P1 as Peer A
    participant P2 as Peer B
    participant P3 as Peer C
    participant P4 as Peer D
    participant P5 as Peer E

    Note over P1,P5: Consensus Trigger (Every 3 Orders)

    P1->>P1: Create Snapshot
    P1->>P2: CONSENSUS_REQUEST_STATE
    P1->>P3: CONSENSUS_REQUEST_STATE
    P1->>P4: CONSENSUS_REQUEST_STATE
    P1->>P5: CONSENSUS_REQUEST_STATE

    P2->>P1: CONSENSUS_STATE_RESPONSE
    P3->>P1: CONSENSUS_STATE_RESPONSE
    P4->>P1: CONSENSUS_STATE_RESPONSE
    P5->>P1: CONSENSUS_STATE_RESPONSE

    P1->>P1: Analyze States
    P1->>P1: Determine Target State

    Note over P1,P5: Consensus Resolution

    P1->>P2: Sync to Target State
    P1->>P3: Sync to Target State
    P1->>P4: Sync to Target State
    P1->>P5: Sync to Target State

    Note over P1,P5: All Peers Synchronized

Loading

Consensus Algorithm:

1. Majority Rule: If >50% peers have identical states → use majority state
2. Plurality Rule: If no majority → use most common state among available peers
3. Deterministic Fallback: If all states unique → use lexicographically smallest hash
4. Timeout Handling: 10-second timeout with partial peer completion

Key Methods:

• startConsensus(): Initiate consensus round with state snapshot
• handleConsensusMessage(message): Process incoming consensus messages
• resolveConsensus(): Apply consensus algorithm to determine target state
• isActive(): Check if consensus is currently running

4. Order Queue (src/Components/orderQueue.js)

graph TB
    subgraph "Order Queue Processing"
        ENQUEUE[Enqueue Order]

        ENQUEUE --> SORT[Sort by Timestamp then Order Number]
        SORT --> PAUSED{Queue Paused for Consensus?}

        PAUSED -->|Yes| WAIT[Wait for Resume]
        PAUSED -->|No| PROCESSING{Currently Processing?}

        PROCESSING -->|Yes| QUEUE[Queue Order]
        PROCESSING -->|No| IMMEDIATE[Process Immediately]

        WAIT --> RESUME[Resume Signal]
        RESUME --> QUEUE

        QUEUE --> PROCESS[Process Next Order]
        IMMEDIATE --> PROCESS

        PROCESS --> EXECUTE[Execute Process Function]
        EXECUTE --> NEXT{More Orders in Queue?}

        NEXT -->|Yes| PROCESS
        NEXT -->|No| IDLE[Queue Idle]
    end

Loading

Features:

• Deterministic Sorting: Timestamp-first, order-number-second
• Pause/Resume: Consensus coordination support
• Sequential Processing: Prevents race conditions
• Automatic Processing: Self-managing execution flow

5. Broadcast Queue (src/Components/broadcastQueue.js)

graph LR
    subgraph "Broadcast Queue Management"
        INPUT[Order Input]

        INPUT --> VALIDATE[Validate Order Structure]
        VALIDATE --> ENQUEUE[Add to Queue]

        ENQUEUE --> SORT[Sort by Timestamp + Order Number]
        SORT --> DELAY[Apply 50ms Delay]

        DELAY --> BROADCAST[Execute Broadcast]
        BROADCAST --> NEXT{More Orders?}

        NEXT -->|Yes| DELAY
        NEXT -->|No| IDLE[Queue Idle]
    end

Loading

Purpose:

• Rate Limiting: 50ms delays between broadcasts
• Order Preservation: Maintains chronological broadcast order
• Network Optimization: Prevents message flooding

6. Orderbook State Manager (src/Components/orderbookState.js)

graph TB
    subgraph "State Management & Fingerprinting"
        CREATE[Create Snapshot]

        CREATE --> COLLECT[Collect Order Data]
        COLLECT --> SORT[Sort Orders Deterministically]

        SORT --> HASH[Generate SHA-256 Hash]
        HASH --> SNAPSHOT[State Snapshot]

        SNAPSHOT --> VALIDATE[Validate Snapshot]
        VALIDATE --> COMPARE[Compare with Peers]

        COMPARE --> CONFLICTS{State Conflicts?}
        CONFLICTS -->|Yes| SYNC[Synchronize State]
        CONFLICTS -->|No| CONSENSUS[Consensus Achieved]

        SYNC --> UPDATE[Update Orderbook]
        UPDATE --> VERIFY[Verify Integrity]
    end

Loading

Key Features:

• Deterministic Hashing: Ensures identical states produce identical hashes
• State Validation: Comprehensive snapshot verification
• Conflict Resolution: Sophisticated state synchronization
• Integrity Verification: Post-sync validation

---

📊 System Flowcharts

Overall System Flow

graph TB
    subgraph "System Startup Flow"
        START[System Start]
        START --> DHT_START[Start DHT Servers]
        DHT_START --> PEER_START[Start Peers A, B, C, D, E]
        PEER_START --> REQ_START[Start Order Requester]
        REQ_START --> DISCOVERY[Peer Discovery]
        DISCOVERY --> READY[System Ready]
    end

    subgraph "Order Processing Flow"
        READY --> ORDER_GEN[Generate Random Order]
        ORDER_GEN --> PEER_SELECT[Select Random Peer]
        PEER_SELECT --> ORDER_SEND[Send Order via RPC]

        ORDER_SEND --> PEER_RCV[Peer Receives Order]
        PEER_RCV --> QUEUE_ADD[Add to Order Queue]
        QUEUE_ADD --> PROCESS[Process Order]

        PROCESS --> ORDERBOOK[Add to Orderbook]
        ORDERBOOK --> MATCH[Attempt Matching]
        MATCH --> BROADCAST[Broadcast to Network]

        BROADCAST --> CONSENSUS_CHECK{Consensus Needed?}
        CONSENSUS_CHECK -->|Every 3 Orders| CONSENSUS[Start Consensus]
        CONSENSUS_CHECK -->|No| ORDER_GEN

        CONSENSUS --> SYNC[Synchronize States]
        SYNC --> ORDER_GEN
    end

Loading

Peer Communication Flow

graph LR
    subgraph "Inter-Peer Communication"
        PEER_A[Peer A]
        PEER_B[Peer B]
        PEER_C[Peer C]

        PEER_A -->|RPC Order| PEER_B
        PEER_B -->|Pub/Sub Broadcast| PEER_A
        PEER_B -->|Pub/Sub Broadcast| PEER_C

        PEER_A -->|Consensus Message| PEER_B
        PEER_A -->|Consensus Message| PEER_C

        PEER_B -->|State Response| PEER_A
        PEER_C -->|State Response| PEER_A

        PEER_A -->|Sync Command| PEER_B
        PEER_A -->|Sync Command| PEER_C
    end

Loading

---

🤝 Consensus Mechanism

Consensus Trigger Conditions

graph TB
    subgraph "Consensus Triggering Logic"
        ORDER_PROCESSED[Order Processed]
        ORDER_PROCESSED --> COUNT[Check Processed Count]

        COUNT --> MODULO{Count % 3 == 0?}
        MODULO -->|Yes| DELAY[Staggered Delay Based on Peer ID]
        MODULO -->|No| TIMER[15-Second Timer Check]

        DELAY --> START_CONSENSUS[Start Consensus Round]

        TIMER --> TIMER_CONDITIONS{Timer Conditions Met?}
        TIMER_CONDITIONS -->|Yes + Not at Checkpoint| BACKUP_CONSENSUS[Backup Consensus]
        TIMER_CONDITIONS -->|No| CONTINUE[Continue Processing]

        START_CONSENSUS --> CONSENSUS_FLOW[Execute Consensus Algorithm]
        BACKUP_CONSENSUS --> CONSENSUS_FLOW
    end

Loading

State Resolution Algorithm

graph TB
    subgraph "Consensus State Resolution"
        COLLECT_STATES[Collect Peer States]
        COLLECT_STATES --> GROUP[Group Identical States]

        GROUP --> MAJORITY{Majority >50% Found?}
        MAJORITY -->|Yes| USE_MAJORITY[Use Majority State]
        MAJORITY -->|No| PLURALITY{Plurality Found?}

        PLURALITY -->|Yes| USE_PLURALITY[Use Most Common State]
        PLURALITY -->|No| DETERMINISTIC[Use Smallest Hash - Deterministic]

        USE_MAJORITY --> APPLY[Apply Target State]
        USE_PLURALITY --> APPLY
        DETERMINISTIC --> APPLY

        APPLY --> BROADCAST_SYNC[Broadcast Sync Command]
        BROADCAST_SYNC --> COMPLETE[Consensus Complete]
    end

Loading

---

🔄 Order Processing Pipeline

Order Lifecycle

graph TB
    subgraph "Complete Order Lifecycle"
        GENERATE[Order Generated by Requester]

        GENERATE --> SEND[Send to Random Peer via RPC]
        SEND --> RECEIVE[Peer Receives Order]

        RECEIVE --> VALIDATE[Validate Order Format]
        VALIDATE --> QUEUE[Add to Order Queue]

        QUEUE --> SEQUENTIAL[Sequential Processing]
        SEQUENTIAL --> DUPLICATE{Already Processed?}

        DUPLICATE -->|Yes| SKIP[Skip Order]
        DUPLICATE -->|No| ADD_BOOK[Add to Orderbook]

        ADD_BOOK --> MATCH_ENGINE[Run Matching Engine]
        MATCH_ENGINE --> TRADES[Execute Trades]

        TRADES --> BROADCAST_PREP[Prepare Broadcast]
        BROADCAST_PREP --> BROADCAST_QUEUE[Add to Broadcast Queue]

        BROADCAST_QUEUE --> RATE_LIMIT[50ms Rate Limiting]
        RATE_LIMIT --> PUB_SUB[Publish to Network]

        PUB_SUB --> OTHER_PEERS[Other Peers Receive]
        OTHER_PEERS --> PEER_QUEUE[Add to Peer Queues]

        PEER_QUEUE --> PEER_PROCESS[Process on Each Peer]
        PEER_PROCESS --> CONSENSUS_TRIGGER{Consensus Trigger?}

        CONSENSUS_TRIGGER -->|Yes| START_CONSENSUS[Start Consensus]
        CONSENSUS_TRIGGER -->|No| COMPLETE[Order Complete]

        START_CONSENSUS --> SYNCHRONIZE[Synchronize All Peers]
        SYNCHRONIZE --> COMPLETE
    end

Loading

---

⚙️ Configuration & Usage

Command Line Interface

# Basic startup (default: 15 orders, with delay, 3 peers)
npm run start

# Custom configuration
node src/starter.js --30 --false --5
# 30 orders, no delay, 5 peers

# Alternative syntax
node src/starter.js --orders=50 --delay=true --peers=4

# Individual component testing
node src/requester.js --25 --true
node src/peer.js --A

Configuration Parameters

Parameter	Type	Default	Description
orderCount	Number	15	Number of orders to generate
withDelay	Boolean	true	Add delays between order generation
peerCount	Number	3	Number of peers to start (1-5)

---

🔧 Technical Implementation Details

Network Architecture

• Protocol: Grenache WebSocket-based P2P communication
• DHT Servers: Dual-server setup for fault tolerance
• Port Management: Dynamic port allocation with conflict resolution
• Channel Naming: Unique per-peer channel identifiers

Performance Optimizations

1. Deterministic Sorting: O(n log n) order processing
2. Hash-based State Comparison: O(1) state equality checking
3. Staggered Consensus: Prevents simultaneous consensus initiation
4. Rate-limited Broadcasting: Prevents network congestion
5. In-memory State Management: No database overhead

Fault Tolerance Features

1. Connection Retry Logic: Exponential backoff with jitter
2. Health Check System: Periodic peer availability verification
3. Consensus Timeout: Graceful degradation on partial failures
4. Duplicate Order Detection: Prevents double processing
5. State Validation: Comprehensive snapshot verification

Data Structures

// Order Structure
{
  id: "nanoid_string",           // Unique identifier
  type: "buy" | "sell",          // Order type
  price: number,                 // Price level
  quantity: number,              // Order quantity
  owner: "string",               // Order owner
  timestamp: number,             // Creation timestamp
  orderNumber: number            // Sequence number
}

// Consensus Snapshot
{
  peerId: "string",              // Creating peer
  timestamp: number,             // Snapshot time
  processedOrderIds: string[],   // Processed order IDs
  buyOrders: Order[],            // Current buy orders
  sellOrders: Order[],           // Current sell orders
  hash: "string"                 // State fingerprint
}

---

📈 Performance Characteristics

Benchmarks (Based on Recent Testing)

Metric	Value	Context
Consensus Time	25-234ms	Typical completion for 5 peers
Order Processing	~1ms	Single order matching
Network Latency	<50ms	Local DHT communication
Memory Usage	~50MB	Per peer with 1000 orders
Throughput	30 orders/sec	With consensus enabled

---

🛠️ Development & Testing

Test Coverage

• Unit Tests: Order book matching logic, queue operations
• Integration Tests: Peer communication, consensus scenarios
• Performance Tests: Load testing with multiple peers
• Chaos Tests: Network partition and failure scenarios

Monitoring & Observability

1. Comprehensive Logging: File-based logs per component
2. Performance Metrics: Consensus timing, order throughput
3. State Monitoring: Order book consistency tracking
4. Network Health: Peer connectivity status

Development Workflow

# Development setup
npm install
npm run test

# Start system for development
npm run start -- --5 --false --2

# Monitor logs
cd logs

---

📚 Architecture Decisions

Design Principles

1. Decentralization First: No single point of failure
2. Consensus-Driven: Eventual consistency through distributed agreement
3. Performance Oriented: Sub-second consensus with efficient matching
4. Fault Tolerant: Graceful degradation under network partitions
5. Developer Friendly: Clear APIs and comprehensive logging

Trade-offs Made

Decision	Benefit	Trade-off
In-memory storage	High performance	No persistence
Fixed peer limit (5)	Simple consensus	Limited scalability
Synchronous consensus	Strong consistency	Higher latency
Broadcast-based communication	Simple implementation	Network overhead
Deterministic ordering	Reproducible behavior	Processing overhead