anchorage_layer_simple/fixKnowledge/api-anchorage-combine-utxos.md

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 :

   ps aux | grep "node.*api-anchorage" | grep -v grep | awk '{print $2}' | xargs kill
   

2. Redémarrer l'API :

   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)