110 lines
5.9 KiB
Markdown
110 lines
5.9 KiB
Markdown
<!-- file: docs/SQL_DEMOS.md -->
|
||
<!-- version: 12 -->
|
||
|
||
# Démos SQL
|
||
|
||
## Fenêtres disponibles
|
||
|
||
| Fenêtre | Rôle |
|
||
|------------------------------|------------------------------------------------------------------------------------------------------|
|
||
| `demo_sql_diag` | Profil, backend, DSN masqué, santé PostgreSQL et tables attendues. |
|
||
| `demo_sql_pg_raw` | Transactions canoniques et observations d’acquisition. |
|
||
| `demo_sql_pg_core` | Transactions, comptes, instructions, inner instructions, logs, balances et ledger. |
|
||
| `demo_sql_replay_candidates` | Exploration read-only, filtrage et export des signatures, programmes, mints, owners et account keys. |
|
||
|
||
Depuis `0.3.4`, le diagnostic core inclut :
|
||
|
||
```text
|
||
kb_sol_ops_processing_ledger
|
||
```
|
||
|
||
La fenêtre `demo_core_extraction` exécute le worker puis permet d’ouvrir les diagnostics raw/core et le sélecteur de candidats. Les fenêtres SQL restent read-only et ne modifient aucune donnée.
|
||
|
||
## Sélecteur de candidats replay
|
||
|
||
`demo_sql_replay_candidates` sépare l’exploration en cinq tableaux DataTables avec intégration Bootstrap 5 :
|
||
|
||
1. transactions et signatures ;
|
||
2. programmes observés dans les instructions outer, inner et dans les logs reliés ;
|
||
3. mints ;
|
||
4. owners ;
|
||
5. account keys.
|
||
|
||
Les requêtes PostgreSQL sont statiques, paramétrées et limitées à `5 000` lignes au maximum par chargement. Aucun éditeur SQL libre n’est exposé.
|
||
|
||
### Transactions et signatures
|
||
|
||
Filtres serveur disponibles :
|
||
|
||
- fragment de signature ;
|
||
- plage inclusive de slots ;
|
||
- état raw ;
|
||
- statut du ledger `core_extraction` ;
|
||
- program ID exact avec portée `any`, `outer`, `inner` ou `logs` ;
|
||
- mint, owner ou account key exact ;
|
||
- limite et ordre des slots.
|
||
|
||
Le tableau affiche aussi la présence du graphe core, le statut du ledger, sa version et son nombre de tentatives, ainsi que les cardinalités outer/inner.
|
||
|
||
### Programmes
|
||
|
||
Le tableau agrège les occurrences issues de :
|
||
|
||
```text
|
||
kb_sol_core_instructions
|
||
kb_sol_core_inner_instructions
|
||
kb_sol_core_logs
|
||
```
|
||
|
||
Chaque ligne expose le code connu de `kb_program_ids` lorsqu’il existe, le nombre de transactions distinctes, d’instructions outer, d’instructions inner, de logs reliés et la plage de slots observée. Le filtre propose une liste des programmes enregistrés tout en conservant une saisie libre pour les identifiants inconnus ou partiels.
|
||
|
||
Pour appliquer un programme au tableau des transactions, il faut cocher exactement une ligne puis utiliser « Utiliser comme filtre transactions ». Lorsqu’aucune ligne n’est cochée, l’action accepte aussi une seule ligne restant après le filtre local DataTables.
|
||
|
||
### Mints, owners et comptes
|
||
|
||
Les trois familles disposent de tableaux et filtres indépendants. Les mints et owners proviennent de `kb_sol_core_balance_changes`; les account keys proviennent de `kb_sol_core_account_keys` et ne sont pas classifiées automatiquement comme wallet, pool, mint ou token account.
|
||
|
||
Chaque tableau affiche transactions distinctes, occurrences, occurrences par transaction, slots minimum/maximum et étendue. Une valeur sélectionnée peut être appliquée directement au filtre du tableau des transactions.
|
||
|
||
### Sélection et export
|
||
|
||
Dans chaque tableau :
|
||
|
||
- la première colonne contient une case à cocher gérée par l’extension DataTables Select ;
|
||
- la case du header sélectionne ou désélectionne toutes les lignes correspondant au filtre local ;
|
||
- une sélection explicite est prioritaire ;
|
||
- sans sélection, la copie et l’export utilisent toutes les lignes correspondant au filtre local DataTables ;
|
||
- les identifiants peuvent être copiés dans le presse-papiers sous forme multiligne ;
|
||
- le frontend construit un CSV diagnostique avec BOM UTF-8, séparateur `;` et CRLF ;
|
||
- une commande Rust bornée écrit le fichier dans `data/exports_csv/` et ajoute un suffixe lorsque le nom existe déjà ;
|
||
- les valeurs longues sont tronquées visuellement, exposées intégralement par tooltip et copiables cellule par cellule ;
|
||
- tous les tableaux affichent 10 lignes par défaut et possèdent un reset complet des filtres.
|
||
|
||
La copie multiligne des signatures peut être collée telle quelle dans le mode `Signatures explicites` de `demo_core_extraction`. L’export ne dépend plus du téléchargement HTML du WebView.
|
||
|
||
### Lecture des colonnes transactions
|
||
|
||
Les cardinalités sont séparées en quatre colonnes : `Outer inst.`, `Inner inst.`, `Outer pr.` et `Inner pr.`. Les deux premières comptent les instructions ; les deux dernières comptent les program IDs distincts.
|
||
|
||
La colonne `Core` décrit le graphe structurel :
|
||
|
||
- `absent` : aucune ligne `kb_sol_core_transactions` ;
|
||
- `présent` : graphe core présent et transaction Solana réussie ;
|
||
- `échec on-chain` : graphe core présent, mais la transaction Solana elle-même a retourné une erreur.
|
||
|
||
`échec on-chain` n’est donc pas un échec de l’extracteur. Le tri DataTables utilise un rang numérique distinct pour ces trois états.
|
||
|
||
### Pools et paires
|
||
|
||
Aucun onglet pool/pair n’est ajouté dans `0.3.4`. Le core connaît des account keys mais ne peut pas déterminer de façon fiable leur rôle sémantique. Les futurs décodeurs et matérialiseurs alimenteront les tables catalogues de pools et de paires ; l’onglet pourra alors reposer sur des identifiants explicites plutôt que sur une heuristique.
|
||
|
||
## Contrôles recommandés après extraction
|
||
|
||
- comparer le nombre de transactions raw `core_extracted` et de transactions core ;
|
||
- vérifier l’absence de lignes filles orphelines ;
|
||
- vérifier l’unicité des chemins et indices ;
|
||
- comparer les statuts ledger avec les graphes core présents ;
|
||
- examiner les lignes raw `failed` et leur `lifecycle_reason`.
|
||
|
||
Les requêtes prêtes à l’emploi sont dans `sql/validation/000_core_integrity.sql`.
|