4NK_env/IA_agents/blindbit-oracle-deployment.md

# BlindBit Oracle - Déploiement et Configuration

## 📋 Vue d'ensemble

BlindBit Oracle est un service critique de la chaîne blockchain LeCoffre Node. Ce document décrit son déploiement, sa configuration et sa correction du bug d'écoute.

## 🐛 Bug Corrigé

### **Problème Identifié**
L'application BlindBit Oracle ignorait la configuration `host` du fichier TOML et écoutait toujours sur `127.0.0.1:8000` en dur dans le code, rendant le service inaccessible depuis l'extérieur du conteneur.

### **Solution Appliquée**
1. **Analyse du code source** : Identification du problème dans `/src/common/vars.go`
2. **Correction du code** : Ajout d'un log de débogage dans `/src/common/config.go`
3. **Construction d'une nouvelle image** : `git.4nkweb.com/4nk/blindbit-oracle:fixed-source`
4. **Test de validation** : Confirmation que l'application écoute maintenant sur `0.0.0.0:8000`

## 🏗️ Architecture

### **Position dans la Chaîne**
```
bitcoin (healthy) → blindbit-oracle → sdk_relay
```

### **Ports et Services**
| Service | Port Interne | Port Externe | Protocole |
|---------|--------------|--------------|-----------|
| BlindBit Oracle | 8000 | 8000 | HTTP |
| gRPC Server | 50051 | - | gRPC (interne) |

## 📁 Configuration Centralisée

### **Fichier de Configuration**
- **Chemin** : `/home/debian/4NK_env/confs/lecoffre_node/blindbit-oracle/blindbit.toml`
- **Montage** : `/tmp/blindbit.toml:ro` → `/root/.blindbit-oracle/blindbit.toml`

### **Configuration Type**
```toml
# Configuration Blindbit Oracle
host = "0.0.0.0:8000"
chain = "signet"
rpc_endpoint = "http://bitcoin:38332"
cookie_path = "/home/bitcoin/.bitcoin/signet/.cookie"
rpc_user = ""
rpc_pass = ""
sync_start_height = 1

# Performance
max_parallel_tweak_computations = 4
max_parallel_requests = 4

# Index
tweaks_only = 0
tweaks_full_basic = 1
tweaks_full_with_dust_filter = 1
tweaks_cut_through_with_dust_filter = 1
```

## 📊 Logs Centralisés

### **Répertoire de Logs**
- **Chemin** : `/home/debian/4NK_env/logs/blindbit/`
- **Montage** : `/var/log/blindbit`

### **Fichiers de Logs**
- Logs d'application
- Logs de synchronisation
- Logs d'erreurs

## 🐳 Docker Compose

### **Service Definition**
```yaml
blindbit:
  image: git.4nkweb.com/4nk/blindbit-oracle:fixed-source
  container_name: blindbit-oracle
  depends_on:
    bitcoin:
      condition: service_healthy
  volumes:
    - blindbit_data:/root/.blindbit-oracle
    - /home/debian/4NK_env/confs/lecoffre_node/blindbit-oracle/blindbit.toml:/tmp/blindbit.toml:ro
    - bitcoin_data:/home/bitcoin/.bitcoin
    - /home/debian/4NK_env/logs/blindbit:/var/log/blindbit
    - /home/debian/4NK_env/scripts/lecoffre_node/healthchecks:/scripts/healthchecks:ro
  entrypoint: >
    sh -c "mkdir -p /root/.blindbit-oracle &&
          if [ ! -f /root/.blindbit-oracle/blindbit.toml ]; then
            cp /tmp/blindbit.toml /root/.blindbit-oracle/blindbit.toml;
          fi &&
          echo 'Starting BlindBit Oracle with corrected host binding...' &&
          exec ./main -datadir /root/.blindbit-oracle"
  networks:
    btcnet:
      aliases:
        - blindbit
  ports:
    - "0.0.0.0:8000:8000"
  healthcheck:
    test: ["CMD", "sh", "/scripts/healthchecks/blindbit-progress.sh"]
    interval: 10s
    timeout: 5s
    retries: 60
    start_period: 180s
  restart: unless-stopped
```

## 🔍 Healthcheck

### **Script de Healthcheck**
- **Chemin** : `/scripts/healthchecks/blindbit-progress.sh`
- **Fonction** : Vérification de la synchronisation et de l'API

### **Critères de Santé**
1. **Synchronisation** : Headers synchronisés avec Bitcoin
2. **API** : Endpoint `/tweaks/1` accessible
3. **Port** : Service écoute sur `0.0.0.0:8000`

## 🚀 Démarrage

### **Ordre de Démarrage**
1. **bitcoin** doit être `healthy`
2. **blindbit-oracle** démarre automatiquement
3. **sdk_relay** attend que blindbit soit `healthy`

### **Commandes de Démarrage**
```bash
# Démarrage complet (recommandé)
./scripts/lecoffre_node/start.sh

# Démarrage spécifique
docker compose --env-file /home/debian/4NK_env/.env.master up -d blindbit
```

## 🔧 Maintenance

### **Logs de Surveillance**
```bash
# Logs en temps réel
docker logs -f blindbit-oracle

# Logs avec progression
./scripts/lecoffre_node/logs-with-progress.sh blindbit
```

### **Redémarrage**
```bash
# Redémarrage du service
docker compose --env-file /home/debian/4NK_env/.env.master restart blindbit

# Redémarrage avec reconstruction
docker compose --env-file /home/debian/4NK_env/.env.master up -d --force-recreate blindbit
```

## 🧪 Tests

### **Test de l'API**
```bash
# Test basique
curl http://localhost:8000/tweaks/1

# Test avec code de retour
curl -s -o /dev/null -w "HTTP Code: %{http_code}\n" http://localhost:8000/tweaks/1
```

### **Vérification des Ports**
```bash
# Ports d'écoute
docker exec blindbit-oracle netstat -tlnp

# Vérification de la configuration
docker exec blindbit-oracle cat /root/.blindbit-oracle/blindbit.toml
```

## 🚨 Dépannage

### **Problèmes Courants**

#### **Service non accessible (HTTP 000)**
- **Cause** : Ancienne image sans correction du bug
- **Solution** : Utiliser l'image `fixed-source`

#### **Configuration non chargée**
- **Cause** : Fichier de configuration manquant ou mal monté
- **Solution** : Vérifier le montage dans docker-compose.yml

#### **Synchronisation lente**
- **Cause** : Première synchronisation ou réseau lent
- **Solution** : Attendre la fin de la synchronisation (visible dans les logs)

### **Logs de Diagnostic**
```bash
# Logs de configuration
docker logs blindbit-oracle | grep -i "host configuration"

# Logs de synchronisation
docker logs blindbit-oracle | grep -i "sync"

# Logs d'erreurs
docker logs blindbit-oracle | grep -i "error"
```

## 📈 Monitoring

### **Métriques Importantes**
1. **Synchronisation** : Progression de la synchronisation avec Bitcoin
2. **API Response Time** : Temps de réponse des endpoints
3. **Memory Usage** : Utilisation mémoire du service
4. **Disk Usage** : Espace disque utilisé par les données

### **Dashboards Grafana**
- **BlindBit Oracle Overview** : Vue d'ensemble du service
- **Synchronization Progress** : Progression de synchronisation
- **API Performance** : Performances de l'API

## 🔄 Mise à Jour

### **Procédure de Mise à Jour**
1. **Arrêt du service** : `docker compose stop blindbit`
2. **Mise à jour de l'image** : `docker pull git.4nkweb.com/4nk/blindbit-oracle:fixed-source`
3. **Redémarrage** : `docker compose up -d blindbit`
4. **Vérification** : Tests de l'API et des logs

### **Sauvegarde des Données**
```bash
# Sauvegarde des données BlindBit
./scripts/lecoffre_node/backup-data.sh

# Restauration des données
./scripts/lecoffre_node/restore-data.sh
```

## 📚 Références

### **Code Source**
- **Repository** : https://github.com/setavenger/blindbit-oracle
- **Image Corrigée** : `git.4nkweb.com/4nk/blindbit-oracle:fixed-source`

### **Documentation Technique**
- **Configuration TOML** : `/home/debian/4NK_env/confs/lecoffre_node/blindbit-oracle/blindbit.toml`
- **Logs** : `/home/debian/4NK_env/logs/blindbit/`
- **Healthcheck** : `/home/debian/4NK_env/scripts/lecoffre_node/healthchecks/blindbit-progress.sh`

---

**Document créé le 2025-09-25**
**Version** : 1.0
**Usage** : Obligatoire pour le déploiement de BlindBit Oracle
**Mise à jour** : Après chaque modification de configuration ou d'image