3.0 KiB
Convention des scenarios KSP
Objet
KSP n'impose pas actuellement de ksp-scenario-api.
Ce document définit les conventions minimales permettant aux crates ksp-scenario-<domain>-lib de rester cohérentes sans les enfermer dans un trait Rust universel.
Source de vérité
La logique fonctionnelle du scenario appartient à :
ksp-scenario-<domain>-lib
Une application desktop demo, un CLI, un test ou une CI appelle cette bibliothèque et ne recrée pas le workflow.
Indépendance de l'interface
Une crate scenario :
- ne dépend pas de Tauri ;
- ne contient pas de DTO TS-RS spécifiques à une UI ;
- ne suppose pas qu'une fenêtre desktop existe ;
- reste appelable depuis un test ou autre interface.
Environnement
Un scenario indique explicitement l'environnement/réseau attendu lorsqu'il est contraint.
Une app demo dont l'environnement est imposé suit la nomenclature :
ksp-app-scenario-<domain>-<environment>-desk-demo
Configuration et ressources
Le scenario utilise les bibliothèques KSP propriétaires de :
- configuration ;
- wallet ;
- transport ;
- Program ;
- execution ;
- Store lorsque le scenario en a réellement besoin.
Il ne contourne pas ces frontières avec des dépendances protocolaires/Solana externes directes.
Les endpoints, wallets et autres ressources utilisées doivent être résolus explicitement ; ils ne sont pas cachés dans l'UI.
Execution policy
Lorsqu'un scenario exécute une opération réelle, il fournit une policy explicite conforme à ksp-execution-policy-api.
Une policy Devnet peut être propre à la crate scenario.
La policy ne fuit pas dans ksp-program-lib.
Résultat
Un scenario doit produire un résultat exploitable par son caller.
Le résultat devrait permettre selon le besoin de distinguer :
- succès/échec fonctionnel ;
- étapes exécutées ;
- identités blockchain utiles ;
- validations/evidence ;
- warnings ;
- données de diagnostic non sensibles.
Le type exact reste spécifique au domaine tant qu'un vrai contrat commun ne justifie pas ksp-scenario-api.
Validation
Le scenario contient la logique de validation fonctionnelle nécessaire pour déterminer si son objectif a été atteint.
L'application demo affiche cette validation mais ne la réimplémente pas.
Logging
La crate scenario utilise ksp-logging-lib.
Les logs peuvent couvrir error, warn, info, debug et trace selon pertinence.
Aucun secret, seed, clé privée ou donnée sensible ne doit être loggé.
Réutilisation
Une même crate scenario doit pouvoir être utilisée par plusieurs callers sans duplication :
desktop demo
test
future CLI/tool
CI/integration
|
v
ksp-scenario-<domain>-lib
Evolution
Une convention peut être enrichie au fil des scenarios réels.
ksp-scenario-api ne sera introduit que si plusieurs implementations démontrent un contrat commun stable et utile.