# Architecture - sdk_relay ## Vue d'Ensemble `sdk_relay` est un service de relais Rust pour les paiements silencieux Bitcoin, conçu pour fonctionner dans l'écosystème sdk_relay. ## Architecture Générale ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Client Web │ │ Client HTTP │ │ Client Rust │ │ (WebSocket) │ │ (REST API) │ │ (Library) │ └─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘ │ │ │ └──────────────────────┼──────────────────────┘ │ ┌─────────────▼─────────────┐ │ sdk_relay │ │ ┌─────────────────────┐ │ │ │ WebSocket Server │ │ │ │ (tokio-tungstenite)│ │ │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ HTTP Server │ │ │ │ (hyper) │ │ │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ Sync Manager │ │ │ │ (Mesh Network) │ │ │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ Bitcoin Core │ │ │ │ (RPC + ZMQ) │ │ │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ Blindbit │ │ │ │ (HTTP API) │ │ │ └─────────────────────┘ │ └─────────────────────────────┘ ``` ## Composants Principaux ### 1. Serveur WebSocket (`src/websocket.rs`) - **Technologie** : `tokio-tungstenite` - **Port** : 8090 (configurable) - **Fonctionnalités** : - Handshake WebSocket - Gestion des connexions multiples - Messages temps réel - Heartbeat automatique ### 2. Serveur HTTP (`src/http.rs`) - **Technologie** : `hyper` - **Port** : 8091 (configurable) - **Fonctionnalités** : - API REST pour les clients - Endpoints de santé - Métriques et statistiques - Configuration dynamique ### 3. Gestionnaire de Synchronisation (`src/sync.rs`) - **Architecture** : Mesh Network - **Fonctionnalités** : - Découverte automatique des relais - Synchronisation périodique - Cache de déduplication - Métriques de synchronisation ### 4. Intégration Bitcoin Core (`src/daemon.rs`) - **RPC** : `bitcoincore-rpc` - **ZMQ** : Notifications temps réel - **Fonctionnalités** : - Connexion RPC sécurisée - Écoute des blocs/transactions - Gestion des wallets - Scan des paiements silencieux ### 5. Service Blindbit (`src/blindbit.rs`) - **Client HTTP** : `reqwest` - **Fonctionnalités** : - Récupération des filtres - Validation des paiements - Cache des résultats ## Types de Synchronisation ### SyncType Enum ```rust pub enum SyncType { StateSync, // État général du relais ProcessSync, // Processus en cours MemberSync, // Membres du réseau TxSync, // Transactions BlockSync, // Blocs PeerSync, // Pairs connectés RelaySync, // Informations des relais HealthSync, // Santé du système MetricsSync, // Métriques de performance ConfigSync, // Configuration CapabilitySync, // Capacités du relais } ``` ### Messages de Synchronisation ```rust pub struct SyncMessage { pub sync_type: SyncType, pub relay_id: String, pub payload: SyncPayload, pub timestamp: u64, pub message_id: String, } pub enum SyncPayload { StateData { state: HashMap }, ProcessData { processes: Vec }, MemberData { members: Vec }, RelayData { relays: Vec }, HealthData { health: HealthStatus }, MetricsData { metrics: SyncMetrics }, // ... autres types } ``` ## Cache de Déduplication ### MessageCache ```rust pub struct MessageCache { cache: Arc>>, ttl: Duration, } pub struct CacheEntry { pub message: SyncMessage, pub timestamp: SystemTime, } ``` **Fonctionnalités** : - Évite les doublons de messages - TTL configurable - Nettoyage automatique - Performance optimisée ## Configuration ### Fichier de Configuration (`.conf`) ```toml # Bitcoin Core core_url=http://bitcoin:18443 core_wallet=relay_wallet zmq_url=tcp://bitcoin:29000 # WebSocket ws_url=0.0.0.0:8090 # Blindbit blindbit_url=http://blindbit:8000 # Synchronisation relay_id=relay-1 sync_interval=30 health_interval=60 # Réseau network=signet dev_mode=true ``` ### Variables d'Environnement ```bash RUST_LOG=debug,bitcoincore_rpc=trace BITCOIN_COOKIE_PATH=/home/bitcoin/.4nk/bitcoin.cookie ENABLE_SYNC_TEST=1 ``` ## Flux de Données ### 1. Initialisation ``` 1. Chargement de la configuration 2. Connexion à Bitcoin Core 3. Connexion à Blindbit 4. Démarrage du serveur WebSocket 5. Démarrage du serveur HTTP 6. Initialisation du SyncManager 7. Découverte des relais ``` ### 2. Synchronisation Périodique ``` 1. Collecte des données locales 2. Création des messages de sync 3. Envoi aux relais connus 4. Réception des messages 5. Mise à jour du cache 6. Application des changements 7. Mise à jour des métriques ``` ### 3. Traitement des Paiements ``` 1. Réception notification ZMQ 2. Récupération du bloc/transaction 3. Scan des outputs 4. Vérification avec Blindbit 5. Notification aux clients 6. Synchronisation avec les relais ``` ## Métriques et Monitoring ### SyncMetrics ```rust pub struct SyncMetrics { pub known_relays: u64, pub mesh_connections: u64, pub sync_requests: u64, pub sync_responses: u64, pub cache_hits: u64, pub cache_misses: u64, pub avg_latency: f64, pub error_count: u64, } ``` ### HealthStatus ```rust pub enum HealthStatus { Healthy, Warning, Critical, Unknown, } ``` ## Sécurité ### Authentification - **Bitcoin Core** : Cookie d'authentification - **WebSocket** : Authentification optionnelle - **HTTP** : Authentification basique ### Validation - Validation des messages de synchronisation - Vérification des signatures (futur) - Rate limiting - Protection contre les attaques DoS ## Performance ### Optimisations - **Asynchrone** : `tokio` pour la concurrence - **Cache** : Déduplication des messages - **Pooling** : Connexions HTTP réutilisées - **Compression** : Messages compressés (futur) ### Métriques de Performance - Latence de synchronisation - Débit des messages - Utilisation mémoire - CPU usage ## Déploiement ### Docker ```dockerfile FROM rust:1.70 as builder WORKDIR /app COPY . . RUN cargo build --release FROM debian:bookworm-slim COPY --from=builder /app/target/release/sdk_relay /usr/local/bin/ EXPOSE 8090 8091 CMD ["sdk_relay"] ``` ### Configuration Docker ```yaml services: sdk_relay: image: 4nk_node_sdk_relay ports: - "8090:8090" - "8091:8091" volumes: - ./config:/home/bitcoin/.4nk environment: - RUST_LOG=debug ``` ## Évolution Future ### Améliorations Planifiées 1. **Chiffrement** : Messages chiffrés end-to-end 2. **Signature** : Messages signés cryptographiquement 3. **Compression** : Compression des messages 4. **Persistance** : Stockage persistant des données 5. **API REST** : Interface REST complète ### Nouvelles Fonctionnalités 1. **Plugins** : Système de plugins 2. **Webhooks** : Notifications webhook 3. **Analytics** : Tableaux de bord avancés 4. **Multi-réseaux** : Support de plusieurs réseaux Bitcoin ## Dépannage ### Problèmes Courants 1. **Connexion Bitcoin Core** : Vérifier le cookie et l'URL 2. **Synchronisation** : Vérifier la connectivité réseau 3. **WebSocket** : Vérifier les ports et le pare-feu 4. **Performance** : Monitorer les métriques ### Logs Utiles ```bash # Logs de synchronisation RUST_LOG=debug,bitcoincore_rpc=trace # Logs WebSocket RUST_LOG=debug,tokio_tungstenite=trace # Logs HTTP RUST_LOG=debug,hyper=trace ``` --- **Cette architecture garantit un service de relais robuste, performant et évolutif pour l'écosystème sdk_relay.** 🚀