Architecture générale

1. Vue d’ensemble

Le workspace est organisé en couches orientées responsabilités :

configuration ─────┐
logging ───────────┼──────────────┐
program IDs ───────┘              │
                                  v
transport -> store -> pipeline -> ks-lib
                         │          │
                         v          v
                 demo scenarios   wallet/signers
                         │          │
                         └────┬─────┘
                              v
                    desktop demo application

Cette représentation indique les relations dominantes. Elle ne remplace pas le graphe exact des dépendances Cargo.

2. Couches

2.1 Fondations

ks-core fournit les erreurs et identités transversales minimales.
ks-config charge, résout et valide la configuration.
ks-logging initialise le logging et le tracing.
ks-program-ids centralise les identifiants de programmes et comptes connus.

2.2 Noyau métier

ks-lib contient quatre familles principales :

modèles et contrats partagés ;
décodeurs ;
exécuteurs ;
matérialisateurs.

La façade publique est constituée par les réexports de ks-lib/src/lib.rs. Les modules internes conservent leurs frontières et leurs conventions de nommage.

2.3 Acquisition et stockage

ks-onchain-transport fournit les clients HTTP/WebSocket, pools, rôles d’endpoints, méthodes RPC standard et contrats liés à l’exécution RPC.
ks-store regroupe les contrats store-neutral et l’implémentation PostgreSQL.

Les transports n’effectuent pas la matérialisation métier. Le stockage ne décide pas quelle surface protocolaire doit être décodée.

2.4 Orchestration

ks-pipeline orchestre :

backfill ;
extraction Core ;
replay de décodage ;
matérialisation ;
corrélation stateful ;
préflight et orchestration d’exécution pour les surfaces prises en charge.

Il dépend des contrats de ks-lib, des données de ks-store et des capacités de ks-onchain-transport sans absorber leurs responsabilités.

2.5 Démonstrations et applications

ks-pipeline-demo-scenarios fournit les fixtures et campagnes réseau réutilisables spécifiques aux validations Devnet/Testnet. Les scénarios réutilisables doivent être appelables sans dépendre du desktop.
Le binaire ks-pipeline-demo-scenarios-cli reste un outil ciblé ; son existence n’impose pas d’exposer chaque scénario par un CLI.
kb-app-demo-desktop est une crate mixte : bibliothèque Tauri et binaire desktop. Les commandes et projections UI y restent, tandis que la logique de scénario réutilisable doit être déléguée à ks-pipeline-demo-scenarios. Le reliquat éventuel de scénarios encore déclarés directement dans le desktop sera audité en 0.5.4.
ks-wallet fournit actuellement une frontière limitée de wallet temporaire et de signataire. Elle devient ks-wallet en 0.5.1, puis sa restructuration fonctionnelle est planifiée en 0.5.2.

3. Flux principal de données

Solana RPC / WebSocket
        │
        v
ks-onchain-transport
        │
        v
ks-store (données brutes/canoniques)
        │
        v
ks-pipeline
        │
        ├── extraction Core
        ├── sélection des décodeurs
        ├── décodage via ks-lib
        ├── matérialisation via ks-lib
        └── stockage des résultats

L’exécution suit un flux séparé : intention typée, construction, préflight, simulation, confirmation opérateur, envoi, confirmation et validation postérieure lorsque la surface le permet.

4. Frontières obligatoires

Les IDs canoniques ne doivent pas être dispersés lorsqu’ils appartiennent au registre de ks-program-ids.
Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par ks-lib.
Les commandes Tauri et payloads frontend spécifiques restent dans kb-app-demo-desktop.
Les scénarios réseau réutilisables spécifiques à Devnet/Testnet appartiennent à ks-pipeline-demo-scenarios, future ks-pipeline-demo-scenarios. kb-app-demo-desktop doit se limiter à l’adaptation Tauri, aux payloads UI, à la présentation et à l’appel de ces scénarios ; les doublons résiduels seront réconciliés en 0.5.4.
Toute primitive ou orchestration réellement généraliste, indépendante de l’UI et d’une campagne de démonstration précise, appartient à ks-pipeline ou à la crate métier propriétaire.
Les fixtures contractuelles communes restent sous test-fixtures/contract-matrices/ lorsqu’elles sont consommées par plusieurs tests.
Les archives documentaires ne participent ni au build ni aux décisions normatives.

5. État de migration

La migration bot2 vers bot3 est close pour le périmètre fonctionnel repris jusqu’à 0.4.7. La version 0.4.8 complète ensuite la fondation Metadata on-chain en distinguant Solana Program Metadata, Token-2022 Token Metadata et Metaplex Token Metadata, avec leurs décodeurs, matérialisateurs, exécuteurs lorsque applicables, orchestration stateful, scénarios réutilisables et intégration desktop.

La série 0.5.x ne vise pas à étendre immédiatement la couverture protocolaire : elle migre d’abord les bibliothèques vers ks-*, puis stabilise ks-config, ks-wallet, ks-store et les frontières de scénarios afin d’éviter de devoir casser ces fondations après l’arrivée des protocoles trading. 0.6.x introduira ensuite le décodeur Anchor générique avant la séquence Meteora/Raydium/Pump/Orca/Jupiter.

5.7 KiB Raw Blame History Unescape Escape