0.7.51

docs/reports/RAYDIUM_POOL_V4_DECISION_NOTE.md

@@ -0,0 +1,56 @@
+<!-- file: docs/reports/RAYDIUM_POOL_V4_DECISION_NOTE.md -->
+
+# Raydium Pool v4 Decision Note — `0.7.51`
+
+## Décision courte
+
+`raydium_pool_v4` ne doit pas être ouvert comme decoder autonome dans `0.7.51`.
+
+Statut retenu :
+
+```text
+Option C — IDL ambiguë / strategy-pool wrapper sans corpus local suffisant.
+```
+
+Conséquence : `raydium_pool_v4` reste une source d'audit/comparaison pour `raydium_amm_v4`. Toute promotion en tranche dédiée exige un program id prouvé localement, des observations dans `k_sol_instruction_observations`, des decoded events locaux et une absence de fallback upstream inexpliqué.
+
+## Comparaison synthétique
+
+| Source | Nom / rôle constaté | Indices structurants | Décision locale |
+|---|---|---|---|
+| `idl/raydium_amm_v4.json` | `raydium_amm` | Instructions AMM v4 legacy : `initialize`, `initialize2`, `deposit`, `withdraw`, `swapBaseIn`, `swapBaseOut`, `monitorStep`, `setParams`. | Source principale pour `raydium_amm_v4`. |
+| `idls/raydium_amm_v4.json` | `raydium_amm` | Variante parallèle à comparer ligne à ligne avec `idl/`. | Source principale complémentaire. |
+| `idl/raydium_pool_v4.json` | `Raydium Liquidity Pool V4` | Entrées orientées stratégie/pool wrapper : `initializeStrategy`, comptes `strategyState`, `strategyAuthority`, `lendingProgramId`; contient aussi des noms comme `swapBaseIn`. | Audit uniquement. Ne pas promouvoir. |
+| `idls/raydium_pool_v4.json` | `Raydium Liquidity Pool V4` | Même famille de signaux que `idl/raydium_pool_v4.json` à vérifier localement. | Audit uniquement. |
+
+## Raisons de non-promotion
+
+1. `raydium_pool_v4` ne prouve pas encore un program id local autonome dans le workspace.
+2. La présence de noms communs (`swapBaseIn`, comptes OpenBook) ne suffit pas à conclure que la surface est le program id AMM v4 canonique `675kPX...`.
+3. Les entrées `initializeStrategy`, `strategyState`, `strategyAuthority` et `lendingProgramId` indiquent un rôle potentiellement distinct : strategy, wrapper, pool manager, lending ou ancienne ABI composite.
+4. Aucune ligne locale `k_sol_instruction_observations` / `k_sol_dex_decoded_events` / `k_sol_dex_event_coverage_entries.local_event_kind` ne justifie une tranche autonome au moment de l'ouverture `0.7.51`.
+
+## Règle de décision future
+
+- Si `raydium_pool_v4` correspond finalement au même program id AMM v4 ou à un layout alternatif compatible, intégrer les discriminants/layouts validés dans `raydium_amm_v4`.
+- Si `raydium_pool_v4` correspond à un autre program id / wrapper / strategy / lending surface, créer une tranche dédiée seulement après corpus local.
+- Si l'IDL reste ambiguë, conserver l'entrée en roadmap comme audit conditionnel sans decoder runtime.
+
+## SQL local attendu avant toute promotion
+
+Une future promotion doit au minimum montrer :
+
+```sql
+SELECT
+    decoder_code,
+    instruction_name,
+    discriminator_hex,
+    COUNT(*) AS observed_count,
+    COUNT(DISTINCT signature) AS tx_count
+FROM k_sol_instruction_observations
+WHERE decoder_code IN ('raydium_amm_v4', 'raydium_pool_v4')
+GROUP BY decoder_code, instruction_name, discriminator_hex
+ORDER BY decoder_code, observed_count DESC;
+```
+
+Puis une preuve de decoded events locaux, de coverage entries mappées et d'absence de fallback upstream résiduel.