khadhroony-bot3/migration/khadhroony-bot2-reference/docs/SQL_DEMOS.md

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 :

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 :

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.