0.7.49

docs/prompts/NEXT_SESSION_PROMPT_0.7.47_UPSTREAM_REGISTRY.md

@@ -0,0 +1,249 @@
+# Prompt de reprise — khadhroony-bobobot `0.7.47`
+
+Reprise du projet `khadhroony-bobobot`.
+
+## Contexte
+
+Le workspace contient principalement :
+
+- `kb_lib` : logique métier Solana/DEX, clients HTTP/WS, décodage, détection, SQLite, replay, validation, diagnostics, metadata, candles, signaux ;
+- `kb_demo_app` : application Tauri V2 de démo/inspection. Elle doit rester une façade UI et ne pas contenir de logique métier DEX profonde.
+
+La version `0.7.46` est clôturée sur `meteora_damm_v1`.
+
+## État validé à la fin de `0.7.46`
+
+- `cargo test -p kb_lib` : vert.
+- `cargo clippy -p kb_lib --all-targets -- -D warnings` : vert.
+- Demo2 et Demo3 fonctionnent bien pour backfill et discovery.
+- Demo3 supporte :
+  - multi-target ;
+  - multi-source ;
+  - pagination `before` / `until` ;
+  - `max_pages` ;
+  - `newest_first` / `oldest_first`.
+- Le replay local supporte le ledger de décodage/replay et les options `skipDexDecode` / `forceDexDecode`.
+- `meteora_damm_v1` couvre les surfaces observées localement :
+  - `swap` ;
+  - `claim_fee` ;
+  - `create_lock_escrow` ;
+  - `lock_liquidity` ;
+  - `remove_liquidity` ;
+  - `add_liquidity` ;
+  - `create_pool`.
+- Les statuts/payloads ne doivent plus utiliser une terminologie spécifique à un dépôt externe particulier.
+- Les statuts génériques attendus sont :
+  - `upstream_git_unverified` ;
+  - `upstream_git_mapped_unverified` ;
+  - `upstream_git_local_corpus_observed` ;
+  - `upstream_git_local_corpus_materialized` ;
+  - `upstream_git_layout_unverified` si le layout est connu depuis une source Git mais pas encore validé localement.
+
+## Décision base de données pour `0.7.47`
+
+La version `0.7.46` est considérée finalisée. Ne pas demander ni proposer de replay forcé de l’ancienne base `0.7.46` pour clôturer cette version, sauf demande explicite.
+
+Pour `0.7.47`, le développement et la validation doivent se faire de préférence sur une **nouvelle base SQLite dédiée**. Cette base servira à constituer un corpus propre avec Demo3 et Demo2 sur plusieurs paires, pools ou programmes de DEX différents.
+
+Règles pratiques :
+
+- l’ancienne base `0.7.46` peut servir de référence historique ou de comparaison, mais elle ne doit pas être migrée ou redécodée automatiquement ;
+- si une validation DB est nécessaire en `0.7.47`, elle doit cibler la nouvelle base de travail `0.7.47` ;
+- les backfills `0.7.47` doivent être construits à partir de Demo3 discovery puis Demo2 signature/pool backfill ;
+- le replay local reste utile, mais seulement après constitution du corpus `0.7.47`, pas comme étape de finalisation de `0.7.46` ;
+- les entrées du registre upstream Git restent des indices tant qu’elles ne sont pas observées sur cette nouvelle base ou sur un corpus explicitement indiqué.
+
+## Objectif de `0.7.47`
+
+`0.7.47` est dédiée à :
+
+```text
+Upstream Git Registry / DEX discovery preparation
+```
+
+L’objectif n’est pas de valider directement un DEX unique. L’objectif est de créer un registre générique permettant d’indexer les `program_id`, discriminants d’instructions, discriminants d’events, noms d’instructions, familles de programmes et types de surfaces issus de dépôts Git externes de decoders Solana.
+
+Ces entrées sont des **indices de découverte**, pas des preuves métier. Elles doivent rester non vérifiées tant qu’elles ne sont pas confirmées par :
+
+1. Demo3 discovery ;
+2. backfill signature/pool via Demo2 ;
+3. replay local sur la base de travail `0.7.47` ;
+4. requêtes SQL de validation sur cette même base ;
+5. invariants métier : pas de faux trade, pas de fausse candle, pas de promotion de `program_id` sans corpus.
+
+## Noms recommandés
+
+Modules possibles :
+
+```text
+kb_lib/src/upstream_registry.rs
+kb_lib/src/upstream_registry_types.rs
+kb_lib/src/upstream_registry_match.rs
+kb_lib/src/upstream_registry_generated.rs
+```
+
+Nom fonctionnel :
+
+```text
+Upstream Git Registry
+```
+
+Ne pas utiliser de nom de dépôt externe spécifique dans les noms publics, les statuts, les tables ou les payloads métier.
+
+## Première tranche attendue
+
+Créer une première version statique du registre dans `kb_lib`, sans modifier la DB si ce n’est pas nécessaire.
+
+Chaque entrée de registre devrait contenir au minimum :
+
+```text
+source_repo
+source_path
+decoder_code
+program_id
+program_family
+surface_kind
+entry_kind = instruction | event | account | program
+entry_name
+discriminator_hex
+discriminator_len
+proof_status
+notes
+```
+
+Les entrées de registre doivent être exposées à `kb_demo_app` via une commande Demo3 ou une commande dédiée, mais la logique reste dans `kb_lib`.
+
+## Familles à indexer en priorité
+
+DEX / AMM / CLMM / orderbook :
+
+```text
+meteora_damm_v2
+meteora_dbc
+meteora_dlmm
+meteora_vault
+raydium_amm_v4
+raydium_clmm
+raydium_cpmm
+raydium_launchpad
+raydium_liquidity_locking
+raydium_stable_swap
+orca_whirlpools
+fluxbeam
+lifinity_v2
+phoenix_v1
+openbook_v2
+stabble_stable_swap
+stabble_weighted_swap
+bonkswap
+boop
+moonshot
+heaven
+okx_dex
+pancake_swap
+vertigo
+virtuals
+wavebreak
+onchain_labs_dex_v1
+onchain_labs_dex_v2
+```
+
+Agrégateurs / ordres / perps / lending :
+
+```text
+jupiter_swap
+jupiter_dca
+jupiter_limit_order
+jupiter_limit_order_2
+jupiter_perpetuals
+jupiter_lend
+kamino_lending
+kamino_vault
+kamino_farms
+kamino_limit_order
+drift_v2
+marginfi_v2
+dflow_aggregator_v4
+zeta
+```
+
+Contexte transactionnel non DEX :
+
+```text
+system_program
+token_program
+token_2022
+associated_token_account
+address_lookup_table
+memo_program
+stake_program
+mpl_token_metadata
+mpl_core
+bubblegum
+name_service
+marinade_finance
+solayer_restaking_program
+swig
+sharky
+circle_message_transmitter_v2
+circle_token_messenger_v2
+```
+
+## Règles de validation
+
+- Une entrée upstream Git reste `upstream_git_unverified` tant qu’elle n’a pas été vue localement.
+- Une entrée branchée dans un decoder mais jamais vue localement reste `upstream_git_mapped_unverified`.
+- Une entrée vue après Demo3/backfill/replay peut devenir `upstream_git_local_corpus_observed`.
+- Une entrée qui alimente correctement une table métier dédiée peut devenir `upstream_git_local_corpus_materialized`.
+- Aucun `program_id`, event ou discriminator ne doit être déclaré vérifié uniquement parce qu’il existe dans un dépôt Git externe.
+- Aucun event non-trade ne doit produire trade, metric ou candle.
+
+## Contraintes de code
+
+- 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)]`.
+- Pas de `anyhow`.
+- Pas de `thiserror`.
+- Pas de `?`, `unwrap`, `expect` dans le code applicatif.
+- Utiliser `match`, `if let Err`, `let Err = ... else`.
+- Tests verts à chaque étape.
+- Si une requête DB est ajoutée/modifiée, mettre à jour les re-exports dans `kb_lib/src/db.rs`, puis `kb_lib/src/lib.rs` si nécessaire.
+
+## Format de livraison attendu
+
+Pour chaque tranche :
+
+1. expliquer brièvement les fichiers touchés ;
+2. fournir une archive des fichiers ajoutés/modifiés seulement, avec l’arborescence du projet ;
+3. indiquer les commandes de test à lancer ;
+4. indiquer les requêtes SQL utiles si validation DB nécessaire ;
+5. ne jamais prétendre qu’un `program_id` ou un event est vérifié sans preuve/corpus.
+
+
+dexlab
+bags / letsbonk / bonk_fun
+believe
+moonit
+launchbeam
+metadao / metaDAO
+printr
+zora
+aldrin
+aldrin_v2
+crema
+cropper
+cropper_legacy
+guacswap
+invariant
+lifinity_v1
+openbook_v1 / serum-style legacy
+orca_v1
+orca_v2
+saber
+saros
+serum_v3
+token_swap