## 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 : ```rust pub struct SyncManager { relay_id: String, sequence_counter: Arc>, sync_cache: Arc>>, last_sync: Arc>>, mesh_connections: Arc>>, known_relays: Arc>>, metrics: Arc>, } ``` ### 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 ```rust pub struct SyncMessage { pub sync_type: SyncType, pub relay_id: String, pub sequence: u64, pub timestamp: u64, pub payload: SyncPayload, } ``` #### Types de Payload ```rust pub enum SyncPayload { StateData { state: String, version: String }, ProcessData { processes: HashMap }, MemberData { members: HashMap }, HealthData { status: HealthStatus, uptime: u64, cpu_usage: f64 }, MetricsData { metrics: SyncMetrics }, PeerData { peers: Vec, last_seen: u64 }, RelayData { relays: Vec, 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 : ```rust 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é : ```rust pub struct MessageCache { cache: Arc>>, } 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 ```rust 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 : ```yaml 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 : ```ini ## .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 ```rust 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