336 lines
12 KiB
Markdown
336 lines
12 KiB
Markdown
<!-- file: docs/architecture/007-EXECUTION_AND_POLICY.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# Execution et Policy
|
|
|
|
## Objet
|
|
|
|
Ce document constitue la sortie principale de `0.0.3-pre.005`.
|
|
|
|
Il précise la frontière entre :
|
|
|
|
- `ProgramExecutionPreparer` et `PreparedProgramExecution` ;
|
|
- `ksp-execution-policy-api` ;
|
|
- `ksp-execution-lib` ;
|
|
- `ksp-wallet-lib` ;
|
|
- `ksp-onchain-transport-lib` ;
|
|
- l'interface/application qui fournit le contexte et les approbations externes.
|
|
|
|
Les types Rust exacts restent volontairement à définir avec la première implémentation réelle.
|
|
|
|
## Chaîne générale
|
|
|
|
```text
|
|
ProgramExecutionRequest
|
|
|
|
|
v
|
|
ProgramExecutionPreparer
|
|
|
|
|
v
|
|
PreparedProgramExecution
|
|
|
|
|
v
|
|
ksp-execution-lib
|
|
|
|
|
+--> policy checkpoints
|
|
+--> transaction/message assembly
|
|
+--> simulation si requise
|
|
+--> signature
|
|
+--> submission
|
|
+--> confirmation
|
|
|
|
|
v
|
|
ExecutionOutcome / pending requirement / error
|
|
```
|
|
|
|
`ksp-program-lib` prépare la sémantique protocolaire. `ksp-execution-lib` orchestre le cycle transactionnel. Ces responsabilités ne sont pas fusionnées.
|
|
|
|
## Entrée fondamentale de `ksp-execution-lib`
|
|
|
|
L'entrée fondamentale de `ksp-execution-lib` est une opération déjà préparée conformément à `ksp-program-api`, conceptuellement `PreparedProgramExecution`.
|
|
|
|
`ksp-execution-lib` ne dépend pas de `ksp-program-lib` et ne reçoit pas des requêtes spécifiques à Token, Meteora, Raydium ou autre protocole.
|
|
|
|
Un helper de composition `prepare + execute` pourra être ajouté plus tard s'il apporte une valeur réelle, mais il ne remplace pas la frontière fondamentale.
|
|
|
|
## `ksp-execution-policy-api`
|
|
|
|
`ksp-execution-policy-api` est un contrat public de décision. Il ne fournit pas une policy générique KSP.
|
|
|
|
Une implémentation de policy appartient au contexte qui en a besoin, par exemple :
|
|
|
|
- une crate `ksp-scenario-<domain>-lib` pour une demo Devnet ;
|
|
- une future bibliothèque d'application générale ;
|
|
- une future bibliothèque spécialisée Trading Intelligence / trading opérationnel.
|
|
|
|
Aucune `ksp-execution-policy-lib` commune n'est créée sans policy réellement commune.
|
|
|
|
## Policy obligatoire pour une exécution réelle
|
|
|
|
Une exécution réelle via `ksp-execution-lib` doit recevoir explicitement une implémentation de `ksp-execution-policy-api`.
|
|
|
|
Il n'existe pas de fallback implicite « allow all » pour la production.
|
|
|
|
Les tests peuvent utiliser une policy explicitement permissive lorsqu'ils ont besoin de tester le cycle d'exécution indépendamment de règles produit.
|
|
|
|
## Policy multi-checkpoints
|
|
|
|
Une policy n'est pas nécessairement évaluée une seule fois au début.
|
|
|
|
Certaines décisions ont besoin d'informations qui n'existent qu'après une étape technique, en particulier la simulation.
|
|
|
|
Direction conceptuelle :
|
|
|
|
```text
|
|
Prepared
|
|
|
|
|
v
|
|
preflight policy
|
|
|
|
|
v
|
|
simulation éventuelle
|
|
|
|
|
v
|
|
post-simulation policy
|
|
|
|
|
v
|
|
signature
|
|
|
|
|
v
|
|
pre-submission policy
|
|
|
|
|
v
|
|
submission / confirmation
|
|
```
|
|
|
|
Les noms et le nombre exact de checkpoints seront définis avec l'API réelle. Le contrat doit rester extensible sans imposer des callbacks inutiles à toutes les policies.
|
|
|
|
## Une policy décide, elle n'exécute pas
|
|
|
|
Une policy peut conceptuellement :
|
|
|
|
- autoriser ;
|
|
- refuser ;
|
|
- ajouter/resserrer des exigences ;
|
|
- exiger une simulation ;
|
|
- exiger une approbation externe ;
|
|
- imposer un niveau minimum de confirmation ;
|
|
- imposer des limites de retry/exécution.
|
|
|
|
Une policy ne :
|
|
|
|
- signe pas ;
|
|
- sélectionne pas un secret wallet ;
|
|
- appelle pas RPC ;
|
|
- n'envoie pas une transaction ;
|
|
- n'ouvre pas une fenêtre Tauri ;
|
|
- ne bloque pas en attente d'une interaction UI.
|
|
|
|
## Trois sources de contraintes
|
|
|
|
L'orchestration distingue trois origines de contraintes.
|
|
|
|
### Contraintes Program
|
|
|
|
Produites par `ProgramExecutionPreparer` dans `PreparedProgramExecution` :
|
|
|
|
- comptes requis ;
|
|
- signers/authorities requis ;
|
|
- ordre et contenu des instructions ;
|
|
- PDA ;
|
|
- invariants/contraintes protocolaires.
|
|
|
|
Elles sont techniques et non négociables par une policy.
|
|
|
|
### Options/contexte du consommateur
|
|
|
|
Le niveau supérieur fournit le contexte d'exécution :
|
|
|
|
- réseau/profil choisi ;
|
|
- wallet/signers sélectionnés ;
|
|
- commitment/timeout souhaités ;
|
|
- options de simulation ;
|
|
- autres choix exposés par l'application/scénario.
|
|
|
|
### Contraintes Policy
|
|
|
|
La policy peut refuser ou resserrer les options du consommateur, mais ne peut pas violer les contraintes techniques Program.
|
|
|
|
## Wallet
|
|
|
|
`ksp-execution-lib` utilise `ksp-wallet-lib` pour les capacités de signature mais ne choisit pas arbitrairement un wallet.
|
|
|
|
Le contexte supérieur fournit les signers/wallet handles sélectionnés ; l'orchestration vérifie qu'ils satisfont les authorities/signers requis par `PreparedProgramExecution`.
|
|
|
|
Les secrets ne sont jamais transportés dans `PreparedProgramExecution`.
|
|
|
|
## Transport on-chain
|
|
|
|
`ksp-execution-lib` utilise `ksp-onchain-transport-lib` pour les primitives réseau nécessaires, notamment selon le besoin :
|
|
|
|
- récupération des données réseau nécessaires à la construction finale ;
|
|
- simulation ;
|
|
- submission ;
|
|
- status/confirmation.
|
|
|
|
`ksp-execution-lib` ne choisit pas arbitrairement Helius, RPC public, WS ou autre provider. Le contexte/configuration supérieur fournit la cible/transport approprié.
|
|
|
|
Le choix du provider est distinct de la policy d'exécution.
|
|
|
|
## Simulation
|
|
|
|
La primitive réseau de simulation appartient à `ksp-onchain-transport-lib`.
|
|
|
|
L'orchestration de la simulation appartient à `ksp-execution-lib` : elle décide quand appeler la primitive selon `PreparedProgramExecution`, options et exigences de policy.
|
|
|
|
La policy peut rendre la simulation obligatoire et peut évaluer son résultat, mais n'effectue pas elle-même l'appel réseau.
|
|
|
|
## Signature
|
|
|
|
`ksp-execution-lib` assemble le message/transaction selon les contrats techniques retenus, résout les signers requis depuis le contexte puis appelle `ksp-wallet-lib` pour les signatures.
|
|
|
|
Les crates Solana précises nécessaires aux messages/transactions seront évaluées au moment de l'implémentation selon la même politique de dépendances modernes que les autres interfaces KSP.
|
|
|
|
## Submission et confirmation
|
|
|
|
Les primitives réseau de submission/status appartiennent à `ksp-onchain-transport-lib`.
|
|
|
|
Le lifecycle :
|
|
|
|
```text
|
|
submitted
|
|
-> processed / confirmed / finalized
|
|
-> timeout / failure
|
|
```
|
|
|
|
est orchestré par `ksp-execution-lib`.
|
|
|
|
Une policy peut imposer un minimum de confirmation mais n'implémente pas la boucle de confirmation.
|
|
|
|
## Retry transport vs retry d'exécution
|
|
|
|
Deux catégories sont distinguées.
|
|
|
|
### Retry transport
|
|
|
|
Retry technique d'un appel réseau identique, par exemple erreur transitoire de connexion/rate-limit. Il appartient au transport selon ses règles propres.
|
|
|
|
### Retry d'exécution
|
|
|
|
Un retry qui modifie le lifecycle de l'opération, par exemple :
|
|
|
|
- blockhash expiré ;
|
|
- reconstruction ;
|
|
- nouvelle simulation ;
|
|
- nouvelle signature ;
|
|
- nouvelle submission.
|
|
|
|
Il appartient à `ksp-execution-lib` et peut être limité/refusé par la policy.
|
|
|
|
## Approbation externe et suspension
|
|
|
|
Une policy peut demander une approbation externe sans connaître l'UI.
|
|
|
|
`ksp-execution-lib` doit pouvoir exposer un état/requirement suspendu conceptuel permettant au caller :
|
|
|
|
1. de recevoir la demande ;
|
|
2. d'obtenir l'approbation via son interface propre ;
|
|
3. de reprendre l'exécution de manière contrôlée.
|
|
|
|
Le mécanisme exact de token/resume sera défini avec le premier besoin réel.
|
|
|
|
Une application Tauri affiche éventuellement le dialogue ; ni la policy ni `ksp-execution-lib` ne dépendent de Tauri pour cela.
|
|
|
|
## Résultat d'exécution
|
|
|
|
Le résultat doit pouvoir exposer conceptuellement :
|
|
|
|
- identité de l'opération préparée ;
|
|
- identité/signature transactionnelle lorsqu'elle existe ;
|
|
- résultat de simulation lorsqu'elle a eu lieu ;
|
|
- résultat de submission ;
|
|
- état de confirmation ;
|
|
- warnings ;
|
|
- informations de décisions/requirements utiles au caller ;
|
|
- erreur/état final ou suspendu.
|
|
|
|
`ksp-execution-lib` ne persiste pas automatiquement ce résultat et ne dépend pas du store.
|
|
|
|
La persistence éventuelle appartient à un composant supérieur de composition.
|
|
|
|
## Logging transversal
|
|
|
|
`ksp-logging-lib` est la façade commune de logging/tracing KSP.
|
|
|
|
Elle possède directement les dépendances techniques de logging, notamment :
|
|
|
|
```text
|
|
tracing
|
|
tracing-appender
|
|
tracing-subscriber
|
|
```
|
|
|
|
et peut dépendre de `ksp-core-lib` pour `Error` / `Result`.
|
|
|
|
Elle possède l'initialisation/configuration du système de logging et expose une façade KSP paramétrable (target/domain/champs structurés et niveaux selon l'API finale).
|
|
|
|
Les crates runtime KSP ne dépendent normalement pas directement de `tracing`; elles utilisent `ksp-logging-lib` pour produire des événements :
|
|
|
|
```text
|
|
error
|
|
warn
|
|
info
|
|
debug
|
|
trace
|
|
```
|
|
|
|
L'API exacte peut utiliser fonctions, macros ou une combinaison des deux afin de préserver les propriétés utiles de `tracing`; ce détail est reporté à l'implémentation de `ksp-logging-lib`.
|
|
|
|
Les applications Tauri constituent une exception technique possible lorsqu'un plugin tel que `tauri-plugin-tracing` impose une intégration directe au framework. Cette adaptation ne doit pas créer une seconde politique de logging parallèle : `ksp-logging-lib` reste la façade/propriétaire KSP.
|
|
|
|
`ksp-core-lib` n'a pas besoin de dépendre de `ksp-logging-lib` dans l'architecture actuelle.
|
|
|
|
Les crates `*-api` purement déclaratives ne dépendent pas du logging par défaut.
|
|
|
|
## Composition de policies
|
|
|
|
La composition de plusieurs policies spécialisées (réseau, montants, risque, deprecated operation, approval utilisateur, etc.) reste une idée à évaluer.
|
|
|
|
Elle n'est pas imposée par `ksp-execution-policy-api` tant que les premières policies réelles n'ont pas démontré un contrat de composition utile.
|
|
|
|
## Dépendances interdites
|
|
|
|
```text
|
|
ksp-execution-policy-api -X-> ksp-wallet-lib
|
|
ksp-execution-policy-api -X-> ksp-onchain-transport-lib
|
|
ksp-execution-policy-api -X-> ksp-store-api
|
|
ksp-execution-policy-api -X-> UI/Tauri
|
|
|
|
ksp-execution-lib -X-> ksp-program-lib
|
|
ksp-execution-lib -X-> ksp-store-api
|
|
ksp-execution-lib -X-> ksp-store-lib
|
|
```
|
|
|
|
## Ownership des implementations de policy
|
|
|
|
`ksp-execution-policy-api` est le contrat commun. Une crate générale `ksp-execution-policy-lib` n'est pas créée par symétrie.
|
|
|
|
Une petite policy strictement propre à un scenario, un orchestrateur ou une application spécialisée peut être implémentée directement dans cette crate. Une ou plusieurs bibliothèques de policies communes ne sont introduites que lorsque plusieurs consommateurs démontrent une réutilisation réelle.
|
|
|
|
Les anciennes règles historiques de type `WalletPolicy` qui concernent limites de dépense, réseau, programme, simulation ou autorisation sont déplacées conceptuellement vers cette frontière policy et non vers `ksp-wallet-lib`.
|
|
|
|
## Execution dans les vertical slices
|
|
|
|
L'exécution n'est pas reportée après « tous les decoders ». Pour chaque groupe Program prioritaire, les opérations pertinentes avancent après décodage/matérialisation jusqu'à préparation, policy, execution et scénarios Devnet lorsque le réseau/protocole permet une validation réelle.
|
|
|
|
## Questions laissées à l'implémentation
|
|
|
|
- types Rust exacts des checkpoints et décisions de policy ;
|
|
- représentation précise de `ExecutionContext` ;
|
|
- mécanisme d'approbation suspendue/reprise ;
|
|
- forme exacte de `ExecutionOutcome` ;
|
|
- limites/retry defaults ;
|
|
- crates Solana actuelles pour message/transaction/versioned transaction ;
|
|
- API fonctions/macros exacte de `ksp-logging-lib` ;
|
|
- éventuelle composition de policies.
|