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

v0.3.5-pre.007

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-31 13:07:56 +02:00
parent e8d2382ac3
commit 80be36bfdd
13 changed files with 479 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
<!-- version: 7 -->
<!-- version: 8 -->
# Couches et dépendances KSP
@@ -150,7 +150,7 @@ Les exécutables et couches supérieures n'importent pas directement les crates
Exceptions bas niveau explicitement autorisées restent limitées aux primitives stables décidées par les règles KSP.
`ksp-interface-lib` concentre les interfaces/wires officielles ou compatibles afin d'éviter les doublons de générations et les dépendances protocolaires dans les couches supérieures.
`ksp-interface-lib` concentre les contrats passifs KSP réellement partagés — wires officiels/compatibles et faits provider-neutral admis — afin d'éviter les doublons de générations, les dépendances protocolaires dans les couches supérieures et la promotion accidentelle d'un DTO Transport en contrat transversal. Les converters depuis Transport restent dans la composition.
## Principe contract-first

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# Contrats initiaux des composants KSP
@@ -94,13 +94,13 @@ Il ne possède pas `WalletPolicy` ni les règles d'autorisation d'exécution.
Le wallet temporaire JSON historique n'est pas migré.
## Interface / wire
## Interface / contrats passifs
`ksp-interface-lib` est la façade wire officielle KSP et expose aussi une API publique wire réutilisable par `ksp-program-lib` et les extensions Program externes.
`ksp-interface-lib` possède les contrats passifs KSP réellement partagés entre composants : façade wire officielle lorsqu'un protocole commun l'exige, et faits d'acquisition provider-neutral lorsqu'une sémantique commune exacte est démontrée. Sa surface publique est réutilisable notamment par `ksp-program-lib`, les extensions Program externes et les composants de composition/acquisition qui ne doivent pas dépendre d'un DTO Transport particulier.
Aucune `ksp-interface-api` séparée n'est retenue actuellement.
La crate sélectionne entre réexport contrôlé, wrapper ou implémentation wire compatible selon stabilité, ownership et graphe de dépendances des interfaces externes.
La crate sélectionne entre réexport contrôlé, wrapper ou implémentation KSP-owned selon stabilité, ownership et graphe de dépendances. Elle ne possède ni Transport/runtime, ni Store/persistence, ni event bus ; les conversions depuis les DTOs Transport restent dans la composition.
## Program

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 26 -->
<!-- version: 27 -->
# Inventaire initial des composants KSP
@@ -32,7 +32,7 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
| Yellowstone | `ksp-onchain-transport-lib` | lib | Stable | `0.2.9` | client gRPC standard/provider-neutral |
| Off-chain price | `ksp-offchain-transport-lib` | lib | Stable | `0.2.11` | prix SOL/USD multi-provider, limits et availability |
| SOL Prices Desk | `ksp-app-solprices-desk` | app | Stable | `0.2.12` | HID provider-agnostic pour visualisation/refresh prix |
| Wire | `ksp-interface-lib` | lib | Stable | `0.2.13` | façade wire officielle + API publique wire |
| Interface passive | `ksp-interface-lib` | lib | Stable | `0.2.13` | façade wire + contrats passifs partagés, dont événements acquisition provider-neutral |
| Program API | `ksp-program-api` | API | Stable | `0.2.14` | contrats extensibles Program |
| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles |
| Program extension | `ksp-program-<name>-lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` |

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 17 -->
<!-- version: 18 -->
# Graphe de dépendances KSP
@@ -169,16 +169,17 @@ Le Wallet stocke/ouvre/signe. Il ne décide pas si une dépense est autorisée.
`WalletPolicy` historique migre conceptuellement vers execution policy, pas vers `ksp-wallet-lib`.
## Interface / wire
## Interface / contrats passifs
```text
ksp-interface-lib
-> ksp-core-lib
-> ksp-logging-lib lorsque runtime logging réel
-> official/compatible wire dependencies retenues
-> official/compatible wire dependencies uniquement lorsqu'un protocole réel les exige
```
`ksp-interface-lib` contient **à la fois** la façade wire officielle et une API publique wire utilisable par les implémentations Program officielles/externes.
`ksp-interface-lib` contient la façade wire officielle **et** les contrats passifs KSP-owned dont la sémantique est réellement partagée, y compris des faits d'acquisition provider-neutral. Les composants Program et les composants de composition peuvent consommer ces contrats sans importer un runtime Transport.
Un événement passif n'autorise aucune dépendance Interface vers Transport, Store, worker/job ou logging runtime. Les converters depuis des DTOs Transport restent dans la composition.
Aucune `ksp-interface-api` séparée n'est retenue actuellement.

34
docs/architecture/006-WIRE_AND_PROGRAM.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/006-WIRE_AND_PROGRAM.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Wire, Program API et implémentations Program
@@ -22,7 +22,7 @@ Les types Rust exacts restent volontairement à définir lors de la première im
## `ksp-interface-lib`
`ksp-interface-lib` est la façade wire officielle KSP pour les programmes Solana supportés officiellement.
`ksp-interface-lib` est la façade des contrats passifs KSP réellement partagés. Elle possède notamment les wires officiels nécessaires aux programmes Solana supportés et peut aussi posséder des faits d'acquisition provider-neutral lorsqu'ils ne sont ni des DTOs Transport ni des modèles persistants Store.
Elle possède ou réexporte de manière contrôlée les contrats nécessaires tels que :
@@ -38,29 +38,51 @@ 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 ;
- RPC/WS/gRPC/provider DTOs ou sessions ;
- event bus, worker, job ou scheduler ;
- wallet/signature capability ;
- persistence, Store, cursor ou retention ;
- matérialisation ;
- interprétation canonique/métier d'une instruction ;
- policy/safety ;
- lifecycle d'exécution réseau.
Les événements d'acquisition admis dans Interface sont de simples faits passifs supplémentaires. Ils ne remplacent pas le DTO Transport riche et leurs conversions appartiennent à la composition qui connaît les deux contrats.
## API publique de `ksp-interface-lib`
`ksp-interface-lib` reste une seule crate pour l'instant : aucune `ksp-interface-api` séparée n'est créée.
La façade doit néanmoins exposer une API publique wire stable et réutilisable par :
La façade doit néanmoins exposer une API publique stable et réutilisable par :
```text
ksp-program-lib
external ksp-program-<name>-lib
compositions/acquisition consumers utilisant un fait passif partagé
```
Une implementation externe peut donc expérimenter contre les mêmes contrats wire publics avant intégration officielle dans KSP. Lorsqu'un wire externe devient officiel, son intégration dans `ksp-interface-lib` doit rester compatible avec l'API publique retenue, sauf évolution de contrat explicitement versionnée/documentée.
Si une future contrainte de dépendances démontre qu'un split `ksp-interface-api` apporte une valeur réelle, il pourra être étudié selon `KSP-API-007`; la symétrie avec Program ne suffit pas.
## Événements passifs d'acquisition
Interface peut posséder un événement d'acquisition seulement si plusieurs sources/consumers partagent exactement le même fait et que le type reste plus petit que les DTOs producteurs. Le contrat ne doit pas accumuler des champs `Option` pour simuler l'union de protocoles hétérogènes.
La frontière durable est :
```text
DTO Transport riche et lossless
|
| conversion explicite par composition/consumer
v
événement Interface passif provider-neutral
```
Un événement Interface ne devient ni un message de bus obligatoire ni une donnée durable. Les informations replayables appartiennent à `ksp-store-api`; les détails de transport, provider, commitment, session, timestamp source-specific et diagnostics qui ne font pas partie du fait commun restent Transport-owned.
Les familles actuellement démontrées sont le lifecycle de slot et le résultat d'exécution d'une transaction. Toute nouvelle famille exige un nouveau gate de convergence, consumer et bornes.
## 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`.

5
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 7 -->
<!-- version: 8 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -353,11 +353,14 @@ ksp-job-backfill
ksp-worker-raw-retriever
-> ksp-worker-api
-> ksp-onchain-transport-lib
-> ksp-interface-lib # seulement si un fait passif partagé aide la composition live
-> ksp-store-lib # façade Store ; backend sélectionné par feature + Config
-> ksp-config-lib
-> ksp-logging-lib
```
Les événements Interface peuvent servir de signal provider-neutral à la composition live, mais ne constituent jamais le backlog durable. Après crash ou perte d'un événement, la reprise s'appuie sur Store et sur les primitives de replay/hydratation appropriées.
### CORE replay/worker
```text