279 lines
21 KiB
Markdown
279 lines
21 KiB
Markdown
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
|
<!-- version: 4 -->
|
|
|
|
# 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). 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.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
|
|
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées |
|
|
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | façade unique `tracing`/appender/subscriber, initialisation et logging structuré KSP ; peut dépendre de core pour Error/Result |
|
|
| 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 |
|
|
| 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 des workers pour managers/apps/orchestrateur |
|
|
| 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 |
|
|
| 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 |
|
|
| Specialized pipelines | `ksp-pipeline-<role>-lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale |
|
|
| 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`.
|
|
|
|
Le détail de cette frontière de conversion est reporté à `pre.003/pre.005`.
|
|
|
|
## 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 futur orchestrateur ;
|
|
- 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.
|
|
|
|
### 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. Une **norme de structure/comportement** commune est préférée à un trait Rust susceptible de limiter des scénarios dont les besoins sont différents. Cette décision pourra être revue si les premières implémentations montrent un vrai contrat commun utile.
|
|
|
|
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.
|
|
|
|
## Pipelines
|
|
|
|
`ksp-pipeline-lib` reste rejeté.
|
|
|
|
Des pipelines spécialisés peuvent être créés à la demande lorsqu'un flux concret possède assez de logique réutilisable pour justifier sa propre frontière. Leur forme n'est pas nécessairement une bibliothèque : certains pourront être workers, jobs ou composants spécialisés.
|
|
|
|
## 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 reportées aux prereleases suivantes
|
|
|
|
- `pre.004` : forme exacte du contrat entre program preparation, execution policy, wallet et transport ;
|
|
- `pre.004` : types publics précis de `ksp-program-api` et policy ;
|
|
- `pre.005` : types publics de transport on-chain et conversion vers les DTO raw de `ksp-store-api` ;
|
|
- `pre.005` : modèles materializer/store, notifications, replay et provenance ;
|
|
- `pre.006` : managers/apps/processus/IPC, norme des scenarios et orchestrateur futur.
|