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.

**Emplacement dans le projet :** le chemin de base du projet est `/home/ncantu/Bureau/code/bitcoin/` ; Mempool se trouve dans le sous-répertoire `mempool/` (soit `.../bitcoin/mempool/`). 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

Depuis la racine du projet (`/home/ncantu/Bureau/code/bitcoin/`) :

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

Le script :
1. Charge les variables d'environnement depuis `../.env` (racine du projet)
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

Depuis la racine du projet :

```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://mempool.4nkweb.com (via nginx proxy, machine bitcoin 192.168.1.105)

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

Depuis la racine du projet (`/home/ncantu/Bureau/code/bitcoin/`) :

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

Depuis la racine du projet :

```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 (mempool.4nkweb.com), ajouter une configuration similaire aux autres services. Mempool est hébergé sur la machine bitcoin (192.168.1.105) uniquement :

```nginx
# Mempool Bitcoin Signet Explorer
server {
    listen 80;
    server_name mempool.4nkweb.com;

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

    location / {
        proxy_pass http://192.168.1.105: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