0.1.0

docs/LIVE_SOURCE_STRATEGY.md

@@ -0,0 +1,104 @@
+<!-- file: docs/LIVE_SOURCE_STRATEGY.md -->
+<!-- version: 3 -->
+
+# Stratégie des sources de transactions
+
+## Décision actuelle
+
+Les sources temps réel payantes ne sont plus l’axe actif de `0.3.x`.
+
+La priorité est :
+
+```text
+backfills HTTP sur comptes gratuits
+  -> transaction canonique
+    -> extraction core
+      -> décodeurs Core/Pump/Meteora/Raydium/Orca/Jupiter
+```
+
+Helius Developer, Triton, Chainstack, Shyft ou un autre provider seront testés seulement lorsque le pipeline pourra décoder et matérialiser immédiatement les transactions reçues.
+
+## Sources futures
+
+### HTTP JSON-RPC
+
+Usage :
+
+- backfill historique ;
+- hydratation de signatures ;
+- réparation ;
+- validation ponctuelle.
+
+Méthodes principales :
+
+```text
+getSignaturesForAddress
+getTransaction
+getSignatureStatuses
+getSlot
+```
+
+### Helius WebSocket enrichi
+
+`transactionSubscribe` est une extension Helius, pas une méthode Solana standard.
+
+Elle sera implémentée dans des modules internes de `kb_rpc`, sans créer de crate séparée, puis convertie vers le modèle canonique commun.
+
+### Yellowstone gRPC
+
+Yellowstone fournit l’équivalent fonctionnel d’un flux de transactions complètes filtrées. Les endpoints Triton, Chainstack, Shyft ou compatibles doivent être supportés par configuration dans `kb_rpc`.
+
+### Solana WebSocket standard
+
+`logsSubscribe` par mention ou avec filtre `"all"` reste une solution de probe, de fallback ou de comparaison. Une notification de logs ne devient durable qu’après hydratation de la transaction ou enregistrement d’une observation technique légère.
+
+## Stockage commun
+
+Toutes les sources convergent vers :
+
+```text
+kb_sol_raw_transactions
+kb_sol_obs_transaction_observations
+```
+
+Les décodeurs ne connaissent ni le fournisseur, ni le protocole, ni la méthode d’acquisition.
+
+## Ordre de mise en œuvre
+
+```text
+0.3.x  transaction canonique, observations, backfill gratuit, extraction core
+0.4.x  décodeurs Core/SPL
+0.5.x  Pump
+0.6.x  Meteora
+0.7.x  Raydium
+0.8.x  Orca
+0.9.x  Jupiter et routeurs
+0.10.x Helius transactionSubscribe, Yellowstone gRPC et comparaison
+```
+
+## Sécurité de reprise
+
+Pendant toute perte du flux principal :
+
+```text
+trading = disabled
+```
+
+Le replay ou le backfill après reconnexion sert à remettre la base en cohérence. Un événement `replayed`, `backfilled` ou `repaired` ne doit pas déclencher rétroactivement un ordre.
+
+## Critères de choix futur
+
+La décision provider devra comparer :
+
+- couverture par programme et CPI ;
+- latence par signature ;
+- coût par Go, crédit ou forfait ;
+- nombre de filtres et streams ;
+- régions ;
+- reconnexion et fenêtre de replay ;
+- pertes et backpressure ;
+- portabilité du protocole ;
+- qualité du support.
+
+Les timings seront mesurés dans `kb_sol_obs_transaction_observations`.
+