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.

```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)