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

sudo systemctl restart anchorage-api

2. Vérification

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

# 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

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

   sudo journalctl -u anchorage-api | grep "Mutex acquisition timeout"
   

2. Opérations longues:

   sudo journalctl -u anchorage-api | grep "took too long"
   

3. Erreurs RPC Bitcoin:

   sudo journalctl -u anchorage-api | grep "ESOCKETTIMEDOUT\|ETIMEDOUT"
   

4. Retry RPC:

   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)