khadhroony-bobobot/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-whirlpool
fluxbeam
lifinity-amm-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