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 DECODE s'ouvre ;
• ksp-job-api et jobs ;
• 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 CORE
  -> D3 DECODE
  -> D4 SPECIALIZED

Aliases fonctionnels :

RAW -> CORE -> DECODE -> SPECIALIZED

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

CORE 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 à CORE -> DECODE.

Progression par couche

RAW et CORE

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.

DECODE et SPECIALIZED

À 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, backfill/RAW tooling, CORE 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.

Workers et jobs

Un worker est un service continu/autonome ; un job est borné/terminable.

Ils utilisent des APIs lifecycle distinctes et ne s'appellent pas entre eux pour transférer les payloads du data plane.

Le Store reste le point durable de synchronisation entre couches de processing.

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/CORE :

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 DECODE/SPECIALIZED par groupe.