# Documentation de Maintenance - Bitcoin Signet Custom

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

## Table des Matières

1. [Vue d'Ensemble](#vue-densemble)
2. [Architecture](#architecture)
3. [Configuration](#configuration)
4. [Commandes de Maintenance](#commandes-de-maintenance)
5. [Gestion du Conteneur](#gestion-du-conteneur)
6. [Gestion des Clés et du Signet](#gestion-des-clés-et-du-signet)
7. [Mining](#mining)
8. [Accès RPC et API](#accès-rpc-et-api)
9. [Mise à Jour](#mise-à-jour)
10. [Dépannage](#dépannage)
11. [Modifications Apportées](#modifications-apportées)
12. [Sauvegarde et Restauration](#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](https://github.com/Easepay/easepay-custom-signet.git).

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](./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
  - `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

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

```bash
# Utilisateur RPC
RPCUSER=bitcoin

# Mot de passe RPC
RPCPASSWORD=bitcoin
```

#### Variables ZMQ

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

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

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

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

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

### Accès au Conteneur

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

### Démarrage

```bash
cd /home/ncantu/Bureau/code/bitcoin
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
```

### Arrêt

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

# 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 \
  -p 38332:38332 -p 38333:38333 -p 28332:28332 -p 28333:28333 -p 28334:28334 \
  bitcoin-signet
```

### Reconstruction de l'Image

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

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

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

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

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

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

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

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

```bash
# 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](./DOMAINS_AND_PORTS.md) pour plus de détails

### Mise à Jour d'un Service

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

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

```bash
# 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](./DOMAINS_AND_PORTS.md)
- [ENVIRONMENT.md](./ENVIRONMENT.md)

---

## Accès RPC et API

### Commandes RPC Courantes

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

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

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

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

```bash
# 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](https://bitcoincore.org/en/download/)
- [GitHub Releases](https://github.com/bitcoin/bitcoin/releases)

##### 3. Sauvegarder les Données

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

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

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

##### 6. Redémarrer le Conteneur

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

# Démarrer avec la nouvelle image
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
```

##### 7. Vérifier la Mise à Jour

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

```bash
# 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](https://bitcoincore.org/en/releases/) 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 :

```bash
# 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
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 Régulière des Mises à Jour

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

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

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

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

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

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

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

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

---

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

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

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

# Créer un nouveau conteneur
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

# 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

### Script de Vérification Rapide

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

```bash
#!/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](https://github.com/Easepay/easepay-custom-signet.git)
- [Documentation Bitcoin Signet](https://en.bitcoin.it/wiki/Signet)
- [Bitcoin Core RPC API](https://developer.bitcoin.org/reference/rpc/)
- [Documentation Docker](https://docs.docker.com/)
- [Mempool Documentation](./MEMPOOL.md) : Documentation de l'explorateur blockchain Mempool

---

**Dernière mise à jour** : 2026-01-24