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

v0.3.8-pre.013-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-04 10:44:45 +02:00
parent c0b3190256
commit 081a5352c0
8 changed files with 409 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
crates/ksp-app-store-desk/package.json
View File

@@ -1,7 +1,7 @@
{
"name": "ksp-app-store-desk",
"private": true,
"version": "0.3.8-pre.2",
"version": "0.3.8",
"type": "module",
"scripts": {
"dev": "vite",

3
crates/ksp-app-wallet-desk/capabilities/default.json
View File

@@ -8,6 +8,7 @@
],
"permissions": [
"core:default",
"tracing:default"
"tracing:default",
"dialog:default"
]
}

1
crates/ksp-app-wallet-desk/package.json
View File

@@ -11,6 +11,7 @@
"@fltsci/tauri-plugin-tracing": "^0.3",
"@fortawesome/fontawesome-free": "^7.3",
"@tauri-apps/api": "^2.11",
"@tauri-apps/plugin-dialog": "^2.7",
"bootstrap": "^5.3",
"datatables.net-bs5": "^3.0",
"datatables.net-select-bs5": "^4.0",

150
deltas/0.3.8/pre.013-fix.001.md Normal file
View File

@@ -0,0 +1,150 @@
<!-- file: deltas/0.3.8/pre.013-fix.001.md -->
<!-- version: 1 -->
# Delta `0.3.8-pre.013-fix.001` — trajectoire Worker RAW Transaction multi-source
## 1. Base requise
```text
0.3.8-pre.013
workspace.package.version = 0.3.8-pre.13
```
Cette correction reste dans le couloir de réconciliation documentaire de `pre.013`. Elle est créée avant `pre.014` afin de ne pas introduire une décision d'architecture durable dans la tranche de publication minimale.
## 2. Objectif
Figer les décisions prises après la réconciliation Store Desk concernant :
```text
0.3.9 ksp-worker-api + audit exhaustif des sources RawTransaction en fin de release
0.3.10 ksp-worker-raw-transaction-ingest-lib multi-source dès V1
0.3.11 ksp-app-raw-transaction-ingest-desk
0.3.12 extension multi-source de ksp-job-backfill-lib + ksp-app-backfill-desk
```
Aucun endpoint Helius, aucune URL, aucun secret nouveau, aucune modification Config/Transport/runtime et aucun code Worker ne sont ajoutés dans `0.3.8`.
## 3. Version
Correction strictement documentaire :
```text
workspace.package.version reste 0.3.8-pre.13
Cargo.toml inchangé
```
Conformément à `VER-ID-008`, l'identifiant de delta n'est pas reflété dans Cargo.
## 4. Décisions durablement documentées
### 4.1 Worker API
`ksp-worker-api` reste une API générique de services continus, distincte de Job API et sans dépendance Solana/Transport/Store/Tauri. Elle doit être fonctionnellement stabilisée avant l'audit détaillé du premier worker concret.
### 4.2 Premier worker RAW
Le nom retenu est :
```text
ksp-worker-raw-transaction-ingest-lib
```
Le worker n'est pas défini par un protocole unique. Il doit pouvoir composer des stratégies d'acquisition alternatives, complémentaires, redondantes ou spécialisées live/catch-up/gap-repair, tout en convergeant vers `RawTransaction` + `RawTransactionObservation` puis `ksp-store-lib`.
### 4.3 Audit de fin `0.3.9`
Après fermeture fonctionnelle de Worker API, `0.3.9` doit auditer au minimum :
```text
HTTP signatures + hydration
HTTP slot/block acquisition
WS logs/signature/block selon disponibilité réelle
extensions transactionnelles provider-specific dont Helius
Yellowstone transactions / transaction_status / blocks / block_meta
replay/from_slot/catch-up selon provider
combinaisons multi-provider et multi-transport
```
L'audit compare discovery, hydration, payload direct, filtres, ordering/duplicates, reconnect/replay, gap recovery, backpressure, commitment, provenance, quotas et gaps KSP Transport/Config.
### 4.4 Helius
Décisions préparatoires seulement :
```text
KSP_SECRET_HELIUS_API_KEY existe déjà et doit être réutilisée via Config
Helius HTTP/WS Mainnet/Devnet sont des sources candidates futures
les endpoints/profils nécessaires ne sont ajoutés qu'en 0.3.10
capabilities standard vs advanced/enhanced doivent être réauditées au moment du travail
aucune URL Helius nouvelle n'entre dans 0.3.8
```
kbot3 reste une référence fonctionnelle obligatoire pour cet audit, jamais une source de code, de DTO, de Config ou de dépendance.
### 4.5 Mainnet / mainnet-beta
Aucun renommage n'est appliqué maintenant. L'audit doit déterminer une stratégie de canonicalisation/aliasing compatible avec Store, Config, Transport, checkpoints et fingerprints afin de ne jamais créer deux identités KSP pour le même cluster.
### 4.6 Backfill
Le backfill `0.3.6`/`0.3.7` est explicitement décrit comme **première stratégie HTTP**, et non comme définition générale du backfill. Après le worker live et sa Desk, `0.3.12` étendra `ksp-job-backfill-lib` et `ksp-app-backfill-desk` avec les autres stratégies historiques/catch-up pertinentes issues du même audit.
## 5. Fichiers modifiés
```text
docs/architecture/004-COMPONENT_INVENTORY.md
docs/architecture/005-DEPENDENCY_GRAPH.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
```
## 6. Fichier ajouté
```text
deltas/0.3.8/pre.013-fix.001.md
```
## 7. Fichiers supprimés
Aucun.
## 8. Hors scope
```text
Cargo.toml
ROADMAP.md
CHANGELOG.md
prompt 0.3.9
src/**
tests/**
frontend/**
Config runtime / std.transport
ksp-onchain-transport-lib runtime
endpoints ou URLs Helius
.env / .env.example
Store/schema/migrations
```
`ROADMAP.md`, `CHANGELOG.md` et le prompt suivant restent réservés à `pre.014`.
## 9. Validations de l'environnement d'assemblage
```text
python3 scripts/audit_rust_workspace_rules.py : clean
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas : clean
Rust export completeness audit : 0 candidate(s)
contrôle différentiel : uniquement architecture + delta
Cargo.toml : inchangé
```
Cargo/rustc/rustfmt ne sont pas requis pour cette correction strictement documentaire.
## 10. Suite
Après application et audits documentaires verts :
```text
0.3.8-pre.014 — CHANGELOG + ROADMAP + prompt 0.3.9
0.3.8-rel.001 — publication stable
```

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 33 -->
<!-- version: 34 -->
# Inventaire initial des composants KSP
@@ -18,44 +18,45 @@ 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 |
| Interface passive | `ksp-interface-lib` | lib | Stable | `0.2.13` | façade wire + contrats passifs partagés, dont événements acquisition provider-neutral |
| 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 | Stable | `0.3.1` | RAW transaction/account, observations, queries, outcomes, rétention et capabilities backend |
| 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` | backfill `RawTransaction` borné via Transport observé + Store, checkpoint et runtime |
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7` | Start/monitoring/Cancel/Resume in-session du backfill RAW via façades KSP |
| 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 | 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 |
| Interface passive | `ksp-interface-lib` | lib | Stable | `0.2.13` | façade wire + contrats passifs partagés, dont événements acquisition provider-neutral |
| 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 | Stable | `0.3.1` | RAW transaction/account, observations, queries, outcomes, rétention et capabilities backend |
| 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 |
| 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 |
| 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

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 22 -->
<!-- version: 23 -->
# Graphe de dépendances KSP
@@ -390,14 +390,23 @@ 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-store-lib
-> ksp-logging-lib
# Config reste possédé par la composition supérieure ; aucune dépendance backend/provider physique
ksp-worker-control-lib
-> ksp-worker-api
-> ksp-core-lib
```
RAW worker et CORE worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles.
`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`.
Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.
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.
RAW worker et CORE worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles. Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.
## Apps
@@ -440,6 +449,21 @@ ksp-app-backfill-desk
La Desk compose les ressources et contrôles du job sans traverser la façade Store : aucune dépendance directe à `ksp-store-api`, `ksp-store-postgres-lib`, `tokio-postgres`, `reqwest`, `tonic` ou `yellowstone-grpc-proto`. Le frontend ne connaît que des rôles HTTP logiques et des DTOs sûrs ; endpoints, credentials, backend Store, RAW et checkpoint concret restent sous les composants Rust propriétaires.
### RAW Transaction Ingest Desk
```text
ksp-app-raw-transaction-ingest-desk
-> ksp-config-lib
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-worker-api
-> ksp-worker-raw-transaction-ingest-lib
-> ksp-onchain-transport-lib
-> ksp-store-lib
```
La Desk sélectionne et supervise les stratégies d'acquisition exposées par le worker et par la composition Config/Transport. Elle peut activer plusieurs sources lorsqu'elles sont compatibles, mais ne reconstruit ni discovery, ni hydration, ni déduplication, ni provenance dans Tauri/TypeScript. Les endpoints, credentials, capacités provider et handles Transport/Store restent Rust-owned.
### Store Desk
```text

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -92,35 +92,161 @@ 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.
### Worker RAW live
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`.
Le worker live futur :
### Worker RAW Transaction live
Le premier worker concret de la couche RAW est retenu sous le nom :
```text
subscriptions/fetch live
|
v
ksp-onchain-transport-lib
|
v
RAW ingestion
|
v
D1 RAW
ksp-worker-raw-transaction-ingest-lib
```
Il ne décode pas et ne matérialise pas.
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.
Sa hot reconfiguration peut concerner selon le transport :
Le modèle cible n'est pas :
- endpoints/providers ;
- rôles ;
- accounts/program IDs suivis ;
- types de subscriptions ;
- filtres ;
- limites/concurrence.
```text
worker -> un transport unique
```
La configuration desired/effective reste distinguée lorsqu'une reconfiguration est asynchrone.
mais :
```text
source(s) / stratégie(s) d'acquisition
|
+--> discovery de références
| |
| +--> hydration éventuelle
|
+--> transaction complète directe
|
v
normalisation RawTransaction commune
|
+--> RawTransaction canonique
+--> RawTransactionObservation par acquisition utile
|
v
ksp-store-lib
```
Une stratégie peut donc être :
- **alternative** : une source choisie à la place d'une autre ;
- **complémentaire** : une source découvre une signature/slot et une autre hydrate la transaction complète ;
- **redondante** : plusieurs providers/transports observent la même transaction et produisent des observations distinctes ;
- **spécialisée** : une source live, une source de catch-up/gap repair et une source historique peuvent coexister avec des responsabilités différentes.
Le worker ne doit pas être réduit à un enum superficiel `Http | WebSocket | Grpc`. La configuration/runtime doit exprimer les **capacités et rôles d'acquisition réellement nécessaires** : discovery, hydration, direct full transaction, live, replay/catch-up, gap repair, filtre, finality/commitment, reprise et limites.
#### Audit obligatoire avant `0.3.10`
La fin de `0.3.9`, après fermeture fonctionnelle de `ksp-worker-api`, produit un audit exhaustif servant d'entrée architecturale à `0.3.10`. Cet audit ne doit pas déformer Worker API pour le premier consumer : un besoin découvert n'est remonté dans `ksp-worker-api` que s'il est réellement générique à des services continus non Solana.
L'audit doit au minimum comparer :
```text
HTTP getSignaturesForAddress + getTransaction
HTTP getBlocks/getBlock et autres stratégies slot/block pertinentes
WS logsSubscribe + hydration HTTP éventuelle
WS signatureSubscribe + hydration éventuelle
WS blockSubscribe lorsqu'une source/provider l'offre réellement
extensions transactionnelles provider-specific, dont Helius transactionSubscribe
Yellowstone transactions
Yellowstone transaction_status
Yellowstone blocks
Yellowstone block_meta
replay/from_slot/catch-up lorsqu'une implémentation/provider le permet
combinaisons multi-provider et multi-transport
```
La liste n'est pas une promesse d'implémentation. Chaque voie est évaluée avant admission et peut être rejetée, réservée au backfill, réservée au live ou nécessiter une adaptation Transport/Config.
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 ? |
#### Helius et Config
L'audit de `0.3.9` doit réexaminer les offres et documentations Helius **courantes au moment du travail**. Les tiers, quotas et capabilities provider ne sont pas figés par ce document.
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
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
```
L'archive kbot3 doit être relue uniquement comme **référence fonctionnelle** pour identifier les méthodes/sources déjà exploitées ou envisagées. Aucun code, DTO, client, URL hardcodée, modèle Config ou dépendance kbot3 n'est repris comme source d'implémentation.
#### `mainnet` et `mainnet-beta`
La terminologie réseau est un audit explicite avant toute modification. Les sources Solana actuelles utilisent de plus en plus `mainnet` alors que plusieurs surfaces/outils historiques conservent `mainnet-beta`.
KSP ne doit jamais créer deux identités persistées pour le même cluster par simple renommage. L'audit doit donc inventorier :
```text
RawNetworkId et valeurs persistées Store
Config profile ids / cluster labels
Transport descriptors et provider metadata
CLI/external aliases réellement acceptés
compatibilité des checkpoints/fingerprints existants
migration ou canonicalisation éventuellement nécessaire
```
Aucun renommage de données persistées ou de profil n'est effectué en `0.3.8`. `0.3.10` ne l'implémente que si l'audit `0.3.9` établit une stratégie de compatibilité sûre.
#### Idempotence et multi-source
La convergence multi-source réutilise les invariants Store acquis :
```text
identité canonique RawTransaction = réseau logique + signature
source/provider/protocole != identité canonique
acquisitions distinctes -> observations/provenances distinctes lorsque pertinentes
même contenu canonique -> idempotence
même identité avec contenu incompatible -> conflit explicite, jamais écrasement silencieux
```
La déduplication ne doit donc pas supprimer la provenance utile sous prétexte que la transaction canonique existe déjà.
#### Rôle de `ksp-app-raw-transaction-ingest-desk`
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` :
```text
une source unique
plusieurs sources redondantes
une combinaison discovery + hydration
une stratégie live + gap repair
```
Le détail des RAW persistés reste la responsabilité de Store Desk.
## CORE
@@ -222,7 +348,9 @@ Un satellite protocolaire reste avec son groupe : Meteora vaults avec Meteora, P
## Worker API
`ksp-worker-api` reste une lifecycle API générique pour services continus.
`ksp-worker-api` reste une lifecycle API générique pour services continus. Elle est volontairement stabilisée avant l'audit détaillé du premier worker RAW afin de ne pas encoder Solana, Transport, Store ou une source d'acquisition particulière dans son contrat.
Le pattern latest-value de `ksp-job-api` peut être réutilisé conceptuellement lorsqu'il convient, mais Worker et Job conservent des sémantiques distinctes : un worker est un service continu qui peut rester actif indéfiniment, tandis qu'un job représente un traitement borné/terminable. Une dépendance `ksp-worker-api -> ksp-job-api` n'est pas supposée ; la réutilisation concrète doit être justifiée par un contrat réellement commun.
Concepts candidats :
@@ -353,13 +481,18 @@ ksp-job-backfill-lib
### RAW worker
```text
ksp-worker-raw-retriever
ksp-worker-raw-transaction-ingest-lib
-> ksp-worker-api
-> ksp-onchain-transport-lib
-> ksp-interface-lib # seulement si un fait passif partagé aide la composition live
-> ksp-store-lib # façade Store ; backend sélectionné par feature + Config
-> ksp-config-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-logging-lib
composition supérieure / future Desk
-> ksp-config-lib
-> ksp-worker-raw-transaction-ingest-lib
-> ksp-onchain-transport-lib
-> ksp-store-lib
```
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.
@@ -392,9 +525,10 @@ selon les capacités réellement introduites.
## 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 ;
- nom final de la crate pipeline RAW si la réutilisation worker + backfill justifie réellement une crate dédiée ;
- taxonomie exacte des stratégies/source capabilities de `ksp-worker-raw-transaction-ingest-lib`, à décider par l'audit de fin `0.3.9` ;
- stratégie sûre de canonicalisation/aliasing `mainnet` / `mainnet-beta`, si un changement KSP est réellement nécessaire ;
- modèle de claim/lease PostgreSQL pour les futurs processors continus ;
- taille de batch et stratégie backpressure ;
- taille de batch et stratégie backpressure des workers de processing ;
- découpage des workers DECODE/SPECIALIZED par groupe lorsque les premiers groupes existent ;
- mécanisme IPC des applications de contrôle futures.

43
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: 10 -->
<!-- version: 11 -->
# Applications, services, scenarios et control plane
@@ -121,6 +121,15 @@ ksp-app-store-desk
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-store-lib
ksp-app-raw-transaction-ingest-desk
-> ksp-config-lib
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-worker-api
-> ksp-worker-raw-transaction-ingest-lib
-> ksp-onchain-transport-lib
-> 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.
@@ -129,6 +138,8 @@ 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.
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
@@ -184,14 +195,17 @@ package ksp-worker-<role>
Exemples conceptuels :
```text
ksp-worker-raw-retriever
ksp-worker-raw-transaction-ingest-lib # premier runtime worker réutilisable retenu
future autonomous raw-ingest binary # seulement si un besoin de service séparé le justifie
future CORE worker
future group-specific DECODE/SPECIALIZED workers when justified
```
Le premier worker RAW est volontairement prévu comme bibliothèque réutilisable afin qu'une Desk ou un futur host puisse le construire sans dupliquer sa logique. Un binaire autonome n'est pas créé par convention seule ; s'il apparaît, il reste un host mince au-dessus de la même bibliothèque et de `ksp-worker-api`.
RAW et CORE reçoivent leurs workers à la fin de leur couche respective. Les workers DECODE/SPECIALIZED ne sont plus tous anticipés comme une chaîne globale fixe : leur granularité doit émerger des premiers vertical slices Program.
Le binaire doit rester mince.
Le binaire, lorsqu'il existe, doit rester mince.
Il ne duplique pas le pipeline ni la logique de worker contenue dans la cible bibliothèque du même package.
@@ -469,26 +483,17 @@ Cette policy appartient au scenario, pas à `ksp-program-lib`.
## 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.
Elle doit passer par le control plane et non modifier directement l'état interne du worker dans PostgreSQL.
Conceptuellement :
Une application spécialisée de worker peut être créée lorsqu'elle est utile pour développer/tester/exploiter ce service. La première application retenue est :
```text
ksp-app-worker-<role>-desk
|
v
ksp-worker-control-lib
|
v
worker-api / remote proxy
|
v
independent worker service
ksp-app-raw-transaction-ingest-desk
```
La nomenclature précise des apps sera fixée à la première implémentation pour éviter de multiplier prématurément les packages.
Elle ne modifie jamais directement l'état interne du worker dans PostgreSQL. Elle passe par les contrats Worker et par la composition Rust propriétaire des ressources.
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.
## Configuration desired vs effective