Skip to content

P2P_ARCHITECTURE.md

Latest commit

 

History

History
241 lines (189 loc) · 10.1 KB

P2P_ARCHITECTURE.md

File metadata and controls

241 lines (189 loc) · 10.1 KB

🌐 CIRO Network P2P Architecture

Overview

This document outlines the peer-to-peer (P2P) networking architecture for CIRO Network, detailing the transition from a centralized coordinator model to a fully decentralized compute marketplace built on libp2p.

🔄 Current Architecture (Centralized)

System Flow

Job Clients → HTTP API → Coordinator → Database → HTTP API → Workers
     ↓                        ↓                        ↓
[REST API]            [In-Memory Pool]           [Registration]
                      [Task Queue]               [Capability Match]

Current Limitations

  • Single Point of Failure: Coordinator centralization
  • Limited Scalability: HTTP-based communication bottleneck
  • No Direct Worker Communication: Everything routes through coordinator
  • Static Discovery: Workers must know coordinator endpoints
  • No Fault Tolerance: If coordinator fails, entire network stops

🎯 Target P2P Architecture (Decentralized)

Network Topology

┌─────────────────────────────────────────────────────────────────┐
│                    CIRO P2P Network                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │  Worker A   │◄──►│  Worker B   │◄──►│  Worker C   │         │
│  │  (libp2p)   │    │  (libp2p)   │    │  (libp2p)   │         │
│  └─────────────┘    └─────────────┘    └─────────────┘         │
│         │                 │                 │                  │
│         └─────────────────┼─────────────────┘                  │
│                           │                                    │
│  ┌─────────────────────────┼─────────────────────────────────┐  │
│  │              Gossip Protocol                             │  │
│  │  • Job Distribution    │  • Capability Broadcasting      │  │
│  │  • Result Collection   │  • Reputation Updates           │  │
│  │  • Network Health      │  • Blockchain State Sync       │  │
│  └─────────────────────────┼─────────────────────────────────┘  │
│                           │                                    │
│  ┌─────────────────────────┼─────────────────────────────────┐  │
│  │                DHT-Based Discovery                       │  │
│  │  • Peer Finding        │  • Capability Indexing         │  │
│  │  • Bootstrap Nodes     │  • Network Topology            │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                 Starknet Integration                       │  │
│  │  • Job Contracts      │  • Payment Settlement           │  │
│  │  • Worker Staking     │  • Reputation Storage           │  │
│  └─────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Key Advantages

  • Decentralized: No single point of failure
  • Scalable: Direct peer-to-peer communication
  • Fault Tolerant: Network continues operating with node failures
  • Efficient: Reduced latency through direct connections
  • Cost Effective: No need for centralized infrastructure

🏗️ P2P Network Components

1. Core P2P Layer (libp2p)

  • Transport: TCP, WebSocket, QUIC
  • Security: Noise protocol encryption
  • Multiplexing: Yamux for connection efficiency
  • Identity: Ed25519 keys for peer authentication

2. Peer Discovery (DHT)

  • Kademlia DHT: Distributed hash table for peer finding
  • Bootstrap Nodes: Initial network entry points
  • Capability Indexing: Find peers by specific capabilities
  • Network Topology: Maintain network structure view

3. Gossip Protocol

  • Job Distribution: Broadcast available jobs
  • Worker Capabilities: Announce worker specifications
  • Result Collection: Aggregate computation results
  • Network Health: Monitor peer status and reputation

4. Starknet Integration

  • Job Contracts: On-chain job registration and escrow
  • Payment Settlement: Automated payment distribution
  • Reputation Storage: Long-term reputation tracking
  • Dispute Resolution: Smart contract-based arbitration

📊 Network Protocol Flow

Job Execution Flow

1. Job Submission
   Client → Network → Gossip Broadcast

2. Worker Discovery
   Network → DHT Lookup → Capability Matching

3. Job Assignment
   Bidding Process → Worker Selection → Task Distribution

4. Execution
   Worker → Compute → Result Generation

5. Result Collection
   Result → Gossip → Aggregation → Verification

6. Settlement
   Blockchain → Payment → Reputation Update

🔧 Implementation Architecture

Core Modules

// rust-node/src/network/
├── p2p.rs              // Core P2P networking layer
├── discovery.rs        // DHT-based peer discovery
├── gossip.rs          // Gossip protocol implementation
├── worker_registry.rs  // Worker capability management
├── job_distribution.rs // Decentralized job distribution
├── result_collector.rs // Result aggregation system
└── reputation.rs       // Network health & reputation

Key Data Structures

pub struct P2PNetwork {
    swarm: libp2p::Swarm<CiroBehaviour>,
    local_peer_id: PeerId,
    bootstrap_peers: Vec<PeerId>,
    capability_index: HashMap<String, Vec<PeerId>>,
}

pub struct GossipMessage {
    JobAnnouncement(JobAnnouncement),
    WorkerCapabilities(WorkerCapabilities),
    JobResult(JobResult),
    ReputationUpdate(ReputationUpdate),
}

🎯 Migration Strategy

Phase 1: Hybrid Operation

  • Maintain existing centralized coordinator
  • Add P2P capabilities alongside current system
  • Allow gradual worker migration to P2P

Phase 2: P2P Primary

  • P2P becomes primary job distribution method
  • Centralized coordinator as fallback
  • Monitor network health and performance

Phase 3: Full Decentralization

  • Remove centralized coordinator dependency
  • Pure P2P operation
  • Enhanced fault tolerance and scalability

📈 Performance Targets

Network Metrics

  • Latency: <100ms for job distribution
  • Discovery: <5s to find suitable workers
  • Throughput: 100+ jobs/second network capacity
  • Uptime: >99.9% network availability

Scalability Metrics

  • Network Size: 1000+ concurrent workers
  • Concurrent Jobs: 500+ simultaneous executions
  • Data Efficiency: Minimal gossip overhead
  • Connection Stability: Resilient to network churn

🔒 Security Considerations

Network Security

  • Peer Authentication: Ed25519 cryptographic identity
  • Transport Encryption: Noise protocol for all communications
  • Reputation System: Prevent malicious actor participation
  • Rate Limiting: Protect against DoS attacks

Economic Security

  • Stake Requirements: Workers must stake tokens to participate
  • Slashing Conditions: Penalize malicious or poor performance
  • Dispute Resolution: Smart contract arbitration system
  • Payment Security: Escrow-based payment protection

🚀 Future Enhancements

Advanced Features

  • Cross-Chain Support: Multi-blockchain job execution
  • Zero-Knowledge Proofs: Verifiable computation results
  • Dynamic Pricing: Market-based job pricing
  • Mobile Workers: Smartphone-based compute participation

Optimization Opportunities

  • Network Topology: Optimize peer connections for efficiency
  • Caching Strategies: Intelligent result and model caching
  • Load Balancing: Advanced job distribution algorithms
  • Edge Computing: Geographically distributed compute

📚 References

Technical Documentation

Implementation Guidelines

This architecture document serves as the foundation for implementing CIRO Network's transition to a fully decentralized compute marketplace. Regular updates will be made as the implementation progresses.