khadhroony-solana-project/docs/architecture/007-EXECUTION_AND_POLICY.md

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

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 :

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 :

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 :

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 :

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

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.