anchorage_layer_simple/fixKnowledge/sync-utxos-rpc-optimization.md

Optimisation du script sync-utxos pour éviter les crashes RPC

Date: 2026-02-08
Auteur: Équipe 4NK

Problème

Le script sync-utxos-cron.sh s'exécute toutes les heures (à 3h00 notamment) et fait un appel RPC très lourd (listunspent avec maximumCount: 9999999). Avec un wallet volumineux (315MB) et potentiellement des centaines de milliers d'UTXOs, cet appel peut :

• Consommer beaucoup de mémoire
• Prendre beaucoup de temps (plusieurs minutes)
• Causer un crash de bitcoind si la mémoire est insuffisante ou si bitcoind est déjà dans un état fragile
• Bloquer le RPC pendant plusieurs minutes, empêchant les autres services de fonctionner

Symptômes observés

• Crash silencieux de bitcoind vers 3h08 (après l'exécution du script à 3h00)
• Erreurs "socket hang up" et "read ECONNRESET" dans les logs du dashboard
• Bitcoind bloqué en chargement de wallet après redémarrage
• Wallet volumineux (315MB) causant des chargements longs

Root causes

1. Appel RPC sans timeout : L'appel listunspent n'avait pas de timeout, pouvant bloquer indéfiniment
2. Pas de vérification préalable : Le script ne vérifiait pas si bitcoind était disponible avant de faire l'appel lourd
3. Pas de retry avec backoff : En cas d'échec temporaire, le script échouait immédiatement
4. Limite trop élevée : maximumCount: 9999999 pouvait charger des centaines de milliers d'UTXOs en mémoire d'un coup
5. Pas de gestion d'erreurs : Les erreurs n'étaient pas gérées de manière gracieuse

Correctifs appliqués

1. Ajout de timeout sur les appels RPC

Fichier : data/sync-utxos-spent-status.mjs

• Timeout de 5 minutes (300000ms) pour l'appel listunspent avec gros wallet
• Timeout de 10 secondes pour le healthcheck getblockchaininfo
• Les timeouts sont configurables via les paramètres de la fonction rpcCall

2. Vérification de santé de bitcoind avant synchronisation

Fichier : data/sync-utxos-spent-status.mjs

• Ajout de la fonction checkBitcoindHealth() qui vérifie que bitcoind répond avant de commencer
• Si bitcoind n'est pas disponible, le script s'arrête immédiatement sans faire d'appel RPC lourd

3. Retry avec backoff exponentiel

Fichier : data/sync-utxos-spent-status.mjs

• Ajout de retry automatique avec backoff exponentiel (1s, 2s, 4s, max 10s)
• Maximum 3 tentatives pour les erreurs de timeout/connexion
• Maximum 2 tentatives pour l'appel listunspent (pour éviter de surcharger bitcoind)

4. Réduction de la limite maximumCount

Fichier : data/sync-utxos-spent-status.mjs

• Réduction de maximumCount de 9999999 à 500000 UTXOs
• Limite la consommation mémoire et réduit le temps de traitement
• Si vous avez plus de 500000 UTXOs, il faudra augmenter cette limite ou optimiser l'approche

5. Amélioration du script cron

Fichier : data/sync-utxos-cron.sh

• Vérification que le conteneur bitcoind est actif avant d'exécuter le script Node.js
• Vérification que le RPC bitcoind répond avant de commencer
• Logs améliorés avec timestamps
• Gestion des codes de sortie pour permettre la détection d'échecs

6. Gestion d'erreurs améliorée

Fichier : data/sync-utxos-spent-status.mjs

• Distinction entre erreurs temporaires (timeout, connexion) et erreurs permanentes
• Messages d'erreur plus informatifs
• Le script ne fait pas échouer le cron si c'est un problème temporaire de bitcoind

Modifications

Fichiers modifiés :

• data/sync-utxos-spent-status.mjs :

  • Ajout de rpcCall() avec timeout et retry
  • Ajout de rpcCallOnce() avec timeout HTTP
  • Ajout de checkBitcoindHealth()
  • Réduction de maximumCount à 500000
  • Timeout de 5 minutes pour listunspent
  • Gestion d'erreurs améliorée

• data/sync-utxos-cron.sh :

  • Vérification de disponibilité de bitcoind avant exécution
  • Logs améliorés avec timestamps
  • Gestion des codes de sortie

Modalités de déploiement

1. Vérifier que les scripts sont exécutables :

   chmod +x data/sync-utxos-cron.sh
   

2. Tester manuellement :

   ./data/sync-utxos-cron.sh
   

3. Vérifier les logs :

   tail -f data/sync-utxos.log
   

4. Surveiller la prochaine exécution (à 3h00) pour vérifier que le problème est résolu

Modalités d'analyse

• Logs du script : data/sync-utxos.log (100 dernières lignes conservées)
• Vérifier les timeouts : Chercher "timeout" dans les logs
• Vérifier les retries : Chercher "Tentative" dans les logs
• Vérifier les erreurs : Chercher "❌" dans les logs

Prévention / suivi

• Surveillance : Surveiller les logs après chaque exécution pour détecter les problèmes
• Ajustement : Si vous avez plus de 500000 UTXOs, augmenter maximumCount ou optimiser l'approche
• Timeout : Si le timeout de 5 minutes est insuffisant, l'augmenter progressivement
• Investigation : En cas de répétition des problèmes, investiguer la mémoire disponible pour bitcoind

Pages affectées

• data/sync-utxos-spent-status.mjs (script de synchronisation amélioré)
• data/sync-utxos-cron.sh (script cron amélioré)
• fixKnowledge/sync-utxos-rpc-optimization.md (ce document)
• fixKnowledge/signet-bitcoind-crash-wallet-loading-stuck.md (documentation du problème)