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

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

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 :

kb_sol_<domain>_<name>

Exemples :

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.

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.

4.5 KiB Raw Blame History Unescape Escape