8.4 KiB
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-<domain>-api. Une implémentation réutilisable se nomme ksp-<role>-lib.
Couples explicitement retenus :
ksp-program-api / ksp-program-lib
ksp-materializer-api / ksp-materializer-lib
ksp-store-api / ksp-store-lib
Lifecycle APIs séparées :
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 par 0.2.11 est exclusivement le prix SOL/USD.
Pour cette surface, Off-chain Transport possède le registry runtime des providers, leurs adapters/wires privés, leurs capacités et contraintes de refresh, la classification des indisponibilités et l'orchestration de refresh individuel/multiple. Plusieurs providers peuvent produire la même paire sans que KSP invente un consensus, une moyenne ou un fallback automatique.
Les adapters provider V1 utilisent uniquement reqwest et les primitives génériques du workspace ; aucun SDK provider n'est introduit. Config peut adapter ses documents vers les settings publics provider-capability-aware, mais Off-chain Transport ne lit jamais directement l'environnement ou les fichiers Config.
ksp-app-solprices-desk est la HID provider-agnostic dédiée : elle liste et déclenche uniquement les surfaces génériques de la crate. Toute connaissance de CoinGecko, CoinMarketCap, CoinPaprika, Kraken, Coinbase, Jupiter, Birdeye ou DexScreener reste sous Off-chain Transport/Config.
Wallet Desk peut consommer la même surface générique comme capacité auxiliaire. Sa moyenne SOL/USD et l'équivalent USD de balance sont des projections locales au consumer calculées à partir des observations du refresh courant ; ils ne deviennent ni un consensus, ni un fallback, ni un prix canonique possédé par Off-chain Transport.
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 :
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 :
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-<domain>-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 :
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 :
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.