khadhroony-bobobot/README.md

khadhroony-bobobot

khadhroony-bobobot est un workspace Rust destiné à la détection, au décodage, à l’analyse et, à terme, au trading semi-automatisé de tokens Solana.

Le README précédent décrivait surtout l’état 0.3.1. Ce fichier reflète l’état de clôture documentaire 0.7.42 : le socle transport HTTP/WS, la résolution transactionnelle, le modèle SQLite, plusieurs connecteurs DEX, les candles, les signaux analytiques, la validation locale, la matrice DEX commune, Demo3, le backfill par signature et la consolidation Raydium DEX-first existent déjà. La famille Raydium est maintenant couverte sur swaps effectifs et premiers événements non-trade prouvés ; les non-swaps AMM v4 legacy restent conservés en audit, et le cas Orca Whirlpools est reporté à 0.7.44.

1. Objectif

L’objectif opérationnel est de construire progressivement une application capable de :

• détecter l’apparition de nouveaux tokens, pools, paires et listings sur Solana ;
• identifier en priorité les DEX effectifs sur lesquels les swaps, liquidités et événements de marché sont réellement exécutés ;
• décoder les transactions pertinentes des DEX ciblés, puis seulement ensuite les launch surfaces et origines de mint/lancement ;
• séparer les swaps/candles des événements utiles seulement à l’analyse : liquidité, cycle de vie de pool, fees, rewards, administration, wallets observés ;
• produire des métriques exploitables : prix, volume, candles/OHLCV, activité, bursts, déséquilibres buy/sell, signaux analytiques ;
• préparer ensuite des règles déterministes de filtrage, d’achat, de vente, de stop-loss et de trailing stop ;
• conserver une traçabilité locale suffisante pour rejouer, diagnostiquer et améliorer les décodeurs.

Le but court terme n’est pas encore le live trading. Le but court terme est de fiabiliser le décodage multi-DEX et la matérialisation des objets métier nécessaires au trading.

2. Workspace

Le workspace contient deux crates principales.

Crate	Rôle
kb_lib	Bibliothèque métier : configuration, tracing, clients réseau, pool HTTP, manager WS, résolution transactionnelle, décodage DEX, détection métier, persistance SQLite, backfill, metadata, candles, signaux analytiques.
kb_demo_app	Application Tauri V2 de démonstration et d’inspection : fenêtres Demo Ws, Demo Ws Manager, Demo Http, Demo Pipeline, Demo Pipeline 2, graphiques candles et commandes de backfill/replay.

La logique métier doit rester dans kb_lib. kb_demo_app doit rester une façade UI/Tauri et ne doit pas récupérer de logique Solana ou DEX profonde.

3. État actuel après 0.7.42

3.1. Socle stabilisé à ne pas refactorer maintenant

Ces éléments fonctionnent et ne sont pas bloquants pour les DEX. Ils ne doivent pas être remaniés dans la phase immédiate :

• ws_client.rs ;
• ws_manager.rs ;
• http_client.rs ;
• http_pool.rs ;
• couches JSON-RPC WS/HTTP déjà stabilisées ;
• orchestration réseau utilisée par les fenêtres de démonstration.

Ils pourront être améliorés plus tard, mais la priorité actuelle est le décodage DEX, les événements métier et les tables d’analyse.

3.2. Pipeline métier existant

Le pipeline 0.7.x couvre déjà les étapes suivantes :

1. réception d’observations via RPC WS ou backfill HTTP ;
2. résolution des transactions via HTTP RPC ;
3. projection transactionnelle normalisée en base ;
4. décodage DEX dans k_sol_dex_decoded_events ;
5. détection métier vers tokens, pools, paires, listings, origins et wallets observés ;
6. matérialisation des trades exploitables ;
7. agrégation pair metrics ;
8. génération candles/OHLCV ;
9. signaux analytiques simples ;
10. inspection via l’application de démonstration.

3.3. Connecteurs validés ou observés via l’application de démo

Les connecteurs suivants sont les surfaces actuellement les plus importantes pour la validation locale :

• pump_fun comme surface de launch / mint initial ;
• pump_swap pour les swaps post-migration Pump ;
• raydium_cpmm : swaps swap_base_input / swap_base_output, lifecycle initialize, liquidity withdraw et collect_creator_fee sur corpus prouvé ;
• raydium_clmm : swaps swap_v2 et legacy swap, liquidité/positions increase_liquidity_v2, decrease_liquidity_v2, open_position_with_token22_nft, close_position sur corpus prouvé ;
• raydium_amm_v4 : swaps AMM v4 legacy 675kPX... matérialisés ; non-swaps legacy conservés en audit tant que le corpus ne permet pas une promotion fiable ;
• meteora_dlmm ;
• meteora_damm_v1, partiel : les swaps sans payload montant/prix exploitable restent conservés mais non actionnables ;
• meteora_damm_v2, observé dans le corpus 0.7.36, mais les swaps sans payload montant/prix exploitable sont maintenant non_actionable_trade ;
• meteora_dbc, observé dans le corpus 0.7.36, mais les swaps sans payload montant/prix exploitable sont maintenant non_actionable_trade.

3.4. Connecteurs à consolider par corpus en priorité DEX-first

Les modules ou surfaces suivantes existent, sont partiellement représentés dans le code ou doivent être recherchés, mais doivent être consolidés par corpus local, invariants et documentation avant de reprendre les launch surfaces :

• raydium_stable_swap ;
• orca_whirlpools ;
• fluxbeam ;
• dexlab ;
• meteora_damm_v1, meteora_damm_v2, meteora_dbc et meteora_dlmm pour la couverture non-trade complète ;
• metaDAO et printr, apparus comme DEX à vérifier côté sources externes de découverte ;
• tout DEX ou programme récurrent détecté dans k_sol_protocol_candidates, DEX Screener ou les transactions locales.

Les launch origins déjà amorcées (meteora_fun_launch, bags, moonit) et les launch surfaces enregistrables (raydium_launchlab, raydium_launchpad, letsbonk, bonk_fun, bags, moonshot, moonit, boop_fun, believe, heaven) sont conservées dans la documentation, mais elles ne sont plus prioritaires tant que les DEX effectifs ne sont pas suffisamment couverts.

3.5. Validation acquise en 0.7.36

La validation 0.7.36_meteora_family_consolidation est considérée comme réalisée lorsque les invariants suivants restent vrais après replay local :

• validationPassed = true ;
• diagnosticsClean = true ;
• blockingIssueCount = 0 ;
• decodedTradeCandidateWithoutTradeEventCount = 0 ;
• decodedTradeCandidateWithoutAmountPayloadCount = 0 ;
• missingTradeEventCount = 0 ;
• pairWithoutTradeCount = 0 pour les paires actionnables ;
• pairWithoutCandleCount = 0 pour les paires actionnables.

Point important : meteora_damm_v2 et meteora_dbc peuvent produire beaucoup d’événements swap décodés sans produire de trade_events lorsque les montants ou prix ne sont pas fiables. Ces événements doivent rester non_actionable_trade et ne doivent pas être comptés comme tradeCandidate ou candleCandidate.

4. Matrice DEX : DEX effectifs d’abord, launch surfaces ensuite

La distinction de travail à partir de 0.7.39 est la suivante :

• un DEX effectif est un programme ou une famille de programmes sur lesquels des swaps, pools, liquidités, fees, rewards, admin/config, burns ou mints utiles sont réellement observables ;
• une launch surface peut être la première source de mint ou de lancement, mais elle ne doit pas masquer la priorité donnée aux programmes où le swap final est exécuté ;
• pour le trading, le DEX effectif, la qualité de décodage du swap et les événements de pool sont prioritaires ; la launch origin reste une information de filtrage à réintroduire après stabilisation des DEX.

4.1. Matrice de travail

Depuis 0.7.29, la matrice de support DEX est portée par kb_lib/src/dex_support_matrix.rs. Elle centralise le code interne, la famille, la version, le type de surface, les program ids vérifiés localement, le statut de support, les capacités actuelles et les raisons de skip.

Depuis 0.7.30, les événements décodés reçoivent aussi une classification plus fine : eventLifecycleKind, eventActionability et nonTradeUseful. Cette classification sert aux diagnostics et prépare la matérialisation future des événements non-trade sans alimenter directement les trades/candles.

Depuis 0.7.32, les diagnostics distinguent explicitement les gaps littéraux de catalogue (literalPairWithoutTradeCount, literalPairWithoutCandleCount) des gaps bloquants/actionnables (blockingPairWithoutTradeCount, blockingPairWithoutCandleCount). Les anciens champs pairWithoutTradeCount et pairWithoutCandleCount restent exposés comme alias de compatibilité pour les gaps bloquants/actionnables.

Depuis 0.7.33, les diagnostics ajoutent une classification pairTradingReadiness au niveau des paires et des résumés agrégés pairTradingReadinessSummaries. Cette classification sépare les paires directement lisibles/tradables contre WSOL ou stable, les paires inversées avec WSOL/stable en base, les paires cross-quote nécessitant un routeur/aggregator, les paires non matérialisées en trade et les cas de quote inconnue. Elle reste purement diagnostique : elle ne modifie ni le replay, ni les trade_events, ni les candles.

Code cible	Type	Priorité 0.7.39+	Prochaine action
pump_swap	AMM / swap	haute	conserver les invariants trade/candle et étendre les événements non-trade prouvés.
raydium_cpmm	AMM	haute	couvert pour swaps input/output, initialize, withdraw et collect_creator_fee prouvés ; poursuivre seulement sur nouveaux discriminators.
raydium_clmm	CLMM	haute	couvert pour swaps v2/legacy, increase/decrease liquidity et open/close position prouvés ; poursuivre seulement sur nouveaux discriminators.
raydium_amm_v4	AMM legacy	haute	swaps legacy couverts et matérialisés ; non-swaps AMM v4 conservés en audit, à compléter plus tard si corpus suffisant.
raydium_stable_swap	AMM legacy	moyenne	vérifier l’usage réel de 5quBtoiQqxF9Jv6KYKctB59NT3gtJD2Y65kdnB1Uev3h et ne l’activer qu’avec corpus.
meteora_dlmm	DLMM	haute	verrouiller swaps, positions, liquidité et lifecycle.
meteora_damm_v1	AMM legacy	haute	conserver le skip sans amounts exploitables et rechercher un corpus swap/liquidité exploitable.
meteora_damm_v2	AMM	haute	vérifier cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG, les swaps, les configs dynamiques et les événements non-trade.
meteora_dbc	bonding curve / DEX effectif partiel	haute	séparer ce qui relève du swap, du bonding curve et de la migration sans faux trade/candle.
orca_whirlpools	CLMM	haute	consolider par corpus fiable : create_pool, swap, liquidité/positions.
fluxbeam	AMM	moyenne	vérifier program id, corpus réel et instructions utiles.
dexlab	AMM	moyenne	vérifier program id, corpus réel, swaps et liens OpenBook éventuels.
metaDAO	DEX à vérifier	haute	rechercher le ou les program ids, corpus, comptes et types d’événements avant toute promotion.
printr	DEX à vérifier	haute	rechercher le ou les program ids, corpus, comptes et types d’événements avant toute promotion.
okx_dex	Aggregator/router	basse DEX direct	classifier sans matérialiser en trade direct avant preuve.
Launch surfaces (pump_fun, raydium_launchlab, raydium_launchpad, bags, letsbonk, bonk_fun, boop_fun, moonshot, moonit, believe, heaven)	Launch / origine	reportée	reprendre après consolidation des DEX effectifs ; aucun program_id fictif.
zora	À vérifier	hors priorité	ne pas intégrer avant preuve de programme Solana pertinent.

5. Base de données

SQLite reste le stockage local initial.

Organisation actuelle à conserver :

• kb_lib/src/db/schema.rs crée les tables et index ;
• chaque table/index est créée dans une fonction dédiée ;
• les requêtes sont sous kb_lib/src/db/queries/ ;
• les entités persistées sont sous kb_lib/src/db/entities/ ;
• les DTO applicatifs sont sous kb_lib/src/db/dtos/.

schema.rs n’est donc pas un fichier métier à splitter immédiatement. Il reste acceptable tant qu’il garde uniquement la responsabilité de création de schéma.

5.1. Tables existantes importantes

Le modèle actuel contient déjà notamment :

• transactions et instructions Solana normalisées ;
• DEX connus ;
• événements DEX décodés ;
• tokens, pools, pool tokens, paires, listings ;
• launch surfaces et attributions ;
• pool origins ;
• swaps et trade events ;
• liquidity events ;
• wallets, participations, holdings ;
• candles ;
• metrics et analytic signals ;
• diagnostics locaux.

5.2. Tables existantes à stabiliser pour les cas non-trade et inconnus

Avant d’étendre trop agressivement les DEX, ces tables doivent être stabilisées et raccordées progressivement aux diagnostics et matérialisations :

Table cible	Rôle
k_sol_transaction_classifications	classifier les transactions connues, inconnues, partielles, échouées, non-DEX, DEX-candidates, launch-candidates.
k_sol_protocol_candidates	conserver les programmes ou patterns suspects/récurrents qui ne correspondent pas encore à un DEX connu.
k_sol_pool_lifecycle_events	matérialiser initialize/create/migrate/open/close/status events.
k_sol_fee_events	conserver fees, creator fees, protocol fees, fund fees.
k_sol_reward_events	conserver reward params, init rewards, collect rewards.
k_sol_pool_admin_events	conserver changements de config, authority, pause/resume, paramètres de pool.

k_sol_liquidity_events existe déjà et doit être stabilisée/étendue plutôt que recréée sans nécessité.

6. Politique de refactor actuelle

Le code et la documentation sont vivants. Les refactors agressifs sont acceptables lorsque cela rend le pipeline plus propre et plus durable, à condition de respecter ces limites :

• ne pas casser les fonctionnalités déjà validées ;
• ne pas toucher pour le moment aux clients et managers réseau stabilisés ;
• faire des étapes courtes, testables et rejouables ;
• conserver les invariants de replay local ;
• ne pas transformer un événement non price-action en trade/candle ;
• documenter les nouveaux types publics avec une rustdoc utile mais pas surchargée ;
• laisser local_pipeline_diagnostics servir d’outil temporaire de validation tant que les DEX ne sont pas stabilisés.

Les fichiers à surveiller en priorité sont :

Fichier	Action recommandée
kb_lib/src/dex_decode.rs	extraire classification, catégories d’événements et enrichissement commun.
kb_lib/src/dex_detect.rs	extraire helpers communs pool/pair/listing/origin/wallets et isoler les handlers par famille.
kb_lib/src/trade_aggregation.rs	isoler extraction de montants, normalisation trade et pricing.
kb_lib/src/dex/*.rs	homogénéiser les contrats de décodeurs sans forcer un gros trait prématuré.

7. Contraintes de code

Contraintes maintenues :

• Rust 2024 ;
• pas de mod.rs ;
• fichiers Rust avec entête // file: ... ;
• fichiers .toml avec entête # file: ... ;
• exposition centralisée via lib.rs ;
• #![deny(unreachable_pub)] et #![warn(missing_docs)] dans les racines concernées ;
• pas de anyhow ;
• pas de thiserror ;
• pas de ?, unwrap, expect dans le code applicatif ;
• usage privilégié de match, if let Err, let Err = ... else ;
• imports externes limités, sauf traits lorsque nécessaire ;
• tests unitaires et tests de replay maintenus.

Les tests peuvent rester plus souples lorsque cela clarifie le test.

8. Priorité immédiate

Les phases 0.7.39, 0.7.40, 0.7.41 et 0.7.42 sont considérées comme closes côté documentation lorsque les tests locaux passent et que les requêtes SQL de contrôle Raydium confirment les invariants de la famille Raydium.

État acquis :

• 0.7.39_dex_first_effective_swap_surfaces : matrice DEX-first, suppression de l’alias raydium, ajout de metaDAO et Printr en to_verify, aucun program_id fictif ;
• 0.7.40 : Demo3 découvre on-chain signatures, mints, deltas SPL Token et comptes candidats par DEX/program id ; Demo Pipeline 2 peut backfiller une signature précise ;
• 0.7.41 : raydium_amm_v4.swap décode les inner instructions 675kPX..., produit trades/candles lorsque les montants sont exploitables, et conserve les failed transactions sans matérialisation marché ;
• 0.7.42 : raydium_cpmm, raydium_clmm et raydium_amm_v4 sont consolidés comme surfaces Raydium effectives ; CLMM/CPMM couvrent les premiers événements non-trade prouvés ; AMM v4 non-swap reste en audit legacy.

Résultat de corpus Raydium 0.7.42 :

• swaps Raydium matérialisés : AMM v4, CLMM swap_v2, CLMM legacy swap, CPMM swap_base_input, CPMM swap_base_output ;
• non-trade Raydium matérialisés : 25 liquidity events, 1 pool lifecycle event, 2 fee events ;
• événements CLMM prouvés : increase_liquidity_v2, decrease_liquidity_v2, open_position_with_token22_nft, close_position ;
• événements CPMM prouvés : initialize, withdraw, collect_creator_fee ;
• audits restants AMM v4 : conservés comme raydium_amm_v4.instruction_audit informatifs, non promus sans preuve ;
• transactions failed : traçables mais exclues de trade_events, metrics et candles.

Limite connue hors Raydium : la base locale peut encore contenir des decoded events orca_whirlpools.swap partiels issus du corpus courant. Orca Whirlpools est volontairement reporté à 0.7.44; ce point ne doit pas bloquer la clôture Raydium 0.7.42.

La prochaine étape est maintenant 0.7.43_meteora_effective_surfaces, puis 0.7.44 pour Orca/FluxBeam/DexLab/metaDAO/Printr.

9. Fichiers utiles pour reprendre dans une nouvelle session

Pour reprendre rapidement le codage dans une nouvelle session, fournir au minimum :

• README.md ;
• ROADMAP.md ;
• CHANGELOG.md ;
• Cargo.toml racine ;
• kb_lib/Cargo.toml ;
• kb_lib/src/lib.rs ;
• kb_lib/src/constants.rs ;
• kb_lib/src/dex.rs ;
• kb_lib/src/dex/*.rs ;
• kb_lib/src/dex_decode.rs ;
• kb_lib/src/dex_detect.rs ;
• kb_lib/src/trade_aggregation.rs ;
• kb_lib/src/pair_candle_aggregation.rs ;
• kb_lib/src/local_pipeline_replay.rs ;
• kb_lib/src/local_pipeline_validation.rs ;
• kb_lib/src/local_pipeline_diagnostics.rs ;
• kb_lib/src/db/schema.rs ;
• kb_lib/src/db.rs ;
• kb_lib/src/db/entities.rs et kb_lib/src/db/entities/* ;
• kb_lib/src/db/dtos.rs et kb_lib/src/db/dtos/* ;
• kb_lib/src/db/queries.rs et kb_lib/src/db/queries/*.

Ajouter kb_demo_app/src/demo_pipeline*.rs, les fichiers frontend associés et les nouvelles démos (Demo3, Demo4, Demo10) seulement si la tâche concerne l’UI, la recherche de corpus, les diagnostics affichés ou le watcher temps réel.