11 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 + ksp-store-<backend>-lib
Lifecycle APIs séparées :
ksp-worker-api
ksp-job-api
ksp-execution-policy-api
Pour Store, le couple API/façade est complété par des crates backend séparées : chaque ksp-store-<backend>-lib implémente ksp-store-api et ne dépend jamais de ksp-store-lib. Les consumers runtime ordinaires utilisent la façade ksp-store-lib, pas une crate backend concrète.
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 / contrats passifs
ksp-interface-lib possède les contrats passifs KSP réellement partagés entre composants : façade wire officielle lorsqu'un protocole commun l'exige, et faits d'acquisition provider-neutral lorsqu'une sémantique commune exacte est démontrée. Sa surface publique est réutilisable notamment par ksp-program-lib, les extensions Program externes et les composants de composition/acquisition qui ne doivent pas dépendre d'un DTO Transport particulier.
Aucune ksp-interface-api séparée n'est retenue actuellement.
La crate sélectionne entre réexport contrôlé, wrapper ou implémentation KSP-owned selon stabilité, ownership et graphe de dépendances. Elle ne possède ni Transport/runtime, ni Store/persistence, ni event bus ; les conversions depuis les DTOs Transport restent dans la composition.
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 STRUCTURAL
-> D3 DECODED
-> D4 DOMAIN
RAW
Acquisition replayable + provenance, sans décodage Program.
STRUCTURAL
Normalisation générique Solana, sans décodage Program.
DECODED
Interprétation Program/protocole puis matérialisation générique/journal durable.
DOMAIN
Projections queryables de domaine : token, metadata, pools, trades, OHLC, routes, etc.
ksp-store-api possède les contrats backend-agnostic. ksp-store-lib fournit la façade/runtime commune et sélectionne les backends compilés par features. PostgreSQL est le backend officiel par défaut mais son implémentation physique appartient à ksp-store-postgres-lib.
Les jobs, workers et applications consomment normalement ksp-store-lib; les crates backend dépendent de ksp-store-api et restent invisibles aux consumers. Une dépendance directe à ksp-store-api reste réservée aux implémentations de contrats ou composants réutilisables qui ont réellement besoin de ces traits/types sans façade runtime.
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 DECODED 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 STRUCTURAL peuvent recevoir leurs workers à la fin de leur couche respective.
Les workers DECODED/DOMAIN 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 l'API passive et runtime-neutral des travaux bornés/terminables. Elle possède JobId, JobKindCode, le lifecycle Created/Running/Cancelling/Completed/Cancelled/Failed, l'intention d'annulation coopérative et le contrat latest-value JobNotification / JobSnapshotSource. Sa dépendance normale reste exclusivement ksp-core-lib.
Le premier job concret est ksp-job-backfill-lib. Il couvre un backfill historique RawTransaction : quatre scopes bornés, découverte/hydratation Transport observée, conversion RAW v1, persistance atomique par ksp-store-lib, concurrence bornée, frontier/checkpoint contigus caller-owned, annulation coopérative et snapshots complets sûrs. Il ne dépend ni de Config, ni d'un backend Store concret, ni d'un Worker.
Les jobs de replay suivants pourront suivre les frontières durables ouvertes : RAW -> STRUCTURAL, STRUCTURAL -> DECODED, DECODED -> DOMAIN. Ils ne sont pas forcés d'adopter le contrat métier du backfill RAW ; seuls les contrats vraiment communs appartiennent à ksp-job-api.
Aucune ksp-job-control-lib n'est créée 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
ksp-app-solprices-desk
ksp-app-backfill-desk
ksp-app-store-desk
STRUCTURAL tooling
ksp-app-market-desk
Une application globale reste future.
ksp-app-backfill-desk est l'interface spécialisée du premier job historique. Elle dépend des façades KSP nécessaires à la composition (ksp-config-lib, ksp-job-api, ksp-job-backfill-lib, ksp-onchain-transport-lib, ksp-store-lib, Core et Logging), garde Store/Transport/checkpoint côté Rust et expose uniquement les options, demandes opérateur bornées, états latest-value et acquittements de contrôle sûrs.
ksp-app-store-desk est l'interface spécialisée d'inspection du Store RAW. Elle dépend de ksp-config-lib, ksp-core-lib, ksp-logging-lib et ksp-store-lib, conserve le Store ouvert côté Rust, expose uniquement des DTOs app-owned backend-neutral et ne fournit aucun command d'écriture. Les tables utilisent les capabilities d'inspection random-access ; les détails rechargent une seule entité et bornent les previews RAW sans déplacer la rétention ou le backend dans Tauri.
Progression verticale Program
À partir de DECODED :
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.