anchorage_layer_simple/docs/INSTALLATION_NEW_NODE.md

Installation d'un Nouveau Nœud et Configuration du Mining

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

Ce guide explique comment installer un nouveau nœud Bitcoin Signet custom et le configurer pour miner sur la chaîne existante.

Table des Matières

1. Prérequis
2. Installation Initiale
3. Configuration pour Rejoindre une Chaîne Existante
4. Configuration du Mining
5. Démarrage du Nœud
6. Vérification
7. Dépannage

---

Prérequis

Logiciels Requis

• Docker : Version 20.10 ou supérieure
• Git : Pour cloner le dépôt
• jq : Pour le traitement JSON (installé automatiquement dans le conteneur)
• Accès réseau : Ports 38332 (RPC), 38333 (P2P), 28332-28334 (ZMQ)

Informations Nécessaires

Pour rejoindre une chaîne signet existante, vous devez obtenir du nœud administrateur :

1. SIGNETCHALLENGE : Le challenge du signet (identifie la chaîne)
2. PRIVKEY : La clé privée du signer (nécessaire pour miner)
3. Adresse IP du nœud : Pour se connecter au réseau (optionnel mais recommandé)

---

Installation Initiale

1. Cloner le Dépôt

git clone https://github.com/Easepay/easepay-custom-signet.git bitcoin-signet
cd bitcoin-signet

2. Créer le Fichier de Configuration

Créez un fichier .env à la racine du projet :

cp env.example .env

3. Construire l'Image Docker

sudo docker build -t bitcoin-signet .

Cette étape peut prendre plusieurs minutes car elle télécharge Bitcoin Core 30.2.

---

Configuration pour Rejoindre une Chaîne Existante

Option A : Nœud Simple (Sans Mining)

Si vous voulez juste un nœud qui se synchronise avec la chaîne sans miner :

# Éditer .env
nano .env

Configuration minimale :

# Mining Configuration
BLOCKPRODUCTIONDELAY=600
MINERENABLED=0
NBITS=1e0377ae
PRIVKEY=
MINETO=
SIGNETCHALLENGE=5121028b8d4cea1b3d8582babc8405bc618fbbb281c0f64e6561aa85968251931cd0a651ae

# RPC Configuration
RPCUSER=bitcoin
RPCPASSWORD=bitcoin

UACOMMENT=CustomSignet

# ZMQ Configuration
ZMQPUBRAWBLOCK=tcp://0.0.0.0:28332
ZMQPUBRAWTX=tcp://0.0.0.0:28333
ZMQPUBHASHBLOCK=tcp://0.0.0.0:28334

# Additional Configuration
RPCBIND=0.0.0.0:38332
RPCALLOWIP=0.0.0.0/0
WHITELIST=0.0.0.0/0
ADDNODE=<IP_DU_NOEUD_ADMINISTRATEUR>:38333
EXTERNAL_IP=

Points importants :

• MINERENABLED=0 : Désactive le mining
• SIGNETCHALLENGE : Doit correspondre exactement à celui de la chaîne
• ADDNODE : Adresse IP et port du nœud administrateur (ex: 192.168.1.103:38333)

Option B : Nœud avec Mining

Si vous voulez miner sur la chaîne :

# Éditer .env
nano .env

Configuration complète :

# Mining Configuration
# Note: Bitcoin Core 30+ uses descriptor wallets (legacy wallets no longer supported)
BLOCKPRODUCTIONDELAY=600
MINERENABLED=1
NBITS=1e0377ae
PRIVKEY=cVCKcgQf2ewV5miairzhrHJCPv4kMbMMBZeJvW5SMhFMSWVtCvXS
MINETO=
SIGNETCHALLENGE=5121028b8d4cea1b3d8582babc8405bc618fbbb281c0f64e6561aa85968251931cd0a651ae

# RPC Configuration
RPCUSER=bitcoin
RPCPASSWORD=bitcoin

UACOMMENT=CustomSignet

# ZMQ Configuration
ZMQPUBRAWBLOCK=tcp://0.0.0.0:28332
ZMQPUBRAWTX=tcp://0.0.0.0:28333
ZMQPUBHASHBLOCK=tcp://0.0.0.0:28334

# Additional Configuration
RPCBIND=0.0.0.0:38332
RPCALLOWIP=0.0.0.0/0
WHITELIST=0.0.0.0/0
ADDNODE=<IP_DU_NOEUD_ADMINISTRATEUR>:38333
EXTERNAL_IP=

Points importants :

• MINERENABLED=1 : Active le mining
• PRIVKEY : Doit être la même que celle utilisée par le nœud administrateur
• SIGNETCHALLENGE : Doit correspondre exactement à celui de la chaîne
• BLOCKPRODUCTIONDELAY : Délai entre les blocs (600 = 10 minutes)
• ADDNODE : Adresse IP et port du nœud administrateur

---

Configuration du Mining

Paramètres de Mining

Les paramètres suivants contrôlent le comportement du mining :

BLOCKPRODUCTIONDELAY

Délai en secondes entre la génération de chaque bloc.

• 600 : 10 minutes (simule le mainnet)
• 60 : 1 minute (pour tests rapides)
• 0 : Pas de délai (mining continu)

Exemple :

BLOCKPRODUCTIONDELAY=600  # 10 minutes

NBITS

Difficulté minimale pour le mining (format hexadécimal).

Recommandation : Ne pas modifier sauf nécessité spécifique.

Valeur par défaut : 1e0377ae

MINETO

Adresse Bitcoin où envoyer la récompense de minage.

• Vide : Une nouvelle adresse est générée pour chaque bloc
• Adresse spécifique : Tous les blocs minent vers cette adresse

Exemple :

MINETO=tb1qwe0nv3s0ewedd63w20r8kwnv22uw8dp2tnj3qc

Modification Dynamique du Délai

Vous pouvez modifier le délai de production de blocs sans redémarrer le conteneur :

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

# Le script mine.sh détectera automatiquement ce changement

---

Démarrage du Nœud

Premier Démarrage

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

Le volume signet-bitcoin-data conserve la chaîne ; sans lui, une recréation du conteneur repart d’une nouvelle chaîne.

Vérifier les 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

Arrêt du Nœud

# 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

# Ou recréer le conteneur (volume persistant pour conserver la chaîne)
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

---

Vérification

1. Vérifier que le Conteneur Fonctionne

# Vérifier le statut
sudo docker ps | grep bitcoin-signet

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

2. Vérifier la Connexion au Réseau

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

# Vérifier les connexions
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo | grep -E "(connections|networkactive)"

Résultat attendu :

• networkactive: true
• connections: 1 ou plus (si connecté au nœud administrateur)

3. Vérifier la Synchronisation

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

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

Résultat attendu :

• chain: "signet"
• verificationprogress: 1 (une fois synchronisé)
• blocks: X (nombre de blocs synchronisés)

4. Vérifier le Wallet (Si Mining Activé)

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

# Vérifier que la clé privée est importée
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin listdescriptors | grep -i "028b8d4cea1b3d8582babc8405bc618fbbb281c0f64e6561aa85968251931cd0a6"

Résultat attendu :

• walletname: "custom_signet"
• format: "sqlite" (descriptor wallet)
• Descriptor avec la clé publique du signet présent

5. Vérifier le Mining (Si Activé)

# Vérifier que le script de mining est actif
sudo docker exec bitcoin-signet-instance ps aux | grep -E "(mine|bitcoind)" | grep -v grep

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

Résultat attendu :

• Processus mine.sh en cours d'exécution
• Messages "Delay before next block" dans les logs
• Message "Private key imported successfully into descriptor wallet"

---

Dépannage

Le Nœud ne se Connecte pas au Réseau

Symptômes :

• connections: 0
• networkactive: true mais pas de connexions

Solutions :

1. Vérifier ADDNODE dans .env :

   grep ADDNODE .env
   

   Doit contenir l'adresse IP et le port du nœud administrateur : ADDNODE=192.168.1.103:38333

2. Vérifier la connectivité réseau :

   # Tester la connexion au nœud administrateur
   nc -zv <IP_NOEUD_ADMIN> 38333
   

3. Vérifier le firewall :

   # Vérifier que le port 38333 est ouvert
   sudo netstat -tlnp | grep 38333
   

4. Vérifier SIGNETCHALLENGE :

   # Le SIGNETCHALLENGE doit être exactement le même que celui du nœud administrateur
   grep SIGNETCHALLENGE .env
   

Le Mining ne Fonctionne pas

Symptômes :

• Pas de processus mine.sh
• Erreurs dans les logs concernant la clé privée

Solutions :

1. Vérifier MINERENABLED :

   grep MINERENABLED .env
   

   Doit être MINERENABLED=1

2. Vérifier PRIVKEY :

   grep PRIVKEY .env
   

   Doit contenir la clé privée exacte du signet

3. Vérifier l'import de la clé :

   sudo docker logs bitcoin-signet-instance | grep -i "importing\|private key"
   

   Doit afficher "Private key imported successfully into descriptor wallet"

4. Vérifier manuellement l'import :

   sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin listdescriptors | grep -i "wpkh"
   

   Doit contenir le descriptor avec la clé publique du signet

Erreur "Cannot obtain a lock"

Symptômes :

• Erreur dans les logs : "Cannot obtain a lock on data directory"

Solutions :

1. Arrêter tous les processus bitcoind :

   sudo docker exec bitcoin-signet-instance pkill bitcoind
   sudo docker restart bitcoin-signet-instance
   

2. Vérifier qu'aucun autre conteneur n'utilise les mêmes ports :

   sudo docker ps | grep -E "(38332|38333)"
   

Le Wallet n'Existe pas

Symptômes :

• Erreur "No wallet is loaded"

Solutions :

1. Créer le wallet manuellement :

   sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin \
     -named createwallet wallet_name="custom_signet" load_on_startup=true descriptors=true
   

2. Charger le wallet :

   sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin loadwallet custom_signet
   

3. Importer la clé privée manuellement :

   PRIVKEY=$(grep PRIVKEY .env | 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}]"
   

Synchronisation Lente

Symptômes :

• verificationprogress reste faible
• blocks n'augmente pas

Solutions :

1. Vérifier les connexions :

   sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo | grep connections
   

   Doit être supérieur à 0

2. Ajouter plusieurs nœuds dans ADDNODE :

   ADDNODE=192.168.1.103:38333,192.168.1.104:38333
   

3. Vérifier la bande passante réseau

---

Commandes Utiles

Accès au Conteneur

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

# Exécuter bitcoin-cli
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin <commande>

Commandes RPC Courantes

# État de la blockchain
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo

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

# État du wallet
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo

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

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

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

Monitoring

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

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

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

---

Partage d'Informations avec d'Autres Nœuds

Pour permettre à d'autres nœuds de rejoindre votre chaîne, partagez :

1. SIGNETCHALLENGE : Identifie la chaîne

   sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/SIGNETCHALLENGE.txt
   

2. PRIVKEY : Nécessaire pour miner (partager uniquement avec les nœuds de confiance)

   sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/PRIVKEY.txt
   

3. Adresse IP et Port : Pour la connexion P2P

   • IP : Votre adresse IP publique ou locale
   • Port : 38333 (port P2P)

4. RPC Credentials (optionnel) : Si vous voulez permettre l'accès RPC

   • RPCUSER : bitcoin (ou personnalisé)
   • RPCPASSWORD : bitcoin (ou personnalisé)
   • Port RPC : 38332

Sécurité : Ne partagez jamais la PRIVKEY publiquement. Elle permet de miner et de signer des blocs sur votre chaîne.

---

Exemple de Configuration Complète

Voici un exemple complet de fichier .env pour un nœud avec mining :

# Mining Configuration
# Note: Bitcoin Core 30+ uses descriptor wallets (legacy wallets no longer supported)
BLOCKPRODUCTIONDELAY=600
MINERENABLED=1
NBITS=1e0377ae
PRIVKEY=cVCKcgQf2ewV5miairzhrHJCPv4kMbMMBZeJvW5SMhFMSWVtCvXS
MINETO=
SIGNETCHALLENGE=5121028b8d4cea1b3d8582babc8405bc618fbbb281c0f64e6561aa85968251931cd0a651ae

# RPC Configuration
RPCUSER=bitcoin
RPCPASSWORD=bitcoin

UACOMMENT=CustomSignet

# ZMQ Configuration
ZMQPUBRAWBLOCK=tcp://0.0.0.0:28332
ZMQPUBRAWTX=tcp://0.0.0.0:28333
ZMQPUBHASHBLOCK=tcp://0.0.0.0:28334

# Additional Configuration
RPCBIND=0.0.0.0:38332
RPCALLOWIP=0.0.0.0/0
WHITELIST=0.0.0.0/0
ADDNODE=192.168.1.103:38333
EXTERNAL_IP=

---

Prochaines Étapes

Une fois le nœud installé et fonctionnel :

1. Lire la documentation de maintenance : docs/MAINTENANCE.md
2. Configurer la sauvegarde : Voir section "Sauvegarde et Restauration"
3. Configurer le monitoring : Surveiller les logs et l'état du nœud
4. Partager les informations : Si vous voulez que d'autres nœuds rejoignent

---

Dernière mise à jour : 2026-01-09