anchorage_layer_simple/fixKnowledge/dashboard-anchor-wrong-chain-insufficient-balance.md

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.
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 :

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 et MAINTENANCE.md.

4. Vérifier l’alignement chaîne / solde

Sur la machine bitcoin :

./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)