# Correction : Combinaison de plusieurs petits UTXOs pour les ancrages avec provisionnement

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

## Problème Identifié

L'API d'ancrage retournait une erreur "No UTXO large enough for anchor with provisioning. Required: 0.00023055 BTC, Largest available: 0.000025 BTC" même lorsque le wallet contenait de nombreux petits UTXOs dont la somme était suffisante.

### Symptômes

- Erreur : "No UTXO large enough for anchor with provisioning. Required: 0.00023055 BTC, Largest available: 0.000025 BTC"
- Le wallet contient plusieurs petits UTXOs de 2500 sats (0.000025 BTC) créés par le provisionnement précédent
- Aucun UTXO assez grand individuellement pour créer une transaction avec provisionnement
- L'API ne peut pas créer de transaction d'ancrage malgré un solde total suffisant

## Cause Racine

La logique de sélection d'UTXOs cherchait uniquement un seul UTXO assez grand pour couvrir le montant total nécessaire (ancrage + 7 UTXOs de provisionnement + frais ≈ 0.00023055 BTC). 

**Problème technique** : Le système ne combinait pas plusieurs petits UTXOs pour atteindre le montant requis. Tous les UTXOs disponibles étaient des petits UTXOs de 2500 sats créés par le provisionnement précédent, mais aucun UTXO individuel n'était assez grand.

## Correctifs Appliqués

### Combinaison automatique de plusieurs UTXOs

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

**Modification** : Ajout d'une logique de combinaison automatique de plusieurs petits UTXOs si aucun UTXO assez grand n'est trouvé.

**Stratégie** :
1. Si aucun UTXO assez grand n'est trouvé, récupérer tous les petits UTXOs disponibles
2. Sélectionner les UTXOs par ordre décroissant jusqu'à atteindre le montant nécessaire
3. Ajuster l'estimation des frais pour tenir compte des inputs supplémentaires (~148 bytes par input)
4. Créer une transaction avec plusieurs inputs combinant tous les UTXOs sélectionnés
5. Verrouiller/déverrouiller tous les UTXOs de manière cohérente

**Détails techniques** :
- Limite de 20 UTXOs maximum pour éviter des transactions trop grandes
- Estimation des frais ajustée dynamiquement : +0.0000001 BTC par input supplémentaire
- Vérification de disponibilité de tous les UTXOs avant création de la transaction
- Marquage de tous les UTXOs comme dépensés après création réussie
- Déverrouillage de tous les UTXOs en cas d'erreur ou de retry

## Modifications

### Fichiers Modifiés

- `api-anchorage/src/bitcoin-rpc.js` :
  - Logique de sélection d'UTXOs : combine plusieurs petits UTXOs si nécessaire
  - Création de transaction : utilise plusieurs inputs au lieu d'un seul
  - Calcul du change : utilise `totalSelectedAmount` au lieu de `selectedUtxo.amount`
  - Vérification de disponibilité : vérifie tous les UTXOs sélectionnés
  - Gestion des erreurs : déverrouille et marque tous les UTXOs comme dépensés
  - Logs : inclut le nombre d'UTXOs combinés

## Modalités de Déploiement

### Redémarrage de l'API

1. **Arrêter l'API** :
   ```bash
   ps aux | grep "node.*api-anchorage" | grep -v grep | awk '{print $2}' | xargs kill
   ```

2. **Redémarrer l'API** :
   ```bash
   cd /srv/4NK/<domaine>/api-anchorage
   npm start
   ```

### Vérification

1. **Tester avec plusieurs petits UTXOs** :
   - Vérifier que l'API peut créer un ancrage même si tous les UTXOs sont petits
   - Vérifier que les logs indiquent "Combining multiple UTXOs for anchor transaction"

2. **Vérifier les transactions** :
   - Les transactions doivent avoir plusieurs inputs si plusieurs UTXOs sont combinés
   - Le change doit être calculé correctement avec le montant total des inputs

## Résultat

✅ **Problème résolu**

- L'API peut maintenant combiner plusieurs petits UTXOs pour créer un ancrage avec provisionnement
- Plus d'erreur "No UTXO large enough" si le solde total est suffisant
- Les transactions avec plusieurs inputs sont correctement créées et gérées
- Tous les UTXOs sont correctement verrouillés/déverrouillés et marqués comme dépensés

**Exemple de transaction avec UTXOs combinés** :
- Transaction : N inputs (petits UTXOs) → 1 OP_RETURN + 1 ancrage (2500 sats) + 7 provisioning (2500 sats chacun) + change
- Les frais sont ajustés pour tenir compte des inputs supplémentaires

## Prévention

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

1. **Combinaison automatique** : Le système combine maintenant automatiquement plusieurs petits UTXOs si nécessaire
2. **Limite de taille** : Limite de 20 UTXOs maximum pour éviter des transactions trop grandes
3. **Estimation des frais** : Les frais sont ajustés dynamiquement pour les transactions avec plusieurs inputs
4. **Gestion cohérente** : Tous les UTXOs sont gérés de manière cohérente (verrouillage, déverrouillage, marquage comme dépensé)

## Pages Affectées

- `api-anchorage/src/bitcoin-rpc.js` :
  - Fonction `createAnchorTransaction()` : Logique de combinaison de plusieurs UTXOs
  - Gestion des inputs multiples dans la création de transaction
  - Vérification et gestion de tous les UTXOs sélectionnés
- `fixKnowledge/api-anchorage-combine-utxos.md` : Documentation (nouveau)