anchorage_layer_simple/features/api-anchorage-monitoring-and-prevention.md

# API d'Ancrage - Monitoring et Prévention des Blocages

**Date:** 2026-01-28
**Auteur:** Équipe 4NK

## Objectif

Implémenter des moyens de contrôle et de correction pour prévenir et résoudre les blocages du mutex et des UTXOs verrouillés dans l'API d'ancrage.

## Motivations

- **Prévention des blocages:** Éviter que le mutex reste bloqué indéfiniment
- **Détection précoce:** Identifier les problèmes avant qu'ils n'affectent les utilisateurs
- **Récupération automatique:** Déverrouiller automatiquement les UTXOs verrouillés depuis trop longtemps
- **Robustesse:** Gérer les timeouts RPC Bitcoin avec retry et backoff
- **Observabilité:** Fournir des endpoints de monitoring détaillés

## Impacts

### Fonctionnels

- **Endpoint `/health/detailed`:** Fournit un état détaillé du mutex, des UTXOs et de la connexion Bitcoin
- **Déverrouillage automatique:** Les UTXOs verrouillés depuis > 10 minutes sont automatiquement déverrouillés au démarrage
- **Timeout de sécurité:** Le mutex est automatiquement libéré après 5 minutes maximum
- **Retry avec backoff:** Les appels RPC Bitcoin sont automatiquement réessayés en cas de timeout
- **Monitoring de durée:** Les opérations > 30 secondes sont loggées avec un warning

### Techniques

- **Timeout sur Promise.all():** La génération d'adresses a un timeout de 30 secondes
- **État du mutex:** Suivi en temps réel de l'état du mutex (locked, waiting)
- **Scripts de maintenance:** Scripts pour diagnostic et nettoyage automatique
- **Documentation:** Documentation complète du monitoring et de la maintenance

## Modifications

### Fichiers modifiés

1. **`api-anchorage/src/routes/health.js`**
   - Ajout de l'endpoint `/health/detailed` avec état du mutex et UTXOs
   - Vérification des UTXOs verrouillés depuis > 10 minutes
   - Codes de statut adaptatifs selon l'état

2. **`api-anchorage/src/bitcoin-rpc.js`**
   - Ajout de `getMutexState()` pour exposer l'état du mutex
   - Suivi de l'état du mutex (`utxoMutexLocked`, `utxoMutexWaiting`)
   - Timeout de sécurité de 5 minutes sur le mutex dans `createAnchorTransaction()`
   - Timeout de 30 secondes sur `Promise.all()` pour la génération d'adresses
   - Méthode `callRPCWithRetry()` pour retry avec backoff exponentiel
   - Méthode `callRPCCommandWithRetry()` pour les commandes RPC
   - Tous les appels RPC critiques utilisent maintenant le retry avec backoff
   - Monitoring de la durée des opérations avec alerte si > 30s

3. **`api-anchorage/src/server.js`**
   - Déverrouillage automatique des UTXOs verrouillés depuis > 10 minutes au démarrage
   - Exclusion de `/health/detailed` de l'authentification API Key
   - Mise à jour de la liste des endpoints dans la route racine

4. **`api-anchorage/cleanup-stale-locks.mjs`** (nouveau)
   - Script pour déverrouiller les UTXOs verrouillés depuis > 10 minutes
   - À exécuter via cron job toutes les 5 minutes

5. **`api-anchorage/diagnose.mjs`** (nouveau)
   - Script de diagnostic complet de l'état des UTXOs
   - Affiche les UTXOs verrouillés avec leur durée de verrouillage
   - Statistiques générales des UTXOs

6. **`signet-dashboard/public/api-docs.html`**
   - Ajout de la documentation de l'endpoint `/health/detailed`
   - Mise à jour de la liste des endpoints publics
   - Correction de l'URL de l'API d'ancrage (anchorage.certificator.4nkweb.com)

7. **`docs/INTERFACES.md`**
   - Ajout de la documentation de l'endpoint `/health/detailed`
   - Mise à jour de la liste des endpoints

8. **`api-anchorage/README-MONITORING.md`** (nouveau)
   - Documentation complète du monitoring et de la maintenance
   - Procédures de dépannage
   - Configuration des cron jobs

### Appels RPC mis à jour avec retry

- `getNewAddress()` → `callRPCWithRetry('getNewAddress', [])`
- `getBalance()` → `callRPCWithRetry('getBalance', [])`
- `checkConnection()` → `callRPCWithRetry('getNetworkInfo', [])` et `callRPCWithRetry('getBlockchainInfo', [])`
- `listunspent()` → `callRPCWithRetry('listunspent', [...])`
- `createrawtransaction` → `callRPCCommandWithRetry('createrawtransaction', ...)`
- `signrawtransactionwithwallet` → `callRPCCommandWithRetry('signrawtransactionwithwallet', ...)`
- `sendrawtransaction` → `callRPCCommandWithRetry('sendrawtransaction', ...)`
- `getmempoolentry` → `callRPCCommandWithRetry('getmempoolentry', ...)`
- `getTransaction()` → `callRPCWithRetry('getTransaction', [...])`
- `getRawTransaction()` → `callRPCWithRetry('getRawTransaction', [...])`
- `getTransactionInfo()` → Utilise `callRPCWithRetry()` pour tous les appels

## Modalités de déploiement

### 1. Redémarrage du service

```bash
sudo systemctl restart anchorage-api
```

### 2. Vérification

```bash
# Health check détaillé
curl http://localhost:3010/health/detailed

# Depuis l'extérieur
curl https://anchorage.certificator.4nkweb.com/health/detailed
```

### 3. Configuration du cron job (optionnel mais recommandé)

Créer `/etc/cron.d/anchorage-cleanup`:

```bash
# Nettoyage automatique des UTXOs verrouillés depuis plus de 10 minutes
# Toutes les 5 minutes
*/5 * * * * ncantu cd /home/ncantu/Bureau/code/bitcoin/api-anchorage && /usr/bin/node cleanup-stale-locks.mjs >> /var/log/anchorage-cleanup.log 2>&1
```

### 4. Test des scripts

```bash
# Diagnostic
cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
node diagnose.mjs

# Nettoyage
node cleanup-stale-locks.mjs

# Déverrouillage manuel
node unlock-utxos.mjs
```

## Modalités d'analyse

### Endpoints de monitoring

1. **GET `/health/detailed`**
   - Vérifier l'état du mutex (`locked`, `waiting`)
   - Vérifier le nombre d'UTXOs verrouillés
   - Vérifier les UTXOs verrouillés depuis > 10 minutes (`stale_locks`)
   - Vérifier la connexion Bitcoin

2. **GET `/api/anchor/locked-utxos`**
   - Liste complète des UTXOs verrouillés
   - Compteur total

### Logs à surveiller

1. **Timeouts de mutex:**
   ```bash
   sudo journalctl -u anchorage-api | grep "Mutex acquisition timeout"
   ```

2. **Opérations longues:**
   ```bash
   sudo journalctl -u anchorage-api | grep "took too long"
   ```

3. **Erreurs RPC Bitcoin:**
   ```bash
   sudo journalctl -u anchorage-api | grep "ESOCKETTIMEDOUT\|ETIMEDOUT"
   ```

4. **Retry RPC:**
   ```bash
   sudo journalctl -u anchorage-api | grep "RPC call failed, retrying"
   ```

### Scripts de diagnostic

1. **`diagnose.mjs`:** Diagnostic complet de l'état des UTXOs
2. **`cleanup-stale-locks.mjs`:** Nettoyage automatique des UTXOs stale
3. **`unlock-utxos.mjs`:** Déverrouillage manuel de tous les UTXOs

## Pages affectées

- `api-anchorage/src/routes/health.js`: Endpoint `/health/detailed`
- `api-anchorage/src/bitcoin-rpc.js`: Monitoring, timeouts, retry avec backoff
- `api-anchorage/src/server.js`: Déverrouillage automatique au démarrage
- `api-anchorage/cleanup-stale-locks.mjs`: Script de nettoyage (nouveau)
- `api-anchorage/diagnose.mjs`: Script de diagnostic (nouveau)
- `api-anchorage/README-MONITORING.md`: Documentation (nouveau)
- `signet-dashboard/public/api-docs.html`: Documentation API mise à jour
- `docs/INTERFACES.md`: Documentation API mise à jour
- `features/api-anchorage-monitoring-and-prevention.md`: Documentation (nouveau)