# 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--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-` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques | | Scenarios | `ksp-scenario--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---desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante | | Specialized pipelines | `ksp-pipeline--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---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--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.