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** :
   ```bash
   chmod +x data/sync-utxos-cron.sh
   ```

2. **Tester manuellement** :
   ```bash
   ./data/sync-utxos-cron.sh
   ```

3. **Vérifier les logs** :
   ```bash
   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)