<!-- file: docs/prompts/PROMPT_0_7_60_meteora_damm_next_dex.md -->

# Prompt — 0.7.60 Meteora DAMM v1 puis DAMM v2

## Décision

Ne pas fusionner Meteora DAMM v1 et Meteora DAMM v2 dans une seule tranche d’implémentation.

Utiliser des versions séparées :

```text
0.7.60 -> meteora_damm_v1
0.7.61 -> meteora_damm_v2
```

Raison :

- `program_id` différents ;
- surfaces IDL/discriminators différentes ;
- corpus historiques et besoins de validation différents ;
- clôture SQL plus lisible ;
- risque réduit de faux positifs cross-version ;
- rollback plus simple si une version contient une hypothèse incorrecte.

Partage autorisé :

- helpers communs privés ;
- patterns communs de récupération fee/reward amounts ;
- conventions communes de coverage/tests ;
- structure commune de rapport ;
- template SQL commun.

Ne pas partager la classification de decoder d’une manière qui masque les discriminators version-spécifiques ou les layouts propres à chaque programme.

## Contexte

`0.7.57 meteora_dlmm` est clos.

Les tranches intermédiaires planifiées avant DAMM sont maintenant :

```text
0.7.58 -> sqlite_db_transaction_merger + validation anti-régression cross-DEX
0.7.59 -> demo4_program_surface_discovery
```

Raison du changement : la régression PumpSwap/PumpFees a montré qu’une base DEX isolée ne suffit pas. Les futurs décodeurs doivent être validés à la fois sur une base dédiée et sur une base consolidée `final.db` issue du merger.

Surfaces Meteora connues :

```text
meteora_dbc      -> clos 0.7.56
meteora_dlmm     -> clos 0.7.57
meteora_damm_v1  -> 0.7.60
meteora_damm_v2  -> 0.7.61
meteora_vault    -> plus tard, surface séparée
```

## Workflow obligatoire pour 0.7.60+

Pour chaque nouvelle tranche DEX :

1. Créer une base vide dédiée au DEX.
2. Backfiller le corpus DAMM v1 dans cette base dédiée.
3. Développer decoder/materializer sur cette base.
4. Clore les gates SQL DAMM v1 localement.
5. Fusionner la base dédiée dans une copie de `final.db` via le merger `0.7.58`.
6. Rejouer la base fusionnée avec :

```text
metadata=no
skipDexDecode=no
forceDexDecode=yes
deferInstructionObservations=yes
```

7. Lancer les validations globales anti-régression Pump/Raydium/Meteora.
8. Ne considérer la tranche close que si la base dédiée et la base fusionnée sont propres.

## Cible 0.7.60 — meteora_damm_v1

Program id depuis la roadmap :

```text
Eo7WjKq67rjJQSZxS6z3YkapzY3eMj6Xy8X5EQVn5UaB
```

Objectif principal :

```text
Full decode + full materialization pour toutes les instructions/events DAMM v1 disponibles depuis les IDL locales et les sources upstream.
```

Familles attendues :

```text
swap
pool_create
add_liquidity
remove_liquidity
lock/unlock liquidity si présent
fee/admin/config
lifecycle/migration si présent
```

Règles :

- Pas de decoded-only pour une entrée utile observée si elle peut être matérialisée sûrement.
- Ne pas créer de trade/candle depuis des non-swaps.
- Ne pas matérialiser les transactions failed.
- Ne pas agréger artificiellement les fees multi-mint.
- Utiliser `k_sol_fee_event_amounts` pour les legs fee fiables.
- Utiliser la récupération inner SPL transfer seulement avec allowlist explicite et tests.
- Conserver toutes les entrées IDL/upstream non observées dans la coverage avec `0/0` et proof status clair.
- Un decoder ne doit pas aborter toute une transaction multi-protocoles pour un payload secondaire tronqué/incompatible si l’entrée peut être ignorée proprement.

## Sources à vérifier

Inspecter d’abord le répertoire local :

```text
idls/
```

Puis comparer avec :

```text
Carbon decoders
Pinax/substreams-solana-idls
0xfnzero sol-parser-sdk / solana-streamer
ancien code local et rapports historiques du projet
samples Solscan / backfills Demo3
surfaces visibles dans Demo4 si 0.7.59 est disponible
```

Ne pas considérer les anciens résultats `0.7.36` ou `0.7.46` comme clôture finale. Revalider depuis le schéma courant et les règles actuelles de matérialisation.

## Plan de travail

1. Créer ou rafraîchir les entrées coverage `meteora_damm_v1`.
2. Vérifier le `program_id` et la surface IDL locale.
3. Étendre l’enum/local classifier des discriminators.
4. Ajouter le naming dans `instruction_observation_index`.
5. Décoder toutes les instructions et tous les events Anchor disponibles.
6. Matérialiser swaps, liquidity, lifecycle, fee, reward/admin/orderbook si applicable.
7. Ajouter des tests synthétiques pour chaque instruction/event IDL, y compris non observé.
8. Ajouter le SQL de validation DAMM v1.
9. Rejouer sur base fraîche dédiée avec `forceDexDecode=yes`.
10. Fusionner la base dédiée vers `final.next.db` via `kb_db_merge`.
11. Rejouer `final.next.db`.
12. Lancer les gates cross-DEX.
13. Clore seulement si les gates locales et globales sont propres.

## Gates SQL obligatoires

Reprendre le pattern DLMM :

```text
fallback upstream pour entrées localement couvertes -> vide
instruction_name null/blank -> vide
decoded sans coverage -> vide
successful non-materialized without skip/policy -> vide
failed tx materialization -> vide
multi-target materialization -> vide
non-swap trade/candle -> vide
fee scalar parent without leg -> vide
orphan fee legs -> vide
coverage logical duplicates -> vide
watchlist sans backlog meteora_damm_v1
```

Ajouter les gates anti-régression globales après merge :

```text
successful non-materialized Pump/Raydium/Meteora expliqué ou vide
pure instruction_audit inattendu -> vide
decoder errors cross-surface -> vide
failed tx materialized -> vide
trade/candle non-swap -> vide
```

## Cible 0.7.61 — meteora_damm_v2

Program id depuis la roadmap :

```text
cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG
```

N’ouvrir cette tranche qu’après clôture DAMM v1.

La tranche v2 peut réutiliser le template et des helpers privés, mais doit conserver ses propres éléments :

```text
decoder code
coverage entries
instruction enum
event mapping
synthetic tests
SQL validation
rapport
base dédiée
validation final.db merge
```

## Livrables attendus pour 0.7.60

Fichiers probables :

```text
kb_lib/src/dex/meteora_damm_v1.rs
kb_lib/src/dex_event_coverage.rs
kb_lib/src/dex_event_classification.rs
kb_lib/src/instruction_observation_index.rs
kb_lib/src/non_trade_event_materialization.rs
validation_sql/SQL_VALIDATION_METEORA_DAMM_V1_0_7_60.sql
validation_sql/SQL_VALIDATION_CROSS_DEX_REGRESSION_AFTER_DAMM_V1_0_7_60.sql
docs/reports/METEORA_DAMM_V1_EVENT_COVERAGE_REPORT.md
```

Mettre à jour les re-exports si des modules ou requêtes sont ajoutés :

```text
kb_lib/src/dex.rs
kb_lib/src/lib.rs
kb_lib/src/db.rs
```

## Note finale

Si la découverte corpus montre que DAMM v1 et v2 partagent une logique basse-niveau précise, créer des helpers privés communs.

Ne pas fusionner les deux protocoles dans un seul decoder, une seule coverage ou un seul rapport de clôture.
