khadhroony-bot3/kb-app-demo-desktop/USAGE.md

Utilisation de kb-app-demo-desktop

Objectif

L’application expose une interface opérateur pour diagnostiquer, simuler et valider les couches de bot3.

Lancer le desktop

Depuis la racine du workspace :

cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json

Le binaire applique un verrou d’instance locale. Une deuxième instance doit échouer proprement.

API Rust publique

La bibliothèque expose uniquement run() :

fn launch_desktop() -> kb_core::Result<()> {
    return kb_app_demo_desktop_lib::run();
}

Le binaire kb-app-demo-desktop appelle cette fonction et convertit son résultat en ExitCode.

Fenêtres initiales

La configuration Tauri crée :

• splash ;
• main.

Les autres fenêtres sont ouvertes par les commandes Tauri dédiées :

• backfill ;
• HTTP ;
• WebSocket ;
• diagnostics SQL ;
• candidats replay ;
• configuration ;
• extraction Core ;
• decode replay ;
• exécution Solana Core ;
• exécution SPL.

Interface Tauri publique

Les commandes Tauri constituent l’interface applicative frontend/backend. Elles ne sont pas des APIs Rust publiques pour les autres crates.

Ouvrir une fenêtre

import { invoke } from "@tauri-apps/api/core";

await invoke("open_demo_http_window");
await invoke("open_demo_ws_window");
await invoke("open_demo_decode_replay_window");

Charger les options HTTP

const options = await invoke("demo_http_options");
console.log(options);

Exécuter une requête HTTP de démonstration

const result = await invoke(
  "demo_http_execute_request",
  {
    request: {
      role: "standard",
      method: "getHealth",
      paramsJson: "[]"
    }
  }
);

console.log(result);

Les champs exacts du payload doivent rester synchronisés avec les types TS-RS générés.

Gérer une session WebSocket

const status = await invoke("demo_ws_status");
console.log(status);

await invoke("demo_ws_connect", {
  request: {
    role: "standard",
    method: "logsSubscribe",
    paramsJson: "[]"
  }
});

await invoke("demo_ws_unsubscribe");
await invoke("demo_ws_disconnect");

La fermeture de la fenêtre ne doit pas être assimilée à une demande de déconnexion.

Lancer un backfill

const options = await invoke("demo_backfill_options");
console.log(options);

const summary = await invoke(
  "demo_backfill_execute",
  {
    request: {
      profileName: "devnet",
      address: "11111111111111111111111111111111",
      limit: 100
    }
  }
);

console.log(summary);

Extraction Core

const options = await invoke(
  "demo_core_extraction_options"
);

const summary = await invoke(
  "demo_core_extraction_execute",
  {
    request: {
      profileName: "devnet",
      limit: 1000
    }
  }
);

console.log(options, summary);

Une campagne longue peut être annulée avec demo_core_extraction_cancel.

Decode replay

const options = await invoke(
  "demo_decode_replay_options"
);

const summary = await invoke(
  "demo_decode_replay_execute",
  {
    request: {
      profileName: "devnet",
      limit: 1000,
      materialize: true
    }
  }
);

console.log(options, summary);

Les diagnostics et annotations sont accessibles par des commandes séparées.

Scénarios Devnet

Les commandes couvrent notamment :

• demo_execution_solana_core_execute ;
• demo_execution_spl_memo_execute ;
• demo_execution_spl_token_execute ;
• demo_execution_spl_ata_execute ;
• demo_execution_spl_token_2022_execute.

const scenarios = await invoke(
  "demo_execution_spl_validation_scenarios"
);

console.log(scenarios);

La simulation et l’envoi doivent rester explicitement distingués dans les requêtes.

Diagnostics PostgreSQL

const diagnostics = await invoke(
  "load_demo_sql_diag"
);
const rawTables = await invoke(
  "load_demo_sql_pg_raw"
);
const coreTables = await invoke(
  "load_demo_sql_pg_core"
);

console.log(diagnostics, rawTables, coreTables);

Capabilities Tauri

Les fenêtres autorisées sont listées dans capabilities/default.json. La capability active doit inclure au minimum les permissions Tauri Core et tracing nécessaires aux fenêtres déclarées.

Toute nouvelle fenêtre ou commande sensible doit être auditée avant ajout de permissions.

Erreurs et invariants

• une simulation ne doit jamais envoyer une transaction ;
• une soumission nécessite une confirmation opérateur explicite ;
• les secrets de wallet ne doivent jamais être sérialisés vers le frontend ;
• les résultats frontend doivent refléter les validations réellement exécutées ;
• l’état WebSocket appartient à l’application, pas à la durée de vie de la fenêtre ;
• les commandes Tauri adaptent les APIs réutilisables sans dupliquer leur logique.

Tests de référence

• tests des options et payloads HTTP ;
• tests de cycle de vie WebSocket ;
• tests de sélection de profil Devnet ;
• tests de System Transfer et Memo ;
• tests ATA, SPL Token et Token-2022 ;
• tests de backfill, extraction Core et decode replay ;
• tests de diagnostics SQL et exports CSV ;
• tests de journalisation frontend ;
• test du verrou d’état applicatif et de la séquence splash.

La base validée de pre.062 contient 117 tests pour cette crate.

Limites durables

• le desktop est une application de démonstration et validation, pas le worker de production ;
• les payloads Tauri sont une API applicative spécifique au frontend ;
• l’application nécessite un environnement graphique pour sa validation complète.