Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.0.3-pre.003

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-14 08:57:39 +02:00
parent bb69cbd557
commit 544e0351b8
12 changed files with 1033 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
docs/architecture/004-COMPONENT_INVENTORY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Inventaire initial des composants KSP
@@ -9,7 +9,7 @@ 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é ?**
Il ne fige pas encore le graphe exact des dépendances. `0.0.3-pre.003` doit explicitement pouvoir corriger cet inventaire lorsque l'étude des dépendances montre qu'une API, une bibliothèque ou une frontière doit être déplacée, séparée ou supprimée.
Le premier inventaire a été produit en `0.0.3-pre.002`. `0.0.3-pre.003` l'a corrigé à partir du graphe formalisé dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md). Les détails internes des APIs restent toutefois révisables dans les prereleases spécialisées suivantes.
## Statuts
@@ -21,40 +21,40 @@ Il ne fige pas encore le graphe exact des dépendances. `0.0.3-pre.003` doit exp
## 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` | logging/tracing commun |
| 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 decoder/executor et types associés |
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés |
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Candidat fort | `0.2.x–0.4.x` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution |
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Candidat fort | `0.2.x–0.4.x` | orchestration spécialisée entre opération préparée, policy, wallet et transport |
| 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 | Candidat fort | `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 |
| 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` | logging/tracing commun |
| 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 decoder/executor et types associés |
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés |
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | `0.2.x+` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution |
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | orchestration spécialisée entre opération préparée, policy, wallet et transport ; dépend de `ksp-program-api`, pas de `ksp-program-lib` |
| 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
@@ -77,7 +77,7 @@ Aucune API commune worker+job n'est prévue.
## Execution policy et orchestration
### Direction retenue pour étude en `pre.003`
### Direction retenue après `pre.003`
La direction privilégiée est une orchestration supérieure plutôt qu'une dépendance directe de `ksp-program-lib` vers le wallet et le transport :
@@ -106,7 +106,7 @@ Une application UI ne doit pas enfouir cette logique dans ses commandes ou compo
Aucune `ksp-execution-policy-lib` générique n'est retenue actuellement. Des implémentations réutilisables pourront être créées plus tard si plusieurs consommateurs partagent réellement la même politique.
Le graphe exact `ksp-execution-lib -> ksp-program-api` ou `ksp-program-lib`, ainsi que la forme des plans/opérations préparées, est explicitement reporté à `pre.003/pre.004`.
`ksp-execution-lib` dépend de `ksp-program-api` et non de `ksp-program-lib`. La forme exacte des plans/opérations préparées et le mécanisme d'injection/appel sont reportés à `pre.004`.
## Transport on-chain
@@ -260,12 +260,22 @@ Chaque application appelle la crate `ksp-scenario-<domain>-lib` correspondante e
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.
## Questions explicitement reportées à `pre.003`
## Corrections issues de `pre.003`
- dépendance exacte de `ksp-execution-lib` vers `ksp-program-api` et/ou `ksp-program-lib` ;
- forme du contrat entre program preparation, execution policy, wallet et transport ;
- emplacement exact des modèles communs nécessaires à l'exécution ;
- types publics de transport on-chain et conversion vers les DTO raw de `ksp-store-api` ;
- dépendances autorisées de `ksp-materializer-api` et `ksp-store-api` ;
- risque de cycles entre program, materializer, store, execution et control ;
- position exacte des notifications de données dans le graphe.
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.