sdk_relay/docs/ARCHITECTURE.md

## 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<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
```rust
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`)
```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.** 🚀