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

v0.3.11-pre.012

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-08 18:58:34 +02:00
parent 636a0c5f43
commit a8cabbebd5
13 changed files with 724 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 37 -->
<!-- version: 38 -->
# Inventaire initial des composants KSP
@@ -45,8 +45,8 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7`, extension `0.3.16` | contrôle du backfill RAW ; sélection des stratégies/sources ajoutée après le worker live |
| Store Desk | `ksp-app-store-desk` | app | Implémenté | `0.3.8` | inspection RAW read-only Transaction/Account/Observation via façade Store |
| RAW transaction common | `ksp-raw-transaction-lib` | lib | Implémenté | `0.3.10` | canonicalisation/wire RAW Transaction v1 source-neutral partagé entre producteurs |
| Worker lifecycle | `ksp-worker-api` | API | Retenu | `0.3.9` | lifecycle/health/progression génériques des services continus |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Retenu | `0.3.11`–`0.3.14` | ingestion continue `RawTransaction` multi-source, déduplication/provenance/recovery |
| Worker lifecycle | `ksp-worker-api` | API | Implémenté | `0.3.9` | lifecycle/health/progression génériques des services continus |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Implémenté | `0.3.11`, extensions `0.3.12+` | fondation source-neutral, puis sources live multi-source/recovery |
| RAW ingest Desk | `ksp-app-raw-transaction-ingest-desk` | app | Retenu | `0.3.15` | choix/supervision d’une ou plusieurs sources/méthodes sans réimplémenter le worker |
| STRUCTURAL job | nom à fixer | job/lib | Retenu | couche STRUCTURAL | normalisation Solana générique RAW -> STRUCTURAL bornée/rejouable |
| STRUCTURAL worker | nom à fixer | worker/lib | Retenu | fin couche STRUCTURAL | backlog RAW -> STRUCTURAL continu |

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 26 -->
<!-- version: 27 -->
# Graphe de dépendances KSP
@@ -419,22 +419,22 @@ Il remplit RAW et ne décode aucun programme. Il ne dépend pas de Config : la c
ksp-worker-api
-> ksp-core-lib
ksp-worker-raw-transaction-ingest-lib
-> ksp-worker-api
-> ksp-onchain-transport-lib
-> ksp-raw-transaction-lib
-> ksp-store-lib
ksp-worker-raw-transaction-ingest-lib # fondation source-neutral matérialisée
-> ksp-core-lib
-> ksp-logging-lib
# Config reste possédé par la composition supérieure ; aucune dépendance backend/provider physique
-> ksp-raw-transaction-lib
-> ksp-store-lib # default-features = false ; aucun backend imposé
-> ksp-worker-api
-> sha2 / tokio # observation key + runtime privé
ksp-worker-control-lib
ksp-worker-control-lib # composant retenu, non matérialisé ici
-> ksp-worker-api
-> ksp-core-lib
```
`ksp-worker-api` est ouvert en `0.3.9` comme contrat générique de services continus et ne connaît ni Solana, ni Transport, ni Store, ni Tauri. Son premier consumer concret est prévu en `0.3.11` avec `ksp-worker-raw-transaction-ingest-lib`, puis ses sources live sont complétées jusqu’en `0.3.14`.
`ksp-worker-api` est ouvert en `0.3.9` comme contrat générique de services continus et ne connaît ni Solana, ni Transport, ni Store, ni Tauri. `ksp-worker-raw-transaction-ingest-lib` est son premier consumer concret : sa fondation `0.3.11` est source-neutral, possède admission/persistence/snapshots/shutdown, et ne dépend pas encore de Transport. Les adapters live sont ajoutés ensuite sans déplacer Config ni backend physique dans le Worker.
Le worker RAW Transaction n'est pas défini comme « un worker WebSocket » ou « un worker gRPC ». Il reçoit une ou plusieurs stratégies d'acquisition construites au-dessus des façades KSP réellement disponibles ; celles-ci peuvent être alternatives, complémentaires (discovery + hydration), redondantes entre providers ou spécialisées live/catch-up/gap-repair. La transaction canonique reste identifiée indépendamment de la source et chaque acquisition utile conserve sa propre observation/provenance Store.
La cible live n'est pas « un worker WebSocket » ou « un worker gRPC ». Les tranches de sources peuvent ajouter `ksp-onchain-transport-lib` lorsque l'adapter productif le nécessite et composer des stratégies alternatives, complémentaires (discovery + hydration), redondantes entre providers ou spécialisées live/catch-up/gap-repair. La transaction canonique reste identifiée indépendamment de la source et chaque acquisition utile conserve sa propre observation/provenance Store.
RAW worker puis STRUCTURAL worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles. Le traitement RAW -> STRUCTURAL borné est porté par un STRUCTURAL job distinct du service continu. Les workers DECODED/DOMAIN sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 17 -->
<!-- version: 18 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -102,6 +102,8 @@ ksp-worker-raw-transaction-ingest-lib
Sa responsabilité est l'acquisition **continue** de `RawTransaction` puis la persistance via `ksp-store-lib`. Il ne décode pas de Program, ne possède aucun SQL/backend physique et ne fait pas de la source réseau une partie de l'identité canonique de transaction.
La fondation matérialisée possède déjà le lifecycle continu, les settings techniques bornés, la queue d'admission privée bornée, la canonicalisation Common RAW, la persistance atomique backend-neutral, les snapshots latest-value et le shutdown borné. Elle ne possède encore aucune source réseau productive et n'a donc aucun edge Transport ; les adapters live/catch-up complètent ensuite ce même Worker sans ouvrir de second runtime parallèle.
Le modèle cible n'est pas :
```text
@@ -140,7 +142,7 @@ Le worker ne doit pas être réduit à un enum superficiel `Http | WebSocket | G
#### Résultat de l'audit `0.3.9`
L'audit exhaustif est synthétisé dans [`011-RAW_TRANSACTION_ACQUISITION.md`](011-RAW_TRANSACTION_ACQUISITION.md). Il confirme qu'un besoin d'acquisition Solana/provider ne remonte pas dans `ksp-worker-api` : le contrat générique reste fermé et le futur Worker concret porte ses propres capabilities de sources.
L'audit exhaustif est synthétisé dans [`011-RAW_TRANSACTION_ACQUISITION.md`](011-RAW_TRANSACTION_ACQUISITION.md). Il confirme qu'un besoin d'acquisition Solana/provider ne remonte pas dans `ksp-worker-api` : le contrat générique reste fermé et le Worker concret porte ses propres capabilities de sources, sans les ouvrir dans sa fondation source-neutral.
Les familles admises par la synthèse couvrent notamment :
@@ -479,14 +481,24 @@ Le Job conserve seul ses scopes, campagnes, checkpoints et lifecycle.
### RAW worker
Fondation source-neutral matérialisée :
```text
ksp-worker-raw-transaction-ingest-lib
-> ksp-core-lib
-> ksp-worker-api
-> ksp-onchain-transport-lib
-> ksp-raw-transaction-lib
-> ksp-interface-lib # seulement si un fait passif partagé aide réellement la composition live
-> ksp-store-lib # façade Store ; aucun backend physique direct
-> ksp-store-lib # façade Store ; default-features=false ; aucun backend physique direct
-> ksp-logging-lib
-> sha2 / tokio # observation key + runtime privé
```
Extension live ultérieure :
```text
ksp-worker-raw-transaction-ingest-lib
-> ksp-onchain-transport-lib # seulement lorsque les adapters sources productifs sont matérialisés
-> ksp-interface-lib # seulement si un fait passif partagé aide réellement la composition live
composition supérieure / future Desk
-> ksp-config-lib
@@ -495,7 +507,7 @@ composition supérieure / future Desk
-> ksp-store-lib
```
Le Worker conserve seul son runtime continu, ses sources actives, sa continuité et son lifecycle. Il n'appelle ni ne pilote le Job Backfill.
Le Worker conserve seul son runtime continu, ses sources actives lorsqu'elles existent, sa continuité et son lifecycle. Il n'appelle ni ne pilote le Job Backfill. La fondation n'expose aucun ingress public : les sources internes futures alimentent la queue bornée et subissent sa backpressure.
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.

4
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: 14 -->
<!-- version: 15 -->
# Applications, services, scenarios et control plane
@@ -138,7 +138,7 @@ Backfill Desk suit exactement cette règle : elle ouvre Store via `ksp-store-lib
Store Desk suit la même frontière sans Transport : Config sélectionne Logging + Store, `ksp-store-lib` fournit health, reads et inspection backend-neutral, et le Store ouvert reste côté Rust. Les DataTables frontend consomment des summaries server-side et counts exacts ; les détails chargent une seule entité avec preview bornée. Aucun command d'écriture, SQL, cursor opaque, backend physique ou secret Store n'est exposé à Tauri/TypeScript.
Raw Transaction Ingest Desk est la surface spécialisée de contrôle prévue après le premier worker concret. Elle peut sélectionner une ou plusieurs stratégies compatibles et afficher lifecycle/health/rates/backpressure/reconnect/recovery, mais la sélection d'une source ne déplace ni discovery, ni hydration, ni déduplication, ni provenance dans l'application. Les endpoints/credentials restent Config/Transport-owned et le détail des entités persistées reste Store Desk-owned.
Raw Transaction Ingest Desk est la surface spécialisée de contrôle prévue après la fondation du premier worker concret. Cette fondation expose déjà lifecycle, stop et snapshots source-neutral ; la Desk ne doit cependant sélectionner des sources ou afficher reconnect/recovery qu'après matérialisation des adapters live correspondants. La sélection d'une source ne déplace ni discovery, ni hydration, ni déduplication, ni provenance dans l'application. Les endpoints/credentials restent Config/Transport-owned et le détail des entités persistées reste Store Desk-owned.
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.

54
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# Acquisition et alimentation `RawTransaction`
@@ -149,7 +149,7 @@ Il peut utiliser **HTTP, WS, Yellowstone gRPC, replay provider ou archive** si c
### 3.2 Worker Raw Transaction Ingest : acquisition continue start/stop
`ksp-worker-raw-transaction-ingest-lib` a pour rôle de **remplir continuellement Store à partir du moment où il est démarré**.
`ksp-worker-raw-transaction-ingest-lib` a pour rôle cible de **remplir continuellement Store à partir du moment où il est démarré**. Sa fondation source-neutral matérialise déjà le runtime, l'admission, la canonicalisation Common RAW, la persistence et les snapshots, mais aucune source réseau productive n'est encore branchée.
Son contrôle métier V1 est volontairement court :
@@ -161,17 +161,17 @@ snapshot / notifications
Le caller ne lui fournit pas une signature, un `program_id`, une plage historique, une limite de campagne ou une requête de backfill. Les endpoints, réseaux, sources activées, capabilities et secrets proviennent de Config/composition, pas d'un payload métier de `start`.
À partir de son démarrage, le Worker :
La fondation actuelle, lorsqu'elle démarre sans adapter source productif, publie son lifecycle/snapshot puis reste contrôlable jusqu'au stop. Dès qu'une source interne est matérialisée, le pipeline cible devient :
```text
acquiert les nouvelles transactions disponibles
hydrate les signaux live incomplets si nécessaire
normalise puis persiste RawTransaction + observations
publie ses notifications indépendamment de leurs lecteurs
publie ses snapshots latest-value indépendamment de leurs lecteurs
continue jusqu'à stop ou fault
```
Le Worker peut utiliser **WS, Yellowstone gRPC, HTTP, block polling, provider streams ou sources EARLY** si ces capacités servent l'acquisition live.
Le Worker peut ensuite utiliser **WS, Yellowstone gRPC, HTTP, block polling, provider streams ou sources EARLY** si ces capacités servent l'acquisition live. Ces sources restent internes au Worker ; le caller ne pousse pas directement des ingress dans sa queue privée.
Il ne lance pas de campagne historique arbitraire.
@@ -648,7 +648,7 @@ Worker lifecycle
backend Store physique
```
Graphe conceptuel :
Graphe matérialisé après la fondation Worker :
```text
ksp-job-backfill-lib --------------------> ksp-raw-transaction-lib ----> ksp-store-api
@@ -657,12 +657,14 @@ ksp-worker-raw-transaction-ingest-lib ---> ksp-raw-transaction-lib ----> ksp-sto
ksp-job-backfill-lib --------------------> ksp-store-lib
ksp-worker-raw-transaction-ingest-lib ---> ksp-store-lib
ksp-job-backfill-lib --------------------> ksp-onchain-transport-lib
ksp-worker-raw-transaction-ingest-lib ---> ksp-onchain-transport-lib
ksp-worker-raw-transaction-ingest-lib -X-> ksp-onchain-transport-lib # aucun adapter live productif encore
aucun edge Job <-> Worker
aucun edge Transport <-> ksp-raw-transaction-lib
```
Les tranches live suivantes peuvent matérialiser l'edge Worker -> Transport lorsqu'un adapter source productif le nécessite ; cet edge n'appartient pas à la fondation source-neutral.
La migration doit préserver exactement les golden bytes/hash RAW v1 déjà prouvés. Aucun RAW v2 n'est justifié.
### 13.1 Transaction wire Legacy/V0/V1
@@ -711,9 +713,40 @@ Yellowstone Transaction/Block -> signal structuré + transaction wire fidèle
RAW v1 complet -> hydration HTTP avant persistence
```
Aucun adapter productif n'est ajouté en `pre.006`. Conformément à `TR-C2`, l'adapter `Transport DTO -> common` demeure réservé au Worker concret, désormais ouvert en `0.3.11`.
Aucun adapter productif n'est ajouté par la qualification cross-source. Conformément à `TR-C2`, l'adapter `Transport DTO -> common` demeure réservé au Worker concret. La fondation `0.3.11` est désormais matérialisée sans Transport ; le premier adapter productif reste donc une responsabilité des tranches live suivantes.
## 14. Handoff Worker live `0.3.11` à `0.3.14`
## 14. Handoff fondation Worker `0.3.11` vers live `0.3.12` à `0.3.14`
### 14.0 État fermé par la fondation source-neutral
La fondation du Worker est matérialisée avec :
```text
consumer de ksp-worker-api
settings réseau/Worker bornés
start/stop sur runtime Tokio caller-owned
supervision privée des tâches
mpsc central borné + backpressure
canonicalisation et assembly via ksp-raw-transaction-lib
observation key déterministe
persistence atomique via ksp-store-lib en mode Normal
concurrence Store bornée
snapshots concrete + projection WorkerSnapshotSource
faults Store/content/source/counter classifiés
shutdown deadline + abort/join sans tâche orpheline
```
Elle ne possède encore :
```text
aucun adapter HTTP/WS/Yellowstone productif
aucun edge ksp-onchain-transport-lib
aucune lecture Config
aucune API publique d'enqueue/source registration
aucun replay/gap-repair live
```
Cette frontière est volontaire : les tranches live ajoutent des sources au supervisor existant au lieu d'introduire un second runtime ou une API d'admission publique.
### 14.1 Contrat fonctionnel
@@ -937,7 +970,8 @@ Transaction V1 = wire source-neutral Legacy/V0/V1 dans common ; ac
Yellowstone pre.006 = transaction wire V1 qualifié ; RAW complet via hydration HTTP
TR-C2 = adapter productif Transport DTO -> common réservé au Worker concret
0.3.10 = common RAW + preuves cross-source
0.3.11 à 0.3.14 = Worker live multi-source par responsabilités bornées
0.3.11 = fondation Worker source-neutral, persistence et observabilité
0.3.12 à 0.3.14 = sources live multi-source, continuité et hardening par responsabilités bornées
0.3.16 = Job Backfill multi-stratégie historique
```