anchorage_layer_simple/docs/MAINTENANCE.md

Documentation de Maintenance - Bitcoin Signet Custom

Auteur : Équipe 4NK Date : 2026-01-09 Version : 1.0

Table des Matières

1. Vue d'Ensemble
2. Architecture
3. Configuration
4. Commandes de Maintenance
5. Gestion du Conteneur
6. Gestion des Clés et du Signet
7. Mining
8. Accès RPC et API
9. Mise à Jour
10. Dépannage
11. Modifications Apportées
12. Sauvegarde et Restauration

---

Vue d'Ensemble

Ce projet installe et configure un Bitcoin Signet custom basé sur le dépôt Easepay/easepay-custom-signet.

Un Signet est un réseau de test Bitcoin qui permet de tester des applications Bitcoin sans risquer de fonds réels et sans l'imprévisibilité du testnet public.

Caractéristiques

• Version Bitcoin Core : 30.2
• Type de Wallet : Descriptor wallets (legacy wallets non supportés depuis Bitcoin Core 30+)
• Réseau : Signet custom
• Mining : Activé avec délai configurable
• Containerisation : Docker
• Base OS : Debian Bookworm

---

Architecture

Structure des Fichiers

bitcoin/
├── Dockerfile                 # Image Docker avec Bitcoin Core
├── docker-entrypoint.sh       # Point d'entrée du conteneur
├── install.sh                 # Script d'installation initiale
├── run.sh                     # Script de démarrage du nœud
├── setup-signet.sh            # Configuration du signet
├── gen-signet-keys.sh         # Génération des clés du signet
├── gen-bitcoind-conf.sh       # Génération de bitcoin.conf
├── mine.sh                    # Script de mining
├── mine-genesis.sh            # Mining du bloc genesis
├── logtail.sh                 # Visualisation des logs
├── rpcauth.py                 # Génération d'authentification RPC
├── miner                       # Script Python de mining
├── miner_imports/             # Imports pour le miner
├── .env                       # Variables d'environnement
├── env.example                # Exemple de configuration
└── docs/                      # Documentation

Ports Exposés

Port	Protocole	Service	Description
3010	HTTP/HTTPS	API REST	API d'ancrage (via nginx) - Port fixe
3015	HTTP/HTTPS	Web	Mempool (explorateur blockchain)
3020	HTTP/HTTPS	Web	Dashboard de supervision - Port fixe
3021	HTTP/HTTPS	API REST	API Faucet - Port fixe
3022	HTTP/HTTPS	API REST	API Filigrane - Port fixe
3023	HTTP/HTTPS	API REST	API ClamAV (antivirus) - Port fixe
38332	TCP	RPC	Interface JSON-RPC pour contrôler le nœud
38333	TCP/UDP	P2P	Réseau peer-to-peer Bitcoin Signet
28332	TCP	ZMQ	Publication des blocs bruts
28333	TCP	ZMQ	Publication des transactions brutes
28334	TCP	ZMQ	Publication des hash de blocs
8999	HTTP	API REST	Mempool Backend API (interne)

Note : Les ports des APIs (3010, 3020, 3021, 3022, 3023) sont fixes et définis dans les services systemd. Voir DOMAINS_AND_PORTS.md pour plus de détails.

Répertoires Importants dans le Conteneur

• /root/.bitcoin/ : Répertoire de données Bitcoin
  • signet/ : Données de la chaîne signet
  • bitcoin.conf : Configuration du nœud (générée par gen-bitcoind-conf.sh ; référence : SIGNET-CUSTOM-CONFIG.md)
  • PRIVKEY.txt : Clé privée du signer
  • SIGNETCHALLENGE.txt : Challenge du signet
  • MAGIC.txt : Magic number du réseau
  • install_done : Marqueur d'installation complète

---

Configuration

Fichier .env

Le fichier .env contient toutes les variables de configuration nécessaires au fonctionnement du signet.

Variables de Mining

# Délai entre la génération de chaque bloc (en secondes)
BLOCKPRODUCTIONDELAY=600

# Activer le mining (1 = activé, 0 = désactivé)
MINERENABLED=1

# Difficulté minimale pour le mining (format hexadécimal)
NBITS=1e0377ae

# Clé privée du signer (générée automatiquement si vide)
PRIVKEY=cVCKcgQf2ewV5miairzhrHJCPv4kMbMMBZeJvW5SMhFMSWVtCvXS

# Adresse de minage (générée automatiquement si vide)
MINETO=

# Challenge du signet (généré automatiquement si vide)
SIGNETCHALLENGE=5121028b8d4cea1b3d8582babc8405bc618fbbb281c0f64e6561aa85968251931cd0a651ae

Variables RPC

# Utilisateur RPC
RPCUSER=bitcoin

# Mot de passe RPC
RPCPASSWORD=bitcoin

Variables ZMQ

# Publication des blocs bruts
ZMQPUBRAWBLOCK=tcp://0.0.0.0:28332

# Publication des transactions brutes
ZMQPUBRAWTX=tcp://0.0.0.0:28333

# Publication des hash de blocs
ZMQPUBHASHBLOCK=tcp://0.0.0.0:28334

Variables Réseau

# Commentaire User-Agent
UACOMMENT=CustomSignet

# Binding RPC
RPCBIND=0.0.0.0:38332

# IPs autorisées pour RPC
RPCALLOWIP=0.0.0.0/0

# IPs whitelistées
WHITELIST=0.0.0.0/0

# Nœuds à ajouter (séparés par des virgules)
ADDNODE=

# IP externe (pour l'annonce publique)
EXTERNAL_IP=

Génération des Clés

Les clés sont générées automatiquement lors de la première installation si PRIVKEY et SIGNETCHALLENGE sont vides dans le .env.

Important : Une fois générées, ces clés doivent être conservées et partagées avec les autres nœuds qui souhaitent rejoindre le même signet.

---

Commandes de Maintenance

Vérification de l'État

# Vérifier que le conteneur est en cours d'exécution
sudo docker ps | grep bitcoin-signet

# Vérifier l'état de la blockchain
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo

# Vérifier l'état du réseau
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo

# Vérifier l'état du wallet
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo

# Vérifier les processus en cours
sudo docker exec bitcoin-signet-instance ps aux | grep -E "(bitcoind|mine)"

Logs

# Voir les logs en temps réel
sudo docker logs -f bitcoin-signet-instance

# Voir les derniers logs
sudo docker logs bitcoin-signet-instance --tail 50

# Voir les logs de debug Bitcoin
sudo docker exec bitcoin-signet-instance tail -f /root/.bitcoin/signet/debug.log

Accès au Conteneur

# Accéder au shell du conteneur
sudo docker exec -it bitcoin-signet-instance bash

# Exécuter bitcoin-cli depuis l'hôte
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin <commande>

---

Gestion du Conteneur

Persistance du datadir (chaîne Bitcoin)

Important : Sans volume persistant, la recréation du conteneur (docker rm puis docker run) supprime les données Bitcoin et le nœud repart sur une nouvelle chaîne (hauteur 0). Pour conserver la chaîne (ex. hauteur ~11530), utilisez toujours un volume persistant.

Volume par défaut (chaîne complète) : Le script update-signet.sh utilise par défaut le volume contenant la chaîne Signet complète (~11530 blocs) s'il existe sur la machine : volume Docker d'ID 4b5dca4d940b9f6e5db67b460f40f230a5ef1195a3769e5f91fa02be6edde649 (variable SIGNET_VOLUME_FULL_CHAIN dans le script). Ainsi, après une mise à jour ou un redémarrage via update-signet.sh, le nœud repart sur la bonne chaîne sans recherche. Si ce volume n'existe pas, le script utilise le volume nommé signet-bitcoin-data.

• Volume « chaîne complète » (prioritaire si présent) : ID 4b5dca4d940b9f6e5db67b460f40f230a5ef1195a3769e5f91fa02be6edde649
• Volume nommé (sinon) : -v signet-bitcoin-data:/root/.bitcoin
• Montage host : -v /chemin/sur/hote/signet-data:/root/.bitcoin (créer le répertoire avant)

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). À utiliser pour restaurer la chaîne sur une autre machine ou après perte du volume. Voir Sauvegarde et Restauration.

Les commandes docker run ci-dessous utilisent le volume approprié (voir update-signet.sh pour la logique par défaut).

Démarrage

cd /home/ncantu/Bureau/code/bitcoin
sudo docker run --env-file .env -d \
  --name bitcoin-signet-instance \
  -v signet-bitcoin-data:/root/.bitcoin \
  -p 38332:38332 \
  -p 38333:38333 \
  -p 28332:28332 \
  -p 28333:28333 \
  -p 28334:28334 \
  bitcoin-signet

Arrêt

# Arrêter le conteneur
sudo docker stop bitcoin-signet-instance

# Arrêter et supprimer le conteneur
sudo docker stop bitcoin-signet-instance && sudo docker rm bitcoin-signet-instance

Redémarrage

# Redémarrer le conteneur
sudo docker restart bitcoin-signet-instance

# Redémarrer après modification du .env
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance
sudo docker run --env-file .env -d --name bitcoin-signet-instance \
  -v signet-bitcoin-data:/root/.bitcoin \
  -p 38332:38332 -p 38333:38333 -p 28332:28332 -p 28333:28333 -p 28334:28334 \
  bitcoin-signet

Reconstruction de l'Image

cd /home/ncantu/Bureau/code/bitcoin
sudo docker build -t bitcoin-signet .

---

Gestion des Clés et du Signet

Récupération des Clés Générées

# Récupérer la clé privée
sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/PRIVKEY.txt

# Récupérer le challenge du signet
sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/SIGNETCHALLENGE.txt

# Récupérer le magic number
sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/MAGIC.txt

Mise à Jour du .env avec les Clés

# Mettre à jour PRIVKEY dans .env
PRIVKEY=$(sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/PRIVKEY.txt)
sed -i "s/^PRIVKEY=.*/PRIVKEY=$PRIVKEY/" .env

# Mettre à jour SIGNETCHALLENGE dans .env
SIGNETCHALLENGE=$(sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/SIGNETCHALLENGE.txt)
sed -i "s/^SIGNETCHALLENGE=.*/SIGNETCHALLENGE=$SIGNETCHALLENGE/" .env

Partage du Signet avec d'Autres Nœuds

Pour qu'un autre nœud rejoigne le même signet, il doit avoir dans son .env :

1. Le même SIGNETCHALLENGE
2. Le même PRIVKEY (si mining activé)
3. L'adresse IP du nœud dans ADDNODE (ex: ADDNODE=192.168.1.100:38333)

---

Mining

Configuration du Mining

Le mining est contrôlé par les variables suivantes dans .env :

• MINERENABLED=1 : Active le mining
• BLOCKPRODUCTIONDELAY=600 : Délai en secondes entre chaque bloc (600 = 10 minutes)
• NBITS=1e0377ae : Difficulté minimale (ne pas modifier sauf nécessité)
• MINETO= : Adresse de minage (vide = nouvelle adresse par bloc)
• PRIVKEY : Clé privée du signer (importée automatiquement dans le descriptor wallet)

Note Bitcoin Core 30+ : La PRIVKEY est automatiquement importée dans le descriptor wallet au démarrage via importdescriptors. Cette importation est nécessaire car le miner utilise walletprocesspsbt pour signer les blocs, ce qui nécessite que la clé soit dans le wallet.

Modification Dynamique du Délai

Pour modifier le délai de production de blocs sans redémarrer :

# Modifier le délai à 60 secondes (1 minute)
sudo docker exec bitcoin-signet-instance bash -c "echo 60 > /root/.bitcoin/BLOCKPRODUCTIONDELAY.txt"

Le script mine.sh lit automatiquement ce fichier s'il existe.

Vérification du Mining

# Vérifier que le script de mining est actif
sudo docker exec bitcoin-signet-instance ps aux | grep mine.sh

# Voir les logs de mining
sudo docker logs bitcoin-signet-instance | grep -E "(Mine|Delay|block)"

# Vérifier le dernier bloc miné
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getbestblockhash

Arrêt du Mining

Pour arrêter le mining, modifier .env :

MINERENABLED=0

Puis redémarrer le conteneur.

---

Maintenance des Services Systemd

Services Disponibles

Tous les services APIs sont gérés par systemd avec redémarrage automatique :

Service	Description	Port	Fichier de Service
anchorage-api	API d'Ancrage	3010	api-anchorage/anchorage-api.service
signet-dashboard	Dashboard	3020	signet-dashboard/signet-dashboard.service
faucet-api	API Faucet	3021	api-faucet/faucet-api.service
filigrane-api	API Filigrane	3022	api-filigrane/filigrane-api.service
clamav-api	API ClamAV	3023	api-clamav/clamav-api.service

Installation des Services

# Installer tous les services
sudo cp api-anchorage/anchorage-api.service /etc/systemd/system/
sudo cp signet-dashboard/signet-dashboard.service /etc/systemd/system/
sudo cp api-faucet/faucet-api.service /etc/systemd/system/
sudo cp api-filigrane/filigrane-api.service /etc/systemd/system/
sudo cp api-clamav/clamav-api.service /etc/systemd/system/

# Recharger systemd
sudo systemctl daemon-reload

# Activer les services (démarrage automatique au boot)
sudo systemctl enable anchorage-api
sudo systemctl enable signet-dashboard
sudo systemctl enable faucet-api
sudo systemctl enable filigrane-api
sudo systemctl enable clamav-api

# Démarrer les services
sudo systemctl start anchorage-api
sudo systemctl start signet-dashboard
sudo systemctl start faucet-api
sudo systemctl start filigrane-api
sudo systemctl start clamav-api

Gestion des Services

# Vérifier le statut d'un service
sudo systemctl status <service-name>

# Démarrer un service
sudo systemctl start <service-name>

# Arrêter un service
sudo systemctl stop <service-name>

# Redémarrer un service
sudo systemctl restart <service-name>

# Voir les logs en temps réel
sudo journalctl -u <service-name> -f

# Voir les derniers logs
sudo journalctl -u <service-name> -n 100

# Voir les logs depuis une date
sudo journalctl -u <service-name> --since "2026-01-24 10:00:00"

Vérification de Tous les Services

# Vérifier le statut de tous les services
sudo systemctl status anchorage-api signet-dashboard faucet-api filigrane-api clamav-api

# Vérifier que tous les ports sont en écoute
sudo ss -tlnp | grep -E ':(3010|3020|3021|3022|3023)'

# Tester les endpoints de santé
curl http://localhost:3010/health
curl http://localhost:3020/health
curl http://localhost:3021/health
curl http://localhost:3022/health
curl http://localhost:3023/health

Redémarrage Automatique

Tous les services sont configurés avec Restart=always et RestartSec=10, ce qui signifie :

• Redémarrage automatique en cas d'échec
• Délai de 10 secondes avant redémarrage
• Redémarrage au boot du système

Ports Fixes

Important : Tous les ports sont fixes et définis dans les services systemd :

• Les ports ne peuvent pas être modifiés sans modifier les services
• Les variables d'environnement dans les services ont priorité sur les fichiers .env
• Voir DOMAINS_AND_PORTS.md pour plus de détails

Mise à Jour d'un Service

# 1. Arrêter le service
sudo systemctl stop <service-name>

# 2. Mettre à jour le code (via git, etc.)
cd /home/ncantu/Bureau/code/bitcoin/<api-directory>
git pull

# 3. Installer les dépendances si nécessaire
npm install

# 4. Redémarrer le service
sudo systemctl start <service-name>

# 5. Vérifier les logs
sudo journalctl -u <service-name> -f

Dépannage des Services

# Si un service ne démarre pas
# 1. Vérifier les logs
sudo journalctl -u <service-name> -n 50

# 2. Vérifier que le port n'est pas déjà utilisé
sudo ss -tlnp | grep :<port>

# 3. Vérifier les permissions
ls -la /home/ncantu/Bureau/code/bitcoin/<api-directory>

# 4. Vérifier que Node.js est installé
which node
node --version

# 5. Tester manuellement
cd /home/ncantu/Bureau/code/bitcoin/<api-directory>
./start.sh

Logs et Monitoring

# Voir tous les logs de tous les services
sudo journalctl -u anchorage-api -u signet-dashboard -u faucet-api -u filigrane-api -u clamav-api -f

# Voir les erreurs uniquement
sudo journalctl -u <service-name> -p err

# Exporter les logs
sudo journalctl -u <service-name> --since "2026-01-24" > logs-<service-name>.txt

Pour plus de détails sur les domaines, ports et configuration, voir :

• DOMAINS_AND_PORTS.md
• ENVIRONMENT.md

---

Accès RPC et API

Commandes RPC Courantes

# Obtenir des informations sur la blockchain
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo

# Obtenir des informations sur le réseau
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo

# Obtenir des informations sur le wallet
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo

# Obtenir le solde
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getbalance

# Obtenir une nouvelle adresse
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnewaddress

# Obtenir la liste des transactions
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin listtransactions

# Obtenir le dernier bloc
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getbestblockhash

# Obtenir un bloc spécifique
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblock <hash>

Accès RPC depuis l'Extérieur

Pour accéder au RPC depuis un autre hôte, utiliser :

bitcoin-cli -rpcconnect=<IP_DU_SERVEUR> -rpcport=38332 \
  -rpcuser=bitcoin -rpcpassword=bitcoin \
  getblockchaininfo

Sécurité : En production, restreindre RPCALLOWIP dans .env et utiliser une authentification plus forte.

ZMQ

Les notifications ZMQ sont disponibles sur les ports 28332, 28333, 28334.

Exemple avec Python :

import zmq

context = zmq.Context()
socket = context.socket(zmq.SUB)
socket.connect("tcp://localhost:28332")
socket.setsockopt(zmq.SUBSCRIBE, b"rawblock")

while True:
    message = socket.recv()
    print(f"New block: {message.hex()}")

---

Mise à Jour

Script de Mise à Jour Automatique

Un script de mise à jour automatique est disponible : update-signet.sh

Utilisation

# Mise à jour vers la dernière version disponible
./update-signet.sh

# Mise à jour vers une version spécifique
./update-signet.sh 30.2

# Aide
./update-signet.sh --help

Fonctionnalités du Script

Le script update-signet.sh effectue automatiquement :

1. Vérification des prérequis : Docker, fichier .env
2. Détection de la version actuelle : Depuis .bitcoin-version ou le Dockerfile
3. Récupération de la dernière version : Depuis les sources officielles Bitcoin
4. Sauvegarde automatique : Données du conteneur et fichier .env
5. Mise à jour du Dockerfile : Modification de la version Bitcoin Core
6. Reconstruction de l'image : Build de la nouvelle image Docker
7. Redémarrage du conteneur : Arrêt propre et redémarrage avec la nouvelle version (volume signet-bitcoin-data pour une seule chaîne Mempool/dashboard/APIs)
8. Vérification post-mise à jour : Contrôle de l'état du nœud

Procédure Manuelle de Mise à Jour

Si vous préférez effectuer la mise à jour manuellement :

1. Vérifier la Version Actuelle

# Version dans le Dockerfile
grep BITCOIN_VERSION Dockerfile

# Version enregistrée
cat .bitcoin-version 2>/dev/null || echo "Non enregistrée"

# Version en cours d'exécution
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo | grep subversion

2. Récupérer la Dernière Version

Consultez les sources officielles :

• Bitcoin Core Releases
• GitHub Releases

3. Sauvegarder les Données

# Créer un répertoire de sauvegarde
mkdir -p backups

# Sauvegarder les données du conteneur
sudo docker exec bitcoin-signet-instance tar czf /tmp/bitcoin-backup.tar.gz /root/.bitcoin/
sudo docker cp bitcoin-signet-instance:/tmp/bitcoin-backup.tar.gz backups/signet-backup-$(date +%Y%m%d-%H%M%S).tar.gz

# Sauvegarder le .env
cp .env backups/.env.backup-$(date +%Y%m%d-%H%M%S)

4. Mettre à Jour le Dockerfile

# Modifier la version dans le Dockerfile
sed -i 's/ARG BITCOIN_VERSION=\${BITCOIN_VERSION:-[0-9]\+\.[0-9]\+}/ARG BITCOIN_VERSION=${BITCOIN_VERSION:-30.2}/' Dockerfile

# Vérifier la modification
grep BITCOIN_VERSION Dockerfile

5. Reconstruire l'Image

# Reconstruire l'image Docker
sudo docker build -t bitcoin-signet .

6. Redémarrer le Conteneur

# Arrêter le conteneur actuel
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance

# Démarrer avec la nouvelle image (volume persistant pour conserver la chaîne)
sudo docker run --env-file .env -d \
  --name bitcoin-signet-instance \
  -v signet-bitcoin-data:/root/.bitcoin \
  -p 38332:38332 \
  -p 38333:38333 \
  -p 28332:28332 \
  -p 28333:28333 \
  -p 28334:28334 \
  bitcoin-signet

7. Vérifier la Mise à Jour

# Attendre quelques secondes pour le démarrage
sleep 10

# Vérifier la version
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo | grep subversion

# Vérifier l'état de la blockchain
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo

# Vérifier les logs
sudo docker logs bitcoin-signet-instance --tail 50

8. Enregistrer la Version

# Enregistrer la nouvelle version
echo "30.2" > .bitcoin-version

Notes Importantes sur les Mises à Jour

Compatibilité des Versions

• Bitcoin Core 26.0+ : Peut avoir des changements de compatibilité avec les wallets legacy
• Bitcoin Core 30.2 : Version actuelle recommandée
• Vérifiez toujours les release notes avant de mettre à jour

Impact sur le Mining

• Le mining reprend automatiquement après la mise à jour
• Les blocs minés avant la mise à jour restent valides
• Aucune perte de données si la sauvegarde est effectuée

Rollback en Cas de Problème

Si la mise à jour pose problème :

# Restaurer l'ancienne version du Dockerfile
git checkout HEAD -- Dockerfile

# Restaurer les données si nécessaire
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance
sudo docker cp backups/signet-backup-YYYYMMDD-HHMMSS.tar.gz bitcoin-signet-instance:/tmp/
sudo docker exec bitcoin-signet-instance tar xzf /tmp/signet-backup-YYYYMMDD-HHMMSS.tar.gz -C /

# Reconstruire avec l'ancienne version
sudo docker build -t bitcoin-signet .

# Redémarrer (volume persistant pour conserver la chaîne)
sudo docker run --env-file .env -d --name bitcoin-signet-instance \
  -v signet-bitcoin-data:/root/.bitcoin \
  -p 38332:38332 -p 38333:38333 -p 28332:28332 -p 28333:28333 -p 28334:28334 \
  bitcoin-signet

Vérification Régulière des Mises à Jour

Pour vérifier régulièrement si une nouvelle version est disponible :

# Script de vérification
#!/bin/bash
CURRENT=$(cat .bitcoin-version 2>/dev/null || echo "unknown")
LATEST=$(curl -s https://bitcoincore.org/bin/ | grep -oP 'bitcoin-core-\K[0-9]+\.[0-9]+\.[0-9]+' | sort -V | tail -1)

if [ "$CURRENT" != "$LATEST" ]; then
    echo "Nouvelle version disponible: $LATEST (actuelle: $CURRENT)"
    echo "Exécutez: ./update-signet.sh $LATEST"
else
    echo "Déjà à jour: $CURRENT"
fi

---

Dépannage

Problèmes Courants

Le conteneur ne démarre pas

# Vérifier les logs
sudo docker logs bitcoin-signet-instance

# Vérifier que les ports ne sont pas déjà utilisés
sudo netstat -tlnp | grep -E "(38332|38333|28332|28333|28334)"

# Vérifier que le fichier .env existe
ls -la .env

Bitcoind ne démarre pas

# Vérifier les logs de debug
sudo docker exec bitcoin-signet-instance tail -100 /root/.bitcoin/signet/debug.log

# Vérifier la configuration
sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/bitcoin.conf

# Vérifier les permissions
sudo docker exec bitcoin-signet-instance ls -la /root/.bitcoin/

Le mining ne fonctionne pas

# Vérifier que MINERENABLED=1 dans .env
grep MINERENABLED .env

# Vérifier que la clé privée est importée
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin listprivkeys

# Vérifier que le script mine.sh est actif
sudo docker exec bitcoin-signet-instance ps aux | grep mine.sh

Erreur "Cannot obtain a lock"

Cette erreur indique qu'un autre processus bitcoind est déjà en cours d'exécution.

# Arrêter tous les processus bitcoind dans le conteneur
sudo docker exec bitcoin-signet-instance pkill bitcoind

# Redémarrer le conteneur
sudo docker restart bitcoin-signet-instance

Le wallet n'existe pas

# Créer le wallet manuellement (Bitcoin Core 30+ nécessite descriptor wallets)
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin \
  -named createwallet wallet_name="custom_signet" load_on_startup=true descriptors=true

# Charger le wallet si nécessaire
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin loadwallet custom_signet

# Importer la clé privée si mining activé (Bitcoin Core 30+ nécessite descriptor wallets)
PRIVKEY=$(cat .env | grep PRIVKEY | cut -d'=' -f2)
DESCRIPTOR_INFO=$(sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getdescriptorinfo "wpkh($PRIVKEY)")
CHECKSUM=$(echo "$DESCRIPTOR_INFO" | jq -r '.checksum')
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin \
  importdescriptors "[{\"desc\":\"wpkh($PRIVKEY)#$CHECKSUM\",\"timestamp\":0,\"internal\":false}]"

Réinitialisation Complète

Si vous devez tout réinitialiser :

# Arrêter et supprimer le conteneur
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance

# Supprimer le volume de données (ATTENTION : perte de données)
sudo docker volume rm $(sudo docker volume ls -q | grep bitcoin)

# Ou supprimer manuellement les données
sudo rm -rf /var/lib/docker/volumes/*/bitcoin-signet-instance/_data

# Relancer avec un nouveau .env (clés seront régénérées ; utiliser un nouveau volume ou supprimer signet-bitcoin-data avant)
sudo docker run --env-file .env -d --name bitcoin-signet-instance \
  -v signet-bitcoin-data:/root/.bitcoin \
  -p 38332:38332 -p 38333:38333 -p 28332:28332 -p 28333:28333 -p 28334:28334 \
  bitcoin-signet

---

Modifications Apportées

Modifications du Dockerfile

1. Mise à jour de Debian : buster-slim → bookworm-slim

   • Raison : Debian Buster n'est plus supporté

2. Détection automatique de l'architecture : Remplacement de TARGETPLATFORM par uname -m

   • Raison : TARGETPLATFORM n'est pas défini par défaut dans docker build

3. Installation de setuptools : Via apt au lieu de pip

   • Raison : PEP 668 empêche l'installation système via pip

Modifications des Scripts

1. gen-signet-keys.sh :

   • Correction de ATADIR → DATADIR (ligne 1)
   • Mise à jour pour utiliser descriptors=true (Bitcoin Core 30+)
   • Raison : Faute de frappe empêchait la création du répertoire temporaire, et Bitcoin Core 30+ nécessite des descriptor wallets

2. setup-signet.sh : Suppression du démarrage de bitcoind

   • Raison : Éviter les conflits de verrou, bitcoind est démarré par run.sh

3. run.sh : Ajout de la création du wallet descriptor et import automatique de la clé privée

   • Raison : Le wallet doit être créé après le démarrage de bitcoind
   • Bitcoin Core 30+ nécessite des descriptor wallets (legacy wallets non supportés)
   • La clé privée est importée automatiquement dans le descriptor wallet pour permettre le mining
   • L'import utilise importdescriptors avec le checksum requis (obtenu via getdescriptorinfo)
   • Le miner utilise walletprocesspsbt qui nécessite que la clé soit dans le wallet

---

Sauvegarde et Restauration

Sauvegarde

Sauvegarde datadir (chaîne complète, prête à télécharger) :

# Créer une archive complète du datadir (blocs + chainstate + config)
./save-signet-datadir-backup.sh
# Crée backups/signet-datadir-YYYYMMDD-HHMMSS.tar.gz et met à jour le symlink :
# backups/signet-datadir-latest.tar.gz -> dernière archive (prête à télécharger)

Le symlink backups/signet-datadir-latest.tar.gz pointe toujours vers la dernière archive créée ; utile pour téléchargement ou restauration rapide : ./restore-signet-from-backup.sh backups/signet-datadir-latest.tar.gz.

Export wallet de minage (réimportable, pour retrouver les fonds sur cette chaîne) :

./export-mining-wallet.sh
# Crée backups/mining-wallet-export-YYYYMMDD-HHMMSS.json et mining-wallet-export-latest.json
# Contient : PRIVKEY, SIGNETCHALLENGE, wallet_name, descriptors avec clés privées, infos chaîne

# Réimporter sur un nœud avec la même chaîne :
./import-mining-wallet.sh backups/mining-wallet-export-latest.json

Export quotidien vers git (2 versions conservées) :

# Tâche cron quotidienne : exporte signet-datadir et mining-wallet vers
# https://git.4nkweb.com/4nk/backup (2 versions max de chaque)
./data/backup-to-git-cron.sh
# Voir features/backup-to-git-daily-cron.md pour configuration cron

Sauvegarde manuelle :

# Sauvegarder les données Bitcoin
sudo docker exec bitcoin-signet-instance tar czf /tmp/bitcoin-backup.tar.gz /root/.bitcoin/

# Copier la sauvegarde hors du conteneur
sudo docker cp bitcoin-signet-instance:/tmp/bitcoin-backup.tar.gz ./bitcoin-backup-$(date +%Y%m%d).tar.gz

# Sauvegarder le fichier .env
cp .env .env.backup-$(date +%Y%m%d)

Restauration

# Arrêter le conteneur
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance

# Créer un nouveau conteneur (volume persistant pour que les données restaurées soient conservées)
sudo docker run --env-file .env -d --name bitcoin-signet-instance \
  -v signet-bitcoin-data:/root/.bitcoin \
  -p 38332:38332 -p 38333:38333 -p 28332:28332 -p 28333:28333 -p 28334:28334 \
  bitcoin-signet

# Attendre que le conteneur démarre
sleep 5

# Restaurer les données
sudo docker cp bitcoin-backup-YYYYMMDD.tar.gz bitcoin-signet-instance:/tmp/
sudo docker exec bitcoin-signet-instance tar xzf /tmp/bitcoin-backup-YYYYMMDD.tar.gz -C /

# Redémarrer le conteneur
sudo docker restart bitcoin-signet-instance

Sauvegarde des Clés

Important : Toujours sauvegarder séparément :

• Le fichier .env (contient PRIVKEY et SIGNETCHALLENGE)
• Les fichiers /root/.bitcoin/PRIVKEY.txt et /root/.bitcoin/SIGNETCHALLENGE.txt

Ces clés sont essentielles pour maintenir la cohérence du signet.

---

Commandes Utiles

Vérification de l'alignement Dashboard / Miner / Signet (chaîne ~11535)

Dashboard, miner et signet utilisent une seule source de vérité : le nœud Bitcoin Signet dans le conteneur bitcoin-signet-instance (RPC port 38332).

Composant	Source de la hauteur
Signet (nœud)	bitcoind dans le conteneur, datadir /root/.bitcoin
Dashboard	RPC getblockchaininfo vers 127.0.0.1:38332 (même nœud)
Miner	S'exécute dans le conteneur, appelle bitcoin-cli -datadir=/root/.bitcoin (même nœud)
Mempool	Backend connecté au même nœud (CORE_RPC_PORT=38332)

La chaîne attendue est d’environ 11535 blocs. Pour vérifier que tout est aligné :

1. Hauteur depuis le nœud (référence) :

   sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo | grep -E '"chain"|"blocks"'
   

   Attendu : "chain": "signet", "blocks": proche de 11535.

2. Hauteur depuis le Dashboard (doit être identique) :

   curl -s http://localhost:3020/api/blockchain/info | grep -o '"blocks":[0-9]*'
   

3. Miner : les logs du conteneur affichent la hauteur à chaque bloc miné (Mined ... at height N). Cette hauteur est celle du nœud.

Si le Dashboard affiche une hauteur très différente (ex. 2) ou si l’API d’ancrage retourne « Insufficient Balance » (0 BTC), exécuter sur la machine bitcoin : ./fix-dashboard-anchor-chain.sh (ou avec chemin de backup pour restaurer la chaîne). Voir fixKnowledge/dashboard-anchor-wrong-chain-insufficient-balance.md et fixKnowledge/signet-chain-lost-volume-persistent.md.

Script de test RPC (même nœud que Mempool) : ./test-mempool-rpc-config.sh [HOST] [PORT] (défaut 127.0.0.1 38332). Script de vérification dashboard signet : ./verify-dashboard-signet.sh (machine bitcoin, pour que https://dashboard.certificator.4nkweb.com/ affiche le signet custom). Script de vérification : exécuter ./verify-chain-alignment.sh à la racine du projet pour comparer la hauteur du nœud et du Dashboard et vérifier qu’elle est dans la plage attendue (~11535).

Script de Vérification Rapide

#!/bin/bash
echo "=== État du Conteneur ==="
sudo docker ps | grep bitcoin-signet

echo -e "\n=== État de la Blockchain ==="
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo | grep -E "(chain|blocks|bestblockhash)"

echo -e "\n=== État du Réseau ==="
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo | grep -E "(networkactive|connections)"

echo -e "\n=== État du Wallet ==="
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo | grep -E "(walletname|balance)"

echo -e "\n=== Processus de Mining ==="
sudo docker exec bitcoin-signet-instance ps aux | grep -E "(bitcoind|mine)" | grep -v grep

Script de Monitoring

#!/bin/bash
watch -n 5 'sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo | grep -E "(chain|blocks|bestblockhash|difficulty)"'

---

Références

• Dépôt Source
• Documentation Bitcoin Signet
• Bitcoin Core RPC API
• Documentation Docker
• Mempool Documentation : Documentation de l'explorateur blockchain Mempool

---

Dernière mise à jour : 2026-02-02