anchorage_layer_simple/docs/DASHBOARD.md

# Dashboard - Pages et Fonctionnalités

**Auteur** : Équipe 4NK
**Date** : 2026-01-28
**Version** : 1.1

## Vue d'Ensemble

Le Dashboard Bitcoin Signet est une interface web de supervision et de test accessible à l'adresse `https://dashboard.certificator.4nkweb.com`.

**Port local :** 3020 (fixe, défini dans le service systemd)

## Pages Disponibles

### 1. Page Principale (`/` ou `/index.html`)

**Fichier :** `signet-dashboard/public/index.html`

**Fonctionnalités :**

#### Section Supervision
- **État de la Blockchain**
  - Hauteur de bloc (mise à jour automatique)
  - Dernier bloc miné (timestamp)
  - Transactions dans le dernier bloc
  - Taille du dernier bloc
  - Hash du dernier bloc
  - Difficulté de mining
  - Taux de hash moyen

- **Statistiques du Réseau**
  - Nombre de pairs connectés
  - Taille totale de la blockchain
  - Taux de transactions par seconde
  - Frais moyens des transactions
  - Montant moyen des transactions

- **État du Wallet**
  - Solde mature
  - Solde immature
  - Solde non confirmé
  - Solde total
  - Nombre d'UTXO

- **Statistiques d'Ancrage**
  - Nombre total d'ancrages
  - **Capacité d'ancrage restante** : Nombre d'ancrages possibles avec les UTXOs disponibles
    - Affiche le nombre total d'ancrages possibles
    - Affiche le nombre d'UTXOs confirmés disponibles (sous-titre)

#### Section Test de l'API d'Ancrage
- **Saisie de Texte**
  - Champ texte pour saisir du contenu
  - Génération automatique du hash SHA256
  - Vérification du hash sur la blockchain
  - Ancrage du document

- **Sélection de Fichier**
  - Upload de fichier
  - Génération automatique du hash SHA256
  - Vérification du hash sur la blockchain
  - Ancrage du document

- **Options de Filigrane**
  - Activation/désactivation du filigrane
  - Texte libre du filigrane
  - Signature cryptographique
  - Nom du dépositaire
  - Options de date (UTC, locale)
  - Options blockchain (numéro de bloc, hash du bloc, hash du document)
  - Noms de fichiers personnalisables

- **Résultats**
  - Affichage des hash (original et filigrané)
  - Liens cliquables vers mempool.4nkweb.com pour les TXID
  - Statut des transactions
  - Confirmations
  - Téléchargement automatique des fichiers :
    1. Document original
    2. Document filigrané
    3. Certificat PDF
    4. Document fusionné (filigrané + certificat)

#### Section Faucet
- **Demande de Sats**
  - Champ pour saisir une adresse Bitcoin Signet
  - Distribution de 50 000 sats (0.0005 BTC)
  - Affichage du TXID et du statut

### 2. Page Liste des Hash (`/hash-list`)

**Fichier :** `signet-dashboard/public/hash-list.html`

**Fonctionnalités :**
- Liste des hash ancrés (source : base SQLite, `GET /api/hash/list?page=&limit=`)
- Informations pour chaque hash : hash SHA256, TXID, hauteur de bloc, confirmations, date ; liens vers mempool.4nkweb.com
- Pagination côté serveur

### 3. Page Liste des UTXO (`/utxo-list`)

**Fichier :** `signet-dashboard/public/utxo-list.html`

**Fonctionnalités :**
- Liste de tous les UTXO du wallet, catégorisés par type :
  - 💰 Bloc Rewards (récompenses de minage)
  - 🔗 Ancrages (transactions d'ancrage, 2500 sats chacun)
  - 🔄 Changes (monnaie de retour)
  - 💸 Frais (transactions avec frais onchain)
- Informations pour chaque UTXO :
  - TXID (lien vers mempool.4nkweb.com)
  - Index de sortie (vout)
  - Montant (en BTC et sats)
  - Adresse
  - Confirmations
  - Statut (Disponible, Verrouillé, Dépensé onchain)
- **Pagination** : chargement par catégorie avec `?category=&page=&limit=` (ex. 100 UTXOs par page), contrôles précédent/suivant
- **Tri** : Tri par montant ou confirmations (croissant/décroissant) en cliquant sur les en-têtes
- **Capacité d'ancrage restante** : Affiche le nombre d'ancrages possibles et le nombre d'UTXOs confirmés disponibles
- **Consolidation** : Bouton pour consolider les petits UTXOs (< 2500 sats) en un gros UTXO (`POST /api/utxo/consolidate`)
  - Affiche dynamiquement le nombre d'UTXOs et le montant total concernés
  - Désactivé si aucun UTXO à consolider
- **Récupérer les frais** : Bouton « Récupérer les frais depuis les ancrages » appelant `POST /api/utxo/fees/update`
- **Filtrage confirmés** : Seuls les UTXOs avec au moins 1 confirmation sont affichés (pour éviter les erreurs "too-long-mempool-chain")
- Export des données (fichier texte téléchargeable)

### 4. Page Rejoindre le Réseau (`/join-signet`)

**Fichier :** `signet-dashboard/public/join-signet.html`

**Fonctionnalités :**
- Instructions pour rejoindre le réseau Signet
- Informations de connexion :
  - Adresse IP du nœud
  - Port P2P (38333)
  - Challenge du signet
  - Magic number
- Commandes pour configurer un nouveau nœud
- Liens vers la documentation

### 5. Page Documentation API (`/api-docs`)

**Fichier :** `signet-dashboard/public/api-docs.html`

**Fonctionnalités :**
- Documentation complète de toutes les APIs
- Endpoints documentés :
  - API d'Ancrage (`/api/anchor/document`, `/api/anchor/verify`), Faucet, Filigrane, ClamAV
  - **API Dashboard** : `/api/utxo/count`, `/api/utxo/list` (pagination, catégories), `/api/utxo/fees`, `POST /api/utxo/fees/update`, `/api/utxo/small-info`, `POST /api/utxo/consolidate`, `/api/hash/list` (pagination), `POST /api/hash/generate`, `/api/mining/difficulty`, `/api/mining/avg-block-time`, `/api/transactions/avg-fee`, `/api/transactions/avg-amount`, `/api/anchor/example`, etc.
- Exemples de requêtes curl, paramètres (query/body), réponses
- Codes de statut HTTP, authentification (APIs externes), format des réponses

### 6. Page Apprendre Bitcoin (`/learn`)

**Fichier :** `signet-dashboard/public/learn.html`

**Fonctionnalités :**
- Ressources éducatives sur Bitcoin
- Concepts de base :
  - Blockchain
  - Transactions
  - Mining
  - Wallets
  - Signet vs Testnet
- Liens vers des ressources externes
- Glossaire des termes

## Navigation

### Menu Principal

Le menu principal est accessible depuis toutes les pages :

- **Dashboard** : Retour à la page principale
- **Explorer Mempool** : Lien vers mempool.4nkweb.com
- **Liste des Hash** : Page de liste des hash
- **Liste des UTXO** : Page de liste des UTXO
- **Rejoindre le Réseau** : Instructions pour rejoindre
- **Documentation API** : Documentation complète
- **Apprendre Bitcoin** : Ressources éducatives

## Mise à Jour Automatique

### Rafraîchissement des Données

- **Métriques principales** : Toutes les 30 secondes
- **Détection de nouveaux blocs** : Polling toutes les 5 secondes
- **Actualisation des métriques** : Automatique lors de la détection d'un nouveau bloc

### Notifications

- Affichage des résultats d'ancrage en temps réel
- Messages d'erreur clairs et détaillés
- Indicateurs de chargement pour les opérations asynchrones

## Fonctionnalités Avancées

### Test de l'API d'Ancrage avec Filigrane

1. **Saisie ou Upload**
   - Texte ou fichier
   - Génération automatique du hash

2. **Configuration du Filigrane**
   - Options personnalisables
   - Avertissement de sécurité affiché

3. **Traitement**
   - Scan antivirus automatique (ClamAV)
   - Conversion en PDF si nécessaire
   - Ajout du filigrane
   - Ancrage sur la blockchain (2 transactions : original + filigrané)
   - Génération du certificat PDF
   - Fusion du PDF filigrané et du certificat

4. **Résultats**
   - Affichage des hash et TXID avec liens
   - Téléchargement automatique de 4 fichiers PDF
   - Résultat du scan antivirus inclus

### Intégration avec Mempool

- Liens cliquables vers mempool.4nkweb.com pour chaque TXID
- Liens également présents dans les PDFs de certificat

## API Endpoints Utilisés

Le dashboard utilise les endpoints suivants. Tous les endpoints internes sont servis par le Dashboard (port 3020), sans authentification.

### Endpoints internes (Dashboard)

- `GET /api/blockchain/info` : Informations sur la blockchain
- `GET /api/blockchain/latest-block` : Dernier bloc miné
- `GET /api/wallet/balance` : Solde du wallet
- `GET /api/network/peers` : Nombre de pairs
- `GET /api/anchor/count` : Nombre d'ancrages
- `GET /api/utxo/count` : Compteurs UTXO (ancrages, disponibles pour ancrage, confirmés) ; optimisé, pas de liste
- `GET /api/utxo/list` : Liste des UTXO (pagination serveur, base SQLite)
  - Query : `category` (all | bloc_rewards | ancrages | changes | fees), `page`, `limit`
  - `category=all` : uniquement les counts (blocRewards, anchors, changes, fees, total, availableForAnchor, confirmedAvailableForAnchor)
  - Sinon : données paginées + `pagination` (category, page, limit, total, totalPages)
- `GET /api/utxo/fees` : Liste des frais (transactions d'ancrage, métadonnées OP_RETURN)
- `POST /api/utxo/fees/update` : Récupère les frais depuis les ancrages et les enregistre (body optionnel : `sinceBlockHeight`)
- `GET /api/utxo/small-info` : Petits UTXOs (< 2500 sats) disponibles pour consolidation
- `POST /api/utxo/consolidate` : Consolide les petits UTXOs en un gros UTXO
- `GET /api/hash/list` : Liste des hash ancrés (pagination : `page`, `limit`)
- `POST /api/hash/generate` : Génère un hash SHA256 (body : `text` ou `fileContent`, optionnel `isBase64`)
- `GET /api/mining/difficulty` : Difficulté de minage
- `GET /api/mining/avg-block-time` : Temps moyen entre blocs (Mempool)
- `GET /api/transactions/avg-fee` : Frais moyen ancrages (1200 sats)
- `GET /api/transactions/avg-amount` : Montant moyen ancrages (1000 sats)
- `GET /api/anchor/example` : Exemple de transaction d'ancrage (page Learn)
- `POST /api/anchor/verify` : Vérification d'un hash (proxy vers API ancrage ; body : `hash`, `txid?`, `apiKey`)
- `POST /api/anchor/test` : Test d'ancrage (proxy vers API ancrage ; body : `hash`, `apiKey`)
- `POST /api/watermark/document` : Ancrage avec filigrane (proxy vers API filigrane)

### Endpoints externes

- `https://certificator.4nkweb.com/api/anchor/document` : API d'ancrage
- `https://watermark.certificator.4nkweb.com/api/watermark/document` : API filigrane
- `https://faucet.certificator.4nkweb.com/api/faucet/request` : API faucet
- `https://mempool.4nkweb.com/fr/tx/{txid}` : Explorateur de transactions

Le Dashboard n'expose pas de route `/health`. Pour vérifier qu'il répond, utiliser par exemple `GET /api/blockchain/info`.

## Styles et Thème

**Fichier CSS :** `signet-dashboard/public/styles.css`

- Design moderne et responsive
- Thème sombre/clair selon les préférences
- Couleurs cohérentes avec l'identité visuelle
- Accessibilité (ARIA, clavier, contraste)

## JavaScript

**Fichier principal :** `signet-dashboard/public/app.js`

- Gestion de toutes les interactions
- Appels API asynchrones
- Mise à jour automatique des données
- Gestion des erreurs
- Téléchargement de fichiers

## Maintenance

### Vérifier que le dashboard fonctionne

```bash
# Vérifier le service
sudo systemctl status signet-dashboard

# Vérifier les logs
sudo journalctl -u signet-dashboard -f

# Tester l'accès (le Dashboard n'expose pas /health)
curl -s http://localhost:3020/api/blockchain/info | head -c 200
```

### Redémarrer le dashboard

```bash
sudo systemctl restart signet-dashboard
```

## Références

- [Documentation Domaines et Ports](./DOMAINS_AND_PORTS.md)
- [Documentation Environnement](./ENVIRONMENT.md)
- [Documentation Maintenance](./MAINTENANCE.md)
- [Documentation API](../signet-dashboard/public/api-docs.html)