sdk_relay/docs/EXEMPLES_PRATIQUES.md

# Exemples Pratiques - sdk_relay

Ce document contient des exemples pratiques pour utiliser le service sdk_relay.

## 🚀 Exemples de Démarrage

### 1. Démarrage local simple

```bash
# Compiler le projet
cargo build --release

# Démarrer avec configuration par défaut
./target/release/sdk_relay

# Démarrer avec configuration personnalisée
./target/release/sdk_relay --config /path/to/config.conf
```

### 2. Démarrage avec variables d'environnement

```bash
# Configuration via variables d'environnement
export CORE_URL="http://localhost:18443"
export CORE_WALLET="my_wallet"
export WS_URL="0.0.0.0:8090"
export NETWORK="signet"
export BLINDBIT_URL="http://localhost:8000"

# Démarrer le service
./target/release/sdk_relay
```

### 3. Démarrage en mode debug

```bash
# Activer les logs détaillés
export RUST_LOG=debug

# Démarrer avec logs complets
./target/release/sdk_relay 2>&1 | tee relay.log

# Démarrer avec profiling
RUSTFLAGS="-C target-cpu=native" cargo run --release
```

## 🔌 Exemples de Connexion WebSocket

### 1. Connexion basique avec JavaScript

```javascript
// Connexion WebSocket simple
const ws = new WebSocket('ws://localhost:8090');

ws.onopen = function() {
    console.log('Connecté au relais');
    
    // Envoyer un message de handshake
    const handshake = {
        type: 'handshake',
        client_id: 'test-client-1',
        version: '1.0.0'
    };
    ws.send(JSON.stringify(handshake));
};

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    console.log('Message reçu:', message);
    
    if (message.type === 'handshake_response') {
        console.log('Handshake réussi, SP address:', message.sp_address);
    }
};

ws.onerror = function(error) {
    console.error('Erreur WebSocket:', error);
};

ws.onclose = function() {
    console.log('Connexion fermée');
};
```

### 2. Connexion avec Python

```python
import asyncio
import websockets
import json

async def connect_to_relay():
    uri = "ws://localhost:8090"
    
    async with websockets.connect(uri) as websocket:
        # Envoyer un message de handshake
        handshake = {
            "type": "handshake",
            "client_id": "python-client-1",
            "version": "1.0.0"
        }
        await websocket.send(json.dumps(handshake))
        
        # Écouter les messages
        async for message in websocket:
            data = json.loads(message)
            print(f"Message reçu: {data}")
            
            if data.get("type") == "handshake_response":
                print(f"SP Address: {data.get('sp_address')}")

# Exécuter
asyncio.run(connect_to_relay())
```

### 3. Connexion avec curl (test)

```bash
# Test de connectivité WebSocket avec curl
curl -v -H "Connection: Upgrade" \
     -H "Upgrade: websocket" \
     -H "Sec-WebSocket-Key: test" \
     -H "Sec-WebSocket-Version: 13" \
     http://localhost:8090/

# Test avec wscat (si installé)
wscat -c ws://localhost:8090
```

## 📡 Exemples de Messages

### 1. Message de Handshake

```json
{
    "type": "handshake",
    "client_id": "client-123",
    "version": "1.0.0",
    "capabilities": ["sync", "mesh", "health"]
}
```

**Réponse attendue :**
```json
{
    "type": "handshake_response",
    "sp_address": "tsp1qqtle38p9mzlmka7m48y762ksygdstlnmlwsjz9p0qp20xf69hasxkqmnsncgw0kw5al4qqhw0xrp8qt479cg6z6hk0954f882dx230hvkvcu5hpe",
    "relay_id": "relay-1",
    "version": "1.0.0",
    "capabilities": ["sync", "mesh", "health", "metrics"]
}
```

### 2. Message de Synchronisation

```json
{
    "flag": "Sync",
    "content": {
        "type": "RelaySync",
        "relay_id": "client-123",
        "timestamp": 1640995200,
        "sequence": 1,
        "payload": {
            "discovery": true,
            "relay_info": {
                "id": "client-123",
                "capabilities": ["sync", "mesh"]
            }
        }
    }
}
```

### 3. Message de Transaction

```json
{
    "type": "new_transaction",
    "txid": "abc123...",
    "outputs": [
        {
            "address": "tsp1...",
            "amount": 1000000,
            "script_pubkey": "001234..."
        }
    ],
    "block_height": 123456
}
```

## 🧪 Exemples de Tests

### 1. Test de connectivité

```bash
# Test de connectivité basique
curl -s http://localhost:8090/ || echo "Port non accessible"

# Test de connectivité depuis un conteneur
docker run --rm --network 4nk_default curlimages/curl \
    curl -s http://sdk_relay_1:8090/

# Test de connectivité WebSocket
python3 -c "
import websockets
import asyncio

async def test():
    try:
        async with websockets.connect('ws://localhost:8090') as ws:
            print('✅ WebSocket accessible')
    except Exception as e:
        print(f'❌ Erreur: {e}')

asyncio.run(test())
"
```

### 2. Test de messages

```bash
# Test avec le script Python fourni
python3 test_websocket_messages.py

# Test de charge
for i in {1..10}; do
    python3 test_websocket_messages.py &
done
wait
```

### 3. Test de synchronisation

```bash
# Test de synchronisation entre relais
./test_sync_logs.sh test

# Test en continu
./test_sync_logs.sh continuous

# Test forcé
./test_sync_logs.sh force
```

## 🔧 Exemples de Configuration

### 1. Configuration de développement

```ini
# .conf.dev
core_url=http://localhost:18443
core_wallet=dev_wallet
ws_url=0.0.0.0:8090
wallet_name=dev_wallet.json
network=signet
blindbit_url=http://localhost:8000
zmq_url=tcp://localhost:29000
data_dir=.4nk
cookie_path=/home/user/.bitcoin/signet/.cookie
dev_mode=true
standalone=true
relay_id=dev-relay-1
```

### 2. Configuration de production

```ini
# .conf.prod
core_url=http://bitcoin:18443
core_wallet=prod_wallet
ws_url=0.0.0.0:8090
wallet_name=prod_wallet.json
network=mainnet
blindbit_url=http://blindbit:8000
zmq_url=tcp://bitcoin:29000
data_dir=/var/lib/4nk
cookie_path=/var/lib/bitcoin/.bitcoin/.cookie
dev_mode=false
standalone=false
relay_id=prod-relay-1
```

### 3. Configuration multi-relais

```ini
# .conf.relay1
relay_id=relay-1
ws_url=0.0.0.0:8090

# .conf.relay2
relay_id=relay-2
ws_url=0.0.0.0:8092

# .conf.relay3
relay_id=relay-3
ws_url=0.0.0.0:8094
```

## 📊 Exemples de Monitoring

### 1. Monitoring des logs

```bash
# Suivre les logs en temps réel
tail -f relay.log | grep -E "(ERROR|WARN|INFO)"

# Filtrer les messages de synchronisation
tail -f relay.log | grep -E "(Sync|Relay|Mesh)"

# Compter les erreurs
grep -c "ERROR" relay.log

# Analyser les performances
grep "processing_time" relay.log | awk '{sum+=$NF; count++} END {print "Avg:", sum/count}'
```

### 2. Monitoring des connexions

```bash
# Vérifier les connexions WebSocket actives
netstat -tlnp | grep :8090

# Compter les connexions
netstat -an | grep :8090 | wc -l

# Vérifier les processus
ps aux | grep sdk_relay
```

### 3. Monitoring des ressources

```bash
# Vérifier l'utilisation mémoire
ps -o pid,ppid,cmd,%mem,%cpu --sort=-%mem | grep sdk_relay

# Vérifier l'espace disque
du -sh /home/user/.4nk/

# Vérifier les fichiers ouverts
lsof -p $(pgrep sdk_relay)
```

## 🛠️ Exemples de Debug

### 1. Debug de connexion Bitcoin Core

```bash
# Vérifier la connectivité RPC
curl -u bitcoin:password --data-binary '{"jsonrpc": "1.0", "id": "test", "method": "getblockchaininfo", "params": []}' -H 'content-type: text/plain;' http://localhost:18443/

# Vérifier le wallet
curl -u bitcoin:password --data-binary '{"jsonrpc": "1.0", "id": "test", "method": "listwallets", "params": []}' -H 'content-type: text/plain;' http://localhost:18443/

# Vérifier les permissions du cookie
ls -la /home/user/.bitcoin/signet/.cookie
```

### 2. Debug de synchronisation

```bash
# Vérifier l'état du SyncManager
grep "SyncManager" relay.log | tail -10

# Vérifier les messages de découverte
grep "discover" relay.log | tail -10

# Vérifier les erreurs de synchronisation
grep "sync.*error" relay.log | tail -10
```

### 3. Debug de WebSocket

```bash
# Vérifier les connexions WebSocket
grep "WebSocket" relay.log | tail -10

# Vérifier les messages reçus
grep "received" relay.log | tail -10

# Vérifier les erreurs de parsing
grep "parse.*error" relay.log | tail -10
```

## 🔒 Exemples de Sécurité

### 1. Configuration de pare-feu

```bash
# Autoriser seulement les ports nécessaires
sudo ufw allow 8090/tcp  # WebSocket sdk_relay
sudo ufw allow 18443/tcp # Bitcoin Core RPC
sudo ufw allow 8000/tcp  # Blindbit API

# Vérifier les règles
sudo ufw status numbered
```

### 2. Configuration SSL/TLS

```bash
# Générer un certificat pour WebSocket sécurisé
openssl req -x509 -newkey rsa:4096 -keyout relay-key.pem -out relay-cert.pem -days 365 -nodes

# Configurer nginx comme proxy SSL
server {
    listen 443 ssl;
    server_name relay.example.com;
    
    ssl_certificate relay-cert.pem;
    ssl_certificate_key relay-key.pem;
    
    location / {
        proxy_pass http://localhost:8090;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}
```

### 3. Monitoring de sécurité

```bash
# Vérifier les connexions suspectes
netstat -tuln | grep :8090

# Vérifier les tentatives d'accès
grep "connection.*from" relay.log | tail -20

# Vérifier les erreurs d'authentification
grep "auth.*error" relay.log | tail -10
```

## 📈 Exemples de Performance

### 1. Test de charge

```bash
# Script de test de charge
#!/bin/bash
for i in {1..100}; do
    python3 -c "
import asyncio
import websockets
import json

async def test_client():
    try:
        async with websockets.connect('ws://localhost:8090') as ws:
            await ws.send(json.dumps({'type': 'handshake', 'client_id': f'client-{i}'}))
            response = await ws.recv()
            print(f'Client {i}: OK')
    except Exception as e:
        print(f'Client {i}: ERROR - {e}')

asyncio.run(test_client())
" &
    sleep 0.1
done
wait
```

### 2. Optimisation mémoire

```bash
# Limiter la mémoire du processus
ulimit -v 1048576  # 1GB

# Démarrer avec profiling mémoire
valgrind --tool=massif ./target/release/sdk_relay

# Analyser le profil mémoire
ms_print massif.out.* > memory_profile.txt
```

### 3. Monitoring des performances

```bash
# Script de monitoring continu
#!/bin/bash
while true; do
    echo "=== $(date) ==="
    
    # Mémoire
    memory=$(ps -o rss= -p $(pgrep sdk_relay))
    echo "Memory: ${memory}KB"
    
    # CPU
    cpu=$(ps -o %cpu= -p $(pgrep sdk_relay))
    echo "CPU: ${cpu}%"
    
    # Connexions WebSocket
    connections=$(netstat -an | grep :8090 | wc -l)
    echo "WebSocket connections: $connections"
    
    # Messages par seconde
    messages=$(grep "message.*processed" relay.log | tail -1 | awk '{print $NF}')
    echo "Messages/sec: $messages"
    
    sleep 30
done
```

## 🚀 Exemples de Déploiement

### 1. Déploiement avec systemd

```ini
# /etc/systemd/system/sdk-relay.service
[Unit]
Description=sdk_relay Service
After=network.target

[Service]
Type=simple
User=bitcoin
WorkingDirectory=/opt/sdk_relay
ExecStart=/opt/sdk_relay/target/release/sdk_relay
Restart=always
RestartSec=10
Environment=RUST_LOG=info

[Install]
WantedBy=multi-user.target
```

```bash
# Activer et démarrer le service
sudo systemctl enable sdk-relay
sudo systemctl start sdk-relay
sudo systemctl status sdk-relay
```

### 2. Déploiement avec Docker

```dockerfile
# Dockerfile
FROM rust:1.89 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bullseye-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/sdk_relay /usr/local/bin/
COPY --from=builder /app/.conf /home/bitcoin/.conf

EXPOSE 8090
CMD ["sdk_relay"]
```

```bash
# Construire et démarrer
docker build -t sdk_relay .
docker run -d --name sdk_relay -p 8090:8090 sdk_relay
```

### 3. Déploiement avec Kubernetes

```yaml
# sdk-relay-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sdk-relay
spec:
  replicas: 3
  selector:
    matchLabels:
      app: sdk-relay
  template:
    metadata:
      labels:
        app: sdk-relay
    spec:
      containers:
      - name: sdk-relay
        image: sdk_relay:latest
        ports:
        - containerPort: 8090
        env:
        - name: RUST_LOG
          value: "info"
        volumeMounts:
        - name: config
          mountPath: /home/bitcoin/.conf
      volumes:
      - name: config
        configMap:
          name: sdk-relay-config
---
apiVersion: v1
kind: Service
metadata:
  name: sdk-relay-service
spec:
  selector:
    app: sdk-relay
  ports:
  - port: 8090
    targetPort: 8090
  type: LoadBalancer
```

Ces exemples couvrent les cas d'usage les plus courants pour sdk_relay. Adaptez-les selon vos besoins spécifiques !