# UTXO-list : récupération frais et complétion historique (dates, blockTime)

**Auteur** : Équipe 4NK  
**Date** : 2026-01-26  
**Version** : 1.0

## Objectif

- Ajouter les dates manquantes dans `hash_list.txt` et compléter l'historique
- Compléter les `blockTime` manquants dans `utxo_list.txt` et compléter l'historique
- Récupérer les frais depuis les transactions d'ancrage (OP_RETURN) et les stocker
- Ajouter un bouton dans l'UI pour déclencher la récupération des frais

## Problème initial

- **hash_list.txt** : format sans date (`hash;txid;blockHeight;confirmations`)
- **utxo_list.txt** : `blockTime` souvent vide (dernier champ)
- **Frais** : absents du fichier (métadonnées OP_RETURN, non stockées)
- Pas de moyen de récupérer/compléter les frais depuis l'UI

## Impacts

- **hash_list.txt** : format étendu avec date (`hash;txid;blockHeight;confirmations;date`)
- **utxo_list.txt** : `blockTime` complété automatiquement lors des écritures futures
- **fees_list.txt** : nouveau fichier pour stocker les frais (`txid;fee;fee_sats;blockHeight;blockTime;confirmations;changeAddress;changeAmount`)
- **UI** : bouton "Récupérer les frais depuis les ancrages" dans section Frais
- **API** : endpoint `/api/utxo/fees/update` pour déclencher la récupération

## Modifications

### Serveur (`signet-dashboard/src/bitcoin-rpc.js`)

- **getHashList()** :
  - Format fichier : ajout colonne `date` (ISO 8601)
  - Lecture : rétrocompatible (gère format avec/sans date)
  - Écriture : ajoute date si manquante (date actuelle)

- **getUtxoList()** :
  - Lecture `fees_list.txt` : charge les frais depuis le fichier si disponible
  - Complète `blockTime` via RPC pour UTXOs confirmés sans `blockTime`

- **updateFeesFromAnchors()** (nouveau) :
  - Lit les ancrages depuis `utxo_list.txt`
  - Pour chaque transaction d'ancrage unique, récupère `getrawtransaction`
  - Extrait les frais depuis OP_RETURN (métadonnées `FEE:`)
  - Stocke dans `fees_list.txt` (format ci-dessus)
  - Ignore les frais déjà présents (évite doublons)

### Serveur (`signet-dashboard/src/server.js`)

- **Route `/api/utxo/fees/update`** (POST) :
  - Appelle `bitcoinRPC.updateFeesFromAnchors()`
  - Retourne `{success, newFees, totalFees, processed}`

### Page UTXO-list (`signet-dashboard/public/utxo-list.html`)

- **Bouton "Récupérer les frais depuis les ancrages"** :
  - Dans header section Frais
  - Spinner pendant traitement
  - Appelle `/api/utxo/fees/update`
  - Recharge la liste après succès

- **Fonction `updateFeesFromAnchors()`** :
  - Gère le spinner et les états du bouton
  - Affiche alert avec résultats

### Scripts batch (`scripts/`)

- **complete-hash-list-dates.js** :
  - Complète les dates manquantes dans `hash_list.txt`
  - Ajoute date actuelle si colonne absente ou vide

- **complete-utxo-list-blocktime.js** :
  - Complète les `blockTime` manquants dans `utxo_list.txt`
  - Récupère `blockTime` via RPC pour UTXOs confirmés sans `blockTime`

- **diagnose-bloc-rewards.js** :
  - Diagnostic Bloc Rewards (pourquoi ~4700 BTC au lieu de 50 BTC)
  - Compare `listunspent`, `getrawtransaction`, `blockheight`
  - Calcule subsidy attendu et frais

## Réponse : Frais dans les autres tableaux ?

**Non, les frais ne sont PAS des UTXOs.** Ce sont des **métadonnées** extraites de l'OP_RETURN des transactions d'ancrage. Ils sont :
- **Absents** de `utxo_list.txt` (ce ne sont pas des UTXOs)
- **Présents** dans le tableau `fees` retourné par `/api/utxo/list` (via RPC / OP_RETURN)
- **Stockés** dans `fees_list.txt` après utilisation du bouton de récupération

Les frais ne sont **pas comptés** dans les autres tableaux (Bloc Rewards, Ancrages, Changes). Ils sont dans un tableau séparé.

## Modalités de déploiement

1. **Redémarrer le dashboard** : `sudo systemctl restart signet-dashboard.service`
2. **Compléter l'historique** (optionnel) :
   ```bash
   node scripts/complete-hash-list-dates.js
   node scripts/complete-utxo-list-blocktime.js
   ```
3. **Récupérer les frais** : utiliser le bouton dans l'UI ou appeler `/api/utxo/fees/update`
4. **Diagnostic Bloc Rewards** (optionnel) :
   ```bash
   node scripts/diagnose-bloc-rewards.js
   ```

## Modalités d'analyse

- **Dates hash_list.txt** : vérifier que colonne date est présente
- **blockTime utxo_list.txt** : vérifier que dernier champ n'est plus vide pour UTXOs confirmés
- **Frais** : vérifier que `fees_list.txt` est créé et contient des frais après utilisation du bouton
- **UI** : vérifier que le bouton fonctionne et affiche le spinner

## Pages affectées

- `signet-dashboard/src/bitcoin-rpc.js` : `getHashList`, `getUtxoList`, `updateFeesFromAnchors`
- `signet-dashboard/src/server.js` : route `/api/utxo/fees/update`
- `signet-dashboard/public/utxo-list.html` : bouton et fonction `updateFeesFromAnchors`
- `scripts/complete-hash-list-dates.js` : nouveau
- `scripts/complete-utxo-list-blocktime.js` : nouveau
- `scripts/diagnose-bloc-rewards.js` : nouveau
- `features/utxo-list-fees-update-and-historical-completion.md` : cette doc