225 lines
9.2 KiB
Markdown
225 lines
9.2 KiB
Markdown
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
|
<!-- version: 11 -->
|
|
|
|
# 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 / 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 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 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 :
|
|
|
|
```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.
|