From 0b6c2bacc50132e5ef9105d6f4f700f2856b29a4 Mon Sep 17 00:00:00 2001 From: ncantu Date: Wed, 28 Jan 2026 15:30:51 +0100 Subject: [PATCH] Document UTXO synchronization fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Motivations:** - Documenter le problème de désynchronisation des UTXOs - Expliquer les solutions mises en place **Evolutions:** - Documentation du problème et des correctifs - Guide d'utilisation des scripts de synchronisation **Pages affectées:** - fixKnowledge/api-anchorage-no-utxos-available.md --- .../api-anchorage-no-utxos-available.md | 180 ++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 fixKnowledge/api-anchorage-no-utxos-available.md diff --git a/fixKnowledge/api-anchorage-no-utxos-available.md b/fixKnowledge/api-anchorage-no-utxos-available.md new file mode 100644 index 0000000..06e4ceb --- /dev/null +++ b/fixKnowledge/api-anchorage-no-utxos-available.md @@ -0,0 +1,180 @@ +# 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. + +```javascript +// 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** : +```bash +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** : +```bash +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** : + ```bash + sudo systemctl restart anchorage-api + ``` + +2. **Vérifier les logs** : + ```bash + sudo journalctl -u anchorage-api -f + ``` + +### Synchronisation manuelle (si nécessaire) + +Si le problème persiste, exécuter le script de synchronisation : + +```bash +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** : + ```bash + 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)