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

v0.2.6-rel.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-22 14:16:31 +02:00
parent 79fee574d9
commit 3c9c1d1349
32 changed files with 428 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 18 -->
<!-- version: 19 -->
# Inventaire initial des composants KSP
@@ -17,42 +17,42 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
## Inventaire synthétique
| Domaine | Composant | Type | Statut | Première cible actuelle | Mission |
|-------------------------|------------------------------------------|--------------------|--------------|---------------------------------|--------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales |
| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP |
| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config |
| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config |
| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Stable | `0.2.1`–`0.2.4` | HTTP standard complet : 52/52 current + 14/14 historical |
| Wallet | `ksp-wallet-lib` | lib | Stable | `0.2.5` | `.kspwallet`, VIEW/OWNER, secrets, signature, import/export |
| Wallet Desk | `ksp-app-wallet-desk` | app | Retenu | `0.2.6` | Wallet + Config composite + HTTP/balance |
| Wallet V2 | `ksp-wallet-lib` | lib | En cours | `0.2.6` | wire/runtime V2 + API default/versionnée ; migration pre.017 |
| Standard WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.7` | WebSocket Solana complet, sessions/subscriptions |
| Helius WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.8` | LaserStream WebSocket comme extension du moteur standard |
| Yellowstone | `ksp-onchain-transport-lib` | lib | Pressenti | `0.2.9` | client gRPC standard/provider-neutral |
| Off-chain price | `ksp-offchain-transport-lib` | lib | Retenu | `0.2.10` | première abstraction/provider de prix SOL/USD, SOL/EUR |
| Price Desk | nom à fixer | app | Retenu | `0.2.11` | visualisation/validation des prix + intégration Wallet Desk |
| Wire | `ksp-interface-lib` | lib | Retenu | `0.2.12` | façade wire officielle + API publique wire |
| Program API | `ksp-program-api` | API | Retenu | `0.2.13` | 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` |
| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | contrats persistence backend-agnostic, RAW d'abord |
| Store PostgreSQL | `ksp-store-lib` | lib | Retenu | `0.3.1` | backend PostgreSQL officiel, RAW d'abord |
| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.3` | lifecycle des jobs terminables |
| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.3` | acquisition historique vers RAW |
| Backfill Desk | nom à fixer | app | Retenu | `0.3.4` | contrôle/inspection du backfill RAW |
| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus |
| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW |
| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE |
| CORE worker | nom à fixer | worker | Retenu | fin couche CORE | backlog RAW -> CORE continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes |
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun |
| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC |
| Trading Intelligence | noms à définir | libs/jobs | Futur | après données stables | features/signaux/anomalies/ML |
| Domaine | Composant | Type | Statut | Première cible actuelle | Mission |
|-------------------------|------------------------------------------|--------------------|--------------|---------------------------------|----------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales |
| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP |
| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config |
| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config |
| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Stable | `0.2.1`–`0.2.4` | HTTP standard complet : 52/52 current + 14/14 historical |
| Wallet | `ksp-wallet-lib` | lib | Stable | `0.2.5` | `.kspwallet`, VIEW/OWNER, secrets, signature, import/export |
| Wallet Desk | `ksp-app-wallet-desk` | app | Stable | `0.2.6` | Wallet + Config composite + HTTP/balance |
| Wallet V2 | `ksp-wallet-lib` | lib | Stable | `0.2.6` | wire/runtime V2 + API default/versionnée + migration explicite |
| Standard WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.7` | WebSocket Solana complet, sessions/subscriptions |
| Helius WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.8` | LaserStream WebSocket comme extension du moteur standard |
| Yellowstone | `ksp-onchain-transport-lib` | lib | Pressenti | `0.2.9` | client gRPC standard/provider-neutral |
| Off-chain price | `ksp-offchain-transport-lib` | lib | Retenu | `0.2.10` | première abstraction/provider de prix SOL/USD, SOL/EUR |
| Price Desk | nom à fixer | app | Retenu | `0.2.11` | visualisation/validation des prix + intégration Wallet Desk |
| Wire | `ksp-interface-lib` | lib | Retenu | `0.2.12` | façade wire officielle + API publique wire |
| Program API | `ksp-program-api` | API | Retenu | `0.2.13` | 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` |
| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | contrats persistence backend-agnostic, RAW d'abord |
| Store PostgreSQL | `ksp-store-lib` | lib | Retenu | `0.3.1` | backend PostgreSQL officiel, RAW d'abord |
| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.3` | lifecycle des jobs terminables |
| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.3` | acquisition historique vers RAW |
| Backfill Desk | nom à fixer | app | Retenu | `0.3.4` | contrôle/inspection du backfill RAW |
| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus |
| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW |
| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE |
| CORE worker | nom à fixer | worker | Retenu | fin couche CORE | backlog RAW -> CORE continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes |
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun |
| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC |
| Trading Intelligence | noms à définir | libs/jobs | Pressenti | après données stables | features/signaux/anomalies/ML |
## Contrats séparés retenus

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 12 -->
<!-- version: 13 -->
# Graphe de dépendances KSP
@@ -33,7 +33,7 @@ Les applications/jobs/workers/scenarios composent les implementations concrètes
Workers continus et jobs bornés gardent des lifecycle APIs séparées.
# Fondations N1
## Fondations N1
```text
ksp-core-lib
@@ -50,7 +50,7 @@ ksp-config-lib
`ksp-config-lib` est l'unique propriétaire des documents Config, `.env` et variables KSP/KSPB.
# Transport on-chain
## Transport on-chain
```text
ksp-onchain-transport-lib
@@ -83,7 +83,7 @@ ksp-onchain-transport-lib
Cette direction est analogue à Config -> Logging : Config exprime/adapte la configuration, le composant reste propriétaire de ses contrats runtime.
## HTTP
### HTTP
```text
HttpEndpointConfig
@@ -96,7 +96,7 @@ JSON-RPC read/write methods
Le pool HTTP sélectionne des endpoints/clients logiques selon rôles/capabilities/priorités/limites.
## WebSocket
### WebSocket
```text
WsEndpoint
@@ -110,11 +110,11 @@ Plusieurs sessions sur une même URL sont autorisées. Un scheduler/pool automat
Helius LaserStream WebSocket étend le même moteur/session ; il ne duplique pas le client standard.
## Yellowstone
### Yellowstone
Yellowstone gRPC est un backend standard/provider-neutral. Les adapters/capabilities Helius/Triton/ERPC/Chainstack/Shyft peuvent venir plus tard sans redéfinir le contrat générique.
# Transport off-chain
## Transport off-chain
```text
ksp-offchain-transport-lib
@@ -127,7 +127,7 @@ Aucune `ksp-offchain-transport-api` globale n'est prévue.
La première surface est un reader de prix ; metadata HTTP/IPFS/Arweave et autres besoins sont ajoutés lorsqu'ils deviennent concrets.
# Wallet
## Wallet
```text
ksp-wallet-lib
@@ -159,7 +159,7 @@ 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 / wire
```text
ksp-interface-lib
@@ -182,7 +182,7 @@ ksp-interface-lib -X-> Store
ksp-interface-lib -X-> Wallet
```
# Program
## Program
```text
ksp-program-api
@@ -206,7 +206,7 @@ ksp-program-<name>-lib
Elle n'a pas besoin de dépendre de `ksp-program-lib`.
# Execution / Policy
## Execution / Policy
```text
ksp-execution-policy-api
@@ -229,7 +229,7 @@ ksp-execution-lib -X-> ksp-program-lib
Une petite policy spécifique peut vivre dans une crate scenario/orchestrateur. Une ou plusieurs bibliothèques de policies communes ne sont créées qu'après démonstration d'une réutilisation réelle.
# Data plane durable
## Data plane durable
```text
D1 RAW
@@ -238,7 +238,7 @@ D1 RAW
-> D4 SPECIALIZED
```
## RAW
### RAW
```text
transport model
@@ -253,7 +253,7 @@ ksp-store-api
ksp-store-lib
```
## CORE
### CORE
```text
D1 RAW
@@ -275,7 +275,7 @@ RAW -> CORE -X-> ksp-program-lib
RAW -> CORE -X-> ksp-materializer-api
```
## DECODE
### DECODE
```text
D2 CORE
@@ -293,7 +293,7 @@ ksp-materializer-api implementation
D3 DECODE / generic journal
```
## SPECIALIZED
### SPECIALIZED
```text
D3 DECODE
@@ -305,7 +305,7 @@ specialized projector/materializer
D4 SPECIALIZED
```
# Materialization
## Materialization
```text
ksp-materializer-api
@@ -319,7 +319,7 @@ ksp-materializer-lib
Program/Materializer ne dépendent pas du Store backend.
# Store
## Store
```text
ksp-store-api
@@ -341,7 +341,7 @@ ksp-store-lib -X-> transport/program/materializer
La première release Store (`0.3.1`) est RAW-only ; les contrats CORE/DECODE/SPECIALIZED sont ajoutés avec leurs couches.
# Jobs
## Jobs
```text
ksp-job-api
@@ -361,7 +361,7 @@ ksp-job-backfill
Il remplit RAW et ne décode rien.
# Workers
## Workers
```text
ksp-worker-api
@@ -376,9 +376,9 @@ RAW worker et CORE worker sont introduits à la fin de leur couche respective, l
Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.
# Apps
## Apps
## Wallet Desk
### Wallet Desk
```text
ksp-app-wallet-desk
@@ -390,7 +390,7 @@ ksp-app-wallet-desk
L'app compose ; elle ne déplace pas Config/Wallet/Transport dans Tauri. Les handles `WalletView`/`WalletOwner` restent côté Rust, et le frontend ne reçoit que des DTOs sûrs. Config fournit la racine/profil Wallet et le profil Transport. Les passwords Wallet ne deviennent jamais des champs des documents JSON Config ; ils peuvent être saisis éphémèrement frontend -> Rust ou provenir plus tard de secrets process/`.env` `KSP_SECRET_WALLET_PASS_*` possédés exclusivement par Config. Le secret Solana ne devient jamais une valeur Config ni un DTO frontend.
## Price Desk
### Price Desk
```text
price desk
@@ -399,7 +399,7 @@ price desk
-> ksp-logging-lib
```
## Backfill app
### Backfill app
```text
backfill app
@@ -409,7 +409,7 @@ backfill app
-> ksp-logging-lib
```
## Market Desk
### Market Desk
```text
ksp-app-market-desk
@@ -420,7 +420,7 @@ ksp-app-market-desk
Elle consomme les projections SPECIALIZED normalisées ; elle ne dépend pas directement des bibliothèques protocole externes.
# Scenarios
## Scenarios
```text
ksp-scenario-<domain>-lib
@@ -437,7 +437,7 @@ Une policy Devnet petite et spécifique peut être implémentée dans la crate s
L'app demo correspondante reste un adapter UI mince.
# Progression verticale Program
## Progression verticale Program
À partir de DECODE :
@@ -454,7 +454,7 @@ wire
Les satellites nécessaires restent dans le même groupe protocolaire.
# Contrôle des cycles
## Contrôle des cycles
Le sens général reste descendant :
@@ -476,7 +476,7 @@ job-api
Les applications/orchestrateurs réalisent les compositions explicites ; aucune boucle inverse ne doit être créée pour éviter une conversion au bon niveau.
# Dépendances non retenues actuellement
## Dépendances non retenues actuellement
```text
ksp-api-lib

52
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Data, Materialization et Store
@@ -32,9 +32,9 @@ Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait dé
- les couches dérivées ne rendent jamais obligatoire une nouvelle acquisition réseau lorsque l'input durable nécessaire existe déjà ;
- D4 privilégie les faits métier génériques lorsqu'une normalisation inter-protocoles est pertinente.
# D1 — RAW
## D1 — RAW
## Mission
### Mission
RAW conserve l'acquisition suffisamment fidèlement pour reconstruire CORE sans redemander la donnée au provider lorsqu'elle a déjà été capturée.
@@ -42,7 +42,7 @@ Le transport peut normaliser plusieurs providers vers un modèle KSP homogène,
D1 ne décode aucun programme Solana/SPL/Metaplex/DEX.
## Frontière Transport -> RAW
### Frontière Transport -> RAW
```text
HTTP / WS / gRPC / provider
@@ -62,7 +62,7 @@ ksp-store-lib
`ksp-onchain-transport-lib` ne dépend ni de `ksp-store-api` ni de `ksp-store-lib`.
## Provenance RAW
### Provenance RAW
Selon la catégorie, D1 doit pouvoir conserver notamment :
@@ -77,9 +77,9 @@ Selon la catégorie, D1 doit pouvoir conserver notamment :
- identité/hash d'idempotence ;
- cursor/page/range/checkpoint lorsque pertinent.
# D2 — CORE
## D2 — CORE
## Mission
### Mission
CORE est une **normalisation canonique générique de la blockchain Solana**.
@@ -104,7 +104,7 @@ Exemples de faits CORE candidats :
Un fait CORE peut contenir un `program_id`, des bytes et des indexes sans savoir que l'instruction représente un `Transfer`, un `Swap` ou une mutation Metadata.
## Frontière RAW -> CORE
### Frontière RAW -> CORE
```text
D1 RAW
@@ -126,7 +126,7 @@ RAW -> CORE -X-> ksp-materializer-api
Les codecs/wires génériques nécessaires à la structure Solana peuvent provenir de `ksp-interface-lib` lorsqu'ils appartiennent à la façade wire officielle, sans transformer cette étape en décodage Program.
## Provenance CORE
### Provenance CORE
D2 doit pouvoir relier chaque résultat à :
@@ -136,9 +136,9 @@ D2 doit pouvoir relier chaque résultat à :
- l'instant de processing/persistence ;
- son état de processing durable lorsque nécessaire.
# D3 — DECODE / matérialisation générique
## D3 — DECODE / matérialisation générique
## Mission
### Mission
DECODE commence lorsque KSP interprète un `program_id`, un layout d'instruction, un compte ou un événement selon un contrat Program/protocole.
@@ -179,7 +179,7 @@ quel état/superseded/failed/replay ?
Les types exacts de decoded facts et du journal sont décidés lorsque les premiers vertical slices Program existent.
## Frontière CORE -> DECODE
### Frontière CORE -> DECODE
```text
D2 CORE
@@ -201,9 +201,9 @@ Les implémentations officielles pourront provenir de `ksp-program-lib` et `ksp-
Program et Materializer ne dépendent pas du backend Store.
# D4 — SPECIALIZED
## D4 — SPECIALIZED
## Mission
### Mission
SPECIALIZED expose des projections queryables utiles aux applications, analyses et futurs modèles ML.
@@ -222,7 +222,7 @@ Exemples :
- faits trading-adjacent ;
- projections d'autres domaines futurs.
## Faits métier génériques
### Faits métier génériques
Les projections de trading ne sont pas séparées automatiquement par protocole.
@@ -249,20 +249,20 @@ pump_trades
Les champs réellement protocol-specific peuvent être conservés dans une extension ou une projection dédiée uniquement lorsqu'un besoin de requête/invariant le justifie.
## Metadata
### Metadata
La direction reste :
- projection canonique commune pour metadata d'assets/tokens alimentée par Metaplex Token Metadata et Token-2022 Metadata ;
- SPM reste distinct et sera redéveloppé plus tard avec le décodage généraliste.
## OHLC
### OHLC
Les candles sont des projections SPECIALIZED calculées à partir des trades/price observations persistés.
Une application marché lit les OHLC matérialisés ; elle ne reparcourt pas toutes les transactions pour reconstruire les candles à chaque affichage.
# Vertical slices Program
## Vertical slices Program
RAW et CORE sont développés horizontalement.
@@ -283,7 +283,7 @@ Un groupe doit atteindre une cohérence verticale suffisante avant que le groupe
Les composants satellites nécessaires à un protocole appartiennent à son groupe : Pump fees avec Pump, Meteora vaults avec Meteora, etc.
# `ksp-store-api`
## `ksp-store-api`
`ksp-store-api` est backend-agnostic et porte les contrats nécessaires aux consommateurs.
@@ -291,7 +291,7 @@ La première implementation `0.3.1` est volontairement **RAW-only** : elle ne cr
Les surfaces CORE/DECODE/SPECIALIZED sont ajoutées quand leurs couches sont réellement ouvertes.
# `ksp-store-lib`
## `ksp-store-lib`
`ksp-store-lib` fournit PostgreSQL comme backend officiel de référence derrière `ksp-store-api`.
@@ -312,7 +312,7 @@ Il ne possède pas :
- materializer ;
- orchestration de worker/job.
# `ksp-materializer-api` et `ksp-materializer-lib`
## `ksp-materializer-api` et `ksp-materializer-lib`
Ils sont introduits seulement lorsque le premier groupe DECODE démontre le contrat réel.
@@ -320,7 +320,7 @@ Ils sont introduits seulement lorsque le premier groupe DECODE démontre le cont
Une projection très locale/spécifique peut rester dans son groupe si la création d'une implémentation commune séparée n'apporte pas de réutilisation réelle.
# Replay
## Replay
Les frontières durables restent replayables indépendamment :
@@ -332,7 +332,7 @@ DECODE -> SPECIALIZED
Un replay d'une couche dérivée ne doit pas refaire arbitrairement les couches précédentes.
# Notifications persistées
## Notifications persistées
Le Store reste source de vérité du backlog.
@@ -348,7 +348,7 @@ notify
Le consumer reconstruit toujours son backlog depuis le Store avec les versions de processor et les marqueurs d'idempotence.
# Acquisition live et backfill
## Acquisition live et backfill
Live et backfill alimentent la même frontière RAW :
@@ -360,7 +360,7 @@ backfill job ----/
Ils ne dupliquent pas le contrat durable.
# Stabilité
## Stabilité
La stabilité cible est différente selon la couche :
@@ -369,7 +369,7 @@ La stabilité cible est différente selon la couche :
- DECODE : extensible par nouveaux Program/versions ;
- SPECIALIZED : plus évolutif selon les besoins de query, trading et analytics.
# Questions laissées ouvertes
## Questions laissées ouvertes
- schémas SQL exacts RAW puis CORE ;
- représentation persistable exacte d'un decoded output ;

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -33,9 +33,9 @@ persistence
À partir de DECODE, les processors/jobs/workers/scenarios sont introduits **avec le groupe Program concerné**, en vertical slice, au lieu de créer à l'avance une grande flotte générique de workers de décodage/materialisation sans programme réel.
# RAW
## RAW
## Pipeline RAW ingestion
### Pipeline RAW ingestion
Concept :
@@ -59,7 +59,7 @@ Une crate spécialisée `ksp-pipeline-raw-ingestion-lib` peut être introduite l
Elle ne choisit pas le provider réseau et ne pilote pas le range historique.
## `ksp-job-backfill`
### `ksp-job-backfill`
Le premier backfill historique appartient à la couche RAW :
@@ -83,7 +83,7 @@ Le job :
- n'effectue aucun décodage Program ;
- n'écrit pas directement des faits CORE/DECODE/SPECIALIZED.
## Worker RAW live
### Worker RAW live
Le worker live futur :
@@ -113,9 +113,9 @@ Sa hot reconfiguration peut concerner selon le transport :
La configuration desired/effective reste distinguée lorsqu'une reconfiguration est asynchrone.
# CORE
## CORE
## Pipeline RAW -> CORE
### Pipeline RAW -> CORE
La normalisation CORE est générique Solana :
@@ -139,7 +139,7 @@ CORE normalizer -X-> ksp-materializer-api
`ksp-interface-lib` peut fournir les wires Solana génériques nécessaires à la structure blockchain.
## Job replay CORE
### Job replay CORE
Un job borné peut rejouer :
@@ -155,15 +155,15 @@ D2 CORE
sans redemander les données au réseau.
## Worker CORE
### Worker CORE
Un worker CORE continu peut consommer le backlog RAW nouvellement persisté et produire CORE.
Le Store reste source de vérité du backlog ; les notifications ne sont qu'un wake-up.
# DECODE et SPECIALIZED
## DECODE et SPECIALIZED
## Introduction par groupe fonctionnel
### Introduction par groupe fonctionnel
KSP ne crée pas d'abord un unique « worker decoder de tout Solana » puis tous les materializers plusieurs séries plus tard.
@@ -189,7 +189,7 @@ Puis le même groupe avance vers préparation d'exécution, policy, execution et
Les jobs de replay et workers live correspondants réutilisent les mêmes processors du groupe.
## Ordre fonctionnel
### Ordre fonctionnel
Direction actuelle :
@@ -211,7 +211,7 @@ Solana Core Programs
Un satellite protocolaire reste avec son groupe : Meteora vaults avec Meteora, Pump fee avec Pump, etc.
# Worker API
## Worker API
`ksp-worker-api` reste une lifecycle API générique pour services continus.
@@ -236,7 +236,7 @@ health
Une capability comme `reconfigure` n'est pas imposée à tous les workers.
# Job API
## Job API
`ksp-job-api` reste distinct de Worker API.
@@ -266,7 +266,7 @@ Les types exacts sont décidés à `0.3.3` avec le premier vrai backfill.
Aucune `ksp-job-control-lib` n'est créée sans duplication concrète.
# Backlog, claim et idempotence
## Backlog, claim et idempotence
Pour les processors asynchrones :
@@ -292,7 +292,7 @@ Les notifications ne remplacent jamais le Store.
La sémantique cible reste at-least-once avec idempotence durable, plutôt qu'un faux exactly-once.
# Processing outcomes
## Processing outcomes
Les états exacts seront définis avec le premier processor durable, mais doivent distinguer au minimum les familles conceptuelles :
@@ -303,7 +303,7 @@ Les états exacts seront définis avec le premier processor durable, mais doiven
- unsupported ;
- superseded/replayed lorsque pertinent.
# Reprise après crash
## Reprise après crash
Un worker/job doit reconstruire son état depuis :
@@ -315,7 +315,7 @@ Un worker/job doit reconstruire son état depuis :
La mémoire du processus ne constitue jamais l'unique source de reprise.
# Logging
## Logging
Tous les pipelines/workers/jobs runtime utilisent `ksp-logging-lib`.
@@ -332,9 +332,9 @@ Les événements utiles comprennent notamment :
- reconfiguration desired/effective ;
- erreurs redacted.
# Dépendances de composition
## Dépendances de composition
## RAW backfill
### RAW backfill
```text
ksp-job-backfill
@@ -345,7 +345,7 @@ ksp-job-backfill
-> ksp-logging-lib
```
## RAW worker
### RAW worker
```text
ksp-worker-raw-retriever
@@ -356,7 +356,7 @@ ksp-worker-raw-retriever
-> ksp-logging-lib
```
## CORE replay/worker
### CORE replay/worker
```text
CORE processor
@@ -368,7 +368,7 @@ CORE processor
Pas de Program API.
## Groupes DECODE/SPECIALIZED
### Groupes DECODE/SPECIALIZED
Le composant de composition du groupe peut utiliser :
@@ -382,7 +382,7 @@ ksp-store-api
selon les capacités réellement introduites.
# Questions laissées ouvertes
## Questions laissées ouvertes
- nom final de la crate pipeline RAW si la réutilisation justifie une crate dédiée ;
- nom final du worker RAW ;

58
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Applications, services, scenarios et control plane
@@ -22,7 +22,7 @@ Les décisions portent sur :
- futur IPC ;
- futur orchestrateur/global app uniquement comme idées à conserver.
# Principe général des applications
## Principe général des applications
Une application KSP est une interface et une couche de composition.
@@ -47,13 +47,13 @@ Elle ne doit pas réimplémenter :
- lifecycle interne d'un worker/job ;
- logique de pipeline réutilisable.
# Applications de validation par couche
## Applications de validation par couche
KSP peut ajouter une petite application spécialisée à la fin d'une couche RAW ou CORE lorsque cela permet de valider et exploiter réellement la couche avant de passer à la suivante. Ces applications lisent les contrats KSP et ne recopient pas les processors dans Tauri.
À partir des vertical slices Program, les applications restent attachées aux besoins réels : demos de scenarios pour l'exécution et Market Desk pour les projections de marché.
# Priorité aux applications spécialisées
## Priorité aux applications spécialisées
KSP ne planifie pas actuellement de cockpit desktop global.
@@ -85,7 +85,7 @@ Les noms exacts des managers workers seront décidés avec les premières applic
Une future application globale de contrôle/exploitation est considérée comme un produit futur attendu, mais elle n'est pas un livrable du roadmap actuel et ne doit pas influencer prématurément les contrats.
# Applications spécialisées et dépendances directes
## Applications spécialisées et dépendances directes
Une application spécialisée peut dépendre directement de la bibliothèque KSP correspondant à sa responsabilité.
@@ -105,7 +105,7 @@ ksp-app-store-desk
Les couches N1–N4 expriment des responsabilités et une direction de dépendances ; elles n'imposent pas de traverser toutes les couches intermédiaires.
# Tauri
## Tauri
Les applications desktop Tauri restent des adapters/interfaces.
@@ -127,7 +127,7 @@ Une application Tauri peut devoir intégrer un plugin/framework de tracing, mais
En distribution, une application Tauri KSP ne dépend pas du checkout source ni du CWD du launcher. Les resources Config/Schemas nécessaires sont embarquées dans le bundle ; Tauri résout leur racine immutable et `ksp-config-lib` prépare une racine KSP user-writable commune avant le bootstrap applicatif. Les Config utilisateur existantes sont conservées, les schemas package-owned sont resynchronisés et `.env` reste une ressource locale writable jamais embarquée. Cette adaptation de packaging ne transfère ni ownership Config ni accès filesystem au frontend.
# Workers comme services indépendants
## Workers comme services indépendants
Les workers KSP doivent pouvoir fonctionner comme **services/processus indépendants**.
@@ -143,7 +143,7 @@ Les workers ne forment pas un pipeline process-to-process couplé.
Ils synchronisent leur data plane via les niveaux durables du Store.
## Packaging préféré
### Packaging préféré
Pour éviter de séparer artificiellement logique réutilisable et executable dans deux packages lorsqu'il n'y a pas encore de besoin, la direction préférée est :
@@ -171,7 +171,7 @@ Il ne duplique pas le pipeline ni la logique de worker contenue dans la cible bi
Une séparation future en packages distincts `*-lib` / executable n'est introduite que si un besoin concret le justifie.
# Responsabilité du binaire worker
## Responsabilité du binaire worker
Le binaire autonome peut notamment :
@@ -186,7 +186,7 @@ Le binaire autonome peut notamment :
Il ne contient pas de logique de processing qui ne serait pas réutilisable depuis la bibliothèque worker.
# Indépendance des workers
## Indépendance des workers
Aucun worker ne dépend directement d'un autre worker concret.
@@ -222,7 +222,7 @@ Les notifications accélèrent le réveil mais ne créent pas une connexion fonc
Cette indépendance permet arrêt, restart ou mise à jour d'un worker sans arrêter volontairement les autres.
# Ordre global de démarrage
## Ordre global de démarrage
Aucun ordre global strict de démarrage n'est figé dans cette prerelease.
@@ -234,11 +234,11 @@ La robustesse recherchée est :
Un futur manager/orchestrateur pourra choisir un ordre pratique de démarrage/arrêt, mais cette policy n'est pas inscrite dans les contrats worker.
# Data plane et control plane
## Data plane et control plane
KSP distingue explicitement deux plans.
## Data plane
### Data plane
Le data plane transporte/persiste les données Solana et les résultats de processing :
@@ -253,7 +253,7 @@ avec notifications de données persistées comme wake-up.
Les workers ne s'échangent pas leurs payloads via le control plane.
## Control plane
### Control plane
Le control plane sert à :
@@ -276,7 +276,7 @@ future manager/orchestrator
Le control plane n'est pas le data plane.
# `ksp-worker-control-lib`
## `ksp-worker-control-lib`
`ksp-worker-control-lib` reste la bibliothèque de gouvernance réutilisable au-dessus de `ksp-worker-api`.
@@ -297,7 +297,7 @@ Elle ne connaît pas :
- Tauri ;
- les types propriétaires d'un worker concret au-delà des contrats publics nécessaires.
# Worker local et worker distant
## Worker local et worker distant
La sémantique de `ksp-worker-api` ne doit pas dépendre du fait qu'un worker soit appelé :
@@ -323,7 +323,7 @@ Conceptuellement :
Le type exact de proxy/transport n'est pas défini maintenant.
# IPC
## IPC
Le besoin d'IPC existe naturellement dès qu'une app manager doit piloter un worker autonome.
@@ -345,7 +345,7 @@ Le premier manager/service réel devra choisir un mécanisme IPC adapté et pour
Le choix du mécanisme exact est reporté à la release fonctionnelle concernée.
# Jobs
## Jobs
Les jobs restent distincts des workers.
@@ -357,7 +357,7 @@ Le fait qu'un worker soit un process/service indépendant ne force pas les jobs
Le packaging/exécution des jobs sera déterminé avec les premiers jobs réels.
# Scenarios : logique dans la bibliothèque
## Scenarios : logique dans la bibliothèque
La source de vérité d'un scenario est toujours :
@@ -387,7 +387,7 @@ Elle peut être consommée par :
- futur CLI/tool ;
- CI/integration environment lorsque pertinent.
# Pas de `ksp-scenario-api` actuellement
## Pas de `ksp-scenario-api` actuellement
Aucun trait universel de scenario n'est imposé.
@@ -395,7 +395,7 @@ Les premières implementations utilisent une norme documentaire commune définie
Une API commune ne sera créée que si plusieurs scenarios réels révèlent un contrat réutilisable qui apporte plus que des conventions.
# Applications desktop demo de scenarios
## Applications desktop demo de scenarios
Convention retenue :
@@ -429,7 +429,7 @@ KSP capabilities
L'app ne construit pas un scenario parallèle.
# Scenarios et execution policy
## Scenarios et execution policy
Une crate scenario peut fournir une implémentation de `ksp-execution-policy-api` adaptée à son environnement.
@@ -443,7 +443,7 @@ Exemple Devnet :
Cette policy appartient au scenario, pas à `ksp-program-lib`.
# Applications worker spécialisées
## Applications worker spécialisées
Une application spécialisée de worker peut être créée lorsqu'elle est utile pour développer/tester/exploiter ce service.
@@ -466,7 +466,7 @@ independent worker service
La nomenclature précise des apps sera fixée à la première implémentation pour éviter de multiplier prématurément les packages.
# Configuration desired vs effective
## Configuration desired vs effective
La configuration persistée/résolue et la configuration effectivement appliquée sont deux faits distincts.
@@ -483,7 +483,7 @@ worker status
Une app spécialisée peut éditer une configuration puis demander son application, mais ne doit pas considérer l'écriture du document comme la preuve que le worker l'a appliquée.
# Market Desk progressive
## Market Desk progressive
Après les groupes Meteora/Raydium/Pump/Orca, KSP prévoit une première application spécialisée candidate `ksp-app-market-desk`.
@@ -493,7 +493,7 @@ Après Jupiter/OKX, la même application est enrichie avec routes, legs, DEX imp
Les OHLC sont matérialisés dans SPECIALIZED et consommés par l'application; ils ne sont pas recalculés à partir de tout l'historique lors de chaque rendu.
# Future orchestrator
## Future orchestrator
Un orchestrateur global pourra devenir utile lorsque plusieurs services/managers/jobs devront être coordonnés.
@@ -509,7 +509,7 @@ Sa responsabilité éventuelle devra rester control plane :
Il ne doit jamais devenir un nouveau propriétaire de Program, Store, transport ou materialization.
# Future global application
## Future global application
Une application globale d'exploitation/contrôle est attendue à terme.
@@ -528,7 +528,7 @@ Avant elle, KSP doit disposer d'applications spécialisées et demos permettant
Son nom et son scope ne sont pas définis.
# Graphe synthétique
## Graphe synthétique
```text
specialized desktop app
@@ -551,7 +551,7 @@ transport -> RAW -> CORE -> DECODE -> SPECIALIZED
Aucun payload de processing n'a besoin de transiter via l'UI/control plane.
# Questions laissées ouvertes
## Questions laissées ouvertes
Les premières implementations concernées devront fixer :