# Dashboard mauvaise chaîne / API d'ancrage "Insufficient Balance" **Auteur** : Équipe 4NK **Date** : 2026-02-02 **Version** : 1.0 ## Symptômes - **Dashboard** (https://dashboard.certificator.4nkweb.com/) : affiche une mauvaise chaîne (hauteur 0, "-", ou valeurs incohérentes) au lieu d’environ 11535 blocs. - **Clients de l’API d’ancrage** : reçoivent `{"error":"Insufficient Balance","message":"Insufficient balance. Required: 0.00001 BTC, Available: 0 BTC"}` et l’API d’ancrage ne fonctionne pas correctement. ## Impacts - Les utilisateurs ne voient pas l’état réel de la blockchain. - L’ancrage de documents échoue (solde 0 côté nœud utilisé par l’API). ## Cause Une seule cause racine couvre les deux symptômes : **le nœud Bitcoin Signet auquel se connectent le Dashboard et l’API d’ancrage n’a pas la bonne chaîne ou n’a pas de solde**. Causes possibles : 1. **Chaîne perdue** : le conteneur `bitcoin-signet-instance` a été recréé **sans volume persistant** (`-v signet-bitcoin-data:/root/.bitcoin`). Le nœud repart sur une nouvelle chaîne (hauteur 0 ou très basse), sans historique de mining → solde 0. Voir [signet-chain-lost-volume-persistent.md](./signet-chain-lost-volume-persistent.md). 2. **Mauvais déploiement** : le Dashboard et/ou l’API d’ancrage tournent sur une **autre machine** (ex. prod 192.168.1.103). Avec `BITCOIN_RPC_HOST=127.0.0.1`, ils appellent alors le RPC de cette machine, où il n’y a pas de nœud Signet (ou un nœud vide) → hauteur 0 ou erreur, solde 0. 3. **Wallet par défaut** : le nœud a la bonne chaîne mais le **wallet par défaut** utilisé par l’API n’est pas celui qui reçoit les récompenses de minage (`custom_signet`) → `getBalance()` retourne 0. ## Correctifs ### 0. Script de correction (machine bitcoin) Sur la machine bitcoin (192.168.1.105), à la racine du projet : ```bash cd /home/ncantu/Bureau/code/bitcoin # Vérifier, redémarrer Dashboard et API d’ancrage, lancer la vérification d’alignement ./fix-dashboard-anchor-chain.sh # Si la chaîne a été perdue, restaurer depuis une sauvegarde puis redémarrer ./fix-dashboard-anchor-chain.sh backups/signet-datadir-YYYYMMDD-HHMMSS.tar.gz ``` Le script teste d'abord la config RPC (même nœud que Mempool) avec `./test-mempool-rpc-config.sh 127.0.0.1 38332`, puis redémarre `signet-dashboard` et `anchorage-api`, lance `verify-chain-alignment.sh`, et affiche le wallet du nœud (solde). **Configuration unique (une seule chaîne pour Mempool, dashboard, APIs, miner) :** Un seul nœud : **bitcoin-signet-instance** sur **38332** (Mempool = host.docker.internal:38332, dashboard/APIs/miner = 127.0.0.1:38332). **Volume par défaut (chaîne complète) :** `update-signet.sh` utilise par défaut le volume contenant la chaîne Signet complète (~11530 blocs) s'il existe : volume Docker d'ID **4b5dca4d940b9f6e5db67b460f40f230a5ef1195a3769e5f91fa02be6edde649** (`SIGNET_VOLUME_FULL_CHAIN` dans le script). Sinon, volume nommé **signet-bitcoin-data**. **Sauvegarde prête à télécharger :** `backups/signet-datadir-latest.tar.gz` (symlink vers la dernière archive créée par `./save-signet-datadir-backup.sh`). **Alignement :** Même machine : `BITCOIN_RPC_HOST=127.0.0.1`, `BITCOIN_RPC_PORT=38332`. Le seul processus sur 38332 doit être le conteneur **bitcoin-signet-instance** (Mempool utilise `host.docker.internal:38332` = ce même conteneur). Vérifier qu’il ne s’agit pas d’un autre Docker : `ss -tlnp | grep 38332` et `docker ps --format '{{.Names}}' | grep bitcoin-signet-instance`. Le miner utilise `BITCOIN_RPC_HOST` / `BITCOIN_RPC_PORT` en env (défaut 127.0.0.1:38332). Tester : `./test-mempool-rpc-config.sh 127.0.0.1 38332`. Vérifier le dashboard : `./verify-dashboard-signet.sh`. ### 1. Vérifier où tournent le Dashboard et l’API d’ancrage - **Dashboard** : doit être sur la **machine bitcoin (192.168.1.105)**. Vérifier le service `signet-dashboard` sur cette machine. - **API d’ancrage** (`anchorage.certificator.4nkweb.com`) : doit être sur la **machine bitcoin (192.168.1.105)**. Vérifier le service `anchorage-api` sur cette machine. Les deux doivent utiliser `BITCOIN_RPC_HOST=127.0.0.1` et `BITCOIN_RPC_PORT=38332` pour parler au nœud local (conteneur sur la même machine). ### 2. Source de vérité : Mempool et utilisateur ncantu **Mempool** (machine bitcoin 192.168.1.105, `/srv/4NK/mempool.4nkweb.com`) se connecte au nœud Signet du même hôte (`host.docker.internal:38332`). Si Mempool affiche la bonne chaîne (~11535 blocs), le nœud utilisé par Mempool sur cette machine a encore la chaîne complète. **Où chercher la chaîne / les sauvegardes (utilisateur ncantu, machine bitcoin 105) :** - **Sauvegarde prête à télécharger** : `backups/signet-datadir-latest.tar.gz` (dernière archive datadir, ~11530 blocs). Créée par `./save-signet-datadir-backup.sh` ; le script met à jour le symlink à chaque sauvegarde. - **Sauvegardes horodatées** : `backups/signet-datadir-YYYYMMDD-HHMMSS.tar.gz`. - **Volume Docker « chaîne complète »** : volume d'ID `4b5dca4d940b9f6e5db67b460f40f230a5ef1195a3769e5f91fa02be6edde649` ; `update-signet.sh` l'utilise par défaut s'il existe (voir docs/MAINTENANCE.md). - **Volume nommé** : après restauration via `restore-signet-from-backup.sh`, le conteneur utilise `signet-bitcoin-data`. Vérifier avec `docker inspect bitcoin-signet-instance` (Mounts). - **Datadir dans le conteneur** : si le conteneur sur 105 n’a jamais été recréé sans volume, les blocs sont dans le conteneur ; faire une sauvegarde avec `save-signet-datadir-backup.sh` ou `docker exec bitcoin-signet-instance tar czf /tmp/bitcoin-backup.tar.gz /root/.bitcoin/` puis `docker cp` vers l’hôte. Pour corriger la machine dont le nœud n’a que quelques blocs (ex. 6) : soit **restaurer** depuis une archive issue de 105 ou de `backups/` sous ncantu, soit **pointer** le Dashboard / l’API d’ancrage vers le RPC du nœud sur 105 (ex. `BITCOIN_RPC_HOST=192.168.1.105`) si l’architecture le permet. ### 3. Restaurer la chaîne si elle a été perdue Si le nœud a une hauteur très basse (ex. 0, 6) ou pas de volume persistant : 1. Sur la machine qui a encore la chaîne ~11535 (ex. machine bitcoin 105, ou là où Mempool affiche la bonne chaîne) : exécuter `./save-signet-datadir-backup.sh`, ou récupérer une archive depuis `/home/ncantu/Bureau/code/bitcoin/backups/` (utilisateur ncantu). 2. Copier l’archive sur la machine à corriger si besoin. 3. Sur la machine à corriger : exécuter `./restore-signet-from-backup.sh backups/signet-datadir-YYYYMMDD-HHMMSS.tar.gz`. 4. Redémarrer le conteneur si nécessaire et vérifier : `sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=$(docker exec bitcoin-signet-instance printenv BITCOIN_DIR 2>/dev/null || echo /root/.bitcoin) getblockchaininfo`. Voir [signet-chain-lost-volume-persistent.md](./signet-chain-lost-volume-persistent.md) et [MAINTENANCE.md](../docs/MAINTENANCE.md). ### 4. Vérifier l’alignement chaîne / solde Sur la machine bitcoin : ```bash ./verify-chain-alignment.sh sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo | grep -E '"chain"|"blocks"' sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo ``` - `chain` doit être `"signet"`, `blocks` proche de 11535. - Le wallet utilisé par défaut (ex. `custom_signet`) doit avoir un solde > 0 après mining. ### 5. Si la chaîne est bonne mais le solde reste 0 Vérifier que le wallet contenant les récompenses de minage est bien celui utilisé par l’API : - Le miner utilise en général le wallet `custom_signet`. - L’API d’ancrage appelle `getBalance()` sans nom de wallet → utilise le **wallet par défaut** du nœud. - Si le nœud a plusieurs wallets, s’assurer que le wallet par défaut est celui qui a du solde (ou charger `custom_signet` au démarrage du nœud comme wallet par défaut). ## Modalités de déploiement - Sur la machine bitcoin : exécuter `./fix-dashboard-anchor-chain.sh` (avec chemin de backup si la chaîne a été perdue). Le script redémarre `signet-dashboard` et `anchorage-api`. - Recréer le conteneur Bitcoin via `./update-signet.sh` : le script utilise par défaut le volume chaîne complète (ID `4b5dca4d940b9f6e5db67b460f40f230a5ef1195a3769e5f91fa02be6edde649`) s'il existe, sinon `signet-bitcoin-data`. Ne pas recréer manuellement sans volume persistant. - Sauvegarde prête à télécharger : `backups/signet-datadir-latest.tar.gz` (créée par `./save-signet-datadir-backup.sh`). ## Modalités d’analyse - Consulter les logs du Dashboard : `sudo journalctl -u signet-dashboard -f` (erreurs RPC). - Consulter les logs de l’API d’ancrage : `sudo journalctl -u anchorage-api -f` (erreurs "Insufficient balance", connexion RPC). - Vérifier la hauteur et le wallet sur le nœud : commandes ci-dessus. ## Pages affectées - fixKnowledge/dashboard-anchor-wrong-chain-insufficient-balance.md (ce fichier) - fixKnowledge/signet-chain-lost-volume-persistent.md (volume chaîne complète, sauvegarde latest) - update-signet.sh (SIGNET_VOLUME_FULL_CHAIN, utilisation par défaut du volume chaîne complète) - save-signet-datadir-backup.sh (symlink signet-datadir-latest.tar.gz, tolérance tar exit 1) - backups/README.md (sauvegarde prête à télécharger, volume par défaut) - docs/MAINTENANCE.md (volume chaîne complète, sauvegarde latest) - test-mempool-rpc-config.sh (test de la config RPC utilisée par Mempool) - verify-dashboard-signet.sh (vérification que le dashboard affiche le signet custom) - fix-dashboard-anchor-chain.sh (script de correction sur la machine bitcoin) - signet-dashboard.service, anchorage-api.service, faucet-api.service (alignement RPC sur le même nœud que Mempool) - signet-dashboard/public/app.js (vérification response.ok et alerte chaîne anormale)