khadhroony-solana-project/docs/architecture/002-LAYERS_AND_DEPENDENCIES.md

Couches et dépendances KSP

Rôle des niveaux architecturaux

Les niveaux architecturaux N1–N4 décrivent les familles de composants du projet. Ils ne doivent pas être confondus avec les niveaux durables D1–D4.

N1 — Fondations communes

• ksp-core-lib ;
• ksp-logging-lib ;
• ksp-config-lib ;
• premières règles/outils transversaux.

N2 — Capacités Solana réutilisables

• ksp-onchain-transport-lib ;
• ksp-offchain-transport-lib ;
• ksp-wallet-lib ;
• ksp-interface-lib ;
• ksp-program-api puis implementations Program ;
• ksp-execution-policy-api et orchestration d'exécution lorsqu'un vertical slice réel le justifie.

N3 — Données, jobs, workers et processing

• ksp-store-api / ksp-store-lib ;
• ksp-materializer-api / implementations lorsque DECODED s'ouvre ;
• ksp-job-api, ksp-job-backfill-lib puis les jobs concrets introduits par les couches ;
• ksp-worker-api et workers ;
• processors/pipelines spécialisés réellement réutilisés.

N4 — Exécutables

• applications desk ;
• services workers ;
• outils/jobs exécutables ;
• demos/scenarios ;
• future orchestration globale.

Chaîne durable indépendante des niveaux N1–N4

La chaîne de données canonique est :

D1 RAW
  -> D2 STRUCTURAL
  -> D3 DECODED
  -> D4 DOMAIN

Aliases fonctionnels :

RAW -> STRUCTURAL -> DECODED -> DOMAIN

RAW et STRUCTURAL sont indépendants du décodage Program.

STRUCTURAL est une normalisation générique de Solana : structure des blocs, transactions, messages, comptes, instructions/CPI brutes, logs/meta et relations fondamentales.

Le premier decoder Program intervient seulement à STRUCTURAL -> DECODED.

Progression par couche

RAW et STRUCTURAL

Ces deux couches sont construites horizontalement.

À la fin de chaque couche, KSP ajoute les composants d'exploitation nécessaires : persistence, replay/backfill, worker/service et application de contrôle lorsque utiles.

DECODED et DOMAIN

À partir du décodage, KSP progresse verticalement par groupe fonctionnel :

wire
 -> decode
 -> materialize
 -> specialized projection si utile
 -> execution preparation
 -> policy
 -> execute
 -> scenarios

Cela évite de développer tous les decoders avant les matérialisations et toutes les executions.

Séparation maximale des dépendances

Chaque composant possède son contrat et reçoit explicitement les données nécessaires.

Exemples structurants :

ksp-onchain-transport-lib -X-> ksp-config-lib
ksp-onchain-transport-lib -X-> ksp-store-api
ksp-wallet-lib            -X-> ksp-onchain-transport-lib
ksp-wallet-lib            -X-> execution policy
ksp-interface-lib         -X-> ksp-program-api
ksp-execution-lib         -X-> ksp-program-lib

La composition supérieure relie les composants.

Configuration

ksp-config-lib est l'unique propriétaire des documents Config, .env et variables KSP/KSPB.

Un composant ne dépend pas de Config pour être utilisable. Il expose des settings publics.

Config peut fournir un document standard et un adapter vers ces settings lorsque cela devient utile :

ksp-config-lib -> public settings du composant

sans dépendance inverse.

Logging

ksp-logging-lib reste l'unique façade KSP de tracing runtime.

Les crates comportant du comportement runtime peuvent en dépendre. Les crates *-api purement déclaratives n'ajoutent cette dépendance que si elles ont réellement un comportement à logger.

Applications

Les applications Tauri restent minces :

• DTOs applicatifs ;
• composition de services KSP ;
• lifecycle fenêtre/UI ;
• instrumentation frontend ;
• aucun déplacement de logique de transport, Wallet, Config, Program, Store ou Materializer dans Tauri.

Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, ksp-app-solprices-desk, ksp-app-backfill-desk, ksp-app-store-desk, STRUCTURAL tooling puis Market Desk. ksp-app-solprices-desk reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de ksp-offchain-transport-lib sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites. ksp-app-backfill-desk compose Config, Transport HTTP, Store et ksp-job-backfill-lib sans absorber découverte, retry/rate-limit, persistance ou checkpoint ; son frontend ne reçoit que des DTOs sûrs et le checkpoint de reprise reste Rust-only. ksp-app-store-desk compose Config, Logging et ksp-store-lib pour une inspection RAW read-only : il n'accède ni au backend physique ni au SQL et sépare la pagination random-access de l'interface de la pagination cursor/keyset réservée aux consumers machine.

Workers et jobs

Un worker est un service continu/autonome ; un job est borné/terminable. ksp-job-api porte le lifecycle commun et l'observation latest-value sans runtime concret. Le premier job, ksp-job-backfill-lib, fournit un runtime single-run historique vers RAW ; il compose Transport et Store sans devenir worker ni service permanent.

Workers et jobs utilisent des APIs lifecycle distinctes et ne s'appellent pas entre eux pour transférer les payloads du data plane. Un checkpoint de job peut être caller-owned sans devenir automatiquement une persistence de control plane.

Le Store reste le point durable de synchronisation des données entre couches de processing ; les snapshots Job décrivent l'état opérationnel du job et ne remplacent pas les données RAW persistées.

Firewall des dépendances externes

Les exécutables et couches supérieures n'importent pas directement les crates Solana/protocoles métier lorsqu'une façade KSP existe ou est prévue.

Exceptions bas niveau explicitement autorisées restent limitées aux primitives stables décidées par les règles KSP.

ksp-interface-lib concentre les contrats passifs KSP réellement partagés — wires officiels/compatibles et faits provider-neutral admis — afin d'éviter les doublons de générations, les dépendances protocolaires dans les couches supérieures et la promotion accidentelle d'un DTO Transport en contrat transversal. Les converters depuis Transport restent dans la composition.

Principe contract-first

Une crate *-api est créée uniquement lorsque l'extension externe/backend/lifecycle exige un contrat séparé.

Cas décidés :

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

ksp-interface-lib, Wallet et transports conservent pour l'instant leurs APIs publiques dans leur bibliothèque d'implémentation.

Groupes Program prioritaires

Après RAW/STRUCTURAL :

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

Un satellite nécessaire à un protocole reste dans son groupe : Pump fee avec Pump, Meteora vault avec Meteora, etc.

Questions encore ouvertes

• forme exacte des settings publics Transport ;
• nécessité future d'un pool automatique de sessions WebSocket ;
• split éventuel d'une API Interface séparée uniquement si un vrai besoin apparaît ;
• contrats Rust exacts de Program/Materializer/Store ;
• mécanisme IPC du premier manager de worker autonome ;
• granularité future des workers DECODED/DOMAIN par groupe.