Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.0.3-pre.004

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-14 09:51:30 +02:00
parent 544e0351b8
commit d33911f925
12 changed files with 776 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/architecture/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/000-README.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Architecture KSP
@@ -21,6 +21,7 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas.
2. [`002-LAYERS_AND_DEPENDENCIES.md`](002-LAYERS_AND_DEPENDENCIES.md) — couches conceptuelles, sens des dépendances et responsabilités des exécutables ;
3. [`003-COMPONENT_CONTRACTS.md`](003-COMPONENT_CONTRACTS.md) — frontières initiales des composants structurants et contrats déjà acquis ;
4. [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) — inventaire courant des domaines, APIs, bibliothèques, workers, jobs, scénarios et applications candidates ;
5. [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) — graphe de dépendances retenu, dépendances interdites et frontières de conversion/composition.
5. [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) — graphe de dépendances retenu, dépendances interdites et frontières de conversion/composition ;
6. [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) — propriété des contrats wire, politique de dépendances codecs/interfaces, API Program ouverte, preparation d'exécution et extensibilité externe.
`004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires.

4
docs/architecture/003-COMPONENT_CONTRACTS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# Contrats initiaux des composants KSP
@@ -9,7 +9,7 @@ Ce document enregistre les frontières déjà suffisamment claires pour guider l
Le principe commun est de définir tôt les contrats nécessaires entre composants, puis d'enrichir les implémentations lorsque le besoin réel apparaît.
L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) et le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md).
L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md), le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) et les contrats Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md).
## Convention API / implémentation

73
docs/architecture/004-COMPONENT_INVENTORY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Inventaire initial des composants KSP
@@ -9,7 +9,7 @@ Ce document constitue le premier inventaire architectural de `0.0.3-pre.002`.
Il répond principalement à la question : **quel composant possède quelle responsabilité ?**
Le premier inventaire a été produit en `0.0.3-pre.002`. `0.0.3-pre.003` l'a corrigé à partir du graphe formalisé dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md). Les détails internes des APIs restent toutefois révisables dans les prereleases spécialisées suivantes.
Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé à partir du graphe, puis `pre.004` a détaillé Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md). Les détails de types Rust restent révisables avec les premières implémentations.
## Statuts
@@ -21,40 +21,41 @@ Le premier inventaire a été produit en `0.0.3-pre.002`. `0.0.3-pre.003` l'a co
## Inventaire synthétique
| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale |
|-------------------------|---------------------------------------------|---------------|-------------------|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées |
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | logging/tracing commun |
| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles |
| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics decoder/executor et types associés |
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés |
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | `0.2.x+` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution |
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | orchestration spécialisée entre opération préparée, policy, wallet et transport ; dépend de `ksp-program-api`, pas de `ksp-program-lib` |
| Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store |
| Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain |
| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature |
| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP |
| Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées |
| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries |
| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus |
| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur |
| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data |
| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique |
| Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core |
| Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine |
| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables |
| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise |
| Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine |
| Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant |
| Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante |
| Specialized pipelines | `ksp-pipeline-<role>-lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale |
| Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML |
| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte |
| Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana |
| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX |
| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale |
|-------------------------|---------------------------------------------|-------------------------|-------------------|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées |
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | logging/tracing commun |
| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles |
| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics ouverts de décodage, préparation d'exécution, descriptors et registry |
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders et `ProgramExecutionPreparer` officiels organisés par domaine/programme/capacité |
| Program extension | `ksp-program-<name>-lib` | lib externe/optionnelle | N2 | À la demande | dès besoin | implémentation externe de `ksp-program-api` pour un Program ID non encore intégré officiellement |
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | `0.2.x+` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution |
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | orchestration spécialisée entre opération préparée, policy, wallet et transport ; dépend de `ksp-program-api`, pas de `ksp-program-lib` |
| Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store |
| Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain |
| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature |
| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP |
| Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées |
| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries |
| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus |
| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur |
| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data |
| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique |
| Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core |
| Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine |
| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables |
| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise |
| Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine |
| Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant |
| Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante |
| Specialized pipelines | `ksp-pipeline-<role>-lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale |
| Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML |
| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte |
| Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana |
| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX |
## APIs séparées retenues

39
docs/architecture/005-DEPENDENCY_GRAPH.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Graphe de dépendances KSP
@@ -87,6 +87,23 @@ ksp-interface-lib -> ksp-core-lib
---
# Propriété des codecs wire
Pour les surfaces wire officielles KSP :
```text
ksp-interface-lib
-> codecs wire nécessaires (borsh/wincode/...)
```
`ksp-program-lib` n'ajoute pas directement une autre génération de codec pour les mêmes surfaces.
Une extension Program externe peut temporairement posséder son wire lorsqu'il n'est pas encore officiellement intégré à `ksp-interface-lib`.
Le critère d'adoption d'une crate d'interface externe inclut la compatibilité de son graphe de dépendances avec le stack KSP actuel.
---
# Graphe Program
```text
@@ -102,7 +119,7 @@ ksp-program-lib
## Frontière de `ksp-program-api`
`ksp-program-api` doit porter les contrats publics nécessaires à une implémentation externe de decoder/executor.
`ksp-program-api` doit porter les contrats publics nécessaires à une implémentation externe de decoder/execution preparation.
Il est également le propriétaire candidat du **contrat d'opération préparée** produit par la sémantique programme et consommé par la couche d'exécution.
@@ -131,10 +148,26 @@ ksp-program-lib -X-> ksp-materializer-lib
ksp-program-lib -X-> ksp-execution-lib
```
Le decoder/executor de programme reste donc testable sans réseau, wallet ou base de données.
Le decoder/execution preparation de programme reste donc testable sans réseau, wallet ou base de données.
---
## Implémentations Program externes
Une implémentation externe peut dépendre de :
```text
ksp-program-<name>-lib
-> ksp-program-api
-> ksp-core-lib
-> ksp-interface-lib # lorsque le wire officiel nécessaire existe
```
Elle ne dépend pas obligatoirement de `ksp-program-lib`.
Le runtime peut composer registry officiel + registry/implémentations externes derrière `ksp-program-api`.
# Graphe Execution / Policy
`ksp-execution-policy-api` et `ksp-execution-lib` sont retenus comme composants.

418
docs/architecture/006-WIRE_AND_PROGRAM.md Normal file
View File

@@ -0,0 +1,418 @@
<!-- file: docs/architecture/006-WIRE_AND_PROGRAM.md -->
<!-- version: 1 -->
# Wire, Program API et implémentations Program
## Objet
Ce document constitue la sortie principale de `0.0.3-pre.004`.
Il précise :
- le rôle de `ksp-interface-lib` ;
- la propriété des codecs wire ;
- la politique de sélection/réimplémentation des crates d'interface externes ;
- la forme générale et ouverte de `ksp-program-api` ;
- la séparation decoder / préparation d'exécution ;
- le registry extensible ;
- l'organisation interne prévue de `ksp-program-lib` ;
- le workflow d'une implémentation de programme développée hors de l'implémentation officielle.
Les types Rust exacts restent volontairement à définir lors de la première implémentation réelle.
## `ksp-interface-lib`
`ksp-interface-lib` est la façade wire officielle KSP pour les programmes Solana supportés officiellement.
Elle possède ou réexporte de manière contrôlée les contrats nécessaires tels que :
- discriminants ;
- layouts d'instructions ;
- layouts de comptes ;
- enums/structures wire ;
- sérialisation/désérialisation wire ;
- règles et seeds de PDA lorsque ces règles appartiennent au contrat protocolaire ;
- constructeurs d'instructions lorsque ceux-ci représentent directement le contrat wire.
Les Program IDs fondamentaux restent possédés par `ksp-core-lib`.
`ksp-interface-lib` ne possède pas :
- RPC/WS/provider ;
- wallet/signature ;
- persistence ;
- matérialisation ;
- interprétation canonique/métier d'une instruction ;
- policy/safety ;
- lifecycle d'exécution réseau.
## Propriété des codecs wire
Pour le code KSP officiel, les dépendances directement utilisées pour encoder/décoder les formats wire, notamment `borsh`, `wincode` ou codecs équivalents, appartiennent normalement à `ksp-interface-lib`.
La règle n'interdit pas qu'une autre crate KSP utilise un codec pour une raison indépendante du wire Solana, mais une telle dépendance directe doit avoir une justification distincte.
En particulier :
```text
ksp-interface-lib
-> borsh / wincode / codecs wire nécessaires
ksp-program-lib
-X-> borsh / wincode pour redécoder directement le wire protocolaire
```
`ksp-program-lib` reçoit des contrats typés/wire exposés par la façade officielle au lieu de recréer la sérialisation protocolaire.
## Politique de sélection des interfaces externes
Une crate externe d'interface Solana/Anza peut être utilisée directement lorsque :
1. elle appartient à une source officielle ou suffisamment normative pour le contrat concerné ;
2. sa surface est suffisamment stable et finale pour l'usage KSP ;
3. son graphe de dépendances est compatible avec le stack de dépendances KSP actuel ;
4. elle n'introduit pas sans nécessité une génération ancienne/incompatible d'un codec ou d'une primitive fondamentale ;
5. son usage évite une réimplémentation KSP sans réduire le contrôle du contrat public.
Une crate protocolaire externe peut être rejetée même si son API fonctionne lorsqu'elle impose un stack ancien ou incompatible avec le reste du workspace.
### Exemples observés pendant la planification
`solana-loader-v3-interface` illustre une interface officielle actuelle qui peut raisonnablement être conservée plutôt que réécrite lorsque sa version et son graphe restent compatibles avec KSP.
`mpl-token-metadata` illustre le cas inverse : KSP ne prévoit pas de l'intégrer comme dépendance runtime. Les contrats wire Metaplex Token Metadata nécessaires seront réimplémentés/possédés par `ksp-interface-lib`.
Ces exemples sont des applications de la règle, pas des exceptions codées en dur : l'état des dépendances doit être revérifié au moment de chaque implémentation.
## Politique anti-doublons de générations
KSP ne cherche pas à figer arbitrairement une version précise des dépendances. Le projet cherche au contraire à rester sur des générations récentes et compatibles.
Les doublons de versions/générations de dépendances fondamentales doivent être inspectés régulièrement, notamment pour :
- codecs wire ;
- primitives Solana ;
- sérialisation ;
- bibliothèques cryptographiques fondamentales.
Un doublon réellement imposé et inévitable par une dépendance retenue peut être temporairement accepté avec justification.
Un doublon évitable provoqué par une crate protocolaire remplaçable doit être éliminé plutôt que normalisé comme dette permanente.
Outils d'audit attendus lorsque le workspace fonctionnel le permettra :
```bash
cargo tree -d
cargo tree -i borsh
cargo tree -i wincode
```
La liste sera complétée selon les dépendances réellement utilisées.
## `ksp-program-api`
`ksp-program-api` porte des contrats publics **ouverts**.
Une implémentation externe doit pouvoir prendre en charge un Program ID encore inconnu de `ksp-program-lib` sans modifier une enum centrale KSP.
### Pas d'enum fermée de programmes
Une structure de la forme suivante est explicitement évitée :
```text
enum DecodedProgram {
Token(...),
Token2022(...),
Meteora(...),
...
}
```
car chaque nouveau protocole exigerait une modification de l'API centrale.
De même, un `Any` runtime non persistable ne peut pas constituer l'unique représentation d'un résultat décodé.
Le résultat doit rester :
- auto-identifiable ;
- extensible ;
- sérialisable/persistable lorsque la frontière Core l'exige ;
- exploitable par une implémentation externe de materializer ;
- compatible avec l'ajout de Program IDs sans modification de l'API commune.
La représentation exacte du payload ouvert sera définie avec les contrats Core/Store/Materializer réels, sans introduire prématurément une enum fermée.
## Familles de decoders
Plutôt qu'un unique trait possédant toutes les surfaces possibles, `ksp-program-api` doit pouvoir distinguer les capacités de décodage.
Familles initiales candidates :
```text
ProgramInstructionDecoder
ProgramAccountDecoder
ProgramEventDecoder
ProgramReturnDataDecoder
```
Les deux premières sont considérées comme besoins fondamentaux probables.
Les autres ne sont ajoutées que lorsqu'une première surface réelle le justifie.
Une implémentation de programme n'est pas obligée de fournir toutes les capacités.
Des descripteurs communs doivent permettre d'identifier les capacités effectivement supportées.
## Politique de décodage historique
Le decoder vise toute surface techniquement décodable dont la définition est connue :
- actuelle ;
- ancienne ;
- legacy ;
- abandonnée ;
- expérimentale/test lorsque le wire est connu ;
- historique distinguable.
Le statut de lifecycle d'une opération n'empêche jamais son décodage historique.
Si une définition a réellement été écrasée sous une identité indistinguable et que l'ancienne forme ne peut plus être reconnue de manière fiable, la définition applicable la plus récente est utilisée.
Le concept `deprecated` n'est donc pas un filtre de decoder.
## Préparation d'exécution Program
Le terme `ProgramExecutor` est abandonné dans le cadrage KSP parce qu'il suggère une exécution transactionnelle complète.
Le contrat prévu est nommé conceptuellement :
```text
ProgramExecutionPreparer
```
Sa responsabilité :
```text
ProgramExecutionRequest
|
v
ProgramExecutionPreparer
|
v
PreparedProgramExecution
```
Noms exacts des types à confirmer lors de l'implémentation.
Le preparer peut notamment :
- valider les paramètres protocolaires ;
- déterminer les comptes requis ;
- dériver les PDA nécessaires ;
- construire une ou plusieurs instructions ;
- indiquer les autorités/signers requis ;
- exposer les contraintes techniques propres à l'opération.
Il ne réalise pas :
- sélection du wallet réel ;
- accès aux secrets ;
- récupération du recent blockhash ;
- signature transactionnelle ;
- simulation RPC ;
- envoi réseau ;
- confirmation ;
- retry réseau ;
- policy/safety de produit.
Ces responsabilités appartiennent aux couches d'exécution supérieures.
## `PreparedProgramExecution`
Le contrat préparé entre Program et Execution doit pouvoir transporter conceptuellement :
- identité du programme/opération ;
- instructions ;
- comptes/authorities/signers requis ;
- contraintes techniques ;
- informations nécessaires à une policy supérieure ;
- metadata de préparation utiles à l'exécution.
Il ne contient pas de secret wallet et ne fixe pas un endpoint réseau concret.
Il doit être consommable par `ksp-execution-lib` indépendamment du fait que l'implémentation Program provienne de `ksp-program-lib` ou d'une crate externe.
## Lifecycle des opérations préparables
Le lifecycle d'une opération d'exécution doit être machine-readable.
Il faut distinguer au minimum conceptuellement :
- opération actuelle/supportée ;
- opération legacy/ancienne mais pas nécessairement déconseillée ;
- opération réellement abandonnée/déconseillée.
Les noms exacts des statuts seront définis plus tard.
Le statut « deprecated » est réservé à une surface clairement abandonnée/remplacée, pas simplement ancienne.
KSP ne rend pas obligatoire l'annotation Rust `#[deprecated]`.
Une opération techniquement encore préparée mais marquée comme abandonnée peut :
1. produire un warning explicite ;
2. transmettre son statut à `ksp-execution-policy-api` ;
3. être autorisée ou rejetée par la policy supérieure selon le contexte.
Le decoder continue de la reconnaître indépendamment de ce statut.
## Registry extensible
Le registry Program doit pouvoir combiner :
- implémentations officielles KSP ;
- implémentations externes ;
- implémentations expérimentales.
Les descripteurs doivent permettre d'identifier au minimum conceptuellement :
- Program ID ;
- identité/version de l'implémentation ;
- capacités de décodage ;
- opérations préparables ;
- statut/lifecycle des opérations ;
- autres capacités nécessaires au dispatch.
Le contrat exact du registry sera défini lors de l'implémentation.
Le registry ne doit pas nécessiter une modification de `ksp-program-api` pour enregistrer un nouveau Program ID.
## Implémentations externes
Une extension externe de programme est une **implémentation** de `ksp-program-api`, pas une nouvelle API commune.
Nomenclature recommandée lorsque l'extension suit les conventions KSP :
```text
ksp-program-<name>-lib
```
Exemple conceptuel :
```text
ksp-program-fluxbeam-lib
```
et non :
```text
ksp-program-fluxbeam-api
```
Cette crate peut dépendre de :
```text
ksp-program-api
ksp-core-lib
ksp-interface-lib
```
selon les besoins.
Elle peut être développée, testée et utilisée par un runtime KSP sans être intégrée à `ksp-program-lib`.
## Wire d'une extension encore non officielle
`ksp-interface-lib` est la façade wire **officielle KSP**, mais `ksp-program-api` ne doit pas empêcher une extension externe de fournir temporairement ses propres définitions wire.
Deux cas sont possibles :
```text
interface officielle déjà dans KSP
-> extension utilise ksp-interface-lib
interface pas encore intégrée
-> extension possède sa définition wire compatible
-> extension implémente ksp-program-api
```
Lors de l'intégration officielle :
1. les définitions wire sont revues/vérifiées ;
2. les contrats wire nécessaires migrent vers `ksp-interface-lib` ;
3. decoder/preparer migrent vers `ksp-program-lib` ;
4. le contrat `ksp-program-api` ne change pas pour cette seule raison.
## Organisation interne de `ksp-program-lib`
`ksp-program-lib` doit être organisé d'abord par domaine puis par programme/protocole, et seulement ensuite par capacité.
Direction retenue :
```text
<domain>/
<program-or-protocol>/
dec/
...
exec_prep/
...
```
Exemples conceptuels :
```text
spl/
token_2022/
dec/
exec_prep/
metadata/
token/
mpl/
dec/
exec_prep/
dex/
meteora/
dlmm/
dec/
exec_prep/
```
Les noms courts `dec` / `exec_prep` restent une convention candidate ; les noms précis seront décidés avec les premières vraies arborescences Rust.
Le principe durable est :
```text
domain -> program/protocol -> capability
```
et non un répertoire racine géant `decoder/` ou `executor/` contenant tous les protocoles.
## Conformité wire
Pour chaque contrat wire réimplémenté, la documentation/tests doivent permettre d'identifier la source normative utilisée.
Les validations peuvent combiner selon le cas :
- documentation/source officielle ;
- fixtures officielles ;
- transactions/comptes réels connus ;
- golden vectors ;
- comparaison avec une implémentation de référence lorsqu'elle peut être utilisée sans polluer durablement le graphe KSP.
Une crate externe provoquant volontairement une génération incompatible de dépendances fondamentales ne doit pas être ajoutée au workspace simplement pour faciliter un test si des fixtures/vecteurs indépendants permettent la même vérification.
## Questions laissées ouvertes
La première implémentation Program devra encore fixer précisément :
- formes Rust des traits decoder ;
- représentation du payload décodé ouvert/persistable ;
- forme exacte des descriptors ;
- types exacts `ProgramExecutionRequest` / `PreparedProgramExecution` ;
- forme du registry et règles de conflit entre plusieurs implémentations d'un même Program ID ;
- stratégie précise de warning/log pour opérations abandonnées ;
- convention finale `dec` / `exec_prep`.
La tranche suivante doit traiter `ksp-execution-policy-api` et `ksp-execution-lib` sans rouvrir les responsabilités Program définies ici.