anchorage_layer_simple/docs/MEMPOOL.md

Mempool - Explorateur Blockchain Bitcoin Signet

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

Vue d'Ensemble

Mempool est un explorateur de blockchain Bitcoin qui permet de visualiser et d'analyser la blockchain et la mempool du signet custom. Il fournit une interface web moderne pour explorer les blocs, transactions, adresses et statistiques du réseau.

Caractéristiques

• Explorateur de blockchain : Visualisation des blocs, transactions et adresses
• Mempool en temps réel : Suivi des transactions en attente
• Statistiques : Graphiques de frais, taux de hash, etc.
• API REST : Accès programmatique aux données
• Interface web moderne : Interface utilisateur Angular responsive

Installation

Prérequis

• Docker et Docker Compose installés
• Nœud Bitcoin Signet en cours d'exécution sur le port 38332
• Accès aux credentials RPC Bitcoin (bitcoin/bitcoin par défaut)

Installation Rapide

cd /home/ncantu/Bureau/code/bitcoin/mempool
./start.sh

Le script :

1. Charge les variables d'environnement depuis ../.env
2. Vérifie la connexion au nœud Bitcoin
3. Crée les répertoires nécessaires
4. Lance les services Docker (frontend, backend, base de données)

Installation Manuelle

cd mempool
docker-compose -f docker-compose.signet.yml up -d

Configuration

Variables d'Environnement

Mempool utilise les mêmes variables que les autres services du projet :

# Bitcoin RPC Configuration (identique aux autres services)
BITCOIN_RPC_HOST=localhost          # ou host.docker.internal depuis Docker
BITCOIN_RPC_PORT=38332              # Port RPC Bitcoin Signet
BITCOIN_RPC_USER=bitcoin            # Utilisateur RPC (identique à RPCUSER dans .env)
BITCOIN_RPC_PASSWORD=bitcoin        # Mot de passe RPC (identique à RPCPASSWORD dans .env)

Ces variables peuvent être définies dans le fichier .env à la racine du projet.

Configuration Docker Compose

Le fichier docker-compose.signet.yml contient toute la configuration nécessaire :

• Frontend : Port 3015 (accessible depuis l'extérieur)
• Backend API : Port 8999 (interne)
• Base de données : MariaDB sur port 3306 (interne)
• Electrs : Port 50002 (interne, pour les recherches d'adresses)
• Réseau : "signet" configuré

Architecture

Client (Navigateur)
  ↓ HTTPS
Nginx Proxy (192.168.1.100:443)
  ↓ HTTP
Mempool Frontend (localhost:3015)
  ↓ HTTP (interne)
Mempool Backend (port 8999)
  ├─→ RPC → Bitcoin Signet Node (localhost:38332)
  └─→ Electrum Protocol → Electrs (port 50002)
       └─→ RPC → Bitcoin Signet Node (localhost:38332)
  ↓ Base de données
MariaDB (cache et statistiques)

Services

Mempool utilise quatre services Docker :

1. web (frontend) : Interface utilisateur Angular

   • Image : mempool/frontend:latest
   • Port : 3015 (exposé)
   • Healthcheck : Vérifie que le frontend répond

2. api (backend) : API Node.js/TypeScript

   • Image : mempool/backend:latest
   • Port : 8999 (interne)
   • Connexion RPC : host.docker.internal:38332
   • Connexion Electrum : electrs:50002
   • Healthcheck : Vérifie que l'API répond

3. db (database) : Base de données MariaDB

   • Image : mariadb:10.5.21
   • Port : 3306 (interne)
   • Données : ./mysql/data
   • Healthcheck : Vérifie que MySQL répond

4. electrs (electrum server) : Serveur Electrum pour l'indexation

   • Image : ghcr.io/romanz/electrs:latest
   • Port : 50002 (interne, TCP)
   • Connexion RPC : host.docker.internal:38332
   • Données : ./electrs/data
   • Healthcheck : Vérifie que le port 50002 répond

Accès

Interface Web

• URL locale : http://localhost:3015
• URL production : https://mempool1.4nkweb.com (via nginx proxy)

API Backend

• URL locale : http://localhost:8999/api/v1/
• Endpoints principaux :
  • /api/v1/backend-info : Informations sur le backend
  • /api/v1/blocks : Liste des blocs
  • /api/v1/transactions : Transactions
  • /api/v1/mempool : Mempool en temps réel

Utilisation

Démarrage

cd mempool
./start.sh

Vérification de l'État

# État des services
sudo docker-compose -f docker-compose.signet.yml ps

# Logs en temps réel
sudo docker-compose -f docker-compose.signet.yml logs -f

# Logs d'un service spécifique
sudo docker-compose -f docker-compose.signet.yml logs -f api

Arrêt

# Arrêter les services
sudo docker-compose -f docker-compose.signet.yml down

# Arrêter et supprimer les volumes (base de données)
sudo docker-compose -f docker-compose.signet.yml down -v

Fonctionnalités

Exploration de la Blockchain

• Blocs : Liste des blocs minés avec détails (hash, hauteur, timestamp, transactions)
• Transactions : Détails des transactions (inputs, outputs, frais)
• Adresses : Historique des transactions par adresse (nécessite Electrum Server)
• Recherche : Recherche par hash de bloc, transaction ou adresse

Mempool

• Transactions en attente : Visualisation des transactions non confirmées
• Graphiques de frais : Estimation des frais recommandés
• Statistiques : Taux de transactions par seconde, taille de la mempool

Statistiques

• Réseau : Taux de hash, difficulté, temps entre blocs
• Mining : Pools de minage, distribution des blocs
• Frais : Évolution des frais dans le temps

Maintenance

Mise à Jour

cd mempool
# Récupérer les dernières images
sudo docker-compose -f docker-compose.signet.yml pull

# Redémarrer avec les nouvelles images
sudo docker-compose -f docker-compose.signet.yml up -d

Sauvegarde

Les données importantes sont stockées dans :

• Cache : ./data/ (peut être supprimé, sera régénéré)
• Base de données : ./mysql/data/ (à sauvegarder pour conserver les statistiques)
• Index Electrs : ./electrs/data/ (peut être supprimé, sera réindexé mais prend du temps)

# Sauvegarder la base de données
sudo docker-compose -f docker-compose.signet.yml exec db mysqldump -u mempool -pmempool mempool > mempool_backup.sql

# Restaurer la base de données
sudo docker-compose -f docker-compose.signet.yml exec -T db mysql -u mempool -pmempool mempool < mempool_backup.sql

Logs

# Tous les services
sudo docker-compose -f docker-compose.signet.yml logs -f

# Service spécifique
sudo docker-compose -f docker-compose.signet.yml logs -f api
sudo docker-compose -f docker-compose.signet.yml logs -f web
sudo docker-compose -f docker-compose.signet.yml logs -f db

Dépannage

Le frontend ne se charge pas

Symptômes : Erreur 502 ou timeout sur http://localhost:3015

Solutions :

1. Vérifier que le service web est démarré :

   sudo docker-compose -f docker-compose.signet.yml ps
   

2. Vérifier les logs du frontend :

   sudo docker-compose -f docker-compose.signet.yml logs web
   

3. Vérifier que le backend est accessible :

   curl http://localhost:8999/api/v1/backend-info
   

L'API ne peut pas se connecter à Bitcoin Core

Symptômes : Erreurs dans les logs de l'API concernant la connexion RPC

Solutions :

1. Vérifier que Bitcoin Core est en cours d'exécution :

   bitcoin-cli -rpcport=38332 -rpcuser=bitcoin -rpcpassword=bitcoin getblockchaininfo
   

2. Vérifier les logs de l'API :

   sudo docker-compose -f docker-compose.signet.yml logs api | grep -i rpc
   

3. Vérifier que host.docker.internal est accessible :

   sudo docker-compose -f docker-compose.signet.yml exec api ping -c 1 host.docker.internal
   

4. Sur Linux, si host.docker.internal ne fonctionne pas :

   • Trouver l'IP de la passerelle Docker :

     docker network inspect mempool_mempool-signet | grep Gateway
     

   • Modifier docker-compose.signet.yml pour utiliser cette IP au lieu de host.docker.internal

La base de données ne démarre pas

Symptômes : Le service db est en état "unhealthy" ou ne démarre pas

Solutions :

1. Vérifier les logs de la base de données :

   sudo docker-compose -f docker-compose.signet.yml logs db
   

2. Vérifier les permissions du répertoire :

   ls -la mysql/data
   chmod -R 1000:1000 mysql/data
   

3. Supprimer et recréer le volume :

   sudo docker-compose -f docker-compose.signet.yml down -v
   sudo docker-compose -f docker-compose.signet.yml up -d db
   

Synchronisation lente

Symptômes : Mempool met du temps à synchroniser les blocs

Solutions :

1. Vérifier que Bitcoin Core est synchronisé :

   bitcoin-cli -rpcport=38332 getblockchaininfo
   

2. Vérifier les index Bitcoin Core :

   • txindex=1 doit être activé
   • blockfilterindex=1 doit être activé
   • coinstatsindex=1 doit être activé

3. Augmenter les ressources Docker si nécessaire

Intégration avec l'Infrastructure

Configuration Nginx (sur proxy 192.168.1.100)

Pour exposer Mempool via le proxy nginx (mempool1.4nkweb.com), ajouter une configuration similaire aux autres services :

# Mempool Bitcoin Signet Explorer
server {
    listen 80;
    server_name mempool1.4nkweb.com;

    access_log /var/log/nginx/mempool1.4nkweb.com.access.log;
    error_log /var/log/nginx/mempool1.4nkweb.com.error.log;

    location / {
        proxy_pass http://192.168.1.XXX:3015;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }
}

Note : Remplacer 192.168.1.XXX par l'IP du serveur où Mempool est déployé.

Cohérence avec les Autres Services

Mempool s'intègre parfaitement avec l'infrastructure existante :

• Port : 3015 (cohérent avec la numérotation : 3010, 3015, 3020, 3021)
• RPC Bitcoin : Même configuration que les autres services (localhost:38332, bitcoin/bitcoin)
• Variables d'environnement : Compatible avec le .env du projet
• Documentation : Structure similaire aux autres services

API Endpoints

Backend Info

GET /api/v1/backend-info

Retourne les informations sur le backend Mempool.

Réponse :

{
  "isElectrs": false,
  "isEsplora": false,
  "isLiquid": false,
  "network": "signet",
  "mempoolSize": 0,
  "blockCount": 716,
  "lastBlockHash": "...",
  "lastBlockTime": 1234567890
}

Blocks

GET /api/v1/blocks
GET /api/v1/blocks/:hash
GET /api/v1/blocks/tip/height

Retourne les informations sur les blocs.

Transactions

GET /api/v1/tx/:txid
GET /api/v1/tx/:txid/outspend

Retourne les informations sur les transactions.

Mempool

GET /api/v1/mempool
GET /api/v1/mempool/txids

Retourne les informations sur la mempool.

Fonctionnalités

Recherche d'Adresses

La recherche d'adresses est activée grâce au serveur Electrs intégré. Mempool peut maintenant :

• Rechercher des transactions par adresse
• Afficher l'historique complet des transactions d'une adresse
• Calculer les soldes par adresse
• Suivre les UTXOs (Unspent Transaction Outputs)

Le serveur Electrs indexe la blockchain au démarrage. Pour un signet custom avec peu de blocs, l'indexation est rapide.

Pools de Minage

Les pools de minage affichés sont ceux de mainnet/testnet. Pour un signet custom, ces informations ne sont pas pertinentes mais n'affectent pas le fonctionnement.

Performance

Mempool indexe les blocs et maintient un cache en base de données. Pour un signet custom avec peu de blocs, les performances sont excellentes.

Optimisations

• Cache : Les données sont mises en cache pour améliorer les performances
• Indexation : Seuls les 11000 derniers blocs sont indexés par défaut
• Base de données : MariaDB optimisée pour les requêtes fréquentes

Sécurité

Recommandations

• RPC Bitcoin : Ne pas exposer le port RPC (38332) publiquement
• Base de données : Les credentials par défaut doivent être changés en production
• Nginx : Utiliser HTTPS avec certificats SSL valides
• Firewall : Restreindre l'accès aux ports Docker

Support

Pour plus d'informations :

• Documentation officielle : https://mempool.space/docs
• Repository GitHub : https://github.com/mempool/mempool
• Documentation locale : mempool/README.SIGNET.md
• Adaptations : mempool/ADAPTATION.md

Changelog

• 2026-01-24 : Installation initiale et configuration pour signet custom
• 2026-01-24 : Adaptation à l'infrastructure existante
• 2026-01-24 : Documentation complète