76 lines
4.7 KiB
Markdown
76 lines
4.7 KiB
Markdown
<!-- file: crates/ksp-app-raw-transaction-ingest-desk/USAGE.md -->
|
||
<!-- version: 7 -->
|
||
|
||
# Utilisation de `ksp-app-raw-transaction-ingest-desk`
|
||
|
||
## 1. Lancement
|
||
|
||
Depuis la racine du workspace :
|
||
|
||
```bash
|
||
(cd crates/ksp-app-raw-transaction-ingest-desk && cargo tauri dev)
|
||
```
|
||
|
||
Tauri déclenche lui-même les hooks frontend configurés. Les scripts npm applicatifs de développement, contrôle ou build ne sont pas lancés directement par l'opérateur.
|
||
|
||
Le runtime prépare les ressources Config nécessaires, charge le composite dédié, initialise Logging puis ouvre le shell desktop.
|
||
|
||
## 2. Vue Routes
|
||
|
||
La vue Routes charge un inventaire déterministe construit côté Rust depuis le composite Config validé. Le sélecteur présente les réseaux logiques `devnet`, `mainnet` et `testnet`, jamais les providers. Chaque réseau agrège les profils Transport same-network configurés pour ses capabilities. La vue projette, pour chaque route V1 :
|
||
|
||
```text
|
||
route_id
|
||
famille et label sûrs
|
||
réseau logique lorsque résolu
|
||
état Config
|
||
selectable oui/non
|
||
raison sûre lorsque la route est indisponible
|
||
génération d'inventaire
|
||
```
|
||
|
||
`Configured` signifie uniquement que toutes les requirements Config nécessaires à la route sont cohérentes. Les profils `solana-public` standard committés déclarent explicitement les capabilities `Logs` et `Block`; `standard-block-direct` est donc Configured sur les trois réseaux logiques tant que ce socle Config reste valide. L'inventaire seul ne fait aucun probe réseau et n'ouvre aucun Store ni Worker.
|
||
|
||
Un refresh reconstruit l'inventaire depuis Config et publie une nouvelle génération. La sélection visuelle d'un réseau ne choisit aucune URL, provider ou ressource physique et ne démarre aucune acquisition. Une capability optionnelle dont le secret n'est pas résolu rend uniquement la route qui en dépend indisponible ; les routes satisfaites par le Transport de base du même réseau restent composables.
|
||
Une route provider-specific dont aucune source n’est déclarée pour le réseau n’est pas une erreur de configuration : elle est hors inventaire pour ce réseau. Par exemple, Helius Transaction est projetée sur Devnet/Mainnet lorsque `transport.helius` existe, mais pas sur Testnet lorsqu’aucune source Helius Testnet n’est déclarée.
|
||
|
||
Les URLs, tokens, metadata secrètes, handles Transport/Store/Worker, URI Store, source keys et payloads RAW restent backend-only.
|
||
|
||
### Start/Stop mono-route
|
||
|
||
Pour une route `Configured`, choisir `confirmed` ou `finalized` puis utiliser `Start`. Le backend revalide la génération d'inventaire et la composition Config, ouvre le Store correspondant, exige son état `Ready`, construit le Worker exact et installe son handle avant de renvoyer l'accusé runtime.
|
||
|
||
Un seul Worker peut être actif ou en démarrage dans cette tranche. Un second Start est refusé tant que le Worker précédent n'est pas terminal et que son Store n'a pas été explicitement fermé. `Stop` est coopératif : la commande attend le terminal Worker et la fermeture Store avant de rendre le slot à nouveau disponible. Si le Worker est déjà terminal et nettoyé avant le clic Stop, la commande retourne idempotemment le dernier état terminal sûr ; ce comportement permet de resynchroniser le contrôle `pre.008` sans introduire le monitoring continu réservé à une tranche ultérieure.
|
||
|
||
Le frontend n'effectue aucun polling runtime continu dans cette tranche. Une terminaison spontanée est nettoyée côté backend ; sa projection temps réel vers l'UI appartient au monitoring ultérieur.
|
||
|
||
## 3. Raisons d'indisponibilité
|
||
|
||
Les reasons exposées sont des codes applicatifs bornés, par exemple :
|
||
|
||
```text
|
||
profile_unresolved
|
||
network_mismatch
|
||
missing_http_get_transaction
|
||
missing_http_block_scan
|
||
missing_ws_logs_capability
|
||
missing_ws_block_capability
|
||
missing_helius_transaction_capability
|
||
missing_yellowstone_grpc
|
||
missing_required_secret
|
||
```
|
||
|
||
Le texte arbitraire d'une erreur provider ou d'un secret Config n'est jamais projeté dans l'inventaire.
|
||
|
||
## 4. Diagnostics
|
||
|
||
La vue Diagnostics expose uniquement des informations techniques sûres nécessaires à l'exploitation du Desk, notamment l'identité de version, l'état du shell, la composition Config bootstrap, l'état Logging et la génération d'inventaire.
|
||
|
||
Les diagnostics ne doivent pas exposer de credentials, d'URI Store, d'URL d'endpoint, de source key, de handle runtime ou de payload `RawTransaction`.
|
||
|
||
## 5. Runtime packagé
|
||
|
||
Le build Tauri embarque les documents Config et schemas enregistrés. `ksp-config-lib` prépare ensuite la racine KSP user-writable sans embarquer `.env`.
|
||
|
||
Les fichiers Config et les secrets restent administrés par les mécanismes Config KSP ; l'interface ne contourne pas cette ownership.
|