Documentation: ajout ARCHITECTURE.md, API.md, SECURITY.md et mise à jour INDEX.md

.gitlab-ci.yml

@@ -1,26 +0,0 @@
-# You can override the included template(s) by including variable overrides
-# SAST customization: https://docs.gitlab.com/ee/user/application_security/sast/#customizing-the-sast-settings
-# Secret Detection customization: https://docs.gitlab.com/ee/user/application_security/secret_detection/#customizing-settings
-# Dependency Scanning customization: https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#customizing-the-dependency-scanning-settings
-# Container Scanning customization: https://docs.gitlab.com/ee/user/application_security/container_scanning/#customizing-the-container-scanning-settings
-# Note that environment variables can be set in several places
-# See https://docs.gitlab.com/ee/ci/variables/#cicd-variable-precedence
-stages:
-- build
-- test
-- deploy
-- review
-- dast
-- staging
-- canary
-- production
-- incremental rollout 10%
-- incremental rollout 25%
-- incremental rollout 50%
-- incremental rollout 100%
-- performance
-- cleanup
-sast:
-  stage: test
-include:
-- template: Auto-DevOps.gitlab-ci.yml

SECURITY.md

@@ -0,0 +1,62 @@
+# Politique de Sécurité - sdk_relay
+
+## Signalement de Vulnérabilités
+
+**NE PAS** créer d'issue publique pour les vulnérabilités de sécurité.
+
+**Contact :** security@4nkweb.com
+
+### Processus de Signalement
+1. Email à security@4nkweb.com
+2. Objet : "SECURITY VULNERABILITY - sdk_relay"
+3. Description détaillée
+4. Étapes de reproduction
+5. Impact potentiel
+
+### Réponse
+- Accusé de réception sous 48h
+- Évaluation de la vulnérabilité
+- Plan de correction
+- Communication de la résolution
+
+## Bonnes Pratiques
+
+### Code
+- Validation des entrées utilisateur
+- Gestion sécurisée des erreurs
+- Pas de secrets en dur
+- Utilisation de dépendances à jour
+
+### Configuration
+- Authentification Bitcoin Core
+- Validation des messages WebSocket
+- Rate limiting
+- Logs sans données sensibles
+
+### Déploiement
+- Images Docker signées
+- Variables d'environnement sécurisées
+- Monitoring de sécurité
+- Mises à jour régulières
+
+## Audit de Sécurité
+
+### Composants
+- **WebSocket** : Validation des messages
+- **HTTP API** : Authentification et autorisation
+- **Bitcoin Core** : Connexion RPC sécurisée
+- **Synchronisation** : Validation des relais
+
+### Tests
+- `cargo audit` pour les dépendances
+- Tests de sécurité automatisés
+- Validation des configurations
+- Tests de pénétration
+
+## Responsabilité
+
+La sécurité est une responsabilité partagée entre l'équipe de maintenance et la communauté.
+
+---
+
+**Merci de contribuer à maintenir sdk_relay sécurisé !** 🔒

docs/API.md

@@ -0,0 +1,466 @@
+# API Reference - sdk_relay
+
+## Vue d'Ensemble
+
+`sdk_relay` expose deux interfaces principales :
+- **WebSocket** (port 8090) : Communication temps réel
+- **HTTP** (port 8091) : API REST
+
+## Interface WebSocket
+
+### Connexion
+```javascript
+const ws = new WebSocket('ws://localhost:8090');
+```
+
+### Handshake Initial
+```javascript
+// Message de handshake
+const handshake = {
+    "type": "handshake",
+    "client_id": "my-client",
+    "version": "1.0.0",
+    "capabilities": ["sync", "notifications"]
+};
+
+ws.send(JSON.stringify(handshake));
+```
+
+### Types de Messages
+
+#### 1. Messages de Synchronisation
+```json
+{
+    "type": "sync",
+    "sync_type": "StateSync",
+    "relay_id": "relay-1",
+    "payload": {
+        "state": {
+            "uptime": "3600",
+            "version": "1.0.0",
+            "network": "signet"
+        }
+    },
+    "timestamp": 1703001600,
+    "message_id": "msg-123"
+}
+```
+
+#### 2. Messages de Notification
+```json
+{
+    "type": "notification",
+    "notification_type": "payment_detected",
+    "data": {
+        "txid": "abc123...",
+        "block_height": 12345,
+        "amount": "0.001",
+        "address": "sp1..."
+    },
+    "timestamp": 1703001600
+}
+```
+
+#### 3. Messages de Santé
+```json
+{
+    "type": "health",
+    "status": "healthy",
+    "metrics": {
+        "uptime": 3600,
+        "memory_usage": "128MB",
+        "cpu_usage": "5%",
+        "connections": 10
+    },
+    "timestamp": 1703001600
+}
+```
+
+### Événements WebSocket
+
+#### Connexion
+```javascript
+ws.onopen = function() {
+    console.log('Connecté à sdk_relay');
+    // Envoyer le handshake
+    ws.send(JSON.stringify(handshake));
+};
+```
+
+#### Réception de Messages
+```javascript
+ws.onmessage = function(event) {
+    const message = JSON.parse(event.data);
+    
+    switch(message.type) {
+        case 'handshake_response':
+            console.log('Handshake accepté');
+            break;
+        case 'sync':
+            handleSyncMessage(message);
+            break;
+        case 'notification':
+            handleNotification(message);
+            break;
+        case 'health':
+            handleHealthUpdate(message);
+            break;
+    }
+};
+```
+
+#### Gestion d'Erreurs
+```javascript
+ws.onerror = function(error) {
+    console.error('Erreur WebSocket:', error);
+};
+
+ws.onclose = function(event) {
+    console.log('Connexion fermée:', event.code, event.reason);
+};
+```
+
+## Interface HTTP
+
+### Base URL
+```
+http://localhost:8091
+```
+
+### Endpoints
+
+#### 1. Santé du Service
+```http
+GET /health
+```
+
+**Réponse :**
+```json
+{
+    "status": "healthy",
+    "uptime": 3600,
+    "version": "1.0.0",
+    "timestamp": 1703001600
+}
+```
+
+#### 2. Métriques
+```http
+GET /metrics
+```
+
+**Réponse :**
+```json
+{
+    "sync_metrics": {
+        "known_relays": 3,
+        "mesh_connections": 6,
+        "sync_requests": 150,
+        "sync_responses": 150,
+        "cache_hits": 120,
+        "cache_misses": 30,
+        "avg_latency": 45.2,
+        "error_count": 0
+    },
+    "system_metrics": {
+        "memory_usage": "128MB",
+        "cpu_usage": "5%",
+        "active_connections": 10,
+        "total_requests": 1000
+    }
+}
+```
+
+#### 3. Configuration
+```http
+GET /config
+```
+
+**Réponse :**
+```json
+{
+    "relay_id": "relay-1",
+    "network": "signet",
+    "ws_url": "0.0.0.0:8090",
+    "http_url": "0.0.0.0:8091",
+    "bitcoin_core": {
+        "url": "http://bitcoin:18443",
+        "wallet": "relay_wallet"
+    },
+    "blindbit": {
+        "url": "http://blindbit:8000"
+    },
+    "sync": {
+        "interval": 30,
+        "health_interval": 60
+    }
+}
+```
+
+#### 4. Relais Connus
+```http
+GET /relays
+```
+
+**Réponse :**
+```json
+{
+    "relays": [
+        {
+            "relay_id": "relay-1",
+            "address": "sdk_relay_1:8090",
+            "version": "1.0.0",
+            "uptime": 3600,
+            "health": "healthy",
+            "last_seen": 1703001600
+        },
+        {
+            "relay_id": "relay-2",
+            "address": "sdk_relay_2:8090",
+            "version": "1.0.0",
+            "uptime": 3600,
+            "health": "healthy",
+            "last_seen": 1703001600
+        }
+    ]
+}
+```
+
+#### 5. Statut de Synchronisation
+```http
+GET /sync/status
+```
+
+**Réponse :**
+```json
+{
+    "status": "syncing",
+    "last_sync": 1703001600,
+    "next_sync": 1703001630,
+    "sync_types": [
+        "StateSync",
+        "HealthSync",
+        "MetricsSync"
+    ],
+    "errors": []
+}
+```
+
+#### 6. Forcer la Synchronisation
+```http
+POST /sync/force
+Content-Type: application/json
+
+{
+    "sync_types": ["StateSync", "HealthSync"]
+}
+```
+
+**Réponse :**
+```json
+{
+    "status": "sync_triggered",
+    "sync_types": ["StateSync", "HealthSync"],
+    "timestamp": 1703001600
+}
+```
+
+#### 7. Logs
+```http
+GET /logs?level=info&limit=100
+```
+
+**Paramètres :**
+- `level` : debug, info, warn, error
+- `limit` : nombre de lignes (défaut: 100)
+
+**Réponse :**
+```json
+{
+    "logs": [
+        {
+            "timestamp": "2024-12-19T10:00:00Z",
+            "level": "info",
+            "message": "Relay started successfully"
+        },
+        {
+            "timestamp": "2024-12-19T10:00:30Z",
+            "level": "info",
+            "message": "Sync completed"
+        }
+    ]
+}
+```
+
+## Codes d'Erreur
+
+### WebSocket
+- `1000` : Fermeture normale
+- `1001` : Client part
+- `1002` : Erreur de protocole
+- `1003` : Type de données non supporté
+- `1006` : Connexion fermée anormalement
+- `1011` : Erreur serveur
+
+### HTTP
+- `200` : Succès
+- `400` : Requête invalide
+- `404` : Endpoint non trouvé
+- `500` : Erreur serveur interne
+- `503` : Service indisponible
+
+## Exemples d'Utilisation
+
+### Client JavaScript
+```javascript
+class SdkRelayClient {
+    constructor(url) {
+        this.ws = new WebSocket(url);
+        this.setupEventHandlers();
+    }
+
+    setupEventHandlers() {
+        this.ws.onopen = () => this.onConnect();
+        this.ws.onmessage = (event) => this.onMessage(event);
+        this.ws.onerror = (error) => this.onError(error);
+        this.ws.onclose = (event) => this.onClose(event);
+    }
+
+    onConnect() {
+        console.log('Connecté à sdk_relay');
+        this.sendHandshake();
+    }
+
+    sendHandshake() {
+        const handshake = {
+            type: 'handshake',
+            client_id: 'js-client',
+            version: '1.0.0',
+            capabilities: ['sync', 'notifications']
+        };
+        this.ws.send(JSON.stringify(handshake));
+    }
+
+    onMessage(event) {
+        const message = JSON.parse(event.data);
+        console.log('Message reçu:', message);
+    }
+
+    onError(error) {
+        console.error('Erreur WebSocket:', error);
+    }
+
+    onClose(event) {
+        console.log('Connexion fermée:', event.code, event.reason);
+    }
+}
+
+// Utilisation
+const client = new SdkRelayClient('ws://localhost:8090');
+```
+
+### Client Python
+```python
+import asyncio
+import websockets
+import json
+
+class SdkRelayClient:
+    def __init__(self, url):
+        self.url = url
+        self.websocket = None
+
+    async def connect(self):
+        self.websocket = await websockets.connect(self.url)
+        await self.send_handshake()
+
+    async def send_handshake(self):
+        handshake = {
+            "type": "handshake",
+            "client_id": "python-client",
+            "version": "1.0.0",
+            "capabilities": ["sync", "notifications"]
+        }
+        await self.websocket.send(json.dumps(handshake))
+
+    async def listen(self):
+        async for message in self.websocket:
+            data = json.loads(message)
+            print(f"Message reçu: {data}")
+
+    async def close(self):
+        if self.websocket:
+            await self.websocket.close()
+
+# Utilisation
+async def main():
+    client = SdkRelayClient('ws://localhost:8090')
+    await client.connect()
+    await client.listen()
+
+asyncio.run(main())
+```
+
+### Client cURL
+```bash
+# Vérifier la santé
+curl http://localhost:8091/health
+
+# Obtenir les métriques
+curl http://localhost:8091/metrics
+
+# Obtenir la configuration
+curl http://localhost:8091/config
+
+# Forcer la synchronisation
+curl -X POST http://localhost:8091/sync/force \
+  -H "Content-Type: application/json" \
+  -d '{"sync_types": ["StateSync"]}'
+```
+
+## Limites et Quotas
+
+### WebSocket
+- **Connexions simultanées** : 1000 par défaut
+- **Taille des messages** : 1MB maximum
+- **Heartbeat** : 30 secondes
+- **Timeout de connexion** : 60 secondes
+
+### HTTP
+- **Taux limite** : 1000 requêtes/minute
+- **Taille des requêtes** : 10MB maximum
+- **Timeout** : 30 secondes
+- **Connexions simultanées** : 100
+
+## Sécurité
+
+### Authentification
+- **WebSocket** : Authentification optionnelle via handshake
+- **HTTP** : Authentification basique (à configurer)
+
+### Validation
+- Validation JSON des messages
+- Rate limiting
+- Protection contre les attaques DoS
+
+### Chiffrement
+- **WebSocket** : WSS (WebSocket Secure) recommandé
+- **HTTP** : HTTPS recommandé
+
+## Monitoring
+
+### Métriques Clés
+- **Latence** : Temps de réponse des APIs
+- **Débit** : Messages par seconde
+- **Erreurs** : Taux d'erreur
+- **Connexions** : Nombre de connexions actives
+
+### Alertes
+- Service indisponible
+- Latence élevée (> 1s)
+- Taux d'erreur élevé (> 5%)
+- Mémoire/CPU élevés
+
+---
+
+**Cette API permet une intégration complète avec sdk_relay pour les clients WebSocket et HTTP.** 🚀

docs/ARCHITECTURE.md

@@ -0,0 +1,332 @@
+# 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
+```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 4NK Node.** 🚀

docs/INDEX.md

@@ -1,13 +1,18 @@
 # Documentation - sdk_relay
 
 ## Guides
-- [Architecture](ARCHITECTURE.md)
+- [Architecture](ARCHITECTURE.md) - Architecture technique détaillée
-- [API](API.md)
+- [API](API.md) - Référence complète des APIs WebSocket et HTTP
-- [Contribution](../CONTRIBUTING.md)
+- [Contribution](../CONTRIBUTING.md) - Guide de contribution
-- [Sécurité](../SECURITY.md)
+- [Sécurité](../SECURITY.md) - Politique de sécurité
-- [Changelog](../CHANGELOG.md)
+- [Changelog](../CHANGELOG.md) - Historique des versions
 
 ## Tests
 - Exécuter: `cargo test --all`
 - Lint: `cargo clippy -- -D warnings`
 - Format: `cargo fmt -- --check`
+
+## Développement
+- Build: `cargo build --release`
+- Run: `cargo run -- --config .conf`
+- Docker: `docker build -f Dockerfile .`