4nk/anchorage_layer_simple
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
anchorage_layer_simple/features/api-anchorage-automatic-consolidation.md
ncantu 7a6b9e8b6e Add automatic UTXO consolidation before anchor when funds insufficient 
**Motivations:**
- Consolider automatiquement les petits UTXOs avant un ancrage si les fonds sont insuffisants
- Améliorer l'efficacité en réduisant le nombre d'inputs dans les transactions
- Permettre l'ancrage même avec des fonds répartis sur plusieurs petits UTXOs

**Root causes:**
- Le wallet contient souvent de nombreux petits UTXOs (2500 sats) créés par le provisioning
- Les fonds sont répartis sur plusieurs petits UTXOs, rendant difficile la création d'ancrages avec provisioning complet
- La consolidation manuelle via le dashboard n'est pas automatique

**Correctifs:**
- Ajout d'une méthode attemptAutoConsolidation() qui appelle l'API du dashboard pour consolider
- Intégration de la consolidation automatique dans createAnchorTransaction() avant la réduction du provisioning
- Protection contre les abus : cooldown de 5 minutes, limite à la première tentative

**Evolutions:**
- Consolidation automatique déclenchée si au moins 5 petits UTXOs ET (fonds insuffisants OU > 10 petits UTXOs)
- Réessai automatique de l'ancrage après consolidation
- Fallback sur la réduction du provisioning si la consolidation échoue ou n'est pas suffisante

**Pages affectées:**
- api-anchorage/src/bitcoin-rpc.js
- features/api-anchorage-automatic-consolidation.md
2026-01-28 15:20:13 +01:00

4.8 KiB
Raw Blame History

Fonctionnalité : Consolidation automatique des UTXOs

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

Objectif

Permettre à l'API d'ancrage de consolider automatiquement les petits UTXOs avant un ancrage si les fonds sont insuffisants ou si le nombre de petits UTXOs est élevé.

Motivations

  • Problème : Le wallet contient souvent de nombreux petits UTXOs (2500 sats chacun) créés par le provisioning, ce qui rend difficile la création d'ancrages avec provisioning complet
  • Solution : Consolider automatiquement les petits UTXOs en un gros UTXO avant l'ancrage si nécessaire
  • Bénéfices :
    • Réduction des frais de transaction (moins d'inputs)
    • Facilitation de la sélection d'UTXOs (un seul gros UTXO au lieu de plusieurs petits)
    • Amélioration de l'efficacité globale
    • Ancrage réussi même avec des fonds répartis sur plusieurs petits UTXOs

Implémentation

Conditions de déclenchement

La consolidation automatique est déclenchée si :

  1. Au moins 5 petits UTXOs (< 2500 sats) sont disponibles
  2. ET l'une des conditions suivantes :
    • Les fonds disponibles sont insuffisants pour l'ancrage requis
    • Plus de 10 petits UTXOs sont disponibles (consolidation préventive)

Protection contre les abus

  • Cooldown de 5 minutes : Évite les consolidations trop fréquentes
  • Limite à la première tentative : La consolidation n'est tentée qu'une fois par ancrage (retryCount === 0)
  • Gestion des erreurs : Si la consolidation échoue, le système continue avec la réduction du provisioning

Processus

  1. Détection : Lors de la création d'un ancrage, si les fonds sont insuffisants et qu'il y a au moins 5 petits UTXOs
  2. Consolidation : Appel de l'API du dashboard (/api/utxo/consolidate) pour consolider les petits UTXOs
  3. Attente : Attente de 2 secondes pour la propagation de la transaction, puis 5 secondes supplémentaires pour la mise à jour de la base de données
  4. Réessai : Réessai de l'ancrage avec les nouveaux UTXOs consolidés
  5. Fallback : Si la consolidation échoue ou n'est pas suffisante, réduction automatique du provisioning

Modifications

Fichiers Modifiés

  • api-anchorage/src/bitcoin-rpc.js :
    • Ajout de lastConsolidationAttempt et consolidationCooldown dans le constructeur
    • Ajout de la méthode attemptAutoConsolidation()
    • Intégration de la consolidation automatique dans createAnchorTransaction()

Fichiers Créés

  • features/api-anchorage-automatic-consolidation.md : Cette documentation

Configuration

Variables d'environnement

  • DASHBOARD_API_URL : URL de l'API du dashboard (défaut : http://localhost:3020)
  • CONSOLIDATION_COOLDOWN : Délai minimum entre les consolidations en ms (défaut : 300000 = 5 minutes)

Seuils configurables

  • Nombre minimum de petits UTXOs : 5 (hardcodé)
  • Seuil pour consolidation préventive : 10 petits UTXOs (hardcodé)
  • Montant maximum pour "petit UTXO" : 2500 sats (0.000025 BTC, hardcodé)

Exemple d'utilisation

Scénario : Wallet avec 9 UTXOs de 0.000025 BTC chacun (total : 0.00021000 BTC), ancrage nécessite 0.00023145 BTC

  1. Détection : 9 petits UTXOs détectés, fonds insuffisants
  2. Consolidation : Les 9 UTXOs sont consolidés en 1 UTXO de ~0.0002 BTC (après frais)
  3. Réessai : L'ancrage est réessayé avec le nouveau UTXO consolidé
  4. Résultat : Ancrage réussi avec provisioning complet

Avantages

  1. Automatisation : Plus besoin d'intervention manuelle pour consolider
  2. Efficacité : Réduction des frais de transaction (moins d'inputs)
  3. Robustesse : Ancrage réussi même avec des fonds répartis
  4. Prévention : Consolidation préventive si trop de petits UTXOs

Limitations

  1. Cooldown : Une consolidation ne peut être tentée qu'une fois toutes les 5 minutes
  2. Dépendance : Nécessite que l'API du dashboard soit accessible
  3. Frais : La consolidation elle-même coûte des frais (~0.00001 BTC + frais par input)
  4. Confirmation : La consolidation doit être confirmée avant que les nouveaux UTXOs soient utilisables

Améliorations futures

  1. Consolidation périodique : Cron job pour consolider automatiquement les petits UTXOs
  2. Seuils configurables : Variables d'environnement pour les seuils
  3. Monitoring : Métriques sur les consolidations automatiques
  4. Optimisation : Consolider seulement si bénéfique (coût < gain)

Pages Affectées

  • api-anchorage/src/bitcoin-rpc.js :
    • Constructeur : Ajout des propriétés de cache pour la consolidation
    • Méthode attemptAutoConsolidation() : Nouvelle méthode pour la consolidation automatique
    • Méthode createAnchorTransaction() : Intégration de la consolidation automatique
  • features/api-anchorage-automatic-consolidation.md : Documentation (nouveau)