230 lines
11 KiB
Markdown
230 lines
11 KiB
Markdown
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
|
<!-- version: 15 -->
|
|
|
|
# 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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```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 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 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 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 -> CORE, CORE -> DECODE, DECODE -> SPECIALIZED. 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 :
|
|
|
|
```text
|
|
ksp-app-config-desk
|
|
ksp-app-wallet-desk
|
|
ksp-app-solprices-desk
|
|
ksp-app-backfill-desk
|
|
ksp-app-store-desk
|
|
CORE 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 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.
|