anchorage_layer_simple/features/utxo-list-fees-update-and-historical-completion.md

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

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

   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