Document UTXO synchronization fix
**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
This commit is contained in:
ncantu
parent
9929653ec2
commit
0b6c2bacc5
180
fixKnowledge/api-anchorage-no-utxos-available.md
Normal file
180
fixKnowledge/api-anchorage-no-utxos-available.md
Normal file
@ -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)
|
||||
Loading…
x
Reference in New Issue
Block a user