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 -> kb-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

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

2.2 Noyau métier

kb-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 kb-lib/src/lib.rs. Les modules internes conservent leurs frontières et leurs conventions de nommage.

2.3 Acquisition et stockage

kb-onchain-transport fournit les clients HTTP/WebSocket, pools, rôles d’endpoints, méthodes RPC standard et contrats liés à l’exécution RPC.
kb-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

kb-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 kb-lib, des données de kb-store et des capacités de kb-onchain-transport sans absorber leurs responsabilités.

2.5 Démonstrations et applications

kb-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 kb-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 à kb-pipeline-demo-scenarios. Le reliquat éventuel de scénarios encore déclarés directement dans le desktop sera audité en 0.5.4.
kb-wallet fournit actuellement une frontière limitée de wallet temporaire et de signataire. Sa restructuration est planifiée en 0.5.2.

3. Flux principal de données

Solana RPC / WebSocket
        │
        v
kb-onchain-transport
        │
        v
kb-store (données brutes/canoniques)
        │
        v
kb-pipeline
        │
        ├── extraction Core
        ├── sélection des décodeurs
        ├── décodage via kb-lib
        ├── matérialisation via kb-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 kb-program-ids.
Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par kb-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 à kb-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 à kb-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 stabilise d’abord kb-config, kb-wallet, kb-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.6 KiB Raw Blame History Unescape Escape