154 lines
10 KiB
Markdown
154 lines
10 KiB
Markdown
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
|
<!-- version: 7 -->
|
|
|
|
# Inventaire initial des composants KSP
|
|
|
|
## Objet
|
|
|
|
Ce document maintient l'inventaire synthétique des composants retenus ou pressentis. Les numéros de release précis restent soumis au sizing de chaque session.
|
|
|
|
## Statuts
|
|
|
|
- `Stable` — implémenté et publié ;
|
|
- `Retenu` — composant/contrat décidé ;
|
|
- `Pressenti` — direction décidée mais périmètre exact à confirmer ;
|
|
- `À la demande` — créé seulement au premier besoin réel ;
|
|
- `Non retenu` — explicitement écarté pour l'instant.
|
|
|
|
## Inventaire synthétique
|
|
|
|
| Domaine | Composant | Type | Statut | Première cible actuelle | Mission |
|
|
|-------------------------|------------------------------------------|--------------------|--------------|---------------------------------|----------------------------------------------------------|
|
|
| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales |
|
|
| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP |
|
|
| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config |
|
|
| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config |
|
|
| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.1` | JSON-RPC HTTP complet, settings, pools, rôles |
|
|
| Wallet | `ksp-wallet-lib` | lib | Retenu | `0.2.5` | `.kspwallet`, secrets, signature, import/export |
|
|
| Wallet Desk | `ksp-app-wallet-desk` | app | Retenu | `0.2.6` | Wallet + Config composite + HTTP/balance |
|
|
| Standard WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.7` | WebSocket Solana complet, sessions/subscriptions |
|
|
| Helius WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.8` | LaserStream WebSocket comme extension du moteur standard |
|
|
| Yellowstone | `ksp-onchain-transport-lib` | lib | Pressenti | `0.2.9` | client gRPC standard/provider-neutral |
|
|
| Off-chain price | `ksp-offchain-transport-lib` | lib | Retenu | `0.2.10` | première abstraction/provider de prix SOL/USD, SOL/EUR |
|
|
| Price Desk | nom à fixer | app | Retenu | `0.2.11` | visualisation/validation des prix |
|
|
| Wire | `ksp-interface-lib` | lib | Retenu | `0.2.12` | façade wire officielle + API publique wire |
|
|
| Program API | `ksp-program-api` | API | Retenu | `0.2.13` | contrats extensibles Program |
|
|
| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles |
|
|
| Program extension | `ksp-program-<name>-lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` |
|
|
| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | contrats persistence backend-agnostic, RAW d'abord |
|
|
| Store PostgreSQL | `ksp-store-lib` | lib | Retenu | `0.3.1` | backend PostgreSQL officiel, RAW d'abord |
|
|
| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.3` | lifecycle des jobs terminables |
|
|
| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.3` | acquisition historique vers RAW |
|
|
| Backfill Desk | nom à fixer | app | Retenu | `0.3.4` | contrôle/inspection du backfill RAW |
|
|
| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus |
|
|
| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW |
|
|
| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE |
|
|
| CORE worker | nom à fixer | worker | Retenu | fin couche CORE | backlog RAW -> CORE continu |
|
|
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation |
|
|
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes |
|
|
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
|
|
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
|
|
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
|
|
| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun |
|
|
| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC |
|
|
| Trading Intelligence | noms à définir | libs/jobs | Futur | après données stables | features/signaux/anomalies/ML |
|
|
|
|
## Contrats séparés retenus
|
|
|
|
```text
|
|
ksp-program-api
|
|
ksp-materializer-api
|
|
ksp-store-api
|
|
ksp-worker-api
|
|
ksp-job-api
|
|
ksp-execution-policy-api
|
|
```
|
|
|
|
Pas de crates séparées actuellement pour :
|
|
|
|
```text
|
|
ksp-interface-api
|
|
ksp-wallet-api
|
|
ksp-onchain-transport-api
|
|
ksp-offchain-transport-api
|
|
ksp-scenario-api
|
|
ksp-job-control-lib
|
|
ksp-data-api
|
|
```
|
|
|
|
## Transport
|
|
|
|
`ksp-onchain-transport-lib` doit couvrir l'intégralité des opérations documentées de la surface ciblée par chaque release. Les statuts deprecated/obsolete encore fonctionnels et unstable/experimental restent exposés avec warning runtime KSP.
|
|
|
|
La Config standard Transport appartient à `ksp-config-lib`, qui adapte vers les settings publics du transport ; le transport ne dépend jamais de Config.
|
|
|
|
Les WebSockets supportent plusieurs sessions pour un même endpoint URL, mais un pool/scheduler automatique n'est créé qu'après besoin démontré.
|
|
|
|
Les providers Yellowstone spécifiques restent des extensions futures ; le contrat standard est provider-neutral.
|
|
|
|
## Wallet
|
|
|
|
Le format natif est `.kspwallet`.
|
|
|
|
Les anciens temporary wallets JSON ne sont pas migrés.
|
|
|
|
`WalletPolicy` est exclu du Wallet et relève de l'execution policy.
|
|
|
|
Import/export reste extensible ; les formats supplémentaires sont suivis dans `docs/IDEAS.md`.
|
|
|
|
## Data plane
|
|
|
|
```text
|
|
RAW -> CORE -> DECODE -> SPECIALIZED
|
|
```
|
|
|
|
- RAW : acquisition replayable ;
|
|
- CORE : normalisation blockchain générique sans decoder Program ;
|
|
- DECODE : interpretation Program + matérialisation générique/journal ;
|
|
- SPECIALIZED : projections queryables de domaine.
|
|
|
|
## Progression des processors
|
|
|
|
RAW et CORE sont complétés couche par couche avec jobs/workers/apps utiles.
|
|
|
|
À partir de DECODE, progression verticale par groupe :
|
|
|
|
```text
|
|
wire -> decode -> materialize -> specialized -> prepare -> policy -> execute -> scenario
|
|
```
|
|
|
|
Groupes prioritaires :
|
|
|
|
```text
|
|
Solana Core Programs
|
|
SPL token/trading
|
|
token metadata
|
|
Anchor
|
|
Meteora
|
|
Raydium
|
|
Pump
|
|
Orca
|
|
Market Desk V1
|
|
Jupiter/OKX routing
|
|
Market Desk V2
|
|
trading-adjacent
|
|
general decoding
|
|
```
|
|
|
|
Meteora vaults, Pump fees et autres satellites nécessaires restent dans leur groupe.
|
|
|
|
## Applications spécialisées
|
|
|
|
Les applications servent de validations/exploitations réelles sans absorber la logique des bibliothèques.
|
|
|
|
Market Desk est progressive : V1 après les DEX prioritaires, puis enrichissement routing après Jupiter/OKX.
|
|
|
|
## Questions restantes
|
|
|
|
- noms exacts de Price Desk et Backfill Desk ;
|
|
- surface exacte Yellowstone après audit normatif de `0.2.9-pre.001` ;
|
|
- nécessité future d'un pool automatique WS ;
|
|
- types exacts `ksp-program-api`/`ksp-materializer-api`/`ksp-store-api` ;
|
|
- nom/packaging précis du premier RAW worker et du CORE normalizer ;
|
|
- granularité des workers DECODE/SPECIALIZED par groupe.
|