345 lines
27 KiB
Markdown
345 lines
27 KiB
Markdown
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
||
<!-- version: 10 -->
|
||
|
||
# Inventaire initial des composants KSP
|
||
|
||
## Objet
|
||
|
||
Ce document constitue le premier inventaire architectural de `0.0.3-pre.002`.
|
||
|
||
Il répond principalement à la question : **quel composant possède quelle responsabilité ?**
|
||
|
||
Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé à partir du graphe, puis `pre.004` a détaillé Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md), `pre.005` Execution/Policy, `pre.006` les niveaux durables/Materialization/Store, `pre.007` l'exploitation workers/jobs/pipelines, `pre.008` Apps/Services/Scenarios/Control, puis `pre.009` le séquencement des premières releases fonctionnelles. La séquence détaillée est dans `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`. Les détails de types Rust restent révisables avec les premières implémentations.
|
||
|
||
## Statuts
|
||
|
||
- **Retenu** — composant ou responsabilité considérée nécessaire dans la trajectoire actuelle ;
|
||
- **Candidat fort** — composant très probable mais dont la frontière exacte doit encore être validée ;
|
||
- **Futur retenu** — responsabilité acquise mais implémentation différée ;
|
||
- **À la demande** — ne doit être créé que lorsqu'un premier besoin concret le justifie ;
|
||
- **Non retenu actuellement** — idée volontairement non créée ; elle peut être réévaluée si l'usage réel change.
|
||
|
||
## Inventaire synthétique
|
||
|
||
| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale |
|
||
|----------------------------------|---------------------------------------------|-------------------------|-------------------|-----------------------------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.1` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
|
||
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.3` par défaut | documents de configuration, profils, résolution, modifications autorisées |
|
||
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.2` | façade unique `tracing`/appender/subscriber, initialisation et logging structuré KSP ; peut dépendre de core pour Error/Result |
|
||
| Config desktop | `ksp-app-config-desk` | app | N4 | Retenu | `0.1.4` par défaut | app spécialisée Tauri validant chargement, profils, édition, sauvegarde, validation et diagnostics Config |
|
||
| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles |
|
||
| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics ouverts de décodage, préparation d'exécution, descriptors et registry |
|
||
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders et `ProgramExecutionPreparer` officiels organisés par domaine/programme/capacité |
|
||
| Program extension | `ksp-program-<name>-lib` | lib externe/optionnelle | N2 | À la demande | dès besoin | implémentation externe de `ksp-program-api` pour un Program ID non encore intégré officiellement |
|
||
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | premier besoin d'exécution réelle | policy obligatoire, multi-checkpoints, décision/requirements sans wallet/réseau/UI |
|
||
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | consomme `PreparedProgramExecution`; orchestre policy/simulation/signature/submission/confirmation/retry sans dépendre de `ksp-program-lib` ou du store |
|
||
| Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store |
|
||
| Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain |
|
||
| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature |
|
||
| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation |
|
||
| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP |
|
||
| Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées |
|
||
| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries, backlog/replay et notification backend |
|
||
| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus |
|
||
| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable de services workers autonomes pour apps spécialisées puis futurs managers/orchestrateurs |
|
||
| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data |
|
||
| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique |
|
||
| Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core |
|
||
| Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine |
|
||
| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables |
|
||
| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise |
|
||
| Core replay | `ksp-job-replay-core` | job | N4 | Retenu | `0.3.x/0.6.x` | replay borné D1 -> D2 via le pipeline Core |
|
||
| Generic materialization replay | `ksp-job-replay-generic-materialization` | job | N4 | Retenu | `0.3.x/0.6.x` | replay borné D2 -> D3 via le pipeline générique |
|
||
| Domain projection replay | `ksp-job-replay-domain-projection` | job | N4 | Retenu | `0.3.x/0.6.x` | replay borné D3 -> D4 via le pipeline de projection |
|
||
| Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques |
|
||
| Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine |
|
||
| Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant |
|
||
| Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante |
|
||
| Raw ingestion pipeline | `ksp-pipeline-raw-ingestion-lib` | lib | N3 | Retenu | `0.3.x` | conversion/persistence transport model -> D1 partagée par worker live et backfill |
|
||
| Core processing pipeline | `ksp-pipeline-core-processing-lib` | lib | N3 | Retenu | `0.3.x/0.6.x` | logique D1 -> D2 partagée par worker et replay, basée sur `ksp-program-api` |
|
||
| Generic materialization pipeline | `ksp-pipeline-generic-materialization-lib` | lib | N3 | Retenu | `0.3.x/0.6.x` | logique D2 -> D3 partagée par worker et replay, basée sur `ksp-materializer-api` |
|
||
| Domain projection pipeline | `ksp-pipeline-domain-projection-lib` | lib | N3 | Retenu | `0.3.x/0.6.x` | logique D3 -> D4 partagée par worker et replay, basée sur `ksp-materializer-api` |
|
||
| Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML |
|
||
| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte |
|
||
| Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana |
|
||
| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX |
|
||
|
||
## APIs séparées retenues
|
||
|
||
Les couples suivants ont une justification d'extensibilité suffisante :
|
||
|
||
```text
|
||
ksp-program-api -> ksp-program-lib
|
||
ksp-materializer-api -> ksp-materializer-lib
|
||
ksp-store-api -> ksp-store-lib
|
||
```
|
||
|
||
Les APIs lifecycle sont également séparées :
|
||
|
||
```text
|
||
ksp-worker-api -> workers continus
|
||
ksp-job-api -> jobs terminables
|
||
```
|
||
|
||
Aucune API commune worker+job n'est prévue.
|
||
|
||
## Execution policy et orchestration
|
||
|
||
La frontière détaillée est définie dans [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md).
|
||
|
||
Principes retenus :
|
||
|
||
```text
|
||
PreparedProgramExecution
|
||
|
|
||
v
|
||
ksp-execution-lib
|
||
| | |
|
||
policy wallet onchain transport
|
||
```
|
||
|
||
- `ksp-execution-lib` dépend de `ksp-program-api`, pas de `ksp-program-lib` ;
|
||
- une policy est explicitement fournie pour toute exécution réelle ;
|
||
- la policy peut être évaluée à plusieurs checkpoints ;
|
||
- une policy décide/contraint mais n'exécute pas de réseau/signature/UI ;
|
||
- Program constraints, options caller et policy constraints restent trois sources distinctes ;
|
||
- wallet/signers et transport/provider sont fournis par la composition supérieure ;
|
||
- simulation/submission/status sont des primitives transport orchestrées par execution ;
|
||
- signature est une capacité wallet orchestrée par execution ;
|
||
- retry réseau identique et retry de lifecycle d'exécution restent distincts ;
|
||
- une approbation externe peut suspendre/reprendre l'exécution sans faire dépendre la policy de l'UI ;
|
||
- aucun accès Store depuis `ksp-execution-lib`.
|
||
|
||
`ksp-logging-lib` est consommé transversalement par les crates runtime qui doivent logger, sans imposer une dépendance aux crates `*-api` déclaratives ni à `ksp-core-lib`.
|
||
|
||
## Transport on-chain
|
||
|
||
Aucune crate `ksp-onchain-transport-api` n'est prévue.
|
||
|
||
`ksp-onchain-transport-lib` peut contenir plusieurs familles hétérogènes :
|
||
|
||
- HTTP RPC ;
|
||
- WebSocket RPC ;
|
||
- Helius avancé ;
|
||
- Yellowstone ;
|
||
- autres providers/transports futurs.
|
||
|
||
Les adapters providers doivent toutefois faire sortir de la crate des **modèles de transport homogènes par catégorie de donnée**, afin que les consommateurs n'aient pas à comprendre chaque réponse propriétaire.
|
||
|
||
Ces modèles :
|
||
|
||
- restent indépendants de `ksp-store-api` ;
|
||
- conservent les informations raw/provenance nécessaires ;
|
||
- ne réalisent aucun décodage métier/protocolaire ;
|
||
- doivent être facilement et explicitement convertibles par `ksp-worker-raw-retriever` vers les modèles raw persistants de `ksp-store-api`.
|
||
|
||
Les principes de cette frontière sont désormais fixés : transport et Store restent indépendants, et la conversion explicite transport -> D1 appartient au pipeline/composant de composition. Les DTO exacts seront définis avec les premières implémentations Transport/Store.
|
||
|
||
## Transport off-chain
|
||
|
||
Aucune crate `ksp-offchain-transport-api` ni trait global `OffchainTransport` n'est prévu.
|
||
|
||
`ksp-offchain-transport-lib` regroupe volontairement des accès hétérogènes afin d'éviter une explosion de petites crates. Metadata externes, quotes, prix hors blockchain ou routage peuvent conserver des APIs/modules spécialisés à l'intérieur de cette crate sans prétendre partager une abstraction métier commune.
|
||
|
||
## Wallet
|
||
|
||
Aucune crate `ksp-wallet-api` n'est prévue.
|
||
|
||
`ksp-wallet-lib` est propriétaire du format wallet KSP, des opérations de protection/import/export et de l'accès contrôlé aux capacités pubkey/secret/signature nécessaires aux couches supérieures.
|
||
|
||
Les applications futures utilisant ce wallet restent des consommateurs de `ksp-wallet-lib`, pas des implémentations alternatives du contrat wallet.
|
||
|
||
## Workers
|
||
|
||
### `ksp-worker-api`
|
||
|
||
`ksp-worker-api` est une **lifecycle API de services continus**.
|
||
|
||
Elle pourra porter des contrats communs comme identité, état, health, start/stop/shutdown et événements de lifecycle. Une capacité optionnelle comme la reconfiguration à chaud ne doit devenir universelle que si plusieurs workers la partagent réellement.
|
||
|
||
Elle ne contient aucun concept de progression/checkpoint terminal propre aux jobs.
|
||
|
||
### `ksp-worker-control-lib`
|
||
|
||
`ksp-worker-control-lib` est une implémentation réutilisable de gouvernance au-dessus de `ksp-worker-api`.
|
||
|
||
Elle doit pouvoir être consommée par :
|
||
|
||
- une application desktop manager spécialisée ;
|
||
- une future application globale ;
|
||
- un éventuel orchestrateur commun si un besoin opérationnel concret le justifie ;
|
||
- des tools/tests lorsque pertinent.
|
||
|
||
Les applications restent des interfaces et ne réimplémentent pas elles-mêmes registre, dispatch start/stop, agrégation d'état ou reconfiguration générique.
|
||
|
||
### Packaging des workers
|
||
|
||
Chaque package `ksp-worker-<role>` doit pouvoir fournir :
|
||
|
||
```text
|
||
library target
|
||
-> logique/runtime service réutilisable
|
||
|
||
binary target
|
||
-> bootstrap autonome mince
|
||
```
|
||
|
||
Cette direction permet de tester/réutiliser la logique sans perdre la propriété « service indépendant ».
|
||
|
||
Le binaire autonome n'est pas une seconde implémentation du worker.
|
||
|
||
### Workers de processing
|
||
|
||
Le modèle initial d'un unique W2 est remplacé par une chaîne de responsabilités plus étroites :
|
||
|
||
```text
|
||
raw persisted
|
||
|
|
||
v
|
||
ksp-worker-core-processor
|
||
|
|
||
v
|
||
canonical Core
|
||
|
|
||
v
|
||
ksp-worker-generic-materializer
|
||
|
|
||
v
|
||
generic materialization/journal
|
||
|
|
||
v
|
||
ksp-worker-domain-projector
|
||
|
|
||
v
|
||
domain projections
|
||
```
|
||
|
||
Le nom `ksp-worker-domain-projector` est explicitement provisoire jusqu'à ce que les contrats de matérialisation spécialisée soient définis.
|
||
|
||
## Jobs
|
||
|
||
`ksp-job-api` est une **lifecycle API de travaux déclenchés et terminables**.
|
||
|
||
Elle peut porter identité, état, progression, cancel, résultat et, lorsque pertinent, pause/resume/checkpoint.
|
||
|
||
Aucune `ksp-job-control-lib` n'est prévue actuellement. Le fait que plusieurs jobs implémentent `ksp-job-api` suffit tant qu'aucune duplication concrète de gouvernance ne justifie une bibliothèque commune.
|
||
|
||
## Notifications de données
|
||
|
||
Les notifications de données restent indépendantes du lifecycle des workers et des jobs.
|
||
|
||
Le même type de donnée persistée doit produire le même contrat de notification quelle que soit son origine :
|
||
|
||
```text
|
||
worker live -----\
|
||
job backfill -----+--> même notification de donnée
|
||
import -----------/
|
||
```
|
||
|
||
`ksp-store-api` reste le propriétaire candidat de ces références/notifications lorsqu'elles signifient qu'une donnée persistée est disponible.
|
||
|
||
Le transport de notification reste distinct du contrat de donnée.
|
||
|
||
## Scénarios et demos
|
||
|
||
Aucune crate monolithique de scénarios n'est prévue.
|
||
|
||
Les scénarios vivent dans des crates spécialisées :
|
||
|
||
```text
|
||
ksp-scenario-memo-lib
|
||
ksp-scenario-token-lib
|
||
ksp-scenario-ata-lib
|
||
ksp-scenario-token-2022-lib
|
||
ksp-scenario-metadata-lib
|
||
ksp-scenario-spm-lib
|
||
...
|
||
```
|
||
|
||
`ksp-scenario-api` n'est pas retenu actuellement. La norme commune est documentée dans `docs/rules/SCENARIO_CONVENTION.md` et peut évoluer avec les premières implémentations.
|
||
|
||
Les applications de démonstration correspondantes suivent la forme :
|
||
|
||
```text
|
||
ksp-app-scenario-<domain>-<environment>-desk-demo
|
||
```
|
||
|
||
Exemples :
|
||
|
||
```text
|
||
ksp-app-scenario-memo-devnet-desk-demo
|
||
ksp-app-scenario-token-2022-devnet-desk-demo
|
||
ksp-app-scenario-metadata-devnet-desk-demo
|
||
```
|
||
|
||
Chaque application appelle la crate `ksp-scenario-<domain>-lib` correspondante et ne duplique pas son scénario. La crate scenario doit également pouvoir être appelée hors desktop.
|
||
|
||
## Applications spécialisées et control plane
|
||
|
||
Les applications spécialisées sont prioritaires sur une future application globale.
|
||
|
||
Une app worker spécialisée passe par `ksp-worker-control-lib` / `ksp-worker-api` et ne manipule pas directement l'état interne du worker dans le Store.
|
||
|
||
Le data plane est D1–D4. Le control plane porte start/stop/status/health/reconfigure et reste séparé des payloads de processing.
|
||
|
||
Les workers doivent être exploitables comme services autonomes. Le mécanisme IPC exact reste à définir à la première implémentation manager/service ; aucun `ksp-ipc-api` générique n'est créé maintenant.
|
||
|
||
Une future application globale est conservée dans `docs/IDEAS.md` seulement.
|
||
|
||
## Pipelines
|
||
|
||
`ksp-pipeline-lib` reste rejeté.
|
||
|
||
Le premier besoin concret de réutilisation est maintenant identifié : worker live et job de replay/backfill doivent partager la même logique d'une frontière durable.
|
||
|
||
Pipelines retenus :
|
||
|
||
```text
|
||
ksp-pipeline-raw-ingestion-lib
|
||
ksp-pipeline-core-processing-lib
|
||
ksp-pipeline-generic-materialization-lib
|
||
ksp-pipeline-domain-projection-lib
|
||
```
|
||
|
||
Les pipelines sont backend/implementation agnostic autant que possible : ils dépendent des APIs (`ksp-store-api`, `ksp-program-api`, `ksp-materializer-api`) et reçoivent les implémentations concrètes par composition depuis worker/job.
|
||
|
||
## Modèle opérationnel workers/jobs
|
||
|
||
Le backlog de processing est défini par les inputs applicables moins les processing outcomes terminaux du processor/version/capability cible.
|
||
|
||
L'absence d'output n'est pas une preuve d'absence de traitement.
|
||
|
||
KSP retient :
|
||
|
||
```text
|
||
notification wake-up + periodic polling
|
||
Store backlog = source de vérité
|
||
claim/lease = ownership temporaire
|
||
at-least-once + idempotence = sémantique de traitement
|
||
```
|
||
|
||
Le raw retriever expose une hot reconfiguration avec distinction desired/effective configuration.
|
||
|
||
Les jobs de replay restent distincts des workers continus et réutilisent les mêmes pipelines.
|
||
|
||
## Corrections issues de `pre.003`
|
||
|
||
Le graphe confirme les principes suivants :
|
||
|
||
- Program et Materializer restent indépendants du store et des I/O réseau ;
|
||
- `ksp-execution-policy-api` et `ksp-execution-lib` sont retenus ;
|
||
- `ksp-execution-lib` consomme `ksp-program-api`, pas l'implémentation officielle `ksp-program-lib` ;
|
||
- `ksp-materializer-api` peut dépendre de `ksp-program-api`, mais ni Materializer API/lib ni Store API/lib ne se dépendent mutuellement ;
|
||
- les workers/jobs spécialisés réalisent les conversions explicites entre modèles de transport, processing et persistence ;
|
||
- aucun `ksp-data-api` global n'est introduit ;
|
||
- `ksp-worker-control-lib` est retenu comme gouvernance workers réutilisable ; aucune `ksp-job-control-lib` n'est retenue.
|
||
|
||
## Questions restantes après la fondation
|
||
|
||
- types Rust exacts des contrats ouverts de `ksp-program-api` ;
|
||
- DTO exacts des modèles transport et D1/D2/D3/D4 avec les premières implémentations concernées ;
|
||
- schémas SQL, indexes, claims/leases et pagination du Store PostgreSQL ;
|
||
- première implémentation manager/service : mécanisme IPC et proxy distant Worker ;
|
||
- contexte requis par les projectors stateful ;
|
||
- futur : orchestrateur commun seulement si un besoin opérationnel concret le justifie ; l'application globale reste un produit futur après validation des apps spécialisées.
|