# 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](#prérequis)
2. [Installation Initiale](#installation-initiale)
3. [Configuration pour Rejoindre une Chaîne Existante](#configuration-pour-rejoindre-une-chaîne-existante)
4. [Configuration du Mining](#configuration-du-mining)
5. [Démarrage du Nœud](#démarrage-du-nœud)
6. [Vérification](#vérification)
7. [Dépannage](#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

```bash
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 :

```bash
cp env.example .env
```

### 3. Construire l'Image Docker

```bash
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 :

```bash
# Éditer .env
nano .env
```

Configuration minimale :

```bash
# 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 :

```bash
# Éditer .env
nano .env
```

Configuration complète :

```bash
# 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** :
```bash
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** :
```bash
MINETO=tb1qwe0nv3s0ewedd63w20r8kwnv22uw8dp2tnj3qc
```

### Modification Dynamique du Délai

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

```bash
# 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

```bash
sudo docker run --env-file .env -d \
  --name bitcoin-signet-instance \
  -p 38332:38332 \
  -p 38333:38333 \
  -p 28332:28332 \
  -p 28333:28333 \
  -p 28334:28334 \
  bitcoin-signet
```

### Vérifier les Logs

```bash
# 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

```bash
# 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

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

# Ou recréer le conteneur
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance
sudo docker run --env-file .env -d \
  --name bitcoin-signet-instance \
  -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

```bash
# 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

```bash
# 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

```bash
# 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é)

```bash
# 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é)

```bash
# 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** :
   ```bash
   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** :
   ```bash
   # Tester la connexion au nœud administrateur
   nc -zv <IP_NOEUD_ADMIN> 38333
   ```

3. **Vérifier le firewall** :
   ```bash
   # Vérifier que le port 38333 est ouvert
   sudo netstat -tlnp | grep 38333
   ```

4. **Vérifier SIGNETCHALLENGE** :
   ```bash
   # 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** :
   ```bash
   grep MINERENABLED .env
   ```
   Doit être `MINERENABLED=1`

2. **Vérifier PRIVKEY** :
   ```bash
   grep PRIVKEY .env
   ```
   Doit contenir la clé privée exacte du signet

3. **Vérifier l'import de la clé** :
   ```bash
   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** :
   ```bash
   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** :
   ```bash
   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** :
   ```bash
   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** :
   ```bash
   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** :
   ```bash
   sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin loadwallet custom_signet
   ```

3. **Importer la clé privée manuellement** :
   ```bash
   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** :
   ```bash
   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** :
   ```bash
   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

```bash
# 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

```bash
# É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

```bash
# 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
   ```bash
   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)
   ```bash
   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 :

```bash
# 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