v0.0.3-pre.005
This commit is contained in:
323
docs/architecture/007-EXECUTION_AND_POLICY.md
Normal file
323
docs/architecture/007-EXECUTION_AND_POLICY.md
Normal file
@@ -0,0 +1,323 @@
|
||||
<!-- file: docs/architecture/007-EXECUTION_AND_POLICY.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user