Documentation: ajout ARCHITECTURE.md, API.md, SECURITY.md et mise à jour INDEX.md
This commit is contained in:
parent
26379f4dca
commit
b96269fd5d
@ -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
|
||||
62
SECURITY.md
Normal file
62
SECURITY.md
Normal file
@ -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é !** 🔒
|
||||
466
docs/API.md
Normal file
466
docs/API.md
Normal file
@ -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.** 🚀
|
||||
332
docs/ARCHITECTURE.md
Normal file
332
docs/ARCHITECTURE.md
Normal file
@ -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.** 🚀
|
||||
@ -1,13 +1,18 @@
|
||||
# Documentation - sdk_relay
|
||||
|
||||
## Guides
|
||||
- [Architecture](ARCHITECTURE.md)
|
||||
- [API](API.md)
|
||||
- [Contribution](../CONTRIBUTING.md)
|
||||
- [Sécurité](../SECURITY.md)
|
||||
- [Changelog](../CHANGELOG.md)
|
||||
- [Architecture](ARCHITECTURE.md) - Architecture technique détaillée
|
||||
- [API](API.md) - Référence complète des APIs WebSocket et HTTP
|
||||
- [Contribution](../CONTRIBUTING.md) - Guide de contribution
|
||||
- [Sécurité](../SECURITY.md) - Politique de sécurité
|
||||
- [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 .`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user