anchorage_layer_simple/features/api-anchorage-automatic-consolidation.md

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