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 sdk_client, incluant la synchronisation entre relais et les composants système.

Vue d'Ensemble de l'Architecture

L'infrastructure sdk_client 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