khadhroony-solana-project/docs/architecture/004-COMPONENT_INVENTORY.md

Inventaire initial des composants KSP

Objet

Ce document maintient l'inventaire synthétique des composants retenus ou pressentis. Les numéros de release précis restent soumis au sizing de chaque session.

Statuts

• Stable — implémenté et publié ;
• Implémenté — présent et techniquement validé, en attente de publication stable ;
• Retenu — composant/contrat décidé ;
• Pressenti — direction décidée mais périmètre exact à confirmer ;
• À la demande — créé seulement au premier besoin réel ;
• Non retenu — explicitement écarté pour l'instant.

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, 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

ksp-program-api
ksp-materializer-api
ksp-store-api
ksp-worker-api
ksp-job-api
ksp-execution-policy-api

Pas de crates séparées actuellement pour :

ksp-interface-api
ksp-wallet-api
ksp-onchain-transport-api
ksp-offchain-transport-api
ksp-scenario-api
ksp-job-control-lib
ksp-data-api

Transport

ksp-onchain-transport-lib doit couvrir l'intégralité des opérations documentées de la surface ciblée par chaque release. 0.2.1 stabilise la foundation HTTP et quatre wrappers typés canari, 0.2.2 ajoute 22 wrappers Accounts/Tokens/Cluster et 0.2.3 stabilise les 11 Transactions. La release stable 0.2.4 ajoute les 10 Blocks + 5 Economics et atteint 52/52 méthodes HTTP courantes typées, avec 14/14 historiques Deprecated/Removed conservées pour compliance. Les statuts deprecated/obsolete encore fonctionnels et unstable/experimental restent exposés avec warning runtime KSP. La release stable 0.2.7 ajoute le moteur WebSocket Solana standard complet : 9 familles subscribe + 9 unsubscribe typées, sessions physiques explicites, subscriptions logiques, reconnect/resubscribe/backpressure/shutdown bornés et Config Transport V2, sans second composant réseau ni dépendance inverse vers Config.

La Config standard Transport appartient à ksp-config-lib, qui adapte vers les settings publics du transport ; le transport ne dépend jamais de Config.

Les WebSockets supportent plusieurs sessions pour un même endpoint URL, mais un pool/scheduler automatique n'est créé qu'après besoin démontré.

Les providers Yellowstone spécifiques restent des extensions futures ; le contrat standard est provider-neutral.

ksp-offchain-transport-lib ouvre en 0.2.11 une première surface SOL/USD multi-provider. La crate possède les adapters reqwest, les capacités/rate limits, l’état runtime et le refresh individuel/multiple. Elle ne dépend pas de Config et n’expose aucun wire provider comme contrat de l’application. ksp-app-solprices-desk, prévu en 0.2.12, consomme exclusivement cette surface générique et reste une HID sans connaissance provider.

Wallet

Le format natif est .kspwallet.

Les anciens temporary wallets JSON ne sont pas migrés.

WalletPolicy est exclu du Wallet et relève de l'execution policy.

Import/export reste extensible ; les formats supplémentaires sont suivis dans docs/IDEAS.md.

Data plane

RAW -> CORE -> DECODE -> SPECIALIZED

• RAW : acquisition replayable ;
• CORE : normalisation blockchain générique sans decoder Program ;
• DECODE : interpretation Program + matérialisation générique/journal ;
• SPECIALIZED : projections queryables de domaine.

Progression des processors

RAW et CORE sont complétés couche par couche avec jobs/workers/apps utiles.

À partir de DECODE, progression verticale par groupe :

wire -> decode -> materialize -> specialized -> prepare -> policy -> execute -> scenario

Groupes prioritaires :

Solana Core Programs
SPL token/trading
token metadata
Anchor
Meteora
Raydium
Pump
Orca
Market Desk V1
Jupiter/OKX routing
Market Desk V2
trading-adjacent
general decoding

Meteora vaults, Pump fees et autres satellites nécessaires restent dans leur groupe.

Applications spécialisées

Les applications servent de validations/exploitations réelles sans absorber la logique des bibliothèques.

Market Desk est progressive : V1 après les DEX prioritaires, puis enrichissement routing après Jupiter/OKX.

Questions restantes

• nécessité future d'un pool automatique WS ;
• types exacts ksp-materializer-api lors de l'ouverture DECODE ;
• nom/packaging précis du premier RAW worker et du CORE normalizer ;
• granularité des workers DECODE/SPECIALIZED par groupe.