145 lines
5.1 KiB
Markdown
145 lines
5.1 KiB
Markdown
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
|
<!-- version: 4 -->
|
|
|
|
# Contrats initiaux des composants KSP
|
|
|
|
## Objet
|
|
|
|
Ce document enregistre les frontières déjà suffisamment claires pour guider la planification. Il ne définit pas encore les API Rust finales.
|
|
|
|
Le principe commun est de définir tôt les contrats nécessaires entre composants, puis d'enrichir les implémentations lorsque le besoin réel apparaît.
|
|
|
|
L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md).
|
|
|
|
## Convention API / implémentation
|
|
|
|
Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP peut séparer :
|
|
|
|
```text
|
|
ksp-<domain>-api
|
|
ksp-<domain>-lib
|
|
```
|
|
|
|
La crate `ksp-<domain>-api` est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`.
|
|
|
|
Cette séparation n'est pas automatique. Elle est utilisée lorsqu'une vraie frontière d'extension/backend/lifecycle la justifie.
|
|
|
|
Couples retenus :
|
|
|
|
```text
|
|
ksp-program-api / ksp-program-lib
|
|
ksp-materializer-api / ksp-materializer-lib
|
|
ksp-store-api / ksp-store-lib
|
|
```
|
|
|
|
APIs lifecycle retenues :
|
|
|
|
```text
|
|
ksp-worker-api
|
|
ksp-job-api
|
|
```
|
|
|
|
Aucune API commune worker+job n'est prévue.
|
|
|
|
## Execution policy
|
|
|
|
`ksp-program-lib` ne possède pas la politique de sécurité/autorisation d'un produit.
|
|
|
|
La direction retenue pour étude est un contrat public séparé :
|
|
|
|
```text
|
|
ksp-execution-policy-api
|
|
```
|
|
|
|
Il doit permettre à différents contextes de fournir leurs propres décisions de policy sans modifier `ksp-program-lib` : scenario Devnet, application générale, futur produit trading, etc.
|
|
|
|
Les applications UI sélectionnent/injectent une implémentation réutilisable appropriée ; elles ne doivent pas enfouir une politique complexe directement dans la couche d'interface.
|
|
|
|
## Execution orchestration
|
|
|
|
`ksp-execution-lib` devient un candidat fort de pipeline/orchestrateur spécialisé pour relier :
|
|
|
|
- la préparation/sémantique programme ;
|
|
- une implémentation de `ksp-execution-policy-api` ;
|
|
- `ksp-wallet-lib` ;
|
|
- `ksp-onchain-transport-lib`.
|
|
|
|
Le but est d'éviter que `ksp-program-lib` dépende directement du wallet/transport uniquement pour réaliser le cycle réseau/signature.
|
|
|
|
Le graphe exact reste à valider dans `pre.003`.
|
|
|
|
## Transport on-chain
|
|
|
|
Aucune `ksp-onchain-transport-api` séparée n'est prévue.
|
|
|
|
`ksp-onchain-transport-lib` regroupe les transports/providers on-chain et expose des modèles de sortie homogènes par catégorie de données.
|
|
|
|
Il ne dépend pas de `ksp-store-api`.
|
|
|
|
Les modèles de transport doivent cependant être conçus pour une conversion explicite et simple vers les modèles raw persistants du store, sans décodage protocolaire.
|
|
|
|
## Transport off-chain
|
|
|
|
Aucune `ksp-offchain-transport-api` commune n'est prévue.
|
|
|
|
La crate est volontairement hétérogène : metadata, prix, quotes, routage et autres ressources externes peuvent avoir des modules/APIs distincts à l'intérieur d'une seule crate afin d'éviter une prolifération de crates artificielles.
|
|
|
|
## Wallet
|
|
|
|
Aucune `ksp-wallet-api` n'est prévue.
|
|
|
|
`ksp-wallet-lib` possède le format wallet KSP et les capacités de lecture/protection/import/export/pubkey/secret/signature nécessaires à ses consommateurs.
|
|
|
|
## Store et notifications de données
|
|
|
|
`ksp-store-api` reste la frontière backend-agnostic. `ksp-store-lib` contient PostgreSQL comme implémentation de référence.
|
|
|
|
Les notifications de données persistées sont normalisées indépendamment de leur producteur. W1, un job de backfill ou un import utilisent le même contrat pour signaler le même type de donnée.
|
|
|
|
Le contrat de notification est distinct de son transport concret.
|
|
|
|
## Workers
|
|
|
|
`ksp-worker-api` est une lifecycle API pour services continus/live.
|
|
|
|
`ksp-worker-control-lib` est une implémentation réutilisable de gouvernance pouvant être consommée par les applications manager desktop, une future application globale ou un orchestrateur.
|
|
|
|
Workers actuellement retenus :
|
|
|
|
```text
|
|
ksp-worker-raw-retriever
|
|
ksp-worker-core-processor
|
|
ksp-worker-generic-materializer
|
|
ksp-worker-domain-projector
|
|
```
|
|
|
|
Le dernier nom reste provisoire.
|
|
|
|
## Jobs
|
|
|
|
`ksp-job-api` est une lifecycle API distincte pour travaux déclenchés et terminables.
|
|
|
|
`ksp-job-backfill` est retenu pour le backfill historique.
|
|
|
|
Aucune `ksp-job-control-lib` n'est prévue actuellement. D'autres jobs pourront apparaître pour metadata, quotes ou autres besoins ponctuels.
|
|
|
|
## Scénarios
|
|
|
|
Les scénarios restent dans des crates spécialisées `ksp-scenario-<domain>-lib`.
|
|
|
|
`ksp-scenario-api` n'est pas retenu actuellement : une norme de structure/comportement commune est préférée à un trait Rust obligatoire tant qu'un vrai contrat commun n'a pas émergé.
|
|
|
|
Les demos desktop de scénario suivent provisoirement la forme :
|
|
|
|
```text
|
|
ksp-app-scenario-<domain>-<environment>-desk-demo
|
|
```
|
|
|
|
et réutilisent la crate de scénario correspondante.
|
|
|
|
## Pipelines
|
|
|
|
Aucun `ksp-pipeline-lib` monolithique.
|
|
|
|
Des pipelines spécialisés peuvent être ajoutés à la demande. `ksp-execution-lib` est justement étudié comme un pipeline/orchestrateur spécialisé, pas comme une infrastructure universelle.
|