4nk/sdk_relay
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
sdk_relay/docs/ARCHITECTURE.md

9.2 KiB
Raw Blame History

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 4NK Node.

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

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

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<String, String> },
    ProcessData { processes: Vec<ProcessInfo> },
    MemberData { members: Vec<MemberInfo> },
    RelayData { relays: Vec<RelayInfo> },
    HealthData { health: HealthStatus },
    MetricsData { metrics: SyncMetrics },
    // ... autres types
}

Cache de Déduplication

MessageCache

pub struct MessageCache {
    cache: Arc<Mutex<HashMap<String, CacheEntry>>>,
    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)

# 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

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

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

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

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

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

# 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 4NK Node. 🚀