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

v0.2.0-pre.002

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-17 13:33:37 +02:00
parent 7d40de3249
commit 259bff6707
23 changed files with 2999 additions and 3301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,30 +1,17 @@
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
<!-- version: 11 -->
<!-- version: 6 -->
# Contrats initiaux des composants KSP
## Objet
Ce document enregistre les frontières déjà suffisamment claires pour guider la planification. Il ne définit pas encore les API Rust finales.
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), le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md), Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) Execution/Policy dans [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md), Data/Materialization/Store dans [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md) Acquisition/Workers/Jobs dans [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) et Apps/Services/Scenarios/Control dans [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md).
Ce document synthétise les responsabilités des composants KSP. Les types Rust exacts restent définis au moment de leur première implémentation réelle.
## Convention API / implémentation
Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP peut séparer :
Une crate de contrats extensibles se nomme `ksp-<domain>-api`. Une implémentation réutilisable se nomme `ksp-<role>-lib`.
```text
ksp-<domain>-api
ksp-<domain>-lib
```
La crate `ksp-<domain>-api` est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`.
Cette séparation n'est pas automatique. Elle est utilisée lorsqu'une vraie frontière d'extension/backend/lifecycle la justifie.
Couples retenus :
Couples explicitement retenus :
```text
ksp-program-api / ksp-program-lib
@@ -32,185 +19,192 @@ ksp-materializer-api / ksp-materializer-lib
ksp-store-api / ksp-store-lib
```
APIs lifecycle retenues :
Lifecycle APIs séparées :
```text
ksp-worker-api
ksp-job-api
ksp-execution-policy-api
```
Aucune API commune worker+job n'est prévue.
Une crate `*-api` n'est jamais créée uniquement pour la symétrie des noms.
## Execution policy
## Core
`ksp-execution-policy-api` est un contrat public de décision séparé de `ksp-program-lib`, du wallet, du transport et de l'UI.
`ksp-core-lib` porte les primitives transversales réellement fondamentales, dont `Error`/`Result` et le registre KSP des Program IDs fondamentaux.
Une exécution réelle via `ksp-execution-lib` reçoit explicitement une policy ; aucun fallback permissif implicite n'est prévu.
La policy peut être évaluée à plusieurs checkpoints afin d'intégrer des informations obtenues pendant le cycle, notamment le résultat de simulation.
Une policy peut autoriser, refuser ou imposer des requirements ; elle ne réalise pas elle-même la simulation, la signature, le réseau ou une interaction Tauri.
Les implémentations appartiennent aux crates de contexte appropriées : scenario Devnet, future bibliothèque d'application générale, future policy trading, etc.
Aucune `ksp-execution-policy-lib` générique n'est prévue sans logique réellement commune.
## Execution orchestration
`ksp-execution-lib` consomme fondamentalement `PreparedProgramExecution` conforme à `ksp-program-api` et ne dépend pas de `ksp-program-lib`.
Il orchestre :
- policy checkpoints ;
- assemblage message/transaction ;
- simulation via `ksp-onchain-transport-lib` ;
- résolution des signers et signature via `ksp-wallet-lib` ;
- submission ;
- confirmation ;
- retry d'exécution lorsque celui-ci change le lifecycle ;
- suspension/reprise lorsqu'une approbation externe est requise.
Le wallet et le provider/réseau sont sélectionnés/fournis par la composition supérieure ; `ksp-execution-lib` les utilise sans définir une policy de sélection implicite.
Le retry d'un appel réseau identique reste une responsabilité transport, distincte du retry d'exécution nécessitant reconstruction/resimulation/resignature.
`ksp-execution-lib` ne persiste pas automatiquement son résultat et ne dépend pas du store.
Il ne devient pas une crate de modèles métier ou de transport.
## Logging
`ksp-logging-lib` est la façade KSP unique pour le logging/tracing runtime. Elle importe/initialise directement `tracing`, `tracing-appender` et `tracing-subscriber` et peut dépendre de `ksp-core-lib` pour `Error` / `Result`.
`ksp-logging-lib` est la façade unique KSP de tracing runtime.
Les crates comportementales KSP utilisent sa façade pour leurs événements `error`, `warn`, `info`, `debug`, `trace` et pour leurs spans sync/async. Elles n'émettent pas leurs propres logs via une dépendance directe à la stack tracing.
Les composants runtime émettent leurs événements via cette façade. Les targets tiers sont silencieux par défaut et les informations utiles sont réémises sous le target du composant KSP propriétaire.
Chaque émission KSP indique un target correspondant au nom Cargo de la crate propriétaire ; `domain`, `component` et les autres champs structurés décrivent les subdivisions fonctionnelles sans multiplier les targets.
## Config
Le subscriber KSP rend les targets tiers silencieux par défaut. Lorsqu'une information provenant d'une dépendance externe est nécessaire, la crate KSP qui possède l'opération la réémet explicitement sous son propre target ; Logging ne renomme pas les événements tiers.
`ksp-config-lib` est l'unique propriétaire des documents Config, `.env`, variables KSP/KSPB et persistence Config.
Logging possède ses `LoggingSettings`, ses writers/guards et son lifecycle. Le subscriber global est installé une fois, puis la configuration peut être rechargée à chaud via la façade KSP sans dépendance vers Config.
`ksp-core-lib` n'a pas de dépendance logging requise. Les crates `*-api` purement déclaratives restent sans logging par défaut.
Une application Tauri peut exceptionnellement avoir une dépendance/framework tracing imposée par un plugin, sans définir une politique parallèle à `ksp-logging-lib`; les événements KSP restent émis via la façade KSP.
## Frontière materializer / store
Les niveaux durables utilisent D1 Raw, D2 Core canonique, D3 journal de matérialisation générique et D4 projections spécialisées.
`ksp-materializer-api` peut dépendre de `ksp-program-api` pour consommer des contrats Core ouverts. Il doit pouvoir distinguer conceptuellement une matérialisation générique D2 -> D3 et une projection spécialisée D3 -> D4.
`ksp-materializer-lib` reste une bibliothèque de transformation et ne dépend ni de `ksp-store-api` ni de `ksp-store-lib`.
`ksp-store-api` possède les DTO/contrats persistants et reste indépendant des APIs Program/Materializer. Les workers/jobs de processing convertissent explicitement entre modèles runtime et modèles persistants.
D3 est un journal durable obligatoire ; D4 reste plus évolutif. Cette séparation évite d'introduire un `ksp-data-api` monolithique uniquement pour partager des modèles entre couches.
Les composants exposent leurs settings publics ; Config peut fournir un document standard et un adapter vers ces settings sans créer de dépendance inverse.
## Transport on-chain
Aucune `ksp-onchain-transport-api` séparée n'est prévue.
`ksp-onchain-transport-lib` regroupe les transports/providers on-chain et expose des modèles de sortie homogènes par catégorie de données.
`ksp-onchain-transport-lib` possède :
Il ne dépend pas de `ksp-store-api`.
- settings runtime publics ;
- endpoints/providers/clusters ;
- pools/rôles/capabilities ;
- HTTP JSON-RPC ;
- WebSocket ;
- Yellowstone gRPC et futurs adapters provider lorsque introduits ;
- modèles homogènes par catégorie de donnée ;
- observabilité transport.
Les modèles de transport doivent cependant être conçus pour une conversion explicite et simple vers les modèles raw persistants du store, sans décodage protocolaire.
Il ne dépend pas de Config, Store ou Program.
Pour toute surface normative ciblée, toutes les méthodes documentées sont inventoriées/implémentées sauf impossibilité documentée. Les méthodes deprecated/obsolete encore fonctionnelles et unstable/experimental émettent un warning KSP à l'utilisation.
## Transport off-chain
Aucune `ksp-offchain-transport-api` commune n'est prévue.
La crate est volontairement hétérogène : metadata, prix, quotes, routage et autres ressources externes peuvent avoir des modules/APIs distincts à l'intérieur d'une seule crate afin d'éviter une prolifération de crates artificielles.
`ksp-offchain-transport-lib` peut contenir plusieurs modules/APIs distincts : prix, metadata HTTP/IPFS/Arweave, quotes et autres accès externes. La première surface engagée est le prix SOL/USD et SOL/EUR.
## Wallet
Aucune `ksp-wallet-api` n'est prévue.
Aucune `ksp-wallet-api` séparée n'est prévue.
`ksp-wallet-lib` possède le format wallet KSP et les capacités de lecture/protection/import/export/pubkey/secret/signature nécessaires à ses consommateurs.
`ksp-wallet-lib` possède le format `.kspwallet`, le secret protégé, l'identité publique, signature, import/export et conversions utiles.
## Store et notifications de données
Il ne possède pas `WalletPolicy` ni les règles d'autorisation d'exécution.
`ksp-store-api` reste la frontière backend-agnostic. `ksp-store-lib` contient PostgreSQL comme implémentation de référence.
Le wallet temporaire JSON historique n'est pas migré.
Les notifications de données persistées sont normalisées indépendamment de leur producteur. W1, un job de backfill, un import ou un replay utilisent le même contrat pour signaler le même type de donnée.
## Interface / wire
Une notification est seulement un signal de réveil : le Store et les marqueurs d'idempotence/backlog restent la source de vérité. La publication suit l'ordre `persist -> commit -> notify`.
`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.
Le contrat de notification est distinct de son transport concret.
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.
## Program
`ksp-program-api` porte les contrats extensibles de Program : descriptors/capabilities, decoders, outputs et préparation d'exécution lorsque ces contrats sont démontrés.
`ksp-program-lib` porte les implementations officielles et dépend de `ksp-program-api`.
Une crate externe peut implémenter `ksp-program-api` sans dépendre de `ksp-program-lib`.
## Execution policy
`ksp-execution-policy-api` est le contrat commun de décision/safety.
Une policy décide ; elle ne signe pas, n'envoie pas et ne possède ni Wallet ni Transport.
Une petite policy de scenario/orchestrateur peut être implémentée localement. Des bibliothèques communes sont créées uniquement si une réutilisation réelle apparaît.
## Execution orchestration
`ksp-execution-lib` est introduit lorsque le premier vertical slice réel nécessite une orchestration stable entre :
```text
ksp-program-api
ksp-execution-policy-api
ksp-wallet-lib
ksp-onchain-transport-lib
```
Il ne dépend pas de `ksp-program-lib` afin d'accepter des implementations Program externes.
## Store et niveaux durables
La chaîne durable est :
```text
D1 RAW
-> D2 CORE
-> D3 DECODE
-> D4 SPECIALIZED
```
### RAW
Acquisition replayable + provenance, sans décodage Program.
### CORE
Normalisation générique Solana, sans décodage Program.
### DECODE
Interprétation Program/protocole puis matérialisation générique/journal durable.
### SPECIALIZED
Projections queryables de domaine : token, metadata, pools, trades, OHLC, routes, etc.
`ksp-store-api` possède les contrats backend-agnostic. `ksp-store-lib` fournit PostgreSQL comme backend officiel.
La première Store release est RAW-only ; les couches suivantes sont ajoutées quand elles sont réellement ouvertes.
## Materializer
`ksp-materializer-api`/`ksp-materializer-lib` sont introduits avec le premier besoin DECODE réel, pas avant.
Program et Materializer restent indépendants du backend Store ; les composants de composition convertissent leurs outputs vers les DTO persistants.
## Workers
`ksp-worker-api` est une lifecycle API pour services continus/live.
`ksp-worker-api` est la lifecycle API des services continus.
`ksp-worker-control-lib` est une implémentation réutilisable de gouvernance pouvant être consommée d'abord par les applications manager spécialisées, puis éventuellement par un futur orchestrateur ou une future application globale.
RAW et CORE peuvent recevoir leurs workers à la fin de leur couche respective.
Workers retenus :
```text
ksp-worker-raw-retriever
ksp-worker-core-processor
ksp-worker-generic-materializer
ksp-worker-domain-projector
```
Le dernier nom reste provisoire.
Chaque worker doit pouvoir fonctionner comme service/processus indépendant afin d'être arrêté, redémarré ou mis à jour sans imposer l'arrêt des autres. La direction de packaging préférée est un package `ksp-worker-*` avec cible bibliothèque réutilisable et binaire autonome mince.
Les workers de processing utilisent le Store comme source de vérité du backlog, peuvent être réveillés par notification, et doivent pouvoir reprendre après crash. Le raw retriever possède en plus une capacité de hot reconfiguration de sa sélection d'acquisition.
Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program réels, afin de ne pas créer une orchestration générique vide avant les processors.
## Jobs
`ksp-job-api` est une lifecycle API distincte pour travaux déclenchés et terminables.
`ksp-job-api` est la lifecycle API des travaux déclenchés/terminables.
Jobs de données retenus :
Le premier job retenu est le backfill RAW.
Les jobs de replay suivent ensuite les frontières durables ouvertes : RAW -> CORE, CORE -> DECODE, DECODE -> SPECIALIZED.
Aucune `ksp-job-control-lib` n'est prévue sans duplication concrète.
## Scenarios
Les scenarios restent dans `ksp-scenario-<domain>-lib` et sont appelables sans desktop.
Ils composent les Program implementations, policy, Wallet, transport et execution nécessaires à leur vertical slice.
L'application demo correspondante reste une UI mince.
## Applications
KSP privilégie des applications spécialisées servant à valider/exploiter une capacité réelle :
```text
ksp-job-backfill
ksp-job-replay-core
ksp-job-replay-generic-materialization
ksp-job-replay-domain-projection
ksp-app-config-desk
ksp-app-wallet-desk
price desk
backfill/raw tooling
CORE tooling
ksp-app-market-desk
```
Les trois jobs de replay correspondent exactement aux frontières D1 -> D2, D2 -> D3 et D3 -> D4.
Une application globale reste future.
Aucune `ksp-job-control-lib` n'est prévue actuellement. D'autres jobs pourront apparaître pour metadata, quotes ou autres besoins ponctuels.
## Progression verticale Program
## Scénarios
Les scénarios restent dans des crates spécialisées `ksp-scenario-<domain>-lib`.
`ksp-scenario-api` n'est pas retenu actuellement : `docs/rules/SCENARIO_CONVENTION.md` porte la norme commune tant qu'un vrai contrat Rust réutilisable n'a pas émergé.
Les demos desktop de scénario suivent provisoirement la forme :
À partir de DECODE :
```text
ksp-app-scenario-<domain>-<environment>-desk-demo
wire -> decode -> materialize -> specialized -> prepare -> policy -> execute -> scenario
```
et réutilisent la crate de scénario correspondante.
Ordre prioritaire actuel : Solana Core Programs, SPL token/trading, token metadata, Anchor, Meteora, Raydium, Pump, Orca, routing, trading-adjacent, puis décodage généraliste.
## Applications, services et control plane
Les applications spécialisées sont développées avant toute application globale.
Les apps restent des interfaces/compositions et ne réimplémentent pas les workflows des bibliothèques/services sous-jacents.
Les workers sont des services autonomes et ne communiquent pas directement leurs données entre eux. D1–D4 constituent le data plane ; `ksp-worker-api`, `ksp-worker-control-lib`, `ksp-job-api` et le futur IPC constituent le control plane.
Aucun `ksp-ipc-api` générique ni `ksp-orchestrator-lib` n'est retenu comme crate actuelle.
Une future application globale est conservée comme idée produit, pas comme tâche du roadmap présent.
## Pipelines
Aucun `ksp-pipeline-lib` monolithique.
Quatre pipelines spécialisés sont maintenant retenus parce qu'ils évitent de dupliquer une même frontière entre worker live et job :
```text
ksp-pipeline-raw-ingestion-lib
ksp-pipeline-core-processing-lib
ksp-pipeline-generic-materialization-lib
ksp-pipeline-domain-projection-lib
```
Ils dépendent des APIs de domaine nécessaires, pas des implémentations officielles `ksp-store-lib`, `ksp-program-lib` ou `ksp-materializer-lib`. Les workers/jobs réalisent cette composition.
Un satellite nécessaire reste dans son groupe protocolaire.