145 lines
15 KiB
Markdown
145 lines
15 KiB
Markdown
<!-- file: kb_app_demo/README.md -->
|
||
<!-- version: 35 -->
|
||
|
||
# kb_app_demo
|
||
|
||
Application Tauri de démonstration pour valider progressivement les briques runtime de `khadhroony-bot2`.
|
||
|
||
## Fenêtres disponibles
|
||
|
||
- `main` : accueil et rendu du README workspace ;
|
||
- `demo_config` : configuration active, profil actif et schéma JSON ;
|
||
- `demo_http` : test manuel du pool HTTP JSON-RPC standard ;
|
||
- `demo_ws` : test manuel des neuf subscriptions standard via la session persistante typée de `kb_rpc` ;
|
||
- `demo_backfill` : campagnes HTTP bornées par signatures, programme, token ou pool ;
|
||
- `demo_core_extraction` : extraction canonique vers core par signatures, pending, plage de slots ou program id ;
|
||
- `demo_decode_replay` : replay commun de décodage et matérialisation par signatures, programme, état et instruction path ;
|
||
- `demo_execution_solana_core` : fenêtre unique de simulation et d’exécution System transfer, SPL Memo v4, SPL Token `TransferChecked` ou création ATA sur Devnet, avec wallet persistant, confirmation opérateur et replay post-exécution ;
|
||
- `demo_sql_diag`, `demo_sql_pg_raw`, `demo_sql_pg_core` : diagnostics PostgreSQL ;
|
||
- `demo_sql_replay_candidates` : filtres read-only et exports de signatures, programmes et entités ;
|
||
- `splash` : écran de chargement.
|
||
|
||
## Commande de développement
|
||
|
||
```bash
|
||
cargo tauri dev -c kb_app_demo/tauri.conf.json
|
||
```
|
||
|
||
|
||
## Démo WebSocket `0.4.2-pre.025`
|
||
|
||
`demo_ws` est désormais un adaptateur Tauri mince vers `kb_rpc::WsSession`. La fenêtre sélectionne un rôle et une méthode, convertit les champs UI en `StandardWsRequest`, affiche les souscriptions actives et relaie les événements typés avec une limitation de débit vers la WebView. Elle ne gère plus directement la socket, les IDs JSON-RPC, les réponses subscribe/unsubscribe, les timeouts, la reconnexion ou le réabonnement.
|
||
|
||
La même connexion reste partagée entre les subscriptions compatibles d’un endpoint. Les trois méthodes instables ne sont disponibles que lorsque la configuration de l’endpoint annonce explicitement leur request kind. Si le nœud rejette une de ces méthodes comme absente ou non activée, `kb_rpc` désactive automatiquement sa capacité pour la session. Les IDs distants affichés sont actualisés après un réabonnement ; l’identifiant local stable reste interne à la bibliothèque.
|
||
|
||
Les payloads Tauri actifs utilisent des nombres JSON et non des `BigInt`. Le frontend refuse tout identifiant d’unsubscribe qui n’est pas un entier sûr JavaScript avant d’appeler `invoke`.
|
||
|
||
## Démo backfill `0.3.3`
|
||
|
||
`demo_backfill` construit des requêtes bornées vers le moteur réutilisable de `kb_pipeline`, affiche les événements de progression et permet un arrêt coopératif. La fenêtre n’implémente elle-même ni pagination RPC ni persistance.
|
||
|
||
## Démo extraction core `0.3.4`
|
||
|
||
`demo_core_extraction` réutilise le template global et des accordéons Bootstrap 5. Elle expose :
|
||
|
||
- signatures explicites ;
|
||
- lot raw en état `received` ;
|
||
- plage inclusive de slots ;
|
||
- replay par program id déjà présent dans core ;
|
||
- limite, concurrence, force replay par signatures et mode explicite « toutes les signatures » ;
|
||
- version du processor ;
|
||
- journal borné, résumé JSON et arrêt coopératif.
|
||
|
||
La logique profonde reste dans `kb_pipeline`. Tauri ne construit que la requête, connecte `kb_store_pg` et relaie les événements.
|
||
|
||
## Démo candidats replay SQL `0.3.4`
|
||
|
||
`demo_sql_replay_candidates` utilise DataTables avec les intégrations Bootstrap 5 et Select. Elle expose cinq tableaux indépendants :
|
||
|
||
- transactions/signatures filtrables par raw, ledger, slots, programme et entité ;
|
||
- programmes agrégés depuis outer instructions, inner instructions et logs reliés ;
|
||
- mints issus des balance changes core ;
|
||
- owners issus des balance changes core ;
|
||
- account keys issus des comptes résolus core.
|
||
|
||
Les requêtes PostgreSQL sont statiques, paramétrées et bornées. Chaque ligne possède une case à cocher et le header permet de sélectionner ou désélectionner toutes les lignes filtrées. DataTables affiche dix lignes par défaut. Les lignes sélectionnées, ou à défaut les lignes correspondant au filtre local, peuvent être copiées sous forme multiligne ou exportées en CSV. Le frontend produit un CSV UTF-8 avec BOM et séparateur point-virgule, puis une commande Rust l’écrit sous `./data/exports_csv/` sans écraser un fichier existant. LibreOffice Calc peut conserver son dialogue d’import de texte, car CSV ne transporte pas de métadonnées normalisées d’encodage ou de séparateur. Le sélecteur de programmes connus est alimenté par le registre énumérable de `kb_program_ids`. La copie des signatures est directement réutilisable dans `demo_core_extraction`.
|
||
|
||
Les tableaux mints, owners et comptes exposent les transactions distinctes, les occurrences core, le ratio occurrences par transaction, les slots minimum et maximum et leur étendue. Les headers documentent ces métriques avec des tooltips Bootstrap 5.
|
||
|
||
Les cartes de filtres possèdent un bouton `Réinitialiser` qui restaure leurs valeurs par défaut, efface le filtre local DataTables, annule la sélection courante et recharge le tableau. Les limites sont contrôlées contre `maximumLimit` avant l’invocation Tauri ; une valeur supérieure à la borne backend n’est plus envoyée à PostgreSQL. Les signatures, program IDs, mints, owners et account keys sont tronqués visuellement pour conserver des tableaux lisibles. Leur valeur complète reste accessible par tooltip et par une action de copie individuelle directement dans la cellule, en complément des copies multiligne.
|
||
|
||
## Politique future pour les transactions Solana échouées
|
||
|
||
Les futures étapes de décodage doivent traiter les transactions confirmées dont `meta.err` est renseigné. Leur message, leurs instructions, leurs inner instructions disponibles, leurs logs, leur erreur et leur consommation de ressources restent des données d’observation importantes. Elles doivent être décodées avec un statut explicite d’échec on-chain et ne doivent pas être confondues avec un échec du pipeline.
|
||
|
||
La matérialisation doit rester prudente : aucune mutation métier supposée réussie ne doit être produite à partir d’une transaction atomiquement annulée. Les événements d’intention, d’échec, d’audit, de diagnostic et les frais réellement prélevés peuvent en revanche être conservés dans des familles dédiées.
|
||
|
||
## Démo replay decode `0.4.0`
|
||
|
||
`demo_decode_replay` consomme les inputs contextualisés déjà présents dans core. La fenêtre expose les signatures copiées depuis `demo_sql_replay_candidates`, le program ID, les états d’instruction, les instruction paths, les décodeurs disponibles, leur version, la concurrence bornée, le force replay sécurisé, l’arrêt coopératif et la matérialisation optionnelle uniquement lorsqu’un matérialiseur est enregistré. Elle affiche les événements de progression, le résumé par processor ainsi que des diagnostics read-only sur les tables decode, mat, ledger et couverture. Elle propose aussi un journal borné des annotations de transaction commitées, filtrable par signature ; cette vue typée ne donne pas accès au JSON libre ni aux autres familles matérialisées.
|
||
|
||
Pour valider Memo sur un corpus réel, l’opérateur enchaîne `demo_backfill`, `demo_core_extraction`, la sélection dans `demo_sql_replay_candidates`, puis `demo_decode_replay` avec `spl_memo` et l’option de matérialisation. Le journal d’annotations doit alors afficher la signature et le path attendus. Un second replay sans force doit être compté comme `skipped` et ne doit créer aucune annotation supplémentaire.
|
||
|
||
À partir de `pre.020`, la démo enregistre trois matérialiseurs natifs : lifecycle, admin et compliance audit. `0.4.3-pre.002` ajoute staking et les annotations de transaction Memo. Le pipeline sélectionne chacun par surface/entrée exacte ; une observation non pertinente ne crée ni ledger ni refus artificiel.
|
||
|
||
La première implémentation concrète est le classifieur `solana_core_native`, qui reconnaît toutes les surfaces natives enregistrées et les classe `unsupported` tant que leur décodage maximal n’est pas implémenté en `0.4.1`. Cette classification volontaire évite tout faux événement tout en alimentant la couverture observée.
|
||
|
||
## Démo exécution Solana Core `0.4.2-pre.010`
|
||
|
||
`demo_execution_solana_core` est un adaptateur Tauri mince vers `kb_pipeline::execute_devnet_system_transfer`. La fenêtre ne propose que les profils Devnet dont le wallet temporaire est activé et persistant. Elle permet :
|
||
|
||
- de générer une adresse destinataire jetable sans exposer sa clé privée ;
|
||
- de simuler le message exact sans signature ni envoi ;
|
||
- de signer et envoyer après confirmation opérateur explicite ;
|
||
- d’afficher le plan, les comptes et signataires requis, les plafonds, l’erreur et les logs de simulation ;
|
||
- de suivre l’envoi, la confirmation, l’insertion canonique, l’extraction core et le decode replay ciblé ;
|
||
- de demander une annulation coopérative entre deux étapes.
|
||
|
||
Le backend vérifie l’existence du destinataire et refuse un transfert inférieur au minimum rent-exempt lorsque l’adresse est neuve. Les secrets restent confinés dans `kb_wallet`; les payloads TS-rs ne contiennent que des clés publiques et des diagnostics. Les opérations administratives natives plus dangereuses restent hors de cette fenêtre même lorsqu’elles seront disponibles dans les bibliothèques.
|
||
|
||
`0.4.3-pre.005` ajoute dans cette même fenêtre un panneau SPL Memo v4, sans nouvelle WebView. Il appelle `kb_pipeline::execute_devnet_memo`, reste en simulation seule par défaut et réutilise le verrou, le profil et la confirmation opérateur du parcours System. Après un envoi autorisé, le résumé affiche la signature, la confirmation, l’insertion canonique, l’extraction core, le decode replay, le nombre d’annotations `transaction_annotation` et la validation du second replay idempotent. Les soldes et frais Memo sont sérialisés en chaînes décimales afin de préserver leur exactitude aux frontières JSON Tauri.
|
||
|
||
La validation Tauri réelle a couvert le refus d’envoi sans confirmation, une simulation Memo réussie et trois envois v4 confirmés. Chaque résumé terminal a indiqué `annotationCount=1` et `idempotenceValidated=true`. Le clic accidentel sur le bouton System sans destinataire produit indépendamment le refus attendu « Le destinataire est obligatoire » et ne concerne pas le parcours Memo.
|
||
|
||
`0.4.4-pre.007` ajoute dans la même WebView un panneau SPL Token limité à `TransferChecked`, choisi comme parcours opérateur représentatif et non destructif. Le montant brut reste une chaîne décimale, le mint et les decimals sont explicites, et le backend affiche séparément préflight stateful, plan, simulation, confirmation, extraction, decode, nombre de matérialisations et second replay idempotent. La simulation reste le comportement par défaut ; l’envoi exige la confirmation commune et une autorité résolue par le wallet du profil.
|
||
|
||
La même fenêtre expose un journal read-only de `kb_sol_mat_events` borné à 500 lignes. Les filtres de signature, mint, compte, famille et opération sont contrôlés ; mint, compte et opération sont comparés exactement au payload typé après la requête PostgreSQL bornée. Le tableau montre slot, opération, famille, montant brut et signature, puis le payload JSON complet de la ligne sélectionnée. Il ne reconstruit ni snapshot final, ni solde, ni OHLC.
|
||
|
||
La validation Tauri du 15 juillet 2026 a démarré Vite et l'application, initialisé le schéma
|
||
PostgreSQL, puis réussi le préflight et la simulation Token. Le bouton d'envoi a d'abord été refusé
|
||
sans confirmation opérateur, puis refusé avec un diagnostic exact lorsque l'autorité Token fournie
|
||
ne correspondait pas au wallet persistant du profil. Ce comportement est attendu : la WebView ne
|
||
transporte aucune clé externe et l'orchestrateur ne peut signer qu'avec le wallet sélectionné. Un
|
||
envoi depuis cette fenêtre exige donc des comptes dont l'autorité est ce wallet ; le parcours
|
||
backend Devnet aligné a déjà validé l'envoi et la matérialisation complets.
|
||
|
||
`0.4.5-pre.005` ajoute dans la même fenêtre le panneau SPL Associated Token Account. Il sélectionne
|
||
le Token Program classique ou Token-2022, dérive l'ATA readonly depuis wallet, programme et mint,
|
||
puis propose `Create` ou `CreateIdempotent`. Le backend conserve simulation seule par défaut,
|
||
affiche préflight, plafond rent/frais et postconditions, et exige la confirmation commune avant
|
||
l'envoi. Après confirmation, il hydrate la transaction, extrait le core, décode les instructions
|
||
ATA et CPI Token, matérialise leurs faits propriétaires puis vérifie un second replay idempotent.
|
||
|
||
Le journal ATA réutilise la requête PostgreSQL bornée du journal Token et limite la vue aux faits
|
||
lifecycle du processor `spl_token_accounts`. Les filtres signature, mint, ATA et opération sont
|
||
exacts ; aucune clé privée ni logique de dérivation n'est exposée dans la WebView. `RecoverNested`
|
||
reste hors UI et a été validé séparément par le test opt-in Devnet contrôlé.
|
||
|
||
## Frontière de tracing
|
||
|
||
`kb_app_demo` utilise uniquement le target canonique `kb_app_demo`. Les anciens identifiants frontend sont validés puis conservés comme champ `frontend_target`; ils ne deviennent plus des targets Rust distincts.
|
||
|
||
L’application journalise les invocations Tauri, les actions utilisateur, l’état des fenêtres, la progression relayée et les résumés. Les détails de transport RPC, de parsing, de dispatch, de matérialisation et de persistance appartiennent respectivement à `kb_rpc`, `kb_pipeline`, aux processors et à `kb_store_pg`.
|
||
|
||
## Backfill depuis la dernière occurrence
|
||
|
||
Dans `demo_backfill`, la direction « Avant, plus anciennes » accepte désormais une signature d’ancrage vide pour les modes programme, token et pool. Le premier appel `getSignaturesForAddress` est alors effectué sans `before`, donc depuis les signatures les plus récentes. La direction « Après, plus récentes » conserve une ancre obligatoire.
|
||
|
||
## Validation de clôture `0.4.2`
|
||
|
||
`kb_app_demo` compte 88 tests. `cargo tauri dev -c kb_app_demo/tauri.conf.json` démarre Vite, initialise les tables PostgreSQL et permet d’exercer les sessions WebSocket. Aucun `npm run build` séparé n’est requis pour ce jalon : le serveur Vite lancé par Tauri constitue la validation frontend retenue.
|
||
|
||
## Token-2022 validation matrix
|
||
|
||
La fenêtre `DemoExecutionSpl` regroupe les exécutions Devnet SPL Memo, SPL Token classique et Associated Token Account. Elle réutilise les profils, la simulation obligatoire, la confirmation opérateur, l’hydratation canonique, l’extraction core, le décodage, la matérialisation et le second replay. La fenêtre Solana Core est désormais limitée au System Program. Token-2022 et ElGamal Registry seront ajoutés à cette fenêtre dédiée sans fusionner leurs contrats techniques.
|