khadhroony-bobobot/docs/prompts/NEXT_SESSION_PROMPT_0.7.47_UPSTREAM_REGISTRY.md

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 à :

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 :

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 :

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 :

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 :

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 :

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 :

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