khadhroony-bot3/docs/DECODER_SURFACE_AUDIT.md

<!-- file: docs/DECODER_SURFACE_AUDIT.md -->
<!-- version: 1 -->

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