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

v0.3.14-pre.015

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-12 23:07:58 +02:00
parent 8d8b6b9bcb
commit cd7cf2c4c6
11 changed files with 406 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 40 -->
<!-- version: 41 -->
# Inventaire initial des composants KSP
@@ -46,7 +46,7 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
| 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 | 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`–`0.3.13` | fondation + 5 familles live, convergence multi-source, fairness, health et shutdown bornés |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Implémenté | `0.3.11`–`0.3.14` | 5 familles live + gaps/coverage/repair run-local, fairness, health et shutdown bornés |
| 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 |

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 29 -->
<!-- version: 30 -->
# Graphe de dépendances KSP
@@ -433,9 +433,9 @@ ksp-worker-control-lib # composant retenu, non matérialis
-> 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. `ksp-worker-raw-transaction-ingest-lib` est son premier consumer concret : sa fondation `0.3.11` possède admission/persistence/snapshots/shutdown ; `0.3.12` ouvre la première verticale Yellowstone + hydration HTTP ; `0.3.13` matérialise la composition live multi-source. Config et le backend physique restent hors du Worker.
`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` possède admission/persistence/snapshots/shutdown ; `0.3.12` ouvre la première verticale Yellowstone + hydration HTTP ; `0.3.13` matérialise la composition live multi-source ; `0.3.14` ferme la continuité run-local par gaps bornés, preuves de coverage, repair conservatif, health gap-aware et shutdown/fairness durcis. Config et le backend physique restent hors du Worker.
La verticale actuelle n'est ni « un worker WebSocket » ni un moteur historique : `RawTransactionIngestRuntimeResources` contient de `1` à `32` sources logiques validées d'un même réseau parmi cinq familles — Yellowstone, Standard WS `logsSubscribe`, Standard WS `blockSubscribe`, Helius `transactionSubscribe` et HTTP live block polling. Yellowstone, Standard Logs et Helius convergent vers une registry globale d'hydration HTTP `getTransaction`; Standard Block et HTTP Block Polling qualifient directement le wire Base64 Legacy/V0/V1 vers Common RAW. Toutes les acquisitions rejoignent la même admission/persistence, la convergence canonique `(network, signature)` et des observations distinctes par provenance. Reconnect, `from_slot` et `SubscribeReplayInfo` restent propriétaires de Transport ; le Worker observe leur projection sûre, conserve une processing frontier run-local, applique des bornes/fairness globales et fault sur un gap de rétention prouvé sans appeler le Job Backfill.
La verticale actuelle n'est ni « un worker WebSocket » ni un moteur historique : `RawTransactionIngestRuntimeResources` contient de `1` à `32` sources logiques validées d'un même réseau parmi cinq familles — Yellowstone, Standard WS `logsSubscribe`, Standard WS `blockSubscribe`, Helius `transactionSubscribe` et HTTP live block polling. Yellowstone, Standard Logs et Helius convergent vers une registry globale d'hydration HTTP `getTransaction`; Standard Block et HTTP Block Polling qualifient directement le wire Base64 Legacy/V0/V1 vers Common RAW. Toutes les acquisitions rejoignent la même admission/persistence, la convergence canonique `(network, signature)` et des observations distinctes par provenance. Reconnect, `from_slot`, replay natif et retries réseau restent propriétaires de Transport. Le Worker observe leurs preuves sûres, maintient processing/continuity frontiers distinctes, réconcilie uniquement des gaps du run courant avec coverage explicite et mécanismes bornés, et n'appelle jamais le Job Backfill. Une source perdue ne peut rester absente que si sa perte passée est réconciliée et si les sources restantes prouvent encore tout le `TargetCoverage` futur.
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.

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 19 -->
<!-- version: 20 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -131,9 +131,9 @@ normalisation RawTransaction commune
ksp-store-lib
```
Le modèle général autorise des stratégies alternatives, complémentaires ou redondantes, mais la verticale productive actuelle est volontairement plus étroite : **une** source Yellowstone + **une** voie HTTP d'hydration. Ce choix n'inscrit pas le provider ou le protocole dans l'identité RAW et ne ferme pas l'architecture future multi-source.
La verticale productive accepte désormais de `1` à `32` sources logiques d'un même réseau parmi cinq familles : Yellowstone, Standard WS `logsSubscribe`, Standard WS `blockSubscribe`, Helius `transactionSubscribe` et HTTP live block polling. Ces sources peuvent être complémentaires ou redondantes, mais aucune équivalence n'est supposée par le seul provider/protocole : la convergence canonique reste `(network, signature)` et la coverage utilise des scopes structuraux explicites.
Le reconnect/replay du stream est une capacité Transport. Le Worker conserve une processing frontier run-local sur le travail réellement observé, projette `Active/Reconnecting/Closing/Closed/Failed` et des compteurs reconnect/replay/gap, mais ne possède ni checkpoint durable ni campagne de gap repair. Un gap de rétention prouvé par Transport devient un fault `source_failed` ; une récupération historique éventuelle reste une responsabilité séparée du Job Backfill.
Le reconnect/replay du stream est une capacité Transport. Le Worker conserve une processing frontier run-local sur le travail réellement observé et une continuity frontier séparée, projette des gaps bornés et leurs méthodes de réparation, mais ne possède aucun checkpoint durable ni campagne historique. Un gap du run courant peut être réconcilié par replay Transport, coverage redondante prouvée, scan HTTP borné, block fetch ou hydration d'une référence connue. Une perte de source ne devient non terminale que si sa plage passée est entièrement réconciliée et si les sources restantes couvrent encore tout le `TargetCoverage` futur. Toute lacune non bornable/non couverte reste terminale ; aucune récupération n'appelle le Job Backfill.
#### Résultat de l'audit `0.3.9`

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
<!-- version: 14 -->
<!-- version: 15 -->
# Acquisition et alimentation `RawTransaction`
@@ -187,7 +187,7 @@ Yellowstone BlockMeta / Slot
-> continuité run-local uniquement
```
La composition est caller-owned : le Worker ne lit pas Config et ne reçoit pas de secret. `RawTransactionIngestRuntimeResources` accepte de `1` à `32` sources logiques d'un même réseau, refuse les identités source dupliquées et supervise toutes les sources simultanément. Une faute source reste terminale pour le Worker faute d'équivalence de coverage prouvée.
La composition est caller-owned : le Worker ne lit pas Config et ne reçoit pas de secret. `RawTransactionIngestRuntimeResources` accepte de `1` à `32` sources logiques d'un même réseau, refuse les identités source dupliquées et supervise toutes les sources simultanément. Une faute source n'autorise la continuation des siblings que lorsque sa plage de perte est sûre, que la coverage passée est réconciliée et que les sources restantes couvrent encore tout le `TargetCoverage` futur. Aucune équivalence n'est déduite du provider ou du protocole.
Il ne lance pas de campagne historique arbitraire.
@@ -204,17 +204,20 @@ Store durable = persistence des acquisitions admises
blockchain completeness = non prouvée par les métriques ci-dessus
```
Une tentative de replay ne prouve ni succès ni continuité parfaite. Si Transport prouve qu'un slot demandé est antérieur à `first_available`, son compteur de continuity gap augmente ; le Worker projette ce gap puis termine avec un fault `source_failed`.
Une tentative de replay ne prouve ni succès ni continuité parfaite. Si Transport prouve qu'un slot demandé est antérieur à `first_available`, son compteur de continuity gap augmente ; le Worker ouvre ou enrichit alors un gap run-local sans considérer la reconnexion comme une réparation.
Il n'existe pas de délégation automatique vers Backfill :
La réconciliation reste bornée au run :
```text
gap de rétention prouvé
-> Worker fault/stop
-> aucun lancement de campagne historique
gap de continuité borné
-> replay Transport si preuve exploitable
-> coverage redondante structurale si prouvée
-> scan HTTP borné / getBlock / getTransaction selon capability
-> même Common RAW / admission / Store
-> Repaired ou Unresolved explicite
```
Inversement, une demande telle que « récupère les transactions du programme X depuis le slot Y » reste une campagne `ksp-job-backfill-lib`.
Il n'existe toujours aucune délégation automatique vers Backfill. Une demande telle que « récupère les transactions du programme X depuis le slot Y » reste une campagne `ksp-job-backfill-lib`, tandis qu'un gap non bornable ou non réconciliable du run courant fait fault le Worker.
### 3.4 Absence de relation Job ↔ Worker
@@ -734,7 +737,7 @@ RAW v1 complet -> hydration HTTP avant persistence
Cette qualification cross-source a préparé le contrat sans créer d'edge Common RAW -> Transport. L'extension Worker live utilise désormais cette décision conservative : Yellowstone produit des signaux structurés dans le Worker concret, puis HTTP `getTransaction` fournit le matériau RAW complet avant canonicalisation. Common RAW reste entièrement Transport-neutral.
## 14. État du Worker live après `0.3.13`
## 14. État du Worker live après `0.3.14`
### 14.0 Verticale matérialisée
@@ -756,11 +759,14 @@ convergence canonique par (network, signature) + disagreement explicite
persistence atomique via ksp-store-lib en mode Normal + observations supplémentaires idempotentes
quotas pending/in-flight par source et bornes globales exactes
fairness minimale / anti-starvation sous duplicate storm
processing frontier run-local multi-source conservative
processing frontier et continuity frontier run-local distinctes
ledger de gaps inclusifs bornés + TargetCoverage conservative
replay Transport / coverage redondante / scan HTTP / block fetch / hydration comme preuves distinctes
observabilité publique source-neutral des gaps, raisons, états, dernière méthode et compteurs checked
projection source-neutral Active/Reconnecting/Closing/Closed/Failed + gauges source_total/active/reconnecting/failed
observation des compteurs reconnect/replay/gap Transport
health conservative Healthy/Degraded/Unhealthy
fault sur gap de rétention prouvé
health Healthy/Degraded/Unhealthy fondée sur gaps, frontiers et coverage présente/future
fairness nominal/repair sur les mêmes admission/hydration/persistence
source loss non terminale uniquement après réconciliation complète et coverage future prouvée
shutdown deadline + abort/join sans tâche orpheline ni late persistence
```
@@ -790,7 +796,8 @@ acquérir à partir du démarrage
normaliser et persister RawTransaction + observations
publier snapshots/notifications concrètes Worker
laisser reconnect/from_slot/replay au Transport
fault proprement lorsqu'un gap de rétention est prouvé
réconcilier uniquement les gaps bornés du run courant avec des preuves de coverage explicites
fault proprement lorsqu'une lacune reste non bornable, non couverte ou unresolved
```
Il ne doit pas :
@@ -805,7 +812,7 @@ hardcoder un provider unique
### 14.2 Sources Worker V1 matérialisées et reports
Matérialisé dans `0.3.13` :
Matérialisé dans `0.3.13` puis durci dans `0.3.14` :
```text
Yellowstone transactions / blocks / status + HTTP hydration
@@ -815,14 +822,18 @@ Helius transactionSubscribe Full + HTTP hydration
HTTP live block polling getSlot/getBlocksWithLimit/getBlock observed
HTTP hydration partagée et coalescée cross-source
replay Yellowstone conservé propriétaire de Transport pour continuité du run
gaps run-local bornés et continuity frontier distincte de la processing frontier
coverage exacte/superset conservative avec epochs prouvés
repair borné réutilisant Transport/Common RAW/admission/Store existants
source-loss continuation uniquement sous TargetCoverage prouvée
snapshots gap/repair source-neutral et health gap-aware
```
Reste hors de cette verticale et nécessite une tranche dédiée :
```text
sources EARLY / pre-execution
coverage-equivalence ou failover non-terminal entre sources
repair historique multi-source
campagne historique multi-source ou caller-paramétrable
Worker multi-source -> Store live E2E avec environnement complet provisionné
```