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

v0.3.10-pre.006-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-07 23:56:48 +02:00
parent f7c57f21c5
commit 919b4ed46d
13 changed files with 319 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 34 -->
<!-- version: 35 -->
# Inventaire initial des composants KSP
@@ -41,12 +41,12 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
| Store runtime | `ksp-store-lib` | lib | Stable | `0.3.2`–`0.3.4` | façade backend-neutral et conformance RAW 10/10 |
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Stable | `0.3.2`–`0.3.4` | backend référence : fondation, RawTransaction et RawAccountState |
| Job lifecycle | `ksp-job-api` | API | Implémenté | `0.3.6` | identité/lifecycle/annulation/notifications latest-value runtime-neutral |
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6`, extension `0.3.12` | première verticale HTTP puis extension multi-source/historique sans changer l’identité RAW |
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7`, extension `0.3.12` | contrôle du backfill RAW ; sélection des stratégies/sources ajoutée après le worker live |
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6`, extension `0.3.16` | première verticale HTTP puis extension multi-source/historique sans changer l’identité RAW |
| 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 |
| 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.10` | ingestion continue `RawTransaction` multi-source, déduplication/provenance/recovery |
| RAW ingest Desk | `ksp-app-raw-transaction-ingest-desk` | app | Retenu | `0.3.11` | choix/supervision d’une ou plusieurs sources/méthodes sans réimplémenter le worker |
| 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 |
| 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 |
| 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 |

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 23 -->
<!-- version: 24 -->
# Graphe de dépendances KSP
@@ -402,7 +402,7 @@ ksp-worker-control-lib
-> 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.10` avec `ksp-worker-raw-transaction-ingest-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`.
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.

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 14 -->
<!-- version: 15 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -90,7 +90,7 @@ Le job :
Le caller desktop spécialisé actuel est `ksp-app-backfill-desk`. Il compose Config, le pool HTTP et Store, puis remet ces ressources au runtime Backfill. Il peut retenir le checkpoint terminal uniquement en mémoire Rust pour un Resume in-session ; cette rétention applicative ne transforme pas le checkpoint en garantie de reprise durable après redémarrage.
Cette verticale `0.3.6`/`0.3.7` est **la première stratégie de backfill**, pas la définition générale du backfill KSP. Son discovery `getSignaturesForAddress` + hydration `getTransaction` est HTTP parce que cette méthode a été choisie pour le premier vertical slice. Après stabilisation du worker live et de sa Desk, `0.3.12` doit réauditer `ksp-job-backfill-lib` et `ksp-app-backfill-desk` pour intégrer les autres stratégies historiques/catch-up pertinentes identifiées par l'audit RAW Transaction de `0.3.9`.
Cette verticale `0.3.6`/`0.3.7` est **la première stratégie de backfill**, pas la définition générale du backfill KSP. Son discovery `getSignaturesForAddress` + hydration `getTransaction` est HTTP parce que cette méthode a été choisie pour le premier vertical slice. Après stabilisation du worker live et de sa Desk, `0.3.16` doit réauditer `ksp-job-backfill-lib` et `ksp-app-backfill-desk` pour intégrer les autres stratégies historiques/catch-up pertinentes identifiées par l'audit RAW Transaction de `0.3.9`.
### Worker RAW Transaction live
@@ -163,25 +163,25 @@ La présence d'une voie dans l'architecture signifie qu'elle doit pouvoir être
Pour chaque voie, l'audit couvre au minimum :
| Dimension | Question à trancher |
|----------------------|-----------------------------------------------------------------------|
| transport/protocole | HTTP, WS standard, extension provider, Yellowstone ou autre ? |
| réseau | Mainnet, Devnet, Testnet réellement disponibles et utiles ? |
| disponibilité | gratuite/payante/provider-dependent ; limites actuelles à réauditer ? |
| temporalité | live, catch-up, historique, replay récent ? |
| discovery | comment la transaction est-elle découverte ? |
| transaction complète | reçue directement ou hydration nécessaire ? |
| filtres | programmes/comptes/signatures/slots/status et bornes ? |
| ordering/duplicates | quelles garanties existent et quelles duplications sont normales ? |
| reconnect/replay | que se passe-t-il après coupure ? |
| gap recovery | quelle autre stratégie répare les trous ? |
| backpressure | quelles limites et comportements si le consumer ralentit ? |
| commitment/finality | quels niveaux sont disponibles et comment les interpréter ? |
| provenance | quelles métadonnées sûres alimentent `RawTransactionObservation` ? |
| limites/quota | RPS, connexions, subscriptions, credits ou autres limites actuelles ? |
| gap KSP Transport | surface déjà disponible ou adaptation nécessaire en `0.3.10` ? |
| gap KSP Config | profil/secret/capability déjà disponible ou adaptation nécessaire ? |
| usage | continuous ingest, gap repair, historical backfill ou combinaison ? |
| Dimension | Question à trancher |
|----------------------|-----------------------------------------------------------------------------|
| transport/protocole | HTTP, WS standard, extension provider, Yellowstone ou autre ? |
| réseau | Mainnet, Devnet, Testnet réellement disponibles et utiles ? |
| disponibilité | gratuite/payante/provider-dependent ; limites actuelles à réauditer ? |
| temporalité | live, catch-up, historique, replay récent ? |
| discovery | comment la transaction est-elle découverte ? |
| transaction complète | reçue directement ou hydration nécessaire ? |
| filtres | programmes/comptes/signatures/slots/status et bornes ? |
| ordering/duplicates | quelles garanties existent et quelles duplications sont normales ? |
| reconnect/replay | que se passe-t-il après coupure ? |
| gap recovery | quelle autre stratégie répare les trous ? |
| backpressure | quelles limites et comportements si le consumer ralentit ? |
| commitment/finality | quels niveaux sont disponibles et comment les interpréter ? |
| provenance | quelles métadonnées sûres alimentent `RawTransactionObservation` ? |
| limites/quota | RPS, connexions, subscriptions, credits ou autres limites actuelles ? |
| gap KSP Transport | surface déjà disponible ou adaptation nécessaire dans `0.3.10` à `0.3.14` ? |
| gap KSP Config | profil/secret/capability déjà disponible ou adaptation nécessaire ? |
| usage | continuous ingest, gap repair, historical backfill ou combinaison ? |
#### Helius et Config
@@ -192,7 +192,7 @@ Décisions déjà acquises :
```text
KSP_SECRET_HELIUS_API_KEY existe déjà côté environnement KSP
Helius HTTP et WS Mainnet/Devnet doivent être considérés comme futures sources candidates
les profils/endpoints réellement nécessaires sont ajoutés seulement en 0.3.10
les profils/endpoints réellement nécessaires sont ajoutés seulement dans la release Worker qui les consomme, principalement 0.3.13/0.3.14
aucune URL Helius nouvelle n'est ajoutée pendant 0.3.8
Config reste l'unique propriétaire des secrets et de leur résolution
les fonctionnalités standard et advanced/enhanced sont capability-gated, jamais supposées par le seul nom du provider
@@ -226,7 +226,7 @@ La déduplication ne doit donc pas supprimer la provenance utile sous prétexte
La Desk prévue après le worker choisit et supervise les **source(s)/méthode(s)** offertes par la composition réellement disponible. Elle ne possède pas la logique de discovery, hydration, déduplication, replay ou persistance.
Elle doit pouvoir représenter selon les capacités finales de `0.3.10` :
Elle doit pouvoir représenter selon les capacités finales du Worker après `0.3.14` :
```text
une source unique

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: 11 -->
<!-- version: 12 -->
# Applications, services, scenarios et control plane
@@ -493,7 +493,7 @@ Elle ne modifie jamais directement l'état interne du worker dans PostgreSQL. El
Le premier déploiement peut piloter `ksp-worker-raw-transaction-ingest-lib` in-process si cela reste le choix le plus simple et le plus sûr. La sémantique de `ksp-worker-api` doit néanmoins rester compatible avec un futur proxy vers un worker autonome ; l'IPC/remote control ne doit pas être anticipé artificiellement avant besoin réel.
La Desk RAW Transaction doit laisser choisir **une ou plusieurs sources/méthodes** parmi les capabilities effectivement configurées/admissibles par `0.3.10`, et superviser leur état sans dupliquer discovery/hydration/déduplication/recovery dans Tauri. Store Desk reste la surface d'inspection détaillée des RAW persistés.
La Desk RAW Transaction doit laisser choisir **une ou plusieurs sources/méthodes** parmi les capabilities effectivement configurées/admissibles par le Worker finalisé en `0.3.14`, et superviser leur état sans dupliquer discovery/hydration/déduplication/recovery dans Tauri. Store Desk reste la surface d'inspection détaillée des RAW persistés.
## Configuration desired vs effective

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
<!-- version: 9 -->
<!-- version: 10 -->
# Acquisition et alimentation `RawTransaction`
@@ -711,9 +711,9 @@ 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 de `pre.007`.
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`.
## 14. Handoff `0.3.10` : Worker live
## 14. Handoff Worker live `0.3.11` à `0.3.14`
### 14.1 Contrat fonctionnel
@@ -783,7 +783,7 @@ settings techniques nécessaires
Elle peut activer plusieurs providers/endpoints simultanément. Les secrets restent Config-owned, avec réutilisation unique de `KSP_SECRET_HELIUS_API_KEY` pour les surfaces Helius concernées.
## 15. Handoff `0.3.12` : Job Backfill multi-stratégie
## 15. Handoff `0.3.16` : Job Backfill multi-stratégie
Le Job doit conserver son vertical slice existant puis ajouter des stratégies historiques choisies selon requête + capabilities + configuration.
@@ -808,18 +808,17 @@ L'exhaustivité de l'architecture ne signifie pas que chaque intégration vendor
Ordre conseillé :
```text
0.3.10 P0 : normalisation RAW commune
0.3.10 P0 : observed getBlock + adapters source-neutral
0.3.10 P0 : Yellowstone transactions/blocks live
0.3.10 P0 : WS logs + hydration, blockSubscribe, Helius transactionSubscribe
0.3.10 P0 : HTTP live block polling/hydration
0.3.10 P1 : multi-source concurrency, dedup, provenance, continuity repair
0.3.10 P1 : smokes gratuits Mainnet/Devnet/Testnet
0.3.10 P2 : EARLY adapters accessibles
0.3.12 P0 : block scan historique
0.3.12 P0 : replay Yellowstone borné
0.3.12 P1 : provider history/archive
0.3.12 P1 : Old Faithful
0.3.10 P0 : normalisation RAW commune + observed getBlock + preuves cross-source
0.3.11 P0 : Worker foundation/runtime + persistence déterministe
0.3.12 P0 : Yellowstone transactions/blocks/status + hydration + replay continuity
0.3.13 P0 : WS logs + hydration, blockSubscribe, Helius transactionSubscribe, HTTP live polling
0.3.13 P1 : multi-source convergence, dedup, provenance, content conflict, backpressure
0.3.14 P0 : continuity repair complet + hardening + smokes gratuits accessibles
0.3.14 P2 : EARLY adapters accessibles seulement si prouvés
0.3.16 P0 : block scan historique
0.3.16 P0 : replay Yellowstone borné
0.3.16 P1 : provider history/archive
0.3.16 P1 : Old Faithful
plus tard : substrats directs et sources vendor-specific sans accès actuel
```
@@ -936,9 +935,10 @@ network identity = mainnet canonique ; mainnet-beta alias legacy/ext
RAW canonicalisation = lower-layer commune, sans edge Job <-> Worker
Transaction V1 = wire source-neutral Legacy/V0/V1 dans common ; activation cluster non supposée
Yellowstone pre.006 = transaction wire V1 qualifié ; RAW complet via hydration HTTP
TR-C2 = adapter productif Transport DTO -> common réservé au Worker pre.007
0.3.10 = Worker live multi-source + adaptations communes nécessaires
0.3.12 = Job Backfill multi-stratégie historique
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.16 = Job Backfill multi-stratégie historique
```
`0.3.9` n'implémente aucune nouvelle stratégie d'acquisition. Il ferme l'architecture et l'inventaire nécessaires aux releases suivantes.