From a6b73f57e6b1ed7aaaa52032a45e7d06dc2f502f Mon Sep 17 00:00:00 2001
From: Nicolas Cantu <nicolas.cantu@pm.me>
Date: Wed, 10 Sep 2025 18:43:35 +0200
Subject: [PATCH] Documentation: Diagnostic Bitcoin Core et corrections
 appliquees

- Creation docs/BITCOIN_TROUBLESHOOTING.md
- Documentation des problemes identifies et solutions
- Repertoire wallets manquant: cree avec permissions correctes
- Mode debug desactive pour stabilite
- Configuration RPC signet documentee
- Dependances docker-compose corrigees
- Etat actuel des services et problemes persistants
- Commandes utiles pour diagnostic
---
 docs/BITCOIN_TROUBLESHOOTING.md | 145 ++++++++++++++++++++++++++++++++
 1 file changed, 145 insertions(+)
 create mode 100644 docs/BITCOIN_TROUBLESHOOTING.md

diff --git a/docs/BITCOIN_TROUBLESHOOTING.md b/docs/BITCOIN_TROUBLESHOOTING.md
new file mode 100644
index 00000000..06db9de7
--- /dev/null
+++ b/docs/BITCOIN_TROUBLESHOOTING.md
@@ -0,0 +1,145 @@
+# Diagnostic et résolution des problèmes Bitcoin Core
+
+## Problèmes identifiés et solutions appliquées
+
+### 1. Répertoire wallets manquant
+
+**Problème** : Bitcoin Core ne peut pas démarrer car le répertoire `/home/bitcoin/.bitcoin/wallets` n'existe pas.
+
+**Erreur** :
+```
+Error: Specified -walletdir "/home/bitcoin/.bitcoin/wallets" does not exist
+```
+
+**Solution appliquée** :
+```bash
+sudo mkdir -p modules/bitcoin/data/wallets
+sudo chown -R 101:101 modules/bitcoin/data/wallets
+```
+
+### 2. Mode debug problématique
+
+**Problème** : Le mode debug (`debug=1`, `loglevel=debug`) génère trop de logs et peut causer des instabilités.
+
+**Solution appliquée** :
+```ini
+#debug=1
+#loglevel=debug
+```
+
+### 3. Configuration RPC signet
+
+**Configuration finale** :
+```ini
+[signet]
+listen=1
+bind=bitcoin.local:38333
+rpcbind=bitcoin.local:18443
+rpcport=18443
+fallbackfee=0.0001
+blockfilterindex=1
+datacarriersize=205
+acceptnonstdtxn=1
+dustrelayfee=0.00000001
+minrelaytxfee=0.00000001
+prune=0
+signetchallenge=0020341c43803863c252df326e73574a27d7e19322992061017b0dc893e2eab90821
+walletdir=/home/bitcoin/.bitcoin/wallets
+wallet=mining
+wallet=watchonly
+maxtxfee=1
+addnode=tlv2yqamflv22vfdzy2hha2nwmt6zrwrhjjzz4lx7qyq7lyc6wfhabyd.onion
+```
+
+### 4. Dépendances Docker Compose
+
+**Problème** : Service `blindbit-oracle` dépendait de `bitcoin.local` au lieu de `bitcoin`.
+
+**Solution appliquée** :
+```yaml
+depends_on:
+  - bitcoin  # au lieu de bitcoin.local
+```
+
+### 5. Configuration réseau Docker
+
+**Réseau autorisé pour RPC** :
+```ini
+rpcallowip=172.20.0.0/16
+```
+
+**Réseau Docker 4NK** :
+```yaml
+networks:
+  4nk_network:
+    driver: bridge
+    ipam:
+      config:
+        - subnet: 172.20.0.0/16
+```
+
+## État actuel des services
+
+### Services stables
+- ✅ **4nk-tor** : Up (health: starting)
+- ✅ **4nk-sdk-storage** : Up (health: starting)
+- ✅ **4nk-sdk-signer** : Up (health: starting)
+- ✅ **4nk-ihm-client** : Up (health: starting)
+- ✅ **coffre-front** : Up
+- ✅ **miniback-postgres** : Up
+
+### Services en redémarrage
+- ⚠️ **bitcoin.local** : Restarting (1)
+- ⚠️ **blindbit-oracle.local** : Restarting (1)
+- ⚠️ **4nk-sdk-relay1** : Restarting (1)
+- ⚠️ **4nk-sdk-relay2** : Restarting (1)
+- ⚠️ **4nk-sdk-relay3** : Restarting (1)
+- ⚠️ **coffre-back-mini** : Restarting (1)
+
+## Problèmes persistants
+
+### Bitcoin Core redémarre en boucle
+
+**Symptômes** :
+- Bitcoin Core se ferme proprement (`Shutdown: done`)
+- Le conteneur redémarre immédiatement
+- Cycle de redémarrage continu
+
+**Causes possibles** :
+1. **Configuration Tor** : `onion=tor:9050` pourrait causer des problèmes de connectivité
+2. **Configuration signet** : Paramètres signet incompatibles
+3. **Problème de réseau** : Conflit avec la configuration réseau Docker
+4. **Configuration wallets** : Wallets `mining` et `watchonly` problématiques
+
+### Services dépendants instables
+
+Les services qui dépendent de Bitcoin Core (blindbit-oracle, sdk-relay*) redémarrent également car ils ne peuvent pas se connecter à l'API RPC Bitcoin.
+
+## Recommandations
+
+1. **Investigation approfondie** : Analyser les logs Bitcoin Core pour identifier la cause racine des redémarrages
+2. **Configuration simplifiée** : Tester avec une configuration Bitcoin minimale
+3. **Tests de connectivité** : Vérifier la connectivité réseau entre les conteneurs
+4. **Documentation** : Maintenir ce document à jour avec les nouvelles découvertes
+
+## Commandes utiles
+
+```bash
+# Vérifier les logs Bitcoin
+docker-compose logs bitcoin
+
+# Vérifier le statut des services
+docker-compose ps
+
+# Redémarrer Bitcoin uniquement
+docker-compose restart bitcoin
+
+# Vérifier les permissions
+ls -la modules/bitcoin/data/
+```
+
+---
+
+**Date de création** : 2025-09-10  
+**Dernière mise à jour** : 2025-09-10  
+**Statut** : En cours de diagnostic