0.1.0

2026-07-23 16:37:12 +02:00
parent 99c345f2f2
commit 0da75c1311
2159 changed files with 230833 additions and 0 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,108 @@
+<!-- file: docs/ARCHITECTURE.md -->
+<!-- version: 7 -->
+
+# Architecture
+
+L'architecture cible est organisée en couches strictes afin d'éviter de recréer un monolithe. Les noms `raw`, `core`, `obs`, `decode`, `mat`, `agg` et `ops` désignent des couches logiques, pas des schémas PostgreSQL applicatifs.
+
+## Chaîne principale
+
+```text
+sources RPC HTTP / WebSocket / gRPC
+  -> kb_rpc
+    -> kb_model transaction canonique
+      -> raw
+        -> core
+          -> obs
+            -> decode
+              -> mat
+                -> agg
+                  -> strategy
+                    -> execution
+
+sources historiques déjà indexées
+  -> kb_external_sources
+    -> candidats de signatures
+      -> kb_pipeline
+        -> hydratation canonique via kb_rpc
+```
+
+## Responsabilités
+
+- `kb_rpc` gère les méthodes et flux RPC Solana : JSON-RPC HTTP, WebSocket, Helius/LaserStream et Yellowstone gRPC lorsque ces surfaces seront activées.
+- `kb_external_sources` est une crate future réservée aux APIs REST, exports et imports historiques externes, par exemple Solscan Pro ou un CSV officiel. Elle ne produit jamais directement une transaction canonique et ne doit pas être confondue avec un futur index interne PostgreSQL.
+- `kb_pipeline` combine la découverte de signatures par `kb_rpc` ou `kb_external_sources` avec l’hydratation canonique par `kb_rpc`.
+- `kb_model` définit la transaction Solana canonique indépendante du fournisseur.
+- `raw` conserve une transaction canonique unique et rejouable par signature.
+- `obs` conserve les observations techniques de source, programme, instruction et discriminator.
+- `core` expose les structures Solana normalisées pour les décodeurs.
+- `decode` contient les événements protocolairement compris.
+- `mat` contient les projections métier.
+- `agg` contient les agrégations temporelles ou analytiques.
+- `ops` trace les modules, versions et traitements.
+
+## Acquisition multi-source
+
+```text
+getTransaction JSON-RPC
+transactionSubscribe Helius
+Yellowstone gRPC
+logsSubscribe + hydration
+        |
+        v
+transaction canonique identique
+```
+
+Les détails de fournisseur restent dans `kb_sol_obs_transaction_observations`. Ils ne contaminent pas les décodeurs ni les tables core.
+
+`kb_rpc` ne doit pas être renommée en `kb_com` ou `kb_transport` pour accueillir des sources historiques externes. Ces noms seraient trop génériques et mélangeraient RPC Solana, APIs REST indexées, imports CSV et orchestration métier. Le nom `kb_external_sources` évite la confusion avec l’indexation locale et décrit explicitement une frontière de fournisseurs externes plutôt qu’une simple action de récupération. Si des primitives HTTP réellement communes apparaissent plus tard, elles pourront être extraites dans une crate technique dédiée sans modifier la frontière fonctionnelle entre `kb_rpc` et `kb_external_sources`.
+
+## Convention DB associée
+
+Quand une couche logique devient une table Solana PostgreSQL, elle est encodée dans le nom de table :
+
+```text
+kb_sol_<domain>_<name>
+```
+
+Exemples :
+
+```text
+kb_sol_raw_transactions
+kb_sol_obs_transaction_observations
+kb_sol_core_transactions
+kb_sol_obs_program_observations
+kb_sol_decode_decoded_events
+kb_sol_mat_trade_events
+kb_sol_ops_processing_ledger
+```
+
+Les formes qualifiées héritées, écrites ici avec `DOT` (`raw DOT sol_transactions`, `core DOT sol_instructions`, `obs DOT program_observations`), sont interdites.
+
+## Frontières interdites
+
+- Un décodeur ne dépend pas du store concret.
+- Un décodeur ne dépend pas du fournisseur ou du transport d’acquisition.
+- Un matérialisateur ne dépend pas du RPC.
+- Le wallet ne dépend pas des décodeurs.
+- L'application de démonstration ne doit pas contourner les APIs de pipeline.
+- Une observation de source ne doit pas dupliquer le payload canonique complet.
+
+## Frontière extraction canonique vers core
+
+Depuis `0.3.4`, `kb_pipeline` contient un extracteur pur qui dépend de `kb_model` et des contrats `kb_store_core`, mais pas de PostgreSQL ni de Tauri. `kb_store_pg` implémente la transaction atomique et `kb_app_demo` ne fait qu’orchestrer la requête opérateur.
+
+```text
+kb_model::CanonicalTransaction
+        |
+        v
+kb_pipeline::core_extraction
+        | CoreExtractionBundle
+        v
+kb_store_core::CoreExtractionStore
+        |
+        v
+kb_store_pg::PostgresStore
+```
+
+Les futurs décodeurs consommeront les inputs core contextualisés ; ils ne reliront pas directement le JSON canonique pour reconstruire les comptes, CPI, logs ou balances.