khadhroony-bot3/docs/DECODER_SURFACE_AUDIT.md

Audit des surfaces de décodage

Ce document suit les noms de crates de décodeurs réservés, les aliases probables et les surfaces à consolider. Il s'appuie sur les IDL locales du dossier idls/ et sur les matrices de conception historiques importées dans l'archive de travail.

Règle de décision

Un nom de décodeur devient canonique seulement si au moins un des critères suivants est vérifié :

• une IDL locale existe avec un program_id explicite ;
• le program_id est prouvé par corpus local ;
• le rôle de la surface est stable : DEX effectif, router, orderbook, launchpad, vault, lending, staking, etc. ;
• le nom respecte la nomenclature <protocol>_<surface> sans alias marketing ambigu.

Un nom historique sans program_id local reste en statut alias_candidate ou watchlist. Il ne doit pas recevoir de logique métier avant consolidation.

Aliases et doublons à traiter

Groupe	Canonique recommandé	Crates ou noms concurrents	Statut	Décision provisoire
OKX Labs	kb_decoder_okx_lab_v1	kb_decoder_okx_v1, kb_decoder_onchain_labs_dex_v1	alias_candidate	L'IDL locale existe pour okx_lab_v1 avec le programme 6m2CDdhRgxpH4WjvdzxAYbGxwdGUz5MziiL5jek2kBma. Les noms okx_v1 et onchain_labs_dex_v1 ne doivent pas être implémentés séparément sans preuve contraire.
OKX Router	kb_decoder_okx_dex_router	kb_decoder_okx_v2, kb_decoder_onchain_labs_dex_v2	alias_candidate	L'IDL locale existe pour okx_dex_router avec le programme proVF4pMXVaYqmy4NjniPh4pqKNfMmsihgd4wdkCX3u. Les noms okx_v2 et onchain_labs_dex_v2 restent des noms historiques à vérifier.
GooseFX	kb_decoder_goosefx_v2, kb_decoder_goosefx_gamma	kb_decoder_goosefx_v1	watchlist	goosefx_v2 et goosefx_gamma ont des IDL locales et des programmes distincts. goosefx_v1 reste une entrée historique sans IDL locale dans l'archive courante.
Fusion AMM	kb_decoder_fusion_amm	kb_decoder_fusionamm	alias_candidate	L'IDL locale se nomme fusion_amm, mais son metadata interne peut utiliser fusionamm. Le crate canonique doit rester lisible : fusion_amm.
PancakeSwap	kb_decoder_pancakeswap	kb_decoder_pancake_swap	alias_candidate	L'IDL locale se nomme pancakeswap. Le crate avec underscore supplémentaire doit rester non canonique.
Orca Wavebreak	kb_decoder_orca_wavebreak	kb_decoder_wavebreak	alias_candidate	L'IDL locale se nomme orca_wavebreak. Le nom sans protocole est trop ambigu.
Jupiter Limit Order v2	kb_decoder_jupiter_limit_order_v2	kb_decoder_jupiter_limit_order_2	alias_candidate	L'IDL locale utilise jupiter_limit_order_v2. Le suffixe _2 ne doit pas être utilisé.
dFlow	kb_decoder_dflow_v4	kb_decoder_dflow_aggregator_v4	alias_candidate	L'IDL locale se nomme dflow_v4. Le nom dflow_aggregator_v4 peut rester comme alias historique mais ne doit pas porter une implémentation distincte sans program_id différent.
Meteora DAMM v1	kb_decoder_meteora_damm_v1	kb_decoder_meteora_pools_amm	alias_candidate	Les matrices historiques indiquent que meteora_pools peut être un alias de DAMM v1. La consolidation doit être décidée par program_id, corpus et naming final.
Raydium LaunchLab	kb_decoder_raydium_launchlab	kb_decoder_raydium_launchpad	naming_mismatch	L'IDL locale se nomme raydium_launchlab. L'ancien nom launchpad décrit la famille métier, mais pas forcément la surface canonique.
Raydium Lock	kb_decoder_raydium_lock	kb_decoder_raydium_liquidity_locking	naming_mismatch	L'IDL locale se nomme raydium_lock. Le nom liquidity_locking est descriptif. La surface canonique doit être confirmée avant implémentation.
Raydium Pool v4	kb_decoder_raydium_amm_v4	kb_decoder_raydium_pool_v4	audit_only	La note historique indique que raydium_pool_v4 ne doit pas être promu comme décodeur autonome sans program_id distinct et corpus local.

Actions recommandées

• Ne pas supprimer immédiatement les crates aliases tant que le squelette sert de matrice de réservation.
• Ne pas implémenter deux décodeurs pour le même program_id.
• Ajouter dans chaque décodeur un mapping explicite surface_code, program_code et program_id dès que le corpus commence.
• Déplacer les aliases historiques vers une table de catalogue ou un document de watchlist quand le support réel commence.
• Supprimer ou fusionner les crates aliases seulement dans un delta dédié, avec validation cargo build et manifeste de suppression.

Surfaces à ajouter ou renommer plus tard

• Ajouter kb_decoder_raydium_launchlab si la décision est de refléter strictement le nom de l'IDL locale.
• Vérifier si kb_decoder_raydium_launchpad doit devenir un alias documentaire ou rester une surface métier.
• Vérifier si kb_decoder_meteora_pools_amm doit être fusionné dans kb_decoder_meteora_damm_v1.
• Vérifier si les crates okx_v1, okx_v2, onchain_labs_dex_v1 et onchain_labs_dex_v2 doivent être supprimés après confirmation des deux programmes OKX canoniques.