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.

Ce document reflète le point de reprise 0.7.43-E5C. La version Cargo reste 0.7.43, mais le lot Meteora ouvert en 0.7.43 n’est pas considéré comme terminé. La priorité immédiate est maintenant de normaliser la roadmap DEX-first, d’ajouter un ledger de décodage/replay pour éviter les rescans inutiles, puis de reprendre les DEX un par un, variante par variante.

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 strictement les swaps/candles des événements utiles seulement à l’analyse : liquidité, cycle de vie de pool, fees, rewards, administration, wallet activity, mint/burn, migration ;
• 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 sans retraiter inutilement toute la base.

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

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, validation et diagnostics.
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, Demo3, 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 utilisée pour inspecter, backfiller et constituer du corpus on-chain ; elle ne doit pas récupérer de logique DEX profonde.

3. État actuel au point de reprise 0.7.43-E5C

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, les tables d’analyse et le replay incrémental.

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. matérialisation partielle des événements non-trade prouvés ;
8. agrégation pair metrics ;
9. génération candles/OHLCV ;
10. signaux analytiques simples ;
11. inspection via l’application de démonstration.

3.3. Résultat local observé avant normalisation

Un corpus local de reprise contient notamment :

Indicateur	Valeur observée
transactions chain	2956
decoded events	7159
trade events	2738
liquidity events	0
pool lifecycle events	1
fee events	0
reward events	0
admin events	0

Cette distribution montre que les swaps sont déjà fortement présents, mais que la matérialisation non-trade n’est pas encore homogène sur le corpus courant. Les nombreux instruction_audit, surtout côté Meteora, doivent devenir un axe de travail DEX par DEX.

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

Les surfaces suivantes existent dans le code, dans la matrice ou dans le corpus local. Leur niveau de preuve doit rester explicite.

Code	Statut de travail	Commentaire
pump_fun	launch surface	Surface de launch / mint initial. À traiter après les DEX effectifs sauf besoin de migration.
pump_swap	DEX effectif	Swaps buy / sell observés. Non-trade à étendre plus tard.
raydium_cpmm	DEX effectif consolidé partiellement	Swaps et premiers events non-trade prouvés sur corpus antérieur.
raydium_clmm	DEX effectif consolidé partiellement	Swaps v2/legacy, positions et liquidity events prouvés sur corpus antérieur.
raydium_amm_v4	DEX effectif legacy	Swaps AMM v4 legacy matérialisés ; non-swaps legacy conservés en audit tant que le corpus ne permet pas une promotion fiable.
meteora_dlmm	DEX effectif à reprendre séparément	Présent et observé ; events non-trade à normaliser.
meteora_damm_v1	DEX effectif à reprendre séparément	Swaps présents ; plusieurs events restent en audit ou non actionnables.
meteora_damm_v2	DEX effectif à reprendre séparément	Swaps et create_pool observés ; nombreux audits à traiter.
meteora_dbc	launch/bonding + DEX effectif partiel à reprendre séparément	Gros volume d’audits ; séparer bonding/launch, swap effectif et migration.
orca_whirlpools	DEX effectif à vérifier	À revalider par corpus dédié avant promotion.
fluxbeam	DEX effectif à vérifier	Program id, corpus et events à vérifier.
dexlab	DEX effectif à vérifier	Program id, corpus et events à vérifier.
metaDAO	candidat à vérifier	Aucun program_id ne doit être déclaré vérifié sans preuve/corpus.
printr	candidat à vérifier	Aucun program_id ne doit être déclaré vérifié sans preuve/corpus.

3.5. Statuts de preuve obligatoires

Aucun program_id, DEX ou event ne doit être documenté comme vérifié sans preuve reproductible.

Statut	Sens
known	Connu/listé dans le code, une doc, une source externe ou la matrice.
observed	Vu dans une transaction, une instruction, une base locale ou un corpus on-chain.
decoded	Un decoder produit un event structuré ou un instruction_audit classé.
materialized	L’event alimente une table métier dédiée : trade, liquidity, lifecycle, fee, reward, admin, mint/burn, etc.
verified_by_corpus	Validé par requêtes SQL, signatures/corpus reproductibles et invariants de validation.

4. Matrice DEX : priorité révisée

À partir du point de reprise 0.7.43-E5C, la priorité est :

1. DEX effectifs actuels : programmes où les swaps, pools, liquidités, positions, fees, rewards, admin/config, burns/mints ou migrations sont réellement exécutés ;
2. launch surfaces : surfaces de mint, bonding, launchpad, migration ou origine ;
3. DEX historiques / legacy / faibles priorités : programmes anciens, peu observés, ou uniquement utiles à la compatibilité/replay historique.

Chaque DEX ou variante de DEX doit avoir sa propre étape de validation. Les familles larges restent utiles pour la navigation, mais le travail de décodage doit être fait par version/protocole : raydium_cpmm, raydium_clmm, raydium_amm_v4, meteora_dlmm, meteora_damm_v1, meteora_damm_v2, meteora_dbc, etc.

4.1. Ordre de travail DEX effectifs

Priorité	Code cible	Rôle	Action prochaine
1	pump_swap	AMM / swap	Maintenir les invariants swaps et chercher les non-trade prouvés.
2	raydium_cpmm	AMM	Garder consolidé ; ne rouvrir que sur nouveaux discriminators/corpus.
3	raydium_clmm	CLMM	Garder consolidé ; ne rouvrir que sur nouveaux discriminators/corpus.
4	raydium_amm_v4	AMM legacy actif	Garder swaps ; ne promouvoir les non-swaps qu’avec corpus.
5	meteora_dlmm	DLMM	Reprendre séparément : swaps, liquidity, positions, lifecycle, fees/rewards/admin.
6	meteora_damm_v1	AMM	Reprendre séparément : swaps exploitables, pools, liquidity, fees/admin.
7	meteora_damm_v2	AMM	Reprendre séparément : create_pool, swaps exploitables, configs dynamiques, non-trade.
8	meteora_dbc	bonding / DEX effectif partiel	Reprendre séparément : swap effectif, bonding curve, migration, launch attribution.
9	orca_whirlpools	CLMM	Revalider par corpus dédié.
10	fluxbeam	AMM	Vérifier program id, events et corpus.
11	dexlab	AMM	Vérifier program id, events et corpus.
12	metaDAO	candidat DEX	Vérifier par corpus avant toute promotion.
13	printr	candidat DEX	Vérifier par corpus avant toute promotion.

4.2. Launch surfaces reportées

À reprendre après les DEX effectifs, sauf si une surface est indispensable pour comprendre une migration vers un pool tradable :

• pump_fun ;
• raydium_launchlab ;
• raydium_launchpad ;
• letsbonk / bonk_fun ;
• bags ;
• moonshot ;
• moonit ;
• boop_fun ;
• believe ;
• heaven ;
• autres launch origins découvertes par corpus.

4.3. DEX historiques ou faibles priorités

À garder dans la matrice mais sans bloquer les versions immédiates :

• raydium_stable_swap tant que son usage réel n’est pas démontré par corpus local ;
• vieux programmes legacy uniquement utiles pour compatibilité ou replay historique ;
• agrégateurs/routeurs comme okx_dex tant qu’ils ne correspondent pas à un DEX direct matérialisable ;
• entrées ambiguës comme zora tant qu’aucun programme Solana pertinent n’est prouvé.

5. Base de données et replay incrémental

SQLite reste le stockage local initial. Le fichier config.json peut pointer vers une base différente pour travailler par corpus, par DEX ou sur base vierge. Le schéma est créé au lancement via les CREATE TABLE IF NOT EXISTS existants.

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/.

5.1. Tables existantes importantes

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

• k_sol_chain_transactions ;
• k_sol_chain_instructions ;
• k_sol_dexes ;
• k_sol_dex_decoded_events ;
• k_sol_tokens ;
• k_sol_pools ;
• k_sol_pairs ;
• k_sol_pool_tokens ;
• k_sol_trade_events ;
• k_sol_liquidity_events ;
• k_sol_pool_lifecycle_events ;
• k_sol_fee_events ;
• k_sol_reward_events ;
• k_sol_pool_admin_events ;
• k_sol_token_mint_events ;
• k_sol_token_burn_events ;
• k_sol_transaction_classifications ;
• k_sol_protocol_candidates.

5.2. Prochaine évolution DB : ledger de décodage/replay

Le replay actuel peut retraiter trop largement les transactions déjà connues. La prochaine tranche DB doit ajouter une structure de suivi permettant de ne pas rescanner les events certains, sauf option explicite.

Objectifs :

• mémoriser qu’une transaction/instruction a déjà été traitée par un decoder donné ;
• stocker le statut de décodage : certain, partiel, inconnu, erreur, non-actionnable, multi-token ambigu ;
• associer le résultat au decoder_code et à une version logique de decoder ;
• permettre un mode force qui ignore le ledger ;
• permettre un mode de reprise ciblé lorsque le decoder change ;
• ne pas skipper automatiquement les transactions multi-token, multi-pool ou multi-event ambiguës ;
• conserver les failed transactions comme traçables mais non actionnables.

Nom de table à décider dans la tranche DB, par exemple :

• k_sol_decode_attempts ; ou
• k_sol_replay_decode_ledger.

Champs conceptuels attendus :

Champ conceptuel	Rôle
transaction_id / signature	rattachement transactionnel stable
instruction_id / instruction_index	granularité instruction si possible
program_id	programme effectivement traité
protocol_name	protocole/DEx résolu
decoder_code	decoder logique utilisé
decoder_version	version logique du decoder
decode_status	certain, partial, unknown, failed, skipped, ambiguous
certainty	niveau de confiance machine
event_count	nombre d’events produits
payload_hash / instruction_hash	détection de changement d’entrée
reason_code / error_json	diagnostic sans panic
created_at / updated_at	audit local

6. Politique de replay

Règles cibles :

• par défaut, ne pas retraiter une instruction dont le ledger indique un décodage certain avec le même decoder/version et la même entrée ;
• retraiter si force = true ;
• retraiter si le decoder concerné change de version logique ;
• retraiter si la transaction contient plusieurs tokens/pools/events et que le ledger la classe comme ambiguë ou partielle ;
• retraiter si un event précédemment instruction_audit devient décodable par un nouveau decoder ;
• ne jamais créer de faux trade/candle pour un event dont les montants ne sont pas fiables ;
• conserver les audits utiles pour améliorer les decoders.

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 de kb_lib ;
• kb_demo_app peut rester plus souple tant qu’elle reste une application de démonstration ;
• usage privilégié de match, if let Err, let Err = ... else dans kb_lib ;
• imports externes limités, sauf traits lorsque nécessaire ;
• tests unitaires et tests de replay maintenus.

Si une requête DB est ajoutée ou modifiée, mettre à jour les re-exports dans kb_lib/src/db.rs, puis dans kb_lib/src/lib.rs si la surface publique l’exige.

8. Priorité immédiate

La priorité immédiate après le point de reprise 0.7.43-E5C est :

1. 0.7.43 : resynchronisation documentaire, normalisation DEX-first et gel du point de reprise ;
2. 0.7.44 : ajout du ledger de décodage/replay et options de replay force / skip sûr ;
3. 0.7.45 : reprise séparée de meteora_dlmm ;
4. 0.7.46 : reprise séparée de meteora_damm_v1 ;
5. 0.7.47 : reprise séparée de meteora_damm_v2 ;
6. 0.7.48 : reprise séparée de meteora_dbc ;
7. 0.7.49 : revalidation séparée de orca_whirlpools ;
8. 0.7.50+ : FluxBeam, DexLab, metaDAO, Printr, puis launch surfaces.

Garde-fous constants :

• pas de faux trade ;
• pas de fausse candle ;
• pas de program_id fictif ;
• pas de promotion d’un DEX sans corpus transactionnel ;
• pas de logique métier DEX profonde dans kb_demo_app ;
• pas de metadata manquante bloquante ;
• pas de refactor réseau inutile tant que les clients HTTP/WS existants suffisent.

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 ;
• clippy.toml ;
• config.json ;
• 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/dex_support_matrix.rs ;
• kb_lib/src/dex_event_classification.rs ;
• kb_lib/src/non_trade_event_materialization.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/onchain_dex_pair_discovery.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, kb_demo_app/src/demo3.rs, les fichiers frontend associés et les nouvelles démos seulement si la tâche concerne l’UI, la recherche de corpus, les diagnostics affichés ou le watcher temps réel.