sdk_client/docs/ARCHITECTURE.md

Architecture — sdk_client

Ce document décrit l’architecture du module sdk_client (bibliothèque cliente Silent Payments), ses modules internes, flux principaux et invariants. Il est centré sur le code de ce dépôt.

Périmètre

• Interface principale: WebAssembly via wasm_bindgen et tsify.
• Modules internes: api.rs (surface fonctionnelle), user.rs (appareil local), wallet.rs (portefeuille SP), peers.rs (pair minimal), lib.rs (agrégation).
• Dépendances clés: sdk_common (cryptographie, SP, Merkle, PSBT), serde, rand, wasm-logger.

Flux essentiels

• Initialisation/Pairing: création ou restauration d’appareil, appairage optionnel par process_id et adresses SP.
• Traitement d’événements: analyse de transactions et messages chiffrés, mises à jour de processus, génération de diffs et commits.
• Gestion de processus: création et évolution d’états avec engagements PCD (racines Merkle) et règles/ rôles.
• Transactions SP: construction, dérivation des secrets partagés, signature et préparation de messages réseau.

Invariants

• Secrets jamais exposés en clair hors du module.
• États identifiés par racines Merkle, preuves cohérentes avec l’arbre.
• Rôles déterminent visibilité/validation des champs.
• Tailles et formats bornés à la frontière WASM.

Traçabilité documentaire

• Toute évolution doit être répercutée dans docs/API.md et docs/USAGE.md et les risques dans docs/SECURITY_AUDIT.md.

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    │
                    └─────────────────┘

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

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 :

services:
  sdk_relay_1:
    container_name: sdk_relay_1
    ports:
      - "8090:8090"
      - "8091:8091"
    environment:
      - ENABLE_SYNC_TEST=1

  sdk_relay_2:
    container_name: sdk_relay_2
    ports:
      - "8092:8090"
      - "8093:8091"
    environment:
      - ENABLE_SYNC_TEST=1

  sdk_relay_3:
    container_name: sdk_relay_3
    ports:
      - "8094:8090"
      - "8095:8091"
    environment:
      - ENABLE_SYNC_TEST=1

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 : Seulement les ports nécessaires
• 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