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

v0.3.1-pre.009

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-29 11:22:29 +02:00
parent 55325ffd32
commit 2f0eb316f5
13 changed files with 412 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
<!-- version: 9 -->
<!-- version: 11 -->
# Contrats initiaux des composants KSP
@@ -16,7 +16,7 @@ Couples explicitement retenus :
```text
ksp-program-api / ksp-program-lib
ksp-materializer-api / ksp-materializer-lib
ksp-store-api / ksp-store-lib
ksp-store-api / ksp-store-lib + ksp-store-<backend>-lib
```
Lifecycle APIs séparées :
@@ -27,6 +27,8 @@ ksp-job-api
ksp-execution-policy-api
```
Pour Store, le couple API/façade est complété par des crates backend séparées : chaque `ksp-store-<backend>-lib` implémente `ksp-store-api` et ne dépend jamais de `ksp-store-lib`. Les consumers runtime ordinaires utilisent la façade `ksp-store-lib`, pas une crate backend concrète.
Une crate `*-api` n'est jamais créée uniquement pour la symétrie des noms.
## Core
@@ -156,7 +158,9 @@ Interprétation Program/protocole puis matérialisation générique/journal dura
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.
`ksp-store-api` possède les contrats backend-agnostic. `ksp-store-lib` fournit la façade/runtime commune et sélectionne les backends compilés par features. PostgreSQL est le backend officiel par défaut mais son implémentation physique appartient à `ksp-store-postgres-lib`.
Les jobs, workers et applications consomment normalement `ksp-store-lib`; les crates backend dépendent de `ksp-store-api` et restent invisibles aux consumers. Une dépendance directe à `ksp-store-api` reste réservée aux implémentations de contrats ou composants réutilisables qui ont réellement besoin de ces traits/types sans façade runtime.
La première Store release est RAW-only ; les couches suivantes sont ajoutées quand elles sont réellement ouvertes.

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 23 -->
<!-- version: 25 -->
# Inventaire initial des composants KSP
@@ -17,42 +17,43 @@ 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 | Stable | `0.2.6` | Wallet + Config + balance HTTP + projection SOL/USD auxiliaire |
| 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 | Stable | `0.2.7` | WebSocket Solana 18/18, sessions/subscriptions bornées |
| Helius WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.8` | LaserStream WS : 7 standard + transaction, actor partagé |
| 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 | Retenu | `0.2.13` | façade wire officielle + API publique wire |
| Program API | `ksp-program-api` | API | Retenu | `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` |
| 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 |
| 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 + balance HTTP + projection SOL/USD auxiliaire |
| 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 | Stable | `0.2.7` | WebSocket Solana 18/18, sessions/subscriptions bornées |
| Helius WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.8` | LaserStream WS : 7 standard + transaction, actor partagé |
| 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 |
| 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` |
| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | RAW transaction/account, observations, queries, outcomes, rétention et capabilities backend |
| Store runtime | `ksp-store-lib` | lib | Retenu | `0.3.2` | façade Store commune, dispatch par features/config |
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Retenu | `0.3.2` | backend PostgreSQL officiel par défaut, privé derrière Store |
| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.4` | lifecycle des jobs terminables |
| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.4` | acquisition historique vers RAW via `ksp-store-lib` |
| Backfill Desk | nom à fixer | app | Retenu | `0.3.5` | 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

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 15 -->
<!-- version: 17 -->
# Graphe de dépendances KSP
@@ -336,6 +336,12 @@ ksp-store-api
-> ksp-core-lib
ksp-store-lib
-> ksp-store-api
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-store-postgres-lib # feature postgres par défaut, optionnelle au build
ksp-store-postgres-lib
-> ksp-store-api
-> ksp-core-lib
-> ksp-logging-lib
@@ -347,9 +353,11 @@ Interdictions :
```text
ksp-store-api -X-> transport/program/materializer
ksp-store-lib -X-> transport/program/materializer
ksp-store-postgres-lib -X-> ksp-store-lib
worker/job -X-> ksp-store-postgres-lib
```
La première release Store (`0.3.1`) est RAW-only ; les contrats CORE/DECODE/SPECIALIZED sont ajoutés avec leurs couches.
La première release Store (`0.3.1`) est RAW-only ; les contrats CORE/DECODE/SPECIALIZED sont ajoutés avec leurs couches. Les consumers runtime ordinaires (jobs, workers, apps) utilisent `ksp-store-lib`; ils ne sélectionnent ni n'importent directement `ksp-store-postgres-lib` ou un autre backend.
## Jobs
@@ -364,7 +372,7 @@ Premier job pressenti :
ksp-job-backfill
-> ksp-job-api
-> ksp-onchain-transport-lib
-> ksp-store-api
-> ksp-store-lib
-> ksp-config-lib
-> ksp-logging-lib
```
@@ -426,7 +434,7 @@ backfill app
```text
ksp-app-market-desk
-> ksp-store-api
-> ksp-store-lib
-> live transport only where explicitly useful
-> KSP domain/query contracts
```

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 4 -->
<!-- version: 6 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -262,7 +262,7 @@ status
progress
```
Les types exacts sont décidés à `0.3.3` avec le premier vrai backfill.
Les types exacts sont décidés à `0.3.4` avec le premier vrai backfill.
Aucune `ksp-job-control-lib` n'est créée sans duplication concrète.
@@ -290,6 +290,8 @@ output + durable outcome
Les notifications ne remplacent jamais le Store.
La taille du batch, la priorité et la stratégie de sélection appartiennent au worker/job/executor. Store fournit les primitives de query/cursor/claim nécessaires et peut refléter une contrainte physique du backend, mais `ksp-store-lib` n'invente pas un plafond métier global inférieur à la capacité réellement disponible.
La sémantique cible reste at-least-once avec idempotence durable, plutôt qu'un faux exactly-once.
## Processing outcomes
@@ -340,7 +342,7 @@ Les événements utiles comprennent notamment :
ksp-job-backfill
-> ksp-job-api
-> ksp-onchain-transport-lib
-> ksp-store-api / backend injecté
-> ksp-store-lib # façade Store ; backend sélectionné par feature + Config
-> ksp-config-lib # orchestration/config, pas ownership transport
-> ksp-logging-lib
```
@@ -351,7 +353,7 @@ ksp-job-backfill
ksp-worker-raw-retriever
-> ksp-worker-api
-> ksp-onchain-transport-lib
-> ksp-store-api / backend injecté
-> ksp-store-lib # façade Store ; backend sélectionné par feature + Config
-> ksp-config-lib
-> ksp-logging-lib
```

5
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: 6 -->
<!-- version: 7 -->
# Applications, services, scenarios et control plane
@@ -107,10 +107,11 @@ ksp-app-solprices-desk
-> ksp-offchain-transport-lib
ksp-app-store-desk
-> ksp-store-api
-> ksp-store-lib
```
`ksp-store-lib` réexporte la surface Store commune nécessaire aux applications ; une app ne dépend pas directement de `ksp-store-api` uniquement pour atteindre les modèles/capabilities, et ne dépend jamais d'une crate backend concrète.
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