anchorage_layer_simple/fixKnowledge/api-anchorage-no-utxos-available.md

Correction : Erreur "No available UTXOs in database"

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

Problème Identifié

L'API d'ancrage retournait une erreur "No available UTXOs in database (all are locked, spent, or unconfirmed)" même lorsque Bitcoin RPC indiquait que de nombreux UTXOs étaient disponibles.

Symptômes

• Erreur : "No available UTXOs in database (all are locked, spent, or unconfirmed)"
• Tous les UTXOs dans la base de données sont marqués comme dépensés (is_spent_onchain = 1)
• Bitcoin RPC indique que de nombreux UTXOs sont disponibles (214767 UTXOs)
• L'API ne peut pas créer de transaction d'ancrage

Cause Racine

Désynchronisation de la base de données : La base de données SQLite n'était pas synchronisée avec l'état réel des UTXOs dans Bitcoin. Tous les UTXOs étaient marqués comme dépensés alors qu'ils étaient disponibles dans Bitcoin.

Problème technique :

• La base de données peut être désynchronisée si la synchronisation automatique n'a pas été exécutée récemment
• Les UTXOs peuvent être mal marqués comme dépensés si une transaction échoue ou si la synchronisation est interrompue
• Aucune vérification automatique n'était effectuée avant de chercher des UTXOs

Correctifs Appliqués

1. Synchronisation automatique dans l'API anchorage

Fichier : api-anchorage/src/bitcoin-rpc.js

Modification : Ajout d'une synchronisation automatique si aucun UTXO n'est disponible dans la base de données.

// Si aucun UTXO disponible dans la DB, vérifier avec Bitcoin RPC si des UTXOs sont réellement disponibles
if (availableUtxos.length === 0) {
  // Récupérer tous les UTXOs disponibles depuis Bitcoin
  const unspent = await this.callRPCCommandWithRetry('listunspent', 1, 9999999);
  
  if (unspent.length > 0) {
    // Créer une table temporaire et synchroniser
    // Mettre à jour les UTXOs existants comme non dépensés s'ils sont disponibles
    // Réessayer la requête après synchronisation
  }
}

Impact : L'API synchronise automatiquement les UTXOs depuis Bitcoin RPC si aucun UTXO n'est disponible, évitant les erreurs de désynchronisation.

2. Script de correction des UTXOs mal marqués

Fichier : api-anchorage/fix-utxos-status.mjs

Fonctionnalité : Script pour corriger les UTXOs mal marqués comme dépensés.

• Vérifie tous les UTXOs marqués comme dépensés
• Compare avec listunspent depuis Bitcoin RPC
• Met à jour le statut is_spent_onchain pour les UTXOs réellement disponibles

Usage :

node api-anchorage/fix-utxos-status.mjs

3. Script de synchronisation complète

Fichier : api-anchorage/sync-utxos-from-bitcoin.mjs

Fonctionnalité : Script pour synchroniser tous les UTXOs disponibles depuis Bitcoin RPC.

• Récupère tous les UTXOs disponibles depuis Bitcoin RPC
• Met à jour le statut is_spent_onchain pour les UTXOs existants
• Synchronise la base de données avec l'état réel de Bitcoin

Usage :

node api-anchorage/sync-utxos-from-bitcoin.mjs

Modifications

Fichiers Modifiés

• api-anchorage/src/bitcoin-rpc.js :
  • Ajout de la synchronisation automatique dans createAnchorTransaction()
  • Vérification avec Bitcoin RPC si aucun UTXO n'est disponible
  • Mise à jour automatique du statut is_spent_onchain

Fichiers Créés

• api-anchorage/fix-utxos-status.mjs : Script de correction des UTXOs mal marqués
• api-anchorage/sync-utxos-from-bitcoin.mjs : Script de synchronisation complète
• fixKnowledge/api-anchorage-no-utxos-available.md : Cette documentation

Modalités de Déploiement

Redémarrage de l'API

1. Redémarrer l'API :

   sudo systemctl restart anchorage-api
   

2. Vérifier les logs :

   sudo journalctl -u anchorage-api -f
   

Synchronisation manuelle (si nécessaire)

Si le problème persiste, exécuter le script de synchronisation :

cd /home/ncantu/Bureau/code/bitcoin
node api-anchorage/sync-utxos-from-bitcoin.mjs

Modalités d'Analyse

Vérification que la correction fonctionne

1. Vérifier les statistiques UTXOs :

   cd api-anchorage
   node diagnose.mjs
   

   • Doit afficher des UTXOs disponibles (> 0)

2. Vérifier les logs de l'API :

   • Les logs doivent indiquer "Synchronized UTXOs with Bitcoin RPC" si une synchronisation a été effectuée
   • Plus d'erreur "No available UTXOs in database"

3. Tester un ancrage :

   • L'ancrage doit réussir avec des UTXOs disponibles
   • Plus d'erreur de désynchronisation

Cas limites

1. Base de données complètement désynchronisée :

   • La synchronisation automatique doit corriger le problème
   • Le script de synchronisation manuelle peut être utilisé si nécessaire

2. Tous les UTXOs réellement dépensés :

   • L'erreur est légitime si tous les UTXOs sont réellement dépensés
   • Il faut obtenir plus de fonds via le faucet ou le mining

3. Synchronisation en cours :

   • La synchronisation automatique peut prendre quelques secondes
   • L'API attend la synchronisation avant de réessayer

Résultat

✅ Problème résolu

• Synchronisation automatique des UTXOs depuis Bitcoin RPC si aucun UTXO n'est disponible
• Scripts de diagnostic et de correction pour maintenir la cohérence
• L'API peut maintenant créer des ancrages même si la base de données est temporairement désynchronisée

Exemple de synchronisation réussie :

• UTXOs disponibles dans Bitcoin : 214767
• UTXOs mis à jour dans la base de données : 214767
• UTXOs disponibles après synchronisation : 214767

Prévention

Pour éviter ce problème à l'avenir :

1. Synchronisation automatique : L'API synchronise automatiquement les UTXOs si aucun n'est disponible
2. Scripts de maintenance : Utiliser les scripts de synchronisation régulièrement
3. Monitoring : Surveiller les statistiques UTXOs avec diagnose.mjs
4. Synchronisation périodique : Considérer l'ajout d'un cron job pour synchroniser périodiquement

Pages Affectées

• api-anchorage/src/bitcoin-rpc.js :
  • Fonction createAnchorTransaction() : Synchronisation automatique des UTXOs
  • Vérification avec Bitcoin RPC si aucun UTXO n'est disponible
• api-anchorage/fix-utxos-status.mjs : Script de correction (nouveau)
• api-anchorage/sync-utxos-from-bitcoin.mjs : Script de synchronisation (nouveau)
• fixKnowledge/api-anchorage-no-utxos-available.md : Documentation (nouveau)