4NK_node/docs/ARCHITECTURE.md

Architecture Technique - 4NK_node

Ce guide décrit l'architecture technique détaillée de l'infrastructure 4NK_node, incluant la synchronisation entre relais et les composants système.

Vue d'Ensemble de l'Architecture

L'infrastructure 4NK_node est composée de plusieurs services interconnectés qui forment un système distribué pour les paiements silencieux Bitcoin.

Architecture Générale

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Bitcoin Core  │    │    Blindbit     │    │   SDK Relay 1   │
│   (Signet)      │    │   (Service SP)  │    │   (WebSocket)   │
│   Port: 18443   │    │   Port: 8000    │    │   Port: 8090    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Docker Network │
                    │   (btcnet)      │
                    └─────────────────┘
                                 │
                    ┌─────────────────┐
                    │   SDK Relay 2   │
                    │   (WebSocket)   │
                    │   Port: 8092    │
                    └─────────────────┘
                                 │
                    ┌─────────────────┐
                    │   SDK Relay 3   │
                    │   (WebSocket)   │
                    │   Port: 8094    │
                    └─────────────────┘

Reverse proxy public (Nginx)

Un reverse proxy dédié assure désormais l'exposition publique unique de l'infrastructure :

• Sert les assets statiques de l’interface ihm_client générés dans ihm_client/dist
• Termine TLS en 443 (auto-signé par défaut) et force la redirection HTTP→HTTPS
• Proxifie les routes applicatives :
  • / → UI statique
  • /api/ → sdk_relay_1 (HTTP)
  • /ws/ → sdk_relay_1 (WebSocket, upgrade)
  • /storage/ → sdk_storage (HTTP 8081 via proxy)
  • /signer/ws/ → sdk_signer (WebSocket 9090 via proxy)
• Tous les autres services restent strictement internes au réseau Docker btcnet

Composants Principaux

1. Bitcoin Core (Nœud Signet)

Rôle : Nœud Bitcoin Core configuré en mode signet pour le développement et les tests.

Caractéristiques :

• Port RPC : 18443
• Port ZMQ : 29000
• Réseau : Signet
• Validation : Complète des transactions
• Stockage : Blockchain complète
• Interface : JSON-RPC

Fonctionnalités :

• Validation des transactions
• Stockage de la blockchain
• Interface RPC pour les interactions
• Support des wallets
• Notifications ZMQ pour les événements

2. Service Blindbit

Rôle : Service pour les paiements silencieux (Silent Payments).

Caractéristiques :

• Port : 8000
• Interface : HTTP REST API
• Protocole : HTTP

Fonctionnalités :

• Génération d'adresses de paiement silencieux
• Validation des transactions
• Interface HTTP pour les interactions
• Gestion des clés et signatures

3. Service SDK Relay

4. Service SDK Storage

5. Service SDK Signer

Rôle : Serveur WebSocket de signature/gestion de processus, connecté aux relais SDK.

Caractéristiques :

• Port interne : 9090 (WebSocket)
• Dépendances : sdk_relay_1 (URL relay ws://sdk_relay_1:8090)
• Publication : via reverse proxy en /signer/ws/
• Persistance : volume sdk_signer_data pour la base locale

Rôle : Stockage clé/valeur TTL simple pour échanges temporisés.

Caractéristiques :

• Port interne : 8081
• Endpoints : /store (POST), /retrieve/:key (GET)
• Persistance : volume sdk_storage_data mappé sur /app/storage
• Publication : uniquement via reverse proxy en /storage/*

Rôle : Relais pour les interactions SDK avec synchronisation mesh.

Caractéristiques :

• Port WebSocket : 8090
• Port HTTP : 8091
• Protocole : WebSocket/WSS
• Synchronisation : Mesh network

Fonctionnalités :

• Connexion au nœud Bitcoin Core
• Gestion des wallets
• Interface WebSocket
• Scan des blocs pour les paiements silencieux
• Synchronisation entre relais
• Cache de déduplication

Architecture de Synchronisation

Gestionnaire de Synchronisation (SyncManager)

Le SyncManager est le composant central qui gère toute la logique de synchronisation entre les relais :

pub struct SyncManager {
    relay_id: String,
    sequence_counter: Arc<Mutex<u64>>,
    sync_cache: Arc<Mutex<HashMap<String, Instant>>>,
    last_sync: Arc<Mutex<HashMap<SyncType, u64>>>,
    mesh_connections: Arc<Mutex<HashMap<String, MeshConnection>>>,
    known_relays: Arc<Mutex<HashMap<String, RelayInfo>>>,
    metrics: Arc<Mutex<SyncMetrics>>,
}

Types de Synchronisation

Le système supporte plusieurs types de synchronisation :

• StateSync : Synchronisation de l'état général du relais
• ProcessSync : Synchronisation des processus en cours
• MemberSync : Synchronisation des membres
• TxSync : Synchronisation des transactions
• BlockSync : Synchronisation des blocs
• PeerSync : Synchronisation des pairs connectés
• RelaySync : Synchronisation des informations des relais
• HealthSync : Synchronisation de la santé du relais
• MetricsSync : Synchronisation des métriques
• ConfigSync : Synchronisation de la configuration
• CapabilitySync : Synchronisation des capacités

Messages de Synchronisation

Structure des Messages

pub struct SyncMessage {
    pub sync_type: SyncType,
    pub relay_id: String,
    pub sequence: u64,
    pub timestamp: u64,
    pub payload: SyncPayload,
}

Types de Payload

pub enum SyncPayload {
    StateData { state: String, version: String },
    ProcessData { processes: HashMap<String, String> },
    MemberData { members: HashMap<String, String> },
    HealthData { status: HealthStatus, uptime: u64, cpu_usage: f64 },
    MetricsData { metrics: SyncMetrics },
    PeerData { peers: Vec<PeerInfo>, last_seen: u64 },
    RelayData { relays: Vec<RelayInfo>, network_topology: NetworkTopology },
}

Fonctionnalités de Synchronisation

1. Découverte Automatique des Relais

Le système implémente une découverte automatique des relais dans le réseau :

pub async fn discover_relays(&self) -> Result<()> {
    let relay_hosts = vec![
        "sdk_relay_1",
        "sdk_relay_2",
        "sdk_relay_3",
    ];

    for host in relay_hosts {
        if host == self.relay_id {
            continue; // Ignorer soi-même
        }

        let relay_info = RelayInfo {
            relay_id: host.to_string(),
            address: format!("{}:8090", host),
            // ... autres champs
        };

        self.add_relay(relay_info)?;
    }

    Ok(())
}

2. Cache de Déduplication

Pour éviter les doublons, un cache de déduplication est implémenté :

pub struct MessageCache {
    cache: Arc<Mutex<HashMap<String, Instant>>>,
}

impl MessageCache {
    pub fn is_duplicate(&self, message_id: &str) -> bool {
        let mut cache = self.cache.lock().unwrap();
        if cache.contains_key(message_id) {
            true
        } else {
            cache.insert(message_id.to_string(), Instant::now());
            false
        }
    }
}

3. Synchronisation Périodique

Le système effectue une synchronisation périodique avec des intervalles configurés :

• Synchronisation d'état : Toutes les 30 secondes
• Synchronisation de santé : Toutes les 60 secondes
• Synchronisation de métriques : Toutes les 120 secondes
• Synchronisation des relais : Toutes les 300 secondes (5 minutes)

4. Gestion des Connexions Mesh

pub struct MeshConnection {
    pub relay_id: String,
    pub address: String,
    pub connected_since: u64,
    pub last_heartbeat: u64,
    pub status: ConnectionStatus,
}

Configuration Multi-Relais

Configuration Docker

Le système supporte la configuration de plusieurs relais via Docker, avec une publication unique via reverse proxy :

# Publication unique via reverse proxy
services:
  reverse_proxy:
    image: nginx:alpine
    volumes:
      - ./proxy/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
      - ./ihm_client/dist:/usr/share/nginx/html:ro
    ports:
      - "80:80"
      - "443:443"
    networks:
      - btcnet

  # Relais internes seulement (pas de ports exposés)
  sdk_relay_1:
    networks:
      - btcnet
  sdk_relay_2:
    networks:
      - btcnet
  sdk_relay_3:
    networks:
      - btcnet

Configuration par Relais

Chaque relais a sa propre configuration :

# .conf.docker.relay1
relay_id=relay-1
ws_url=0.0.0.0:8090

# .conf.docker.relay2
relay_id=relay-2
ws_url=0.0.0.0:8090

# .conf.docker.relay3
relay_id=relay-3
ws_url=0.0.0.0:8090

Métriques de Synchronisation

pub struct SyncMetrics {
    pub messages_sent: u64,
    pub messages_received: u64,
    pub sync_errors: u64,
    pub last_sync_timestamp: u64,
    pub connected_relays: u64,
    pub mesh_health: f64,
}

Flux de Données

1. Flux de Synchronisation

Relay 1 ──┐
          ├─── SyncManager ──── MessageCache ──── Mesh Network
Relay 2 ──┤
          │
Relay 3 ──┘

2. Flux de Traitement des Transactions

Bitcoin Core ──── ZMQ Notifications ──── SDK Relay ──── Blindbit
     │                    │                    │            │
     └─── Block Scan ─────┴─── Silent Payment ─┴─── Validation

3. Flux de Communication WebSocket

Client ──── WebSocket ──── SDK Relay ──── Bitcoin Core RPC
  │            │              │
  └─── Events ─┴─── Commands ─┴─── Responses

Sécurité et Isolation

1. Isolation Réseau

• Réseau privé : btcnet pour la communication inter-services
• Ports exposés : Uniquement 80/443 sur reverse_proxy ; tous les autres services sont internes (aucune publication de ports)
• Volumes : Données persistantes isolées

2. Authentification

• Bitcoin Core : Cookie d'authentification
• Blindbit : À définir selon les besoins
• SDK Relay : Authentification WebSocket
• Tor : Pas d'authentification requise

3. Chiffrement

• RPC Bitcoin : HTTP (non chiffré en local)
• HTTP Blindbit : HTTP (non chiffré en local)
• WebSocket SDK Relay : WSS (chiffré)
• Tor : Chiffrement intégré

Performance et Optimisations

1. Ressources Requises

• CPU : Minimum 2 cœurs
• RAM : Minimum 4 GB
• Stockage : Minimum 50 GB pour la blockchain
• Réseau : Connexion stable à Internet

2. Optimisations Implémentées

• Cache : Mise en cache des données fréquemment utilisées
• Compression : Compression des données de blockchain
• Parallélisation : Traitement parallèle des blocs
• Monitoring : Métriques de performance

3. Métriques de Performance

• Latence de synchronisation : < 100ms
• Débit de messages : > 1000 msg/s
• Utilisation mémoire : < 2GB par relais
• Temps de démarrage : < 30 secondes

Monitoring et Observabilité

1. Métriques Collectées

• Métriques système : CPU, RAM, disque, réseau
• Métriques de synchronisation : Messages envoyés/reçus, erreurs
• Métriques de santé : Uptime, statut des connexions
• Métriques métier : Transactions traitées, paiements détectés

2. Logs

• Logs système : Démarrage, arrêt, erreurs
• Logs de synchronisation : Messages, erreurs, métriques
• Logs métier : Transactions, paiements, événements

3. Alertes

• Alertes critiques : Services arrêtés, erreurs de synchronisation
• Alertes de performance : Latence élevée, utilisation mémoire
• Alertes métier : Échecs de traitement, anomalies

Évolutivité

1. Scalabilité Horizontale

• Ajout de relais : Configuration automatique
• Load balancing : Distribution de charge
• Redondance : Relais de secours

2. Scalabilité Verticale

• Ressources : Augmentation CPU/RAM
• Stockage : Extension des volumes
• Réseau : Bande passante

3. Architecture Distribuée

• Microservices : Services indépendants
• API Gateway : Point d'entrée unifié
• Service Discovery : Découverte automatique

Déploiement et Infrastructure

1. Environnements

• Développement : Configuration locale
• Test : Environnement de test
• Production : Configuration optimisée

2. Orchestration

• Docker Compose : Orchestration locale
• Kubernetes : Orchestration distribuée (futur)
• Service Mesh : Communication inter-services

3. CI/CD

• Build : Construction des images
• Test : Tests automatisés
• Déploiement : Déploiement automatique

Troubleshooting

1. Problèmes de Synchronisation

• Connexions perdues : Vérifier la connectivité réseau
• Messages dupliqués : Vérifier le cache de déduplication
• Latence élevée : Vérifier les ressources système

2. Problèmes de Performance

• Utilisation mémoire : Vérifier les fuites mémoire
• CPU élevé : Vérifier les boucles infinies
• Disque plein : Nettoyer les logs et données

3. Problèmes de Configuration

• Ports bloqués : Vérifier le pare-feu
• Volumes manquants : Vérifier les permissions
• Variables d'environnement : Vérifier la configuration

Évolution Future

1. Améliorations Planifiées

• Synchronisation temps réel : Réduction de la latence
• Compression avancée : Optimisation de la bande passante
• Chiffrement end-to-end : Sécurité renforcée

2. Nouvelles Fonctionnalités

• API REST : Interface REST pour les clients
• Webhooks : Notifications en temps réel
• Analytics : Tableaux de bord avancés

3. Intégrations

• Monitoring : Prometheus, Grafana
• Logging : ELK Stack
• Alerting : PagerDuty, Slack