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

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

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

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

```bash
cd mempool
./start.sh
```

### Vérification de l'État

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

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

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

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

```bash
# 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é :
   ```bash
   sudo docker-compose -f docker-compose.signet.yml ps
   ```

2. Vérifier les logs du frontend :
   ```bash
   sudo docker-compose -f docker-compose.signet.yml logs web
   ```

3. Vérifier que le backend est accessible :
   ```bash
   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 :
   ```bash
   bitcoin-cli -rpcport=38332 -rpcuser=bitcoin -rpcpassword=bitcoin getblockchaininfo
   ```

2. Vérifier les logs de l'API :
   ```bash
   sudo docker-compose -f docker-compose.signet.yml logs api | grep -i rpc
   ```

3. Vérifier que `host.docker.internal` est accessible :
   ```bash
   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 :
     ```bash
     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 :
   ```bash
   sudo docker-compose -f docker-compose.signet.yml logs db
   ```

2. Vérifier les permissions du répertoire :
   ```bash
   ls -la mysql/data
   chmod -R 1000:1000 mysql/data
   ```

3. Supprimer et recréer le volume :
   ```bash
   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é :
   ```bash
   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 :

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

```bash
GET /api/v1/backend-info
```

Retourne les informations sur le backend Mempool.

**Réponse** :
```json
{
  "isElectrs": false,
  "isEsplora": false,
  "isLiquid": false,
  "network": "signet",
  "mempoolSize": 0,
  "blockCount": 716,
  "lastBlockHash": "...",
  "lastBlockTime": 1234567890
}
```

### Blocks

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

Retourne les informations sur les blocs.

### Transactions

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

Retourne les informations sur les transactions.

### Mempool

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