494 lines
14 KiB
Markdown
494 lines
14 KiB
Markdown
## 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<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
|
||
|
||
```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<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 :
|
||
|
||
```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<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
|
||
|
||
```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
|
||
|
||
|