# Contrats initiaux des composants KSP ## Objet Ce document synthétise les responsabilités des composants KSP. Les types Rust exacts restent définis au moment de leur première implémentation réelle. ## Convention API / implémentation Une crate de contrats extensibles se nomme `ksp--api`. Une implémentation réutilisable se nomme `ksp--lib`. Couples explicitement retenus : ```text ksp-program-api / ksp-program-lib ksp-materializer-api / ksp-materializer-lib ksp-store-api / ksp-store-lib ``` Lifecycle APIs séparées : ```text ksp-worker-api ksp-job-api ksp-execution-policy-api ``` Une crate `*-api` n'est jamais créée uniquement pour la symétrie des noms. ## Core `ksp-core-lib` porte les primitives transversales réellement fondamentales, dont `Error`/`Result` et le registre KSP des Program IDs fondamentaux. Il ne devient pas une crate de modèles métier ou de transport. ## Logging `ksp-logging-lib` est la façade unique KSP de tracing runtime. Les composants runtime émettent leurs événements via cette façade. Les targets tiers sont silencieux par défaut et les informations utiles sont réémises sous le target du composant KSP propriétaire. ## Config `ksp-config-lib` est l'unique propriétaire des documents Config, `.env`, variables KSP/KSPB et persistence Config. Les composants exposent leurs settings publics ; Config peut fournir un document standard et un adapter vers ces settings sans créer de dépendance inverse. ## Transport on-chain Aucune `ksp-onchain-transport-api` séparée n'est prévue. `ksp-onchain-transport-lib` possède : - settings runtime publics ; - endpoints/providers/clusters ; - pools/rôles/capabilities ; - HTTP JSON-RPC ; - WebSocket ; - Yellowstone gRPC et futurs adapters provider lorsque introduits ; - modèles homogènes par catégorie de donnée ; - observabilité transport. Il ne dépend pas de Config, Store ou Program. Pour toute surface normative ciblée, toutes les méthodes documentées sont inventoriées/implémentées sauf impossibilité documentée. Les méthodes deprecated/obsolete encore fonctionnelles et unstable/experimental émettent un warning KSP à l'utilisation. La complétude vaut aussi à l'intérieur de chaque opération : paramètres, options, overloads et formes legacy supportées sont exposés, et les variantes de réponse sont préservées sans perte. KSP n'est pas tenu de dupliquer un SDK externe lorsque des sous-arbres wire lossless suffisent. ## Transport off-chain Aucune `ksp-offchain-transport-api` commune n'est prévue. `ksp-offchain-transport-lib` peut contenir plusieurs modules/APIs distincts : prix, metadata HTTP/IPFS/Arweave, quotes et autres accès externes. La première surface engagée est le prix SOL/USD et SOL/EUR. ## Wallet Aucune `ksp-wallet-api` séparée n'est prévue. `ksp-wallet-lib` possède le format `.kspwallet`, le secret protégé, l'identité publique, signature, import/export et conversions utiles. Il ne possède pas `WalletPolicy` ni les règles d'autorisation d'exécution. Le wallet temporaire JSON historique n'est pas migré. ## Interface / wire `ksp-interface-lib` est la façade wire officielle KSP et expose aussi une API publique wire réutilisable par `ksp-program-lib` et les extensions Program externes. Aucune `ksp-interface-api` séparée n'est retenue actuellement. La crate sélectionne entre réexport contrôlé, wrapper ou implémentation wire compatible selon stabilité, ownership et graphe de dépendances des interfaces externes. ## Program `ksp-program-api` porte les contrats extensibles de Program : descriptors/capabilities, decoders, outputs et préparation d'exécution lorsque ces contrats sont démontrés. `ksp-program-lib` porte les implementations officielles et dépend de `ksp-program-api`. Une crate externe peut implémenter `ksp-program-api` sans dépendre de `ksp-program-lib`. ## Execution policy `ksp-execution-policy-api` est le contrat commun de décision/safety. Une policy décide ; elle ne signe pas, n'envoie pas et ne possède ni Wallet ni Transport. Une petite policy de scenario/orchestrateur peut être implémentée localement. Des bibliothèques communes sont créées uniquement si une réutilisation réelle apparaît. ## Execution orchestration `ksp-execution-lib` est introduit lorsque le premier vertical slice réel nécessite une orchestration stable entre : ```text ksp-program-api ksp-execution-policy-api ksp-wallet-lib ksp-onchain-transport-lib ``` Il ne dépend pas de `ksp-program-lib` afin d'accepter des implementations Program externes. ## Store et niveaux durables La chaîne durable est : ```text D1 RAW -> D2 CORE -> D3 DECODE -> D4 SPECIALIZED ``` ### RAW Acquisition replayable + provenance, sans décodage Program. ### CORE Normalisation générique Solana, sans décodage Program. ### DECODE Interprétation Program/protocole puis matérialisation générique/journal durable. ### SPECIALIZED Projections queryables de domaine : token, metadata, pools, trades, OHLC, routes, etc. `ksp-store-api` possède les contrats backend-agnostic. `ksp-store-lib` fournit PostgreSQL comme backend officiel. La première Store release est RAW-only ; les couches suivantes sont ajoutées quand elles sont réellement ouvertes. ## Materializer `ksp-materializer-api`/`ksp-materializer-lib` sont introduits avec le premier besoin DECODE réel, pas avant. Program et Materializer restent indépendants du backend Store ; les composants de composition convertissent leurs outputs vers les DTO persistants. ## Workers `ksp-worker-api` est la lifecycle API des services continus. RAW et CORE peuvent recevoir leurs workers à la fin de leur couche respective. Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program réels, afin de ne pas créer une orchestration générique vide avant les processors. ## Jobs `ksp-job-api` est la lifecycle API des travaux déclenchés/terminables. Le premier job retenu est le backfill RAW. Les jobs de replay suivent ensuite les frontières durables ouvertes : RAW -> CORE, CORE -> DECODE, DECODE -> SPECIALIZED. Aucune `ksp-job-control-lib` n'est prévue sans duplication concrète. ## Scenarios Les scenarios restent dans `ksp-scenario--lib` et sont appelables sans desktop. Ils composent les Program implementations, policy, Wallet, transport et execution nécessaires à leur vertical slice. L'application demo correspondante reste une UI mince. ## Applications KSP privilégie des applications spécialisées servant à valider/exploiter une capacité réelle : ```text ksp-app-config-desk ksp-app-wallet-desk price desk backfill/raw tooling CORE tooling ksp-app-market-desk ``` Une application globale reste future. ## Progression verticale Program À partir de DECODE : ```text wire -> decode -> materialize -> specialized -> prepare -> policy -> execute -> scenario ``` Ordre prioritaire actuel : Solana Core Programs, SPL token/trading, token metadata, Anchor, Meteora, Raydium, Pump, Orca, routing, trading-adjacent, puis décodage généraliste. Un satellite nécessaire reste dans son groupe protocolaire.