pump_swap correction.
This commit is contained in:
@@ -1,245 +1,18 @@
|
||||
<!-- file: docs/prompts/prompt_name_0_7_58_demo4_program_surface_discovery.md -->
|
||||
<!-- file: docs/prompts/PROMPT_0_7_58_demo4_program_surface_discovery.md -->
|
||||
|
||||
# Prompt — 0.7.58 Demo4 Program Surface Discovery
|
||||
# OBSOLETE — Prompt déplacé
|
||||
|
||||
## Contexte
|
||||
Ce prompt n'est plus la cible `0.7.58`.
|
||||
|
||||
Nous reprenons le workspace Rust/Tauri `khadhroony-bobobot` après la clôture de `0.7.57 meteora_dlmm`.
|
||||
|
||||
État validé :
|
||||
Nouvel ordre validé :
|
||||
|
||||
```text
|
||||
0.7.57 meteora_dlmm clos
|
||||
cargo test -p kb_lib -> 460 passed
|
||||
cargo clippy -p kb_lib --all-targets -- -D warnings -> OK
|
||||
replay -> 769 replayed, 106 trades, 664 liquidity, 1107 lifecycle, 424 candles
|
||||
instructionObservations = 8062
|
||||
catalogue = 169 tokens / 218 pools / 218 pairs
|
||||
0.7.58 -> sqlite_db_transaction_merger
|
||||
0.7.59 -> demo4_program_surface_discovery
|
||||
```
|
||||
|
||||
Contraintes projet à respecter :
|
||||
|
||||
- Rust 2024.
|
||||
- Code async-first.
|
||||
- Pas de `?`, `unwrap`, `expect` dans le code applicatif.
|
||||
- Pas de `anyhow`, pas de `thiserror`.
|
||||
- Pas de `mod.rs`.
|
||||
- Pas de `pub mod` ; utiliser `mod` privé + `pub use`.
|
||||
- Imports uniquement pour les traits quand c’est possible.
|
||||
- `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]` doivent rester propres.
|
||||
- Tests offline.
|
||||
- Les nouvelles requêtes DB doivent mettre à jour les re-exports dans `kb_lib/src/db.rs` puis `kb_lib/src/lib.rs`.
|
||||
- Les structs DB doivent aller dans `kb_lib/src/db/entities/*.rs` et `kb_lib/src/db/dtos/*.rs`, pas dans les fichiers de requêtes.
|
||||
|
||||
## Objectif
|
||||
|
||||
Ajouter `Demo4` dans `kb_demo_app` et les fonctions de lecture associées dans `kb_lib` pour afficher les surfaces de programmes non encore prises en compte par le système.
|
||||
|
||||
Cette fonctionnalité est strictement un cockpit de découverte et de revue.
|
||||
|
||||
Elle ne doit pas :
|
||||
|
||||
- matérialiser automatiquement des contenus inconnus ;
|
||||
- promouvoir automatiquement des discriminators inconnus dans les décodeurs officiels ;
|
||||
- marquer automatiquement un `program_id` comme supporté ;
|
||||
- créer automatiquement des lignes `trade`, `candle`, `fee`, `liquidity`, `reward`, `admin` ou `orderbook` depuis un contenu inconnu.
|
||||
|
||||
Elle doit :
|
||||
|
||||
- afficher les surfaces inconnues ou non supportées ;
|
||||
- les regrouper de manière exploitable ;
|
||||
- montrer les preuves et signatures samples ;
|
||||
- aider à produire des prompts/patchs futurs validés manuellement.
|
||||
|
||||
## Comportement attendu côté utilisateur
|
||||
|
||||
Créer une nouvelle page ou fenêtre, selon le pattern existant :
|
||||
Utiliser :
|
||||
|
||||
```text
|
||||
kb_demo_app/src/demo4.html
|
||||
kb_demo_app/src/demo4.ts
|
||||
docs/prompts/PROMPT_0_7_59_demo4_program_surface_discovery.md
|
||||
```
|
||||
|
||||
ou l’équivalent si l’application utilise un autre routage.
|
||||
|
||||
Demo4 doit proposer des vues pour :
|
||||
|
||||
1. discriminators inconnus sur des decoders connus ;
|
||||
2. `program_id` connus contenant des instructions non mappées par le decoder spécialisé ;
|
||||
3. `upstream_git.instruction_match` groupés par `upstreamDecoderCode`, `upstreamEntryName`, `upstreamDiscriminatorHex` ;
|
||||
4. `program_id` observés dans les transactions mais absents de la matrice de support ;
|
||||
5. logs Anchor `Program log: Instruction: ...` non mappés localement ;
|
||||
6. events Anchor `Program data:` non mappés localement ;
|
||||
7. layouts de comptes récurrents sur instructions inconnues ;
|
||||
8. répartition success/failed pour chaque surface candidate.
|
||||
|
||||
Filtres souhaités :
|
||||
|
||||
```text
|
||||
program_id
|
||||
candidate_decoder_code
|
||||
discriminator_hex
|
||||
instruction_name / nom log Anchor
|
||||
upstream decoder
|
||||
upstream entry name
|
||||
success only / failed only / both
|
||||
minimum observation count
|
||||
minimum tx count
|
||||
from slot / to slot
|
||||
signature contains
|
||||
show only unknown
|
||||
show only upstream fallback
|
||||
show only high-confidence candidates
|
||||
```
|
||||
|
||||
Colonnes souhaitées :
|
||||
|
||||
```text
|
||||
candidate_kind
|
||||
program_id
|
||||
candidate_decoder
|
||||
known/unknown status
|
||||
discriminator_hex
|
||||
log_instruction_name
|
||||
anchor_event_discriminator
|
||||
account_count
|
||||
layout_hash
|
||||
observed_count
|
||||
tx_count
|
||||
success_count
|
||||
failed_count
|
||||
first_slot
|
||||
last_slot
|
||||
sample_signature
|
||||
confidence_score
|
||||
confidence_reason
|
||||
status
|
||||
```
|
||||
|
||||
Le panneau de détail doit afficher :
|
||||
|
||||
```text
|
||||
sample signatures
|
||||
accounts_json
|
||||
data_json / data prefix
|
||||
logs de transaction
|
||||
inner instructions
|
||||
parsed_json si disponible
|
||||
decoded_payload_json si disponible
|
||||
entrées upstream registry correspondantes
|
||||
preuve de hash Anchor si un nom d’instruction est disponible
|
||||
```
|
||||
|
||||
## Design `kb_lib`
|
||||
|
||||
Ajouter des requêtes read-only et des DTOs. Fichiers suggérés :
|
||||
|
||||
```text
|
||||
kb_lib/src/program_surface_discovery.rs
|
||||
kb_lib/src/db/dtos/program_surface_candidate_summary.rs
|
||||
kb_lib/src/db/dtos/program_surface_candidate_sample.rs
|
||||
kb_lib/src/db/queries/program_surface_discovery.rs
|
||||
```
|
||||
|
||||
Si un statut persistant est nécessaire, ajouter :
|
||||
|
||||
```text
|
||||
kb_lib/src/db/entities/program_surface_candidate.rs
|
||||
kb_lib/src/db/queries/program_surface_candidates.rs
|
||||
```
|
||||
|
||||
Ne pas placer les DTO/entities dans les fichiers de requêtes.
|
||||
|
||||
Statuts candidats suggérés :
|
||||
|
||||
```text
|
||||
new
|
||||
reviewed
|
||||
accepted
|
||||
rejected
|
||||
promoted
|
||||
ignored
|
||||
```
|
||||
|
||||
Si une table persistante est ajoutée, la migration doit être explicite, idempotente et testée.
|
||||
|
||||
## Scoring de découverte
|
||||
|
||||
Le scoring est indicatif uniquement. Il ne doit jamais déclencher une matérialisation.
|
||||
|
||||
Signaux de confiance possibles :
|
||||
|
||||
| Signal | Effet |
|
||||
|---|---:|
|
||||
| `program_id` connu, discriminator inconnu | +20 |
|
||||
| log Anchor `Instruction: X` trouvé | +30 |
|
||||
| `sha256("global:x")` correspond au discriminator | +50 |
|
||||
| observations success répétées | +10 |
|
||||
| account count/layout stable | +10 |
|
||||
| inner instruction family cohérente avec l’action | +10 |
|
||||
| uniquement des transactions failed | -20 |
|
||||
| nom très générique comme `swap`, `claim`, `initialize` sans autre preuve | -15 |
|
||||
| `program_id` inconnu et observation unique | -25 |
|
||||
|
||||
## Helper Anchor
|
||||
|
||||
Ajouter un helper qui normalise les noms d’instructions Anchor depuis les logs :
|
||||
|
||||
```text
|
||||
Program log: Instruction: InitializePresetParameterV2
|
||||
-> initialize_preset_parameter_v2
|
||||
-> sha256("global:initialize_preset_parameter_v2")[0..8]
|
||||
```
|
||||
|
||||
Ce helper doit seulement produire une preuve/candidate record. Il ne doit pas modifier les mappings de decoder.
|
||||
|
||||
## Export Markdown
|
||||
|
||||
Demo4 doit permettre d’exporter un groupe candidat en Markdown pour une future session d’implémentation.
|
||||
|
||||
L’export doit inclure :
|
||||
|
||||
```text
|
||||
candidate decoder
|
||||
program_id
|
||||
discriminator_hex
|
||||
candidate name
|
||||
confidence score
|
||||
preuves/evidence
|
||||
sample signatures
|
||||
account layout
|
||||
logs
|
||||
inner instruction summary
|
||||
proposed target table éventuelle
|
||||
warning explicite : non implémenté, non matérialisé
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
Ajouter des tests offline pour :
|
||||
|
||||
- normalisation des noms Anchor depuis logs ;
|
||||
- calcul de discriminators Anchor pour des noms samples ;
|
||||
- groupement par program/discriminator/layout ;
|
||||
- ordre de score ;
|
||||
- sérialisation/désérialisation des DTOs si utilisés ;
|
||||
- validation des paramètres de commandes UI.
|
||||
|
||||
Aucun test ne doit dépendre de RPC ou du réseau.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
cargo fmt
|
||||
cargo test -p kb_lib program_surface
|
||||
cargo test -p kb_lib
|
||||
cargo clippy -p kb_lib --all-targets -- -D warnings
|
||||
```
|
||||
|
||||
Pour Tauri/frontend, lancer la commande de build/test existante du projet si elle existe.
|
||||
|
||||
## Résultat attendu
|
||||
|
||||
L’utilisateur peut ouvrir Demo4 et voir immédiatement les surfaces unsupported/upstream/unknown présentes dans la base SQLite courante, sans rescanner la blockchain.
|
||||
|
||||
Demo4 est un cockpit de découverte uniquement. Il ne change pas la matérialisation métier.
|
||||
|
||||
@@ -0,0 +1,447 @@
|
||||
<!-- file: docs/prompts/PROMPT_0_7_58_sqlite_db_transaction_merger_binary.md -->
|
||||
|
||||
# Prompt — 0.7.58 Binaire de fusion de bases SQLite transactionnelles + validation anti-régression inter-DEX
|
||||
|
||||
## Contexte
|
||||
|
||||
Nous reprenons le workspace Rust `khadhroony-bobobot` après :
|
||||
|
||||
```text
|
||||
0.7.57 -> meteora_dlmm clos
|
||||
0.7.57-pre.015..023 -> nettoyage PumpSwap / guard PumpFees après régression cross-surface
|
||||
```
|
||||
|
||||
Décision de planification mise à jour :
|
||||
|
||||
```text
|
||||
0.7.58 -> sqlite_db_transaction_merger
|
||||
0.7.59 -> demo4_program_surface_discovery
|
||||
0.7.60 -> meteora_damm_v1
|
||||
0.7.61 -> meteora_damm_v2
|
||||
```
|
||||
|
||||
Le binaire de fusion passe avant `demo4`, car il devient un outil de non-régression indispensable pour les futurs décodeurs/materializers.
|
||||
|
||||
## Objectif principal
|
||||
|
||||
Créer un outil binaire de fusion de bases SQLite transactionnelles permettant de construire une base consolidée de corpus, par exemple `final.db`, à partir :
|
||||
|
||||
```text
|
||||
final.db existante
|
||||
+ base dédiée pump_swap.db
|
||||
+ base dédiée pump_fun.db
|
||||
+ base dédiée pump_fees.db
|
||||
+ base dédiée raydium_*.db
|
||||
+ base dédiée meteora_*.db
|
||||
```
|
||||
|
||||
Le binaire doit fusionner les transactions/instructions déjà backfillées sans RPC, sans redécoder et sans matérialiser pendant le merge.
|
||||
|
||||
Ensuite, la base consolidée doit être rejouable localement avec :
|
||||
|
||||
```text
|
||||
metadata=no
|
||||
skipDexDecode=no
|
||||
forceDexDecode=yes
|
||||
deferInstructionObservations=yes
|
||||
```
|
||||
|
||||
But : détecter les régressions inter-DEX comme celle observée où un décodage `pump_fees` tronqué interrompait la matérialisation `pump_swap.buy_exact_quote_in` dans la même transaction.
|
||||
|
||||
## Règle de workflow future
|
||||
|
||||
Pour chaque nouveau DEX ou nouvelle surface :
|
||||
|
||||
1. Créer une base vide dédiée au DEX en cours.
|
||||
2. Backfiller uniquement les signatures/pools nécessaires pour ce DEX.
|
||||
3. Développer le decoder/materializer sur cette base dédiée.
|
||||
4. Clore avec les SQL propres du DEX.
|
||||
5. Fusionner la base dédiée dans `final.db` ou dans une copie `final.next.db`.
|
||||
6. Rejouer `final.next.db` avec `forceDexDecode=yes`.
|
||||
7. Lancer les validations globales anti-régression sur Pump/Raydium/Meteora et sur les surfaces closes.
|
||||
8. Promouvoir `final.next.db` en `final.db` seulement si les gates sont propres.
|
||||
|
||||
Commande conceptuelle :
|
||||
|
||||
```bash
|
||||
cargo run -p kb_tools --bin kb_db_merge -- --output ./final.next.db --input ./final.db --input ./corpus/pump_swap.db --input ./corpus/pump_fees.db --mode raw-corpus --dry-run
|
||||
```
|
||||
|
||||
Puis, après validation dry-run :
|
||||
|
||||
```bash
|
||||
cargo run -p kb_tools --bin kb_db_merge -- --output ./final.next.db --input ./final.db --input ./corpus/new_dex.db --mode raw-corpus --replace-output
|
||||
```
|
||||
|
||||
## Emplacement recommandé
|
||||
|
||||
Créer un package outil séparé :
|
||||
|
||||
```text
|
||||
kb_tools/
|
||||
Cargo.toml
|
||||
src/bin/kb_db_merge.rs
|
||||
```
|
||||
|
||||
Ajouter `kb_tools` dans le workspace principal.
|
||||
|
||||
Alternative acceptable si la structure workspace rend cela plus simple :
|
||||
|
||||
```text
|
||||
kb_lib/src/bin/kb_db_merge.rs
|
||||
```
|
||||
|
||||
Mais privilégier `kb_tools` pour éviter de mélanger outil CLI et librairie métier.
|
||||
|
||||
## Contraintes de code
|
||||
|
||||
Respecter les contraintes projet :
|
||||
|
||||
- Rust 2024 ;
|
||||
- async-first si accès DB async ;
|
||||
- tracing obligatoire ;
|
||||
- pas de `?` dans le code applicatif ;
|
||||
- pas de `unwrap` / `expect` hors tests ;
|
||||
- pas de `anyhow` / `thiserror` ;
|
||||
- pas de `mod.rs` ;
|
||||
- pas de `pub mod`, utiliser `mod` + `pub use` ;
|
||||
- imports directs seulement pour les traits ;
|
||||
- tests offline ;
|
||||
- types DB sous `kb_lib/src/db/entities/` et `kb_lib/src/db/dtos/`, pas sous `queries/` ;
|
||||
- si des requêtes DB sont ajoutées/modifiées : mettre à jour les re-exports dans `kb_lib/src/db.rs` puis `kb_lib/src/lib.rs`.
|
||||
|
||||
## Modes CLI
|
||||
|
||||
Modes initiaux :
|
||||
|
||||
```text
|
||||
raw-corpus
|
||||
signatures-only
|
||||
full-copy-safe
|
||||
```
|
||||
|
||||
Le mode par défaut doit être :
|
||||
|
||||
```text
|
||||
raw-corpus
|
||||
```
|
||||
|
||||
### `raw-corpus`
|
||||
|
||||
Copier uniquement les données nécessaires à un replay local fiable :
|
||||
|
||||
```text
|
||||
k_sol_chain_transactions
|
||||
k_sol_chain_instructions
|
||||
```
|
||||
|
||||
Ne pas copier les tables matérialisées par défaut :
|
||||
|
||||
```text
|
||||
k_sol_dex_decoded_events
|
||||
k_sol_trade_events
|
||||
k_sol_liquidity_events
|
||||
k_sol_pool_lifecycle_events
|
||||
k_sol_pair_candles
|
||||
k_sol_fee_events
|
||||
k_sol_reward_events
|
||||
k_sol_pool_admin_events
|
||||
k_sol_orderbook_events
|
||||
k_sol_token_account_events
|
||||
k_sol_instruction_observations
|
||||
k_sol_dex_event_coverage_entries
|
||||
```
|
||||
|
||||
Raison : ces tables dépendent de la version de decoder/materializer et doivent être reconstruites par replay local.
|
||||
|
||||
### `signatures-only`
|
||||
|
||||
Créer une table de staging de signatures/slots/source, sans copier les transactions complètes. Ce mode est utile pour audit ou pour préparer des backfills contrôlés.
|
||||
|
||||
### `full-copy-safe`
|
||||
|
||||
Mode optionnel, non prioritaire.
|
||||
|
||||
Copier aussi des lignes décodées/matérialisées uniquement si :
|
||||
|
||||
- le schema version est compatible ;
|
||||
- la version logique de decoder est identique ;
|
||||
- toutes les foreign keys peuvent être remappées ;
|
||||
- le mode est explicitement demandé.
|
||||
|
||||
Ne jamais en faire le mode par défaut.
|
||||
|
||||
## Options CLI minimales
|
||||
|
||||
```text
|
||||
--output <path>
|
||||
--input <path> répétable
|
||||
--mode <raw-corpus|signatures-only|full-copy-safe>
|
||||
--dry-run
|
||||
--replace-output
|
||||
--source-label <label> répétable ou inféré depuis le fichier
|
||||
--limit <n> optionnel pour tests
|
||||
--batch-size <n> optionnel
|
||||
```
|
||||
|
||||
Options utiles pour `final.db` :
|
||||
|
||||
```text
|
||||
--allow-existing-output
|
||||
--merge-into-copy-of <path>
|
||||
--conflict-policy <record|prefer-complete|fail>
|
||||
```
|
||||
|
||||
Par défaut : ne pas écraser l’output existant sans `--replace-output` ou `--merge-into-copy-of`.
|
||||
|
||||
## Politique de déduplication
|
||||
|
||||
Identité canonique :
|
||||
|
||||
```text
|
||||
signature
|
||||
```
|
||||
|
||||
Règles :
|
||||
|
||||
- Une signature déjà présente dans l’output ne doit pas être dupliquée.
|
||||
- Si `slot`, `err_json`, `transaction_json`, `meta_json` ou les instructions diffèrent, enregistrer un conflit.
|
||||
- Ne pas écraser silencieusement.
|
||||
- Si une version est plus complète, ne la préférer que si la politique `prefer-complete` est demandée et que le conflit est journalisé.
|
||||
- Garder une provenance complète source -> output.
|
||||
|
||||
Tables suggérées :
|
||||
|
||||
```text
|
||||
k_sol_db_merge_sources
|
||||
k_sol_db_merge_transactions
|
||||
k_sol_db_merge_conflicts
|
||||
```
|
||||
|
||||
Champs source suggérés :
|
||||
|
||||
```text
|
||||
source_id
|
||||
source_path
|
||||
source_label
|
||||
source_schema_version
|
||||
source_created_at
|
||||
input_transaction_count
|
||||
copied_transaction_count
|
||||
skipped_duplicate_count
|
||||
conflict_count
|
||||
```
|
||||
|
||||
Champs transaction de merge suggérés :
|
||||
|
||||
```text
|
||||
signature
|
||||
slot
|
||||
source_id
|
||||
source_transaction_id
|
||||
output_transaction_id
|
||||
copy_status
|
||||
conflict_status
|
||||
copied_at
|
||||
```
|
||||
|
||||
## Compatibilité de schéma
|
||||
|
||||
Le binaire doit inspecter chaque input via :
|
||||
|
||||
```sql
|
||||
SELECT name, sql FROM sqlite_master WHERE type = 'table';
|
||||
PRAGMA table_info(k_sol_chain_transactions);
|
||||
PRAGMA table_info(k_sol_chain_instructions);
|
||||
```
|
||||
|
||||
Pour `raw-corpus`, refuser proprement une DB qui ne contient pas :
|
||||
|
||||
```text
|
||||
k_sol_chain_transactions
|
||||
k_sol_chain_instructions
|
||||
```
|
||||
|
||||
ou les colonnes nécessaires au replay local.
|
||||
|
||||
Le message d’erreur doit indiquer :
|
||||
|
||||
```text
|
||||
source DB
|
||||
missing table
|
||||
missing column
|
||||
mode demandé
|
||||
```
|
||||
|
||||
## Stratégie de copie
|
||||
|
||||
Algorithme recommandé :
|
||||
|
||||
1. Créer ou initialiser l’output avec le schéma courant `kb_lib`.
|
||||
2. Enregistrer chaque input dans `k_sol_db_merge_sources`.
|
||||
3. Lire les transactions source par slot/signature.
|
||||
4. Pour chaque transaction :
|
||||
- si signature absente de l’output : insérer transaction + instructions enfants ;
|
||||
- si signature présente : comparer les champs canoniques ;
|
||||
- si identique : enregistrer duplicate skipped ;
|
||||
- si différent : enregistrer conflit.
|
||||
5. Remapper `source_transaction_id -> output_transaction_id` pour les instructions.
|
||||
6. Commit par batch.
|
||||
7. Imprimer un résumé final.
|
||||
|
||||
## Validation anti-régression intégrée à 0.7.58
|
||||
|
||||
Ajouter une documentation et, si possible, un script SQL :
|
||||
|
||||
```text
|
||||
validation_sql/SQL_VALIDATION_DB_MERGE_0_7_58.sql
|
||||
validation_sql/SQL_VALIDATION_CROSS_DEX_REGRESSION_0_7_58.sql
|
||||
```
|
||||
|
||||
Checks merge minimaux :
|
||||
|
||||
```sql
|
||||
-- duplicate signatures in output should be empty
|
||||
SELECT signature, COUNT(*)
|
||||
FROM k_sol_chain_transactions
|
||||
GROUP BY signature
|
||||
HAVING COUNT(*) > 1;
|
||||
|
||||
-- orphan instructions should be empty
|
||||
SELECT ins.id
|
||||
FROM k_sol_chain_instructions ins
|
||||
LEFT JOIN k_sol_chain_transactions tx ON tx.id = ins.transaction_id
|
||||
WHERE tx.id IS NULL;
|
||||
|
||||
-- conflicts summary
|
||||
SELECT *
|
||||
FROM k_sol_db_merge_conflicts
|
||||
ORDER BY id DESC
|
||||
LIMIT 100;
|
||||
```
|
||||
|
||||
Checks anti-régression DEX après replay de `final.next.db` :
|
||||
|
||||
```sql
|
||||
-- successful decoded events without any materialized target
|
||||
SELECT
|
||||
de.protocol_name,
|
||||
de.event_kind,
|
||||
json_extract(de.payload_json, '$.eventActionability') AS event_actionability,
|
||||
json_extract(de.payload_json, '$.skipTradeReason') AS skip_trade_reason,
|
||||
COUNT(*) AS missing_count,
|
||||
MIN(tx.signature) AS sample_signature
|
||||
FROM k_sol_dex_decoded_events de
|
||||
JOIN k_sol_chain_transactions tx ON tx.id = de.transaction_id
|
||||
LEFT JOIN k_sol_trade_events te ON te.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_liquidity_events lie ON lie.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_pool_lifecycle_events ple ON ple.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_fee_events fee ON fee.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_reward_events rew ON rew.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_pool_admin_events adm ON adm.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_orderbook_events obe ON obe.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_token_account_events tae ON tae.decoded_event_id = de.id
|
||||
WHERE (tx.err_json IS NULL OR tx.err_json = '' OR tx.err_json = 'null')
|
||||
AND te.id IS NULL
|
||||
AND lie.id IS NULL
|
||||
AND ple.id IS NULL
|
||||
AND fee.id IS NULL
|
||||
AND rew.id IS NULL
|
||||
AND adm.id IS NULL
|
||||
AND obe.id IS NULL
|
||||
AND tae.id IS NULL
|
||||
GROUP BY de.protocol_name, de.event_kind, event_actionability, skip_trade_reason
|
||||
ORDER BY missing_count DESC, de.protocol_name, de.event_kind;
|
||||
```
|
||||
|
||||
Cette requête ne doit pas forcément être vide, mais tout résidu doit être explicitement classé : failed-only, decoded-only justifié, non_actionable prouvé, ou nouveau bug.
|
||||
|
||||
## Vérification/correction Pump/Raydium incluse dans 0.7.58
|
||||
|
||||
La tranche `0.7.58` doit inclure un passage de non-régression sur les surfaces déjà closes, au minimum :
|
||||
|
||||
```text
|
||||
pump_swap
|
||||
pump_fun
|
||||
pump_fees
|
||||
raydium_cpmm
|
||||
raydium_clmm
|
||||
raydium_amm_v4
|
||||
raydium_stable_swap
|
||||
raydium_launchpad
|
||||
meteora_dbc
|
||||
meteora_dlmm
|
||||
```
|
||||
|
||||
Objectif : détecter et corriger les régressions cross-surface, par exemple :
|
||||
|
||||
```text
|
||||
un decoder A ne doit pas faire échouer la matérialisation d’un decoder B dans la même transaction.
|
||||
```
|
||||
|
||||
Règle de decoder :
|
||||
|
||||
- un payload tronqué/incompatible sur une surface secondaire ne doit pas aborter toute la transaction si l’entrée peut être ignorée proprement ;
|
||||
- préférer `Ok(None)` + observation/debug contrôlé pour les payloads tronqués connus ;
|
||||
- conserver `Err` pour corruption critique, violation de schéma interne ou incohérence qui rend la transaction non fiable ;
|
||||
- ajouter des tests synthétiques pour chaque guard.
|
||||
|
||||
## Tests attendus
|
||||
|
||||
Ajouter tests unitaires/offline pour :
|
||||
|
||||
1. merge d’une DB vers output vide ;
|
||||
2. merge de deux DBs disjointes ;
|
||||
3. duplicate signature identique ;
|
||||
4. duplicate signature conflictuelle ;
|
||||
5. conflit instruction enfant ;
|
||||
6. dry-run sans écriture ;
|
||||
7. output existant refusé sans option explicite ;
|
||||
8. source provenance enregistrée ;
|
||||
9. replay final DB possible après merge raw-corpus ;
|
||||
10. non-régression PumpSwap/PumpFees : payload PumpFees tronqué n’empêche pas PumpSwap de matérialiser un trade exact.
|
||||
|
||||
## Livrables attendus
|
||||
|
||||
```text
|
||||
kb_tools/Cargo.toml
|
||||
kb_tools/src/bin/kb_db_merge.rs
|
||||
kb_lib/src/db/entities/db_merge_source.rs
|
||||
kb_lib/src/db/entities/db_merge_transaction.rs
|
||||
kb_lib/src/db/entities/db_merge_conflict.rs
|
||||
kb_lib/src/db/dtos/db_merge_*.rs
|
||||
kb_lib/src/db/queries/db_merge_*.rs
|
||||
validation_sql/SQL_VALIDATION_DB_MERGE_0_7_58.sql
|
||||
validation_sql/SQL_VALIDATION_CROSS_DEX_REGRESSION_0_7_58.sql
|
||||
docs/reports/SQLITE_DB_TRANSACTION_MERGER_0_7_58.md
|
||||
```
|
||||
|
||||
Mettre à jour :
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
kb_lib/src/db.rs
|
||||
kb_lib/src/lib.rs
|
||||
README.md
|
||||
ROADMAP.md
|
||||
CHANGELOG.md
|
||||
```
|
||||
|
||||
## Critères de clôture 0.7.58
|
||||
|
||||
- `cargo test -p kb_lib` OK ;
|
||||
- `cargo test -p kb_tools` OK si package séparé ;
|
||||
- clippy `-D warnings` OK ;
|
||||
- dry-run merge lisible ;
|
||||
- merge réel de plusieurs bases OK ;
|
||||
- pas de duplicate signatures ;
|
||||
- pas d’instructions orphelines ;
|
||||
- conflits journalisés ;
|
||||
- replay local de `final.next.db` OK ;
|
||||
- validation anti-régression Pump/Raydium/Meteora exécutée et documentée.
|
||||
|
||||
## Note finale
|
||||
|
||||
Le merger ne remplace pas `demo3` ni `demo4`.
|
||||
|
||||
Il sert à construire un corpus consolidé de non-régression à partir des bases dédiées. `demo4`, déplacé en `0.7.59`, servira ensuite à explorer les surfaces encore inconnues dans cette base consolidée.
|
||||
@@ -1,245 +1,18 @@
|
||||
<!-- file: docs/prompts/PROMPT_0_7_58_demo4_program_surface_discovery.md -->
|
||||
|
||||
# Prompt — 0.7.58 Demo4 Program Surface Discovery
|
||||
# OBSOLETE — Prompt déplacé
|
||||
|
||||
## Contexte
|
||||
Ce prompt n'est plus la cible `0.7.58`.
|
||||
|
||||
Nous reprenons le workspace Rust/Tauri `khadhroony-bobobot` après la clôture de `0.7.57 meteora_dlmm`.
|
||||
|
||||
État validé :
|
||||
Nouvel ordre validé :
|
||||
|
||||
```text
|
||||
0.7.57 meteora_dlmm clos
|
||||
cargo test -p kb_lib -> 460 passed
|
||||
cargo clippy -p kb_lib --all-targets -- -D warnings -> OK
|
||||
replay -> 769 replayed, 106 trades, 664 liquidity, 1107 lifecycle, 424 candles
|
||||
instructionObservations = 8062
|
||||
catalogue = 169 tokens / 218 pools / 218 pairs
|
||||
0.7.58 -> sqlite_db_transaction_merger
|
||||
0.7.59 -> demo4_program_surface_discovery
|
||||
```
|
||||
|
||||
Contraintes projet à respecter :
|
||||
|
||||
- Rust 2024.
|
||||
- Code async-first.
|
||||
- Pas de `?`, `unwrap`, `expect` dans le code applicatif.
|
||||
- Pas de `anyhow`, pas de `thiserror`.
|
||||
- Pas de `mod.rs`.
|
||||
- Pas de `pub mod` ; utiliser `mod` privé + `pub use`.
|
||||
- Imports uniquement pour les traits quand c’est possible.
|
||||
- `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]` doivent rester propres.
|
||||
- Tests offline.
|
||||
- Les nouvelles requêtes DB doivent mettre à jour les re-exports dans `kb_lib/src/db.rs` puis `kb_lib/src/lib.rs`.
|
||||
- Les structs DB doivent aller dans `kb_lib/src/db/entities/*.rs` et `kb_lib/src/db/dtos/*.rs`, pas dans les fichiers de requêtes.
|
||||
|
||||
## Objectif
|
||||
|
||||
Ajouter `Demo4` dans `kb_demo_app` et les fonctions de lecture associées dans `kb_lib` pour afficher les surfaces de programmes non encore prises en compte par le système.
|
||||
|
||||
Cette fonctionnalité est strictement un cockpit de découverte et de revue.
|
||||
|
||||
Elle ne doit pas :
|
||||
|
||||
- matérialiser automatiquement des contenus inconnus ;
|
||||
- promouvoir automatiquement des discriminators inconnus dans les décodeurs officiels ;
|
||||
- marquer automatiquement un `program_id` comme supporté ;
|
||||
- créer automatiquement des lignes `trade`, `candle`, `fee`, `liquidity`, `reward`, `admin` ou `orderbook` depuis un contenu inconnu.
|
||||
|
||||
Elle doit :
|
||||
|
||||
- afficher les surfaces inconnues ou non supportées ;
|
||||
- les regrouper de manière exploitable ;
|
||||
- montrer les preuves et signatures samples ;
|
||||
- aider à produire des prompts/patchs futurs validés manuellement.
|
||||
|
||||
## Comportement attendu côté utilisateur
|
||||
|
||||
Créer une nouvelle page ou fenêtre, selon le pattern existant :
|
||||
Utiliser :
|
||||
|
||||
```text
|
||||
kb_demo_app/src/demo4.html
|
||||
kb_demo_app/src/demo4.ts
|
||||
docs/prompts/PROMPT_0_7_59_demo4_program_surface_discovery.md
|
||||
```
|
||||
|
||||
ou l’équivalent si l’application utilise un autre routage.
|
||||
|
||||
Demo4 doit proposer des vues pour :
|
||||
|
||||
1. discriminators inconnus sur des decoders connus ;
|
||||
2. `program_id` connus contenant des instructions non mappées par le decoder spécialisé ;
|
||||
3. `upstream_git.instruction_match` groupés par `upstreamDecoderCode`, `upstreamEntryName`, `upstreamDiscriminatorHex` ;
|
||||
4. `program_id` observés dans les transactions mais absents de la matrice de support ;
|
||||
5. logs Anchor `Program log: Instruction: ...` non mappés localement ;
|
||||
6. events Anchor `Program data:` non mappés localement ;
|
||||
7. layouts de comptes récurrents sur instructions inconnues ;
|
||||
8. répartition success/failed pour chaque surface candidate.
|
||||
|
||||
Filtres souhaités :
|
||||
|
||||
```text
|
||||
program_id
|
||||
candidate_decoder_code
|
||||
discriminator_hex
|
||||
instruction_name / nom log Anchor
|
||||
upstream decoder
|
||||
upstream entry name
|
||||
success only / failed only / both
|
||||
minimum observation count
|
||||
minimum tx count
|
||||
from slot / to slot
|
||||
signature contains
|
||||
show only unknown
|
||||
show only upstream fallback
|
||||
show only high-confidence candidates
|
||||
```
|
||||
|
||||
Colonnes souhaitées :
|
||||
|
||||
```text
|
||||
candidate_kind
|
||||
program_id
|
||||
candidate_decoder
|
||||
known/unknown status
|
||||
discriminator_hex
|
||||
log_instruction_name
|
||||
anchor_event_discriminator
|
||||
account_count
|
||||
layout_hash
|
||||
observed_count
|
||||
tx_count
|
||||
success_count
|
||||
failed_count
|
||||
first_slot
|
||||
last_slot
|
||||
sample_signature
|
||||
confidence_score
|
||||
confidence_reason
|
||||
status
|
||||
```
|
||||
|
||||
Le panneau de détail doit afficher :
|
||||
|
||||
```text
|
||||
sample signatures
|
||||
accounts_json
|
||||
data_json / data prefix
|
||||
logs de transaction
|
||||
inner instructions
|
||||
parsed_json si disponible
|
||||
decoded_payload_json si disponible
|
||||
entrées upstream registry correspondantes
|
||||
preuve de hash Anchor si un nom d’instruction est disponible
|
||||
```
|
||||
|
||||
## Design `kb_lib`
|
||||
|
||||
Ajouter des requêtes read-only et des DTOs. Fichiers suggérés :
|
||||
|
||||
```text
|
||||
kb_lib/src/program_surface_discovery.rs
|
||||
kb_lib/src/db/dtos/program_surface_candidate_summary.rs
|
||||
kb_lib/src/db/dtos/program_surface_candidate_sample.rs
|
||||
kb_lib/src/db/queries/program_surface_discovery.rs
|
||||
```
|
||||
|
||||
Si un statut persistant est nécessaire, ajouter :
|
||||
|
||||
```text
|
||||
kb_lib/src/db/entities/program_surface_candidate.rs
|
||||
kb_lib/src/db/queries/program_surface_candidates.rs
|
||||
```
|
||||
|
||||
Ne pas placer les DTO/entities dans les fichiers de requêtes.
|
||||
|
||||
Statuts candidats suggérés :
|
||||
|
||||
```text
|
||||
new
|
||||
reviewed
|
||||
accepted
|
||||
rejected
|
||||
promoted
|
||||
ignored
|
||||
```
|
||||
|
||||
Si une table persistante est ajoutée, la migration doit être explicite, idempotente et testée.
|
||||
|
||||
## Scoring de découverte
|
||||
|
||||
Le scoring est indicatif uniquement. Il ne doit jamais déclencher une matérialisation.
|
||||
|
||||
Signaux de confiance possibles :
|
||||
|
||||
| Signal | Effet |
|
||||
|---|---:|
|
||||
| `program_id` connu, discriminator inconnu | +20 |
|
||||
| log Anchor `Instruction: X` trouvé | +30 |
|
||||
| `sha256("global:x")` correspond au discriminator | +50 |
|
||||
| observations success répétées | +10 |
|
||||
| account count/layout stable | +10 |
|
||||
| inner instruction family cohérente avec l’action | +10 |
|
||||
| uniquement des transactions failed | -20 |
|
||||
| nom très générique comme `swap`, `claim`, `initialize` sans autre preuve | -15 |
|
||||
| `program_id` inconnu et observation unique | -25 |
|
||||
|
||||
## Helper Anchor
|
||||
|
||||
Ajouter un helper qui normalise les noms d’instructions Anchor depuis les logs :
|
||||
|
||||
```text
|
||||
Program log: Instruction: InitializePresetParameterV2
|
||||
-> initialize_preset_parameter_v2
|
||||
-> sha256("global:initialize_preset_parameter_v2")[0..8]
|
||||
```
|
||||
|
||||
Ce helper doit seulement produire une preuve/candidate record. Il ne doit pas modifier les mappings de decoder.
|
||||
|
||||
## Export Markdown
|
||||
|
||||
Demo4 doit permettre d’exporter un groupe candidat en Markdown pour une future session d’implémentation.
|
||||
|
||||
L’export doit inclure :
|
||||
|
||||
```text
|
||||
candidate decoder
|
||||
program_id
|
||||
discriminator_hex
|
||||
candidate name
|
||||
confidence score
|
||||
preuves/evidence
|
||||
sample signatures
|
||||
account layout
|
||||
logs
|
||||
inner instruction summary
|
||||
proposed target table éventuelle
|
||||
warning explicite : non implémenté, non matérialisé
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
Ajouter des tests offline pour :
|
||||
|
||||
- normalisation des noms Anchor depuis logs ;
|
||||
- calcul de discriminators Anchor pour des noms samples ;
|
||||
- groupement par program/discriminator/layout ;
|
||||
- ordre de score ;
|
||||
- sérialisation/désérialisation des DTOs si utilisés ;
|
||||
- validation des paramètres de commandes UI.
|
||||
|
||||
Aucun test ne doit dépendre de RPC ou du réseau.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
cargo fmt
|
||||
cargo test -p kb_lib program_surface
|
||||
cargo test -p kb_lib
|
||||
cargo clippy -p kb_lib --all-targets -- -D warnings
|
||||
```
|
||||
|
||||
Pour Tauri/frontend, lancer la commande de build/test existante du projet si elle existe.
|
||||
|
||||
## Résultat attendu
|
||||
|
||||
L’utilisateur peut ouvrir Demo4 et voir immédiatement les surfaces unsupported/upstream/unknown présentes dans la base SQLite courante, sans rescanner la blockchain.
|
||||
|
||||
Demo4 est un cockpit de découverte uniquement. Il ne change pas la matérialisation métier.
|
||||
|
||||
@@ -0,0 +1,447 @@
|
||||
<!-- file: docs/prompts/PROMPT_0_7_58_sqlite_db_transaction_merger_binary.md -->
|
||||
|
||||
# Prompt — 0.7.58 Binaire de fusion de bases SQLite transactionnelles + validation anti-régression inter-DEX
|
||||
|
||||
## Contexte
|
||||
|
||||
Nous reprenons le workspace Rust `khadhroony-bobobot` après :
|
||||
|
||||
```text
|
||||
0.7.57 -> meteora_dlmm clos
|
||||
0.7.57-pre.015..023 -> nettoyage PumpSwap / guard PumpFees après régression cross-surface
|
||||
```
|
||||
|
||||
Décision de planification mise à jour :
|
||||
|
||||
```text
|
||||
0.7.58 -> sqlite_db_transaction_merger
|
||||
0.7.59 -> demo4_program_surface_discovery
|
||||
0.7.60 -> meteora_damm_v1
|
||||
0.7.61 -> meteora_damm_v2
|
||||
```
|
||||
|
||||
Le binaire de fusion passe avant `demo4`, car il devient un outil de non-régression indispensable pour les futurs décodeurs/materializers.
|
||||
|
||||
## Objectif principal
|
||||
|
||||
Créer un outil binaire de fusion de bases SQLite transactionnelles permettant de construire une base consolidée de corpus, par exemple `final.db`, à partir :
|
||||
|
||||
```text
|
||||
final.db existante
|
||||
+ base dédiée pump_swap.db
|
||||
+ base dédiée pump_fun.db
|
||||
+ base dédiée pump_fees.db
|
||||
+ base dédiée raydium_*.db
|
||||
+ base dédiée meteora_*.db
|
||||
```
|
||||
|
||||
Le binaire doit fusionner les transactions/instructions déjà backfillées sans RPC, sans redécoder et sans matérialiser pendant le merge.
|
||||
|
||||
Ensuite, la base consolidée doit être rejouable localement avec :
|
||||
|
||||
```text
|
||||
metadata=no
|
||||
skipDexDecode=no
|
||||
forceDexDecode=yes
|
||||
deferInstructionObservations=yes
|
||||
```
|
||||
|
||||
But : détecter les régressions inter-DEX comme celle observée où un décodage `pump_fees` tronqué interrompait la matérialisation `pump_swap.buy_exact_quote_in` dans la même transaction.
|
||||
|
||||
## Règle de workflow future
|
||||
|
||||
Pour chaque nouveau DEX ou nouvelle surface :
|
||||
|
||||
1. Créer une base vide dédiée au DEX en cours.
|
||||
2. Backfiller uniquement les signatures/pools nécessaires pour ce DEX.
|
||||
3. Développer le decoder/materializer sur cette base dédiée.
|
||||
4. Clore avec les SQL propres du DEX.
|
||||
5. Fusionner la base dédiée dans `final.db` ou dans une copie `final.next.db`.
|
||||
6. Rejouer `final.next.db` avec `forceDexDecode=yes`.
|
||||
7. Lancer les validations globales anti-régression sur Pump/Raydium/Meteora et sur les surfaces closes.
|
||||
8. Promouvoir `final.next.db` en `final.db` seulement si les gates sont propres.
|
||||
|
||||
Commande conceptuelle :
|
||||
|
||||
```bash
|
||||
cargo run -p kb_tools --bin kb_db_merge -- --output ./final.next.db --input ./final.db --input ./corpus/pump_swap.db --input ./corpus/pump_fees.db --mode raw-corpus --dry-run
|
||||
```
|
||||
|
||||
Puis, après validation dry-run :
|
||||
|
||||
```bash
|
||||
cargo run -p kb_tools --bin kb_db_merge -- --output ./final.next.db --input ./final.db --input ./corpus/new_dex.db --mode raw-corpus --replace-output
|
||||
```
|
||||
|
||||
## Emplacement recommandé
|
||||
|
||||
Créer un package outil séparé :
|
||||
|
||||
```text
|
||||
kb_tools/
|
||||
Cargo.toml
|
||||
src/bin/kb_db_merge.rs
|
||||
```
|
||||
|
||||
Ajouter `kb_tools` dans le workspace principal.
|
||||
|
||||
Alternative acceptable si la structure workspace rend cela plus simple :
|
||||
|
||||
```text
|
||||
kb_lib/src/bin/kb_db_merge.rs
|
||||
```
|
||||
|
||||
Mais privilégier `kb_tools` pour éviter de mélanger outil CLI et librairie métier.
|
||||
|
||||
## Contraintes de code
|
||||
|
||||
Respecter les contraintes projet :
|
||||
|
||||
- Rust 2024 ;
|
||||
- async-first si accès DB async ;
|
||||
- tracing obligatoire ;
|
||||
- pas de `?` dans le code applicatif ;
|
||||
- pas de `unwrap` / `expect` hors tests ;
|
||||
- pas de `anyhow` / `thiserror` ;
|
||||
- pas de `mod.rs` ;
|
||||
- pas de `pub mod`, utiliser `mod` + `pub use` ;
|
||||
- imports directs seulement pour les traits ;
|
||||
- tests offline ;
|
||||
- types DB sous `kb_lib/src/db/entities/` et `kb_lib/src/db/dtos/`, pas sous `queries/` ;
|
||||
- si des requêtes DB sont ajoutées/modifiées : mettre à jour les re-exports dans `kb_lib/src/db.rs` puis `kb_lib/src/lib.rs`.
|
||||
|
||||
## Modes CLI
|
||||
|
||||
Modes initiaux :
|
||||
|
||||
```text
|
||||
raw-corpus
|
||||
signatures-only
|
||||
full-copy-safe
|
||||
```
|
||||
|
||||
Le mode par défaut doit être :
|
||||
|
||||
```text
|
||||
raw-corpus
|
||||
```
|
||||
|
||||
### `raw-corpus`
|
||||
|
||||
Copier uniquement les données nécessaires à un replay local fiable :
|
||||
|
||||
```text
|
||||
k_sol_chain_transactions
|
||||
k_sol_chain_instructions
|
||||
```
|
||||
|
||||
Ne pas copier les tables matérialisées par défaut :
|
||||
|
||||
```text
|
||||
k_sol_dex_decoded_events
|
||||
k_sol_trade_events
|
||||
k_sol_liquidity_events
|
||||
k_sol_pool_lifecycle_events
|
||||
k_sol_pair_candles
|
||||
k_sol_fee_events
|
||||
k_sol_reward_events
|
||||
k_sol_pool_admin_events
|
||||
k_sol_orderbook_events
|
||||
k_sol_token_account_events
|
||||
k_sol_instruction_observations
|
||||
k_sol_dex_event_coverage_entries
|
||||
```
|
||||
|
||||
Raison : ces tables dépendent de la version de decoder/materializer et doivent être reconstruites par replay local.
|
||||
|
||||
### `signatures-only`
|
||||
|
||||
Créer une table de staging de signatures/slots/source, sans copier les transactions complètes. Ce mode est utile pour audit ou pour préparer des backfills contrôlés.
|
||||
|
||||
### `full-copy-safe`
|
||||
|
||||
Mode optionnel, non prioritaire.
|
||||
|
||||
Copier aussi des lignes décodées/matérialisées uniquement si :
|
||||
|
||||
- le schema version est compatible ;
|
||||
- la version logique de decoder est identique ;
|
||||
- toutes les foreign keys peuvent être remappées ;
|
||||
- le mode est explicitement demandé.
|
||||
|
||||
Ne jamais en faire le mode par défaut.
|
||||
|
||||
## Options CLI minimales
|
||||
|
||||
```text
|
||||
--output <path>
|
||||
--input <path> répétable
|
||||
--mode <raw-corpus|signatures-only|full-copy-safe>
|
||||
--dry-run
|
||||
--replace-output
|
||||
--source-label <label> répétable ou inféré depuis le fichier
|
||||
--limit <n> optionnel pour tests
|
||||
--batch-size <n> optionnel
|
||||
```
|
||||
|
||||
Options utiles pour `final.db` :
|
||||
|
||||
```text
|
||||
--allow-existing-output
|
||||
--merge-into-copy-of <path>
|
||||
--conflict-policy <record|prefer-complete|fail>
|
||||
```
|
||||
|
||||
Par défaut : ne pas écraser l’output existant sans `--replace-output` ou `--merge-into-copy-of`.
|
||||
|
||||
## Politique de déduplication
|
||||
|
||||
Identité canonique :
|
||||
|
||||
```text
|
||||
signature
|
||||
```
|
||||
|
||||
Règles :
|
||||
|
||||
- Une signature déjà présente dans l’output ne doit pas être dupliquée.
|
||||
- Si `slot`, `err_json`, `transaction_json`, `meta_json` ou les instructions diffèrent, enregistrer un conflit.
|
||||
- Ne pas écraser silencieusement.
|
||||
- Si une version est plus complète, ne la préférer que si la politique `prefer-complete` est demandée et que le conflit est journalisé.
|
||||
- Garder une provenance complète source -> output.
|
||||
|
||||
Tables suggérées :
|
||||
|
||||
```text
|
||||
k_sol_db_merge_sources
|
||||
k_sol_db_merge_transactions
|
||||
k_sol_db_merge_conflicts
|
||||
```
|
||||
|
||||
Champs source suggérés :
|
||||
|
||||
```text
|
||||
source_id
|
||||
source_path
|
||||
source_label
|
||||
source_schema_version
|
||||
source_created_at
|
||||
input_transaction_count
|
||||
copied_transaction_count
|
||||
skipped_duplicate_count
|
||||
conflict_count
|
||||
```
|
||||
|
||||
Champs transaction de merge suggérés :
|
||||
|
||||
```text
|
||||
signature
|
||||
slot
|
||||
source_id
|
||||
source_transaction_id
|
||||
output_transaction_id
|
||||
copy_status
|
||||
conflict_status
|
||||
copied_at
|
||||
```
|
||||
|
||||
## Compatibilité de schéma
|
||||
|
||||
Le binaire doit inspecter chaque input via :
|
||||
|
||||
```sql
|
||||
SELECT name, sql FROM sqlite_master WHERE type = 'table';
|
||||
PRAGMA table_info(k_sol_chain_transactions);
|
||||
PRAGMA table_info(k_sol_chain_instructions);
|
||||
```
|
||||
|
||||
Pour `raw-corpus`, refuser proprement une DB qui ne contient pas :
|
||||
|
||||
```text
|
||||
k_sol_chain_transactions
|
||||
k_sol_chain_instructions
|
||||
```
|
||||
|
||||
ou les colonnes nécessaires au replay local.
|
||||
|
||||
Le message d’erreur doit indiquer :
|
||||
|
||||
```text
|
||||
source DB
|
||||
missing table
|
||||
missing column
|
||||
mode demandé
|
||||
```
|
||||
|
||||
## Stratégie de copie
|
||||
|
||||
Algorithme recommandé :
|
||||
|
||||
1. Créer ou initialiser l’output avec le schéma courant `kb_lib`.
|
||||
2. Enregistrer chaque input dans `k_sol_db_merge_sources`.
|
||||
3. Lire les transactions source par slot/signature.
|
||||
4. Pour chaque transaction :
|
||||
- si signature absente de l’output : insérer transaction + instructions enfants ;
|
||||
- si signature présente : comparer les champs canoniques ;
|
||||
- si identique : enregistrer duplicate skipped ;
|
||||
- si différent : enregistrer conflit.
|
||||
5. Remapper `source_transaction_id -> output_transaction_id` pour les instructions.
|
||||
6. Commit par batch.
|
||||
7. Imprimer un résumé final.
|
||||
|
||||
## Validation anti-régression intégrée à 0.7.58
|
||||
|
||||
Ajouter une documentation et, si possible, un script SQL :
|
||||
|
||||
```text
|
||||
validation_sql/SQL_VALIDATION_DB_MERGE_0_7_58.sql
|
||||
validation_sql/SQL_VALIDATION_CROSS_DEX_REGRESSION_0_7_58.sql
|
||||
```
|
||||
|
||||
Checks merge minimaux :
|
||||
|
||||
```sql
|
||||
-- duplicate signatures in output should be empty
|
||||
SELECT signature, COUNT(*)
|
||||
FROM k_sol_chain_transactions
|
||||
GROUP BY signature
|
||||
HAVING COUNT(*) > 1;
|
||||
|
||||
-- orphan instructions should be empty
|
||||
SELECT ins.id
|
||||
FROM k_sol_chain_instructions ins
|
||||
LEFT JOIN k_sol_chain_transactions tx ON tx.id = ins.transaction_id
|
||||
WHERE tx.id IS NULL;
|
||||
|
||||
-- conflicts summary
|
||||
SELECT *
|
||||
FROM k_sol_db_merge_conflicts
|
||||
ORDER BY id DESC
|
||||
LIMIT 100;
|
||||
```
|
||||
|
||||
Checks anti-régression DEX après replay de `final.next.db` :
|
||||
|
||||
```sql
|
||||
-- successful decoded events without any materialized target
|
||||
SELECT
|
||||
de.protocol_name,
|
||||
de.event_kind,
|
||||
json_extract(de.payload_json, '$.eventActionability') AS event_actionability,
|
||||
json_extract(de.payload_json, '$.skipTradeReason') AS skip_trade_reason,
|
||||
COUNT(*) AS missing_count,
|
||||
MIN(tx.signature) AS sample_signature
|
||||
FROM k_sol_dex_decoded_events de
|
||||
JOIN k_sol_chain_transactions tx ON tx.id = de.transaction_id
|
||||
LEFT JOIN k_sol_trade_events te ON te.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_liquidity_events lie ON lie.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_pool_lifecycle_events ple ON ple.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_fee_events fee ON fee.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_reward_events rew ON rew.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_pool_admin_events adm ON adm.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_orderbook_events obe ON obe.decoded_event_id = de.id
|
||||
LEFT JOIN k_sol_token_account_events tae ON tae.decoded_event_id = de.id
|
||||
WHERE (tx.err_json IS NULL OR tx.err_json = '' OR tx.err_json = 'null')
|
||||
AND te.id IS NULL
|
||||
AND lie.id IS NULL
|
||||
AND ple.id IS NULL
|
||||
AND fee.id IS NULL
|
||||
AND rew.id IS NULL
|
||||
AND adm.id IS NULL
|
||||
AND obe.id IS NULL
|
||||
AND tae.id IS NULL
|
||||
GROUP BY de.protocol_name, de.event_kind, event_actionability, skip_trade_reason
|
||||
ORDER BY missing_count DESC, de.protocol_name, de.event_kind;
|
||||
```
|
||||
|
||||
Cette requête ne doit pas forcément être vide, mais tout résidu doit être explicitement classé : failed-only, decoded-only justifié, non_actionable prouvé, ou nouveau bug.
|
||||
|
||||
## Vérification/correction Pump/Raydium incluse dans 0.7.58
|
||||
|
||||
La tranche `0.7.58` doit inclure un passage de non-régression sur les surfaces déjà closes, au minimum :
|
||||
|
||||
```text
|
||||
pump_swap
|
||||
pump_fun
|
||||
pump_fees
|
||||
raydium_cpmm
|
||||
raydium_clmm
|
||||
raydium_amm_v4
|
||||
raydium_stable_swap
|
||||
raydium_launchpad
|
||||
meteora_dbc
|
||||
meteora_dlmm
|
||||
```
|
||||
|
||||
Objectif : détecter et corriger les régressions cross-surface, par exemple :
|
||||
|
||||
```text
|
||||
un decoder A ne doit pas faire échouer la matérialisation d’un decoder B dans la même transaction.
|
||||
```
|
||||
|
||||
Règle de decoder :
|
||||
|
||||
- un payload tronqué/incompatible sur une surface secondaire ne doit pas aborter toute la transaction si l’entrée peut être ignorée proprement ;
|
||||
- préférer `Ok(None)` + observation/debug contrôlé pour les payloads tronqués connus ;
|
||||
- conserver `Err` pour corruption critique, violation de schéma interne ou incohérence qui rend la transaction non fiable ;
|
||||
- ajouter des tests synthétiques pour chaque guard.
|
||||
|
||||
## Tests attendus
|
||||
|
||||
Ajouter tests unitaires/offline pour :
|
||||
|
||||
1. merge d’une DB vers output vide ;
|
||||
2. merge de deux DBs disjointes ;
|
||||
3. duplicate signature identique ;
|
||||
4. duplicate signature conflictuelle ;
|
||||
5. conflit instruction enfant ;
|
||||
6. dry-run sans écriture ;
|
||||
7. output existant refusé sans option explicite ;
|
||||
8. source provenance enregistrée ;
|
||||
9. replay final DB possible après merge raw-corpus ;
|
||||
10. non-régression PumpSwap/PumpFees : payload PumpFees tronqué n’empêche pas PumpSwap de matérialiser un trade exact.
|
||||
|
||||
## Livrables attendus
|
||||
|
||||
```text
|
||||
kb_tools/Cargo.toml
|
||||
kb_tools/src/bin/kb_db_merge.rs
|
||||
kb_lib/src/db/entities/db_merge_source.rs
|
||||
kb_lib/src/db/entities/db_merge_transaction.rs
|
||||
kb_lib/src/db/entities/db_merge_conflict.rs
|
||||
kb_lib/src/db/dtos/db_merge_*.rs
|
||||
kb_lib/src/db/queries/db_merge_*.rs
|
||||
validation_sql/SQL_VALIDATION_DB_MERGE_0_7_58.sql
|
||||
validation_sql/SQL_VALIDATION_CROSS_DEX_REGRESSION_0_7_58.sql
|
||||
docs/reports/SQLITE_DB_TRANSACTION_MERGER_0_7_58.md
|
||||
```
|
||||
|
||||
Mettre à jour :
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
kb_lib/src/db.rs
|
||||
kb_lib/src/lib.rs
|
||||
README.md
|
||||
ROADMAP.md
|
||||
CHANGELOG.md
|
||||
```
|
||||
|
||||
## Critères de clôture 0.7.58
|
||||
|
||||
- `cargo test -p kb_lib` OK ;
|
||||
- `cargo test -p kb_tools` OK si package séparé ;
|
||||
- clippy `-D warnings` OK ;
|
||||
- dry-run merge lisible ;
|
||||
- merge réel de plusieurs bases OK ;
|
||||
- pas de duplicate signatures ;
|
||||
- pas d’instructions orphelines ;
|
||||
- conflits journalisés ;
|
||||
- replay local de `final.next.db` OK ;
|
||||
- validation anti-régression Pump/Raydium/Meteora exécutée et documentée.
|
||||
|
||||
## Note finale
|
||||
|
||||
Le merger ne remplace pas `demo3` ni `demo4`.
|
||||
|
||||
Il sert à construire un corpus consolidé de non-régression à partir des bases dédiées. `demo4`, déplacé en `0.7.59`, servira ensuite à explorer les surfaces encore inconnues dans cette base consolidée.
|
||||
330
docs/prompts/PROMPT_0_7_59_DEMO4_PROGRAM_SURFACE_DISCOVERY.md
Normal file
330
docs/prompts/PROMPT_0_7_59_DEMO4_PROGRAM_SURFACE_DISCOVERY.md
Normal file
@@ -0,0 +1,330 @@
|
||||
<!-- file: docs/prompts/PROMPT_0_7_59_demo4_program_surface_discovery.md -->
|
||||
|
||||
# Prompt — 0.7.59 Demo4 Program Surface Discovery
|
||||
|
||||
## Contexte
|
||||
|
||||
Nous reprenons le workspace Rust `khadhroony-bobobot` après :
|
||||
|
||||
```text
|
||||
0.7.57 -> meteora_dlmm clos
|
||||
0.7.58 -> sqlite_db_transaction_merger + validation anti-régression cross-DEX
|
||||
```
|
||||
|
||||
Décision de planification : `demo4_program_surface_discovery` est déplacé de `0.7.58` vers `0.7.59` afin de permettre d’abord la création d’une base consolidée `final.db`.
|
||||
|
||||
Cette base consolidée doit permettre à Demo4 d’explorer :
|
||||
|
||||
```text
|
||||
program_id inconnus
|
||||
program_id connus avec discriminants non mappés
|
||||
Anchor logs Instruction non mappés
|
||||
Program data events non mappés
|
||||
upstream fallbacks
|
||||
layouts répétitifs d’accounts/data
|
||||
success/failed split
|
||||
```
|
||||
|
||||
## Objectif principal
|
||||
|
||||
Ajouter une fenêtre `Demo4` dans `kb_demo_app` et les requêtes `kb_lib` associées pour afficher les surfaces non prises en compte sans les promouvoir automatiquement.
|
||||
|
||||
Demo4 est un outil d’observation, de tri et de préparation de futures tranches de decoder. Il ne doit pas créer de trade, candle, pool, pair, fee, reward, admin ou lifecycle métier.
|
||||
|
||||
## Règles strictes
|
||||
|
||||
Demo4 doit être read-only par défaut.
|
||||
|
||||
Interdictions :
|
||||
|
||||
- ne pas matérialiser automatiquement ;
|
||||
- ne pas ajouter automatiquement de coverage comme supportée ;
|
||||
- ne pas marquer automatiquement un `program_id` comme connu ;
|
||||
- ne pas générer de decoder métier ;
|
||||
- ne pas promouvoir un upstream fallback vers un decoder local sans intervention humaine ;
|
||||
- ne pas masquer les failed transactions ;
|
||||
- ne pas supprimer les observations existantes.
|
||||
|
||||
Actions autorisées :
|
||||
|
||||
- lister ;
|
||||
- grouper ;
|
||||
- scorer ;
|
||||
- exporter Markdown/CSV/JSON ;
|
||||
- marquer manuellement un candidat comme `reviewed`, `ignored`, `accepted_for_future_decoder`, si table de statut ajoutée ;
|
||||
- ouvrir une signature dans Demo Pipeline 2 ou Demo3.
|
||||
|
||||
## Sources de données prioritaires
|
||||
|
||||
Demo4 doit exploiter la base consolidée construite par `0.7.58`, par exemple :
|
||||
|
||||
```text
|
||||
final.db
|
||||
final.next.db
|
||||
```
|
||||
|
||||
Cette base est issue de merges raw-corpus de bases dédiées :
|
||||
|
||||
```text
|
||||
pump_swap.db
|
||||
pump_fun.db
|
||||
pump_fees.db
|
||||
raydium_*.db
|
||||
meteora_*.db
|
||||
```
|
||||
|
||||
Le bénéfice attendu : détecter les surfaces inconnues et les régressions qui n’apparaissent pas dans une base DEX isolée.
|
||||
|
||||
## Surfaces à afficher
|
||||
|
||||
### 1. Program IDs non routés
|
||||
|
||||
Afficher les `program_id` présents dans `k_sol_chain_instructions` qui ne correspondent pas à une surface supportée ou connue.
|
||||
|
||||
Colonnes utiles :
|
||||
|
||||
```text
|
||||
program_id
|
||||
instruction_count
|
||||
tx_count
|
||||
success_count
|
||||
failed_count
|
||||
first_slot
|
||||
last_slot
|
||||
sample_signature
|
||||
sample_data_prefix
|
||||
sample_account_count
|
||||
```
|
||||
|
||||
### 2. Discriminators non mappés sur program id connu
|
||||
|
||||
Pour un `program_id` déjà supporté, afficher les discriminants inconnus ou encore en `instruction_audit`.
|
||||
|
||||
Colonnes utiles :
|
||||
|
||||
```text
|
||||
protocol_guess
|
||||
program_id
|
||||
discriminator_hex
|
||||
data_prefix
|
||||
instruction_count
|
||||
tx_count
|
||||
success_count
|
||||
failed_count
|
||||
sample_signature
|
||||
known_anchor_log_name si disponible
|
||||
upstream_match_status si disponible
|
||||
```
|
||||
|
||||
### 3. Anchor logs `Instruction: ...`
|
||||
|
||||
Extraire depuis `meta_json.logMessages` :
|
||||
|
||||
```text
|
||||
Program log: Instruction: <Name>
|
||||
```
|
||||
|
||||
Normaliser le nom :
|
||||
|
||||
```text
|
||||
InitializePresetParameterV2 -> initialize_preset_parameter_v2
|
||||
```
|
||||
|
||||
Calculer si possible :
|
||||
|
||||
```text
|
||||
sha256("global:<snake_case_name>")[0..8]
|
||||
```
|
||||
|
||||
Comparer au discriminator observé.
|
||||
|
||||
### 4. Program data / Anchor events non mappés
|
||||
|
||||
Lister les `Program data:` ou events Anchor observés mais non classés localement.
|
||||
|
||||
Colonnes utiles :
|
||||
|
||||
```text
|
||||
program_id
|
||||
anchor_event_discriminator_hex
|
||||
payload_size
|
||||
tx_count
|
||||
success_count
|
||||
failed_count
|
||||
sample_signature
|
||||
possible_event_name
|
||||
upstream_match_status
|
||||
```
|
||||
|
||||
### 5. Upstream fallbacks
|
||||
|
||||
Afficher les événements qui viennent encore de :
|
||||
|
||||
```text
|
||||
upstream_git.instruction_match
|
||||
upstream_git.event_match
|
||||
instruction_audit
|
||||
```
|
||||
|
||||
Demo4 doit aider à décider si l’entrée doit devenir :
|
||||
|
||||
```text
|
||||
local decoder
|
||||
coverage 0/0 conservée
|
||||
decoded-only justifié
|
||||
materialized admin/lifecycle/fee/reward/liquidity/orderbook
|
||||
ignored
|
||||
```
|
||||
|
||||
## UI attendue
|
||||
|
||||
Fichiers probables :
|
||||
|
||||
```text
|
||||
kb_demo_app/src/demo4.html
|
||||
kb_demo_app/src/demo4.ts
|
||||
kb_demo_app/src/main.ts
|
||||
kb_demo_app/src/shared/api.ts
|
||||
kb_demo_app/src/shared/types.ts
|
||||
```
|
||||
|
||||
Ajouter une fenêtre Tauri si nécessaire dans :
|
||||
|
||||
```text
|
||||
kb_demo_app/src-tauri/src/main.rs
|
||||
kb_demo_app/tauri.conf.json
|
||||
```
|
||||
|
||||
Organisation UI suggérée :
|
||||
|
||||
```text
|
||||
Filters:
|
||||
- program_id
|
||||
- protocol_guess
|
||||
- success/failed/all
|
||||
- minimum tx_count
|
||||
- known/unknown program
|
||||
- audit/upstream/unknown discriminator
|
||||
- date/slot range si disponible
|
||||
|
||||
Tabs:
|
||||
1. Unknown programs
|
||||
2. Known program unknown discriminators
|
||||
3. Anchor instruction logs
|
||||
4. Program data events
|
||||
5. Upstream fallbacks
|
||||
6. Regression suspects
|
||||
```
|
||||
|
||||
## API / services kb_lib suggérés
|
||||
|
||||
Créer des DTOs sous :
|
||||
|
||||
```text
|
||||
kb_lib/src/db/dtos/program_surface_candidate_summary.rs
|
||||
kb_lib/src/db/dtos/program_surface_candidate_sample.rs
|
||||
```
|
||||
|
||||
Créer des requêtes sous :
|
||||
|
||||
```text
|
||||
kb_lib/src/db/queries/program_surface_discovery.rs
|
||||
```
|
||||
|
||||
Créer éventuellement une façade :
|
||||
|
||||
```text
|
||||
kb_lib/src/program_surface_discovery.rs
|
||||
```
|
||||
|
||||
Rappel : si des requêtes DB sont ajoutées, mettre à jour les re-exports dans :
|
||||
|
||||
```text
|
||||
kb_lib/src/db.rs
|
||||
kb_lib/src/lib.rs
|
||||
```
|
||||
|
||||
## Table de statut optionnelle
|
||||
|
||||
Si utile, ajouter :
|
||||
|
||||
```text
|
||||
k_sol_program_surface_candidates
|
||||
```
|
||||
|
||||
Statuts possibles :
|
||||
|
||||
```text
|
||||
new
|
||||
reviewed
|
||||
accepted_for_future_decoder
|
||||
ignored
|
||||
promoted_manually
|
||||
rejected
|
||||
```
|
||||
|
||||
Ne jamais passer automatiquement à `promoted_manually`.
|
||||
|
||||
## Intégration avec 0.7.58
|
||||
|
||||
Demo4 doit intégrer explicitement la notion de source DB/merge si les tables `k_sol_db_merge_*` existent.
|
||||
|
||||
Exemples d’affichages utiles :
|
||||
|
||||
```text
|
||||
candidate observed in sources: pump_swap.db, pump_fees.db
|
||||
candidate observed only after final.db merge
|
||||
candidate correlated with replay decode failure
|
||||
candidate appears in transaction with multiple DEX protocols
|
||||
```
|
||||
|
||||
Objectif : rendre visibles les régressions cross-surface comme le cas PumpSwap/PumpFees.
|
||||
|
||||
## SQL de validation Demo4
|
||||
|
||||
Ajouter :
|
||||
|
||||
```text
|
||||
validation_sql/SQL_VALIDATION_DEMO4_PROGRAM_SURFACE_DISCOVERY_0_7_59.sql
|
||||
```
|
||||
|
||||
Checks :
|
||||
|
||||
```sql
|
||||
-- Demo4 queries should not create decoded/materialized rows
|
||||
SELECT COUNT(*) FROM k_sol_dex_decoded_events;
|
||||
SELECT COUNT(*) FROM k_sol_trade_events;
|
||||
|
||||
-- candidate status table should not auto-promote anything
|
||||
SELECT status, COUNT(*)
|
||||
FROM k_sol_program_surface_candidates
|
||||
GROUP BY status;
|
||||
```
|
||||
|
||||
Adapter selon schéma réel.
|
||||
|
||||
## Tests attendus
|
||||
|
||||
- requêtes unknown program sur fixture minimale ;
|
||||
- discriminants inconnus sur program connu ;
|
||||
- extraction Anchor `Instruction: Name` ;
|
||||
- hash Anchor discriminator ;
|
||||
- split success/failed ;
|
||||
- no write en mode read-only ;
|
||||
- export Markdown/CSV stable ;
|
||||
- table statut manuelle si implémentée.
|
||||
|
||||
## Critères de clôture 0.7.59
|
||||
|
||||
- `cargo test -p kb_lib` OK ;
|
||||
- `cargo test` UI/Tauri si existant OK ;
|
||||
- clippy `-D warnings` OK ;
|
||||
- Demo4 affiche les surfaces inconnues depuis `final.db` ;
|
||||
- aucun auto-decode métier ;
|
||||
- aucune auto-materialization ;
|
||||
- export exploitable pour préparer `0.7.60 meteora_damm_v1` ou une tranche future ;
|
||||
- README/ROADMAP/CHANGELOG mis à jour.
|
||||
|
||||
## Note finale
|
||||
|
||||
Demo4 ne remplace pas les prompts DEX. Il prépare les prochaines tranches en rendant les surfaces observées lisibles, priorisées et reproductibles.
|
||||
@@ -1,249 +1,18 @@
|
||||
<!-- file: docs/prompts/prompt_name_0_7_59_sqlite_db_transaction_merger_binary.md -->
|
||||
<!-- file: docs/prompts/PROMPT_0_7_59_sqlite_db_transaction_merger_binary.md -->
|
||||
|
||||
# Prompt — 0.7.59 Binaire de fusion de bases SQLite transactionnelles
|
||||
# OBSOLETE — Prompt déplacé
|
||||
|
||||
## Contexte
|
||||
Ce prompt n'est plus la cible `0.7.59`.
|
||||
|
||||
Nous reprenons le workspace Rust `khadhroony-bobobot` après la clôture de `0.7.57 meteora_dlmm` et après/ou en parallèle de `0.7.58 demo4_program_surface_discovery`.
|
||||
|
||||
L’utilisateur possède plusieurs bases SQLite dédiées construites pendant les tranches Raydium, Pump et Meteora. L’objectif est d’éviter de rescanner/backfiller des signatures déjà présentes dans ces bases.
|
||||
|
||||
## Objectif
|
||||
|
||||
Ajouter un module binaire qui utilise `kb_lib` pour fusionner des données de corpus transactionnel depuis plusieurs fichiers SQLite `.db` vers une base SQLite de sortie unique.
|
||||
|
||||
Le merger doit copier suffisamment de données brutes transaction/instruction pour permettre un replay local dans la base consolidée, sans refaire les appels RPC.
|
||||
|
||||
Ce binaire est un outil de consolidation de corpus. Ce n’est pas un scanner blockchain.
|
||||
|
||||
## Forme recommandée
|
||||
|
||||
Créer un nouveau package workspace :
|
||||
Nouvel ordre validé :
|
||||
|
||||
```text
|
||||
kb_tools/
|
||||
Cargo.toml
|
||||
src/bin/kb_db_merge.rs
|
||||
0.7.58 -> sqlite_db_transaction_merger
|
||||
0.7.59 -> demo4_program_surface_discovery
|
||||
```
|
||||
|
||||
Le binaire doit dépendre de `kb_lib` et réutiliser autant que possible les fonctions de schéma/setup/query existantes.
|
||||
|
||||
Alternative acceptable si le workspace préfère ce pattern :
|
||||
Utiliser :
|
||||
|
||||
```text
|
||||
kb_lib/src/bin/kb_db_merge.rs
|
||||
docs/prompts/PROMPT_0_7_58_sqlite_db_transaction_merger_binary.md
|
||||
```
|
||||
|
||||
Préférer `kb_tools` si cela évite de mélanger du code CLI-only dans `kb_lib`.
|
||||
|
||||
## Interface CLI
|
||||
|
||||
Commande suggérée :
|
||||
|
||||
```bash
|
||||
cargo run -p kb_tools --bin kb_db_merge -- \
|
||||
--output ./merged_corpus.db \
|
||||
--input ./raydium.db \
|
||||
--input ./pump.db \
|
||||
--input ./meteora.db \
|
||||
--mode raw-corpus \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
Options requises ou utiles :
|
||||
|
||||
```text
|
||||
--output <path>
|
||||
--input <path> répétable
|
||||
--mode <mode>
|
||||
--dry-run optionnel
|
||||
--replace-output optionnel ; sinon refuser si output existe
|
||||
--source-label optionnel ou inféré depuis le nom de fichier
|
||||
--limit optionnel pour tests
|
||||
```
|
||||
|
||||
Modes initiaux :
|
||||
|
||||
```text
|
||||
raw-corpus
|
||||
full-copy-safe
|
||||
signatures-only
|
||||
```
|
||||
|
||||
## Mode `raw-corpus`
|
||||
|
||||
Mode par défaut recommandé.
|
||||
|
||||
Copier les données brutes canonique nécessaires au replay local sans RPC :
|
||||
|
||||
```text
|
||||
k_sol_chain_transactions
|
||||
k_sol_chain_instructions
|
||||
```
|
||||
|
||||
Si le schéma contient d’autres tables brutes/contextuelles strictement nécessaires, les inspecter avant de les ajouter. Ne copier que les tables sûres, sans duplication sémantique.
|
||||
|
||||
La base output doit ensuite pouvoir exécuter le replay/décodage local depuis les transactions persistées.
|
||||
|
||||
## Mode `full-copy-safe`
|
||||
|
||||
Mode optionnel pour plus tard.
|
||||
|
||||
Copier aussi des lignes décodées/matérialisées seulement si les foreign keys, versions de decoder et versions de schéma sont cohérentes.
|
||||
|
||||
Ne pas l’implémenter comme mode par défaut. Il est plus dangereux car les lignes matérialisées dépendent de la version du code.
|
||||
|
||||
## Mode `signatures-only`
|
||||
|
||||
Copier uniquement les signatures/slots dans une table de staging afin qu’un outil futur décide quoi importer/rejouer.
|
||||
|
||||
## Politique de déduplication
|
||||
|
||||
Identité primaire :
|
||||
|
||||
```text
|
||||
signature
|
||||
```
|
||||
|
||||
Règles :
|
||||
|
||||
- Une même signature dans plusieurs inputs doit produire une seule transaction dans l’output.
|
||||
- Si `meta_json`, `transaction_json`, `slot` ou `err_json` diffèrent pour une même signature, enregistrer un conflit ; ne pas écraser silencieusement.
|
||||
- Préférer la ligne brute la plus complète uniquement si le conflit est explicable et journalisé.
|
||||
- Conserver la provenance dans des tables d’audit de merge.
|
||||
|
||||
Tables suggérées :
|
||||
|
||||
```text
|
||||
k_sol_db_merge_sources
|
||||
k_sol_db_merge_transactions
|
||||
k_sol_db_merge_conflicts
|
||||
```
|
||||
|
||||
Champs source suggérés :
|
||||
|
||||
```text
|
||||
source_id
|
||||
source_path
|
||||
source_label
|
||||
source_schema_version
|
||||
source_created_at
|
||||
input_transaction_count
|
||||
copied_transaction_count
|
||||
skipped_duplicate_count
|
||||
conflict_count
|
||||
```
|
||||
|
||||
Pour chaque signature copiée :
|
||||
|
||||
```text
|
||||
signature
|
||||
slot
|
||||
source_id
|
||||
source_transaction_id
|
||||
copied_at
|
||||
copy_status
|
||||
conflict_status
|
||||
```
|
||||
|
||||
## Règles de sécurité
|
||||
|
||||
- Ne pas appeler RPC.
|
||||
- Ne pas backfiller.
|
||||
- Ne pas décoder DEX pendant le merge.
|
||||
- Ne pas matérialiser trades/candles pendant le merge.
|
||||
- Ne pas supposer une compatibilité de schéma sans inspection.
|
||||
- Ne pas utiliser `ATTACH` avec des chemins non validés/échappés.
|
||||
- Pas de `?`, `unwrap`, `expect` dans le code applicatif.
|
||||
- Les erreurs doivent être explicites, typées projet, et lisibles.
|
||||
- Le mode dry-run doit indiquer exactement ce qui serait copié, ignoré ou marqué conflictuel.
|
||||
|
||||
## Compatibilité de schéma
|
||||
|
||||
Le binaire doit inspecter `sqlite_master` et `PRAGMA table_info(...)` dans chaque DB input.
|
||||
|
||||
Tables requises pour `raw-corpus` :
|
||||
|
||||
```text
|
||||
k_sol_chain_transactions
|
||||
k_sol_chain_instructions
|
||||
```
|
||||
|
||||
Vérifier les colonnes requises par nom. Si une colonne optionnelle manque, l’indiquer clairement et continuer seulement si la copie reste suffisante pour un replay local fiable.
|
||||
|
||||
Si le schéma est incompatible, échouer proprement avec un résumé court.
|
||||
|
||||
## Stratégie de copie
|
||||
|
||||
Algorithme recommandé :
|
||||
|
||||
1. Ouvrir/créer la base output et initialiser le schéma courant via `kb_lib`.
|
||||
2. Pour chaque input DB :
|
||||
- inspecter le schéma ;
|
||||
- enregistrer la source ;
|
||||
- itérer les transactions par slot/signature ;
|
||||
- si la signature est absente de l’output, insérer la transaction et ses instructions enfants ;
|
||||
- si la signature existe, comparer les champs canoniques et ignorer ou enregistrer un conflit ;
|
||||
- préserver le mapping `source_transaction_id -> output_transaction_id` pour les instructions.
|
||||
3. Commit par batches.
|
||||
4. Imprimer un résumé final.
|
||||
|
||||
La taille de batch doit être configurable ou conservatrice.
|
||||
|
||||
## SQL de validation
|
||||
|
||||
Ajouter :
|
||||
|
||||
```text
|
||||
validation_sql/SQL_VALIDATION_DB_MERGE_0_7_59.sql
|
||||
```
|
||||
|
||||
Checks minimaux :
|
||||
|
||||
```sql
|
||||
-- duplicate signatures in output should be empty
|
||||
SELECT signature, COUNT(*)
|
||||
FROM k_sol_chain_transactions
|
||||
GROUP BY signature
|
||||
HAVING COUNT(*) > 1;
|
||||
|
||||
-- orphan instructions should be empty
|
||||
SELECT ins.id
|
||||
FROM k_sol_chain_instructions ins
|
||||
LEFT JOIN k_sol_chain_transactions tx ON tx.id = ins.transaction_id
|
||||
WHERE tx.id IS NULL;
|
||||
|
||||
-- conflicts summary
|
||||
SELECT *
|
||||
FROM k_sol_db_merge_conflicts
|
||||
ORDER BY id DESC
|
||||
LIMIT 100;
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
Ajouter des tests offline avec bases SQLite temporaires :
|
||||
|
||||
1. merge d’une DB vers un output vide ;
|
||||
2. merge de deux DBs avec signatures disjointes ;
|
||||
3. merge de deux DBs avec signature identique et contenu identique ;
|
||||
4. signature dupliquée avec conflit slot/meta et ligne conflict enregistrée ;
|
||||
5. instructions recopiées avec le nouveau `transaction_id` output ;
|
||||
6. dry-run sans écriture des lignes output ;
|
||||
7. table requise manquante -> erreur propre.
|
||||
|
||||
## Documentation
|
||||
|
||||
Mettre à jour :
|
||||
|
||||
```text
|
||||
README.md
|
||||
ROADMAP.md
|
||||
CHANGELOG.md
|
||||
validation_sql/SQL_VALIDATION_DB_MERGE_0_7_59.sql
|
||||
docs/reports/SQLITE_DB_TRANSACTION_MERGER_0_7_59.md
|
||||
```
|
||||
|
||||
## Résultat attendu
|
||||
|
||||
L’utilisateur peut consolider ses anciennes bases Raydium/Pump/Meteora dans une base output et relancer un replay local depuis les lignes brutes existantes, sans refaire les backfills RPC de signatures.
|
||||
|
||||
330
docs/prompts/PROMPT_0_7_59_demo4_program_surface_discovery.md
Normal file
330
docs/prompts/PROMPT_0_7_59_demo4_program_surface_discovery.md
Normal file
@@ -0,0 +1,330 @@
|
||||
<!-- file: docs/prompts/PROMPT_0_7_59_demo4_program_surface_discovery.md -->
|
||||
|
||||
# Prompt — 0.7.59 Demo4 Program Surface Discovery
|
||||
|
||||
## Contexte
|
||||
|
||||
Nous reprenons le workspace Rust `khadhroony-bobobot` après :
|
||||
|
||||
```text
|
||||
0.7.57 -> meteora_dlmm clos
|
||||
0.7.58 -> sqlite_db_transaction_merger + validation anti-régression cross-DEX
|
||||
```
|
||||
|
||||
Décision de planification : `demo4_program_surface_discovery` est déplacé de `0.7.58` vers `0.7.59` afin de permettre d’abord la création d’une base consolidée `final.db`.
|
||||
|
||||
Cette base consolidée doit permettre à Demo4 d’explorer :
|
||||
|
||||
```text
|
||||
program_id inconnus
|
||||
program_id connus avec discriminants non mappés
|
||||
Anchor logs Instruction non mappés
|
||||
Program data events non mappés
|
||||
upstream fallbacks
|
||||
layouts répétitifs d’accounts/data
|
||||
success/failed split
|
||||
```
|
||||
|
||||
## Objectif principal
|
||||
|
||||
Ajouter une fenêtre `Demo4` dans `kb_demo_app` et les requêtes `kb_lib` associées pour afficher les surfaces non prises en compte sans les promouvoir automatiquement.
|
||||
|
||||
Demo4 est un outil d’observation, de tri et de préparation de futures tranches de decoder. Il ne doit pas créer de trade, candle, pool, pair, fee, reward, admin ou lifecycle métier.
|
||||
|
||||
## Règles strictes
|
||||
|
||||
Demo4 doit être read-only par défaut.
|
||||
|
||||
Interdictions :
|
||||
|
||||
- ne pas matérialiser automatiquement ;
|
||||
- ne pas ajouter automatiquement de coverage comme supportée ;
|
||||
- ne pas marquer automatiquement un `program_id` comme connu ;
|
||||
- ne pas générer de decoder métier ;
|
||||
- ne pas promouvoir un upstream fallback vers un decoder local sans intervention humaine ;
|
||||
- ne pas masquer les failed transactions ;
|
||||
- ne pas supprimer les observations existantes.
|
||||
|
||||
Actions autorisées :
|
||||
|
||||
- lister ;
|
||||
- grouper ;
|
||||
- scorer ;
|
||||
- exporter Markdown/CSV/JSON ;
|
||||
- marquer manuellement un candidat comme `reviewed`, `ignored`, `accepted_for_future_decoder`, si table de statut ajoutée ;
|
||||
- ouvrir une signature dans Demo Pipeline 2 ou Demo3.
|
||||
|
||||
## Sources de données prioritaires
|
||||
|
||||
Demo4 doit exploiter la base consolidée construite par `0.7.58`, par exemple :
|
||||
|
||||
```text
|
||||
final.db
|
||||
final.next.db
|
||||
```
|
||||
|
||||
Cette base est issue de merges raw-corpus de bases dédiées :
|
||||
|
||||
```text
|
||||
pump_swap.db
|
||||
pump_fun.db
|
||||
pump_fees.db
|
||||
raydium_*.db
|
||||
meteora_*.db
|
||||
```
|
||||
|
||||
Le bénéfice attendu : détecter les surfaces inconnues et les régressions qui n’apparaissent pas dans une base DEX isolée.
|
||||
|
||||
## Surfaces à afficher
|
||||
|
||||
### 1. Program IDs non routés
|
||||
|
||||
Afficher les `program_id` présents dans `k_sol_chain_instructions` qui ne correspondent pas à une surface supportée ou connue.
|
||||
|
||||
Colonnes utiles :
|
||||
|
||||
```text
|
||||
program_id
|
||||
instruction_count
|
||||
tx_count
|
||||
success_count
|
||||
failed_count
|
||||
first_slot
|
||||
last_slot
|
||||
sample_signature
|
||||
sample_data_prefix
|
||||
sample_account_count
|
||||
```
|
||||
|
||||
### 2. Discriminators non mappés sur program id connu
|
||||
|
||||
Pour un `program_id` déjà supporté, afficher les discriminants inconnus ou encore en `instruction_audit`.
|
||||
|
||||
Colonnes utiles :
|
||||
|
||||
```text
|
||||
protocol_guess
|
||||
program_id
|
||||
discriminator_hex
|
||||
data_prefix
|
||||
instruction_count
|
||||
tx_count
|
||||
success_count
|
||||
failed_count
|
||||
sample_signature
|
||||
known_anchor_log_name si disponible
|
||||
upstream_match_status si disponible
|
||||
```
|
||||
|
||||
### 3. Anchor logs `Instruction: ...`
|
||||
|
||||
Extraire depuis `meta_json.logMessages` :
|
||||
|
||||
```text
|
||||
Program log: Instruction: <Name>
|
||||
```
|
||||
|
||||
Normaliser le nom :
|
||||
|
||||
```text
|
||||
InitializePresetParameterV2 -> initialize_preset_parameter_v2
|
||||
```
|
||||
|
||||
Calculer si possible :
|
||||
|
||||
```text
|
||||
sha256("global:<snake_case_name>")[0..8]
|
||||
```
|
||||
|
||||
Comparer au discriminator observé.
|
||||
|
||||
### 4. Program data / Anchor events non mappés
|
||||
|
||||
Lister les `Program data:` ou events Anchor observés mais non classés localement.
|
||||
|
||||
Colonnes utiles :
|
||||
|
||||
```text
|
||||
program_id
|
||||
anchor_event_discriminator_hex
|
||||
payload_size
|
||||
tx_count
|
||||
success_count
|
||||
failed_count
|
||||
sample_signature
|
||||
possible_event_name
|
||||
upstream_match_status
|
||||
```
|
||||
|
||||
### 5. Upstream fallbacks
|
||||
|
||||
Afficher les événements qui viennent encore de :
|
||||
|
||||
```text
|
||||
upstream_git.instruction_match
|
||||
upstream_git.event_match
|
||||
instruction_audit
|
||||
```
|
||||
|
||||
Demo4 doit aider à décider si l’entrée doit devenir :
|
||||
|
||||
```text
|
||||
local decoder
|
||||
coverage 0/0 conservée
|
||||
decoded-only justifié
|
||||
materialized admin/lifecycle/fee/reward/liquidity/orderbook
|
||||
ignored
|
||||
```
|
||||
|
||||
## UI attendue
|
||||
|
||||
Fichiers probables :
|
||||
|
||||
```text
|
||||
kb_demo_app/src/demo4.html
|
||||
kb_demo_app/src/demo4.ts
|
||||
kb_demo_app/src/main.ts
|
||||
kb_demo_app/src/shared/api.ts
|
||||
kb_demo_app/src/shared/types.ts
|
||||
```
|
||||
|
||||
Ajouter une fenêtre Tauri si nécessaire dans :
|
||||
|
||||
```text
|
||||
kb_demo_app/src-tauri/src/main.rs
|
||||
kb_demo_app/tauri.conf.json
|
||||
```
|
||||
|
||||
Organisation UI suggérée :
|
||||
|
||||
```text
|
||||
Filters:
|
||||
- program_id
|
||||
- protocol_guess
|
||||
- success/failed/all
|
||||
- minimum tx_count
|
||||
- known/unknown program
|
||||
- audit/upstream/unknown discriminator
|
||||
- date/slot range si disponible
|
||||
|
||||
Tabs:
|
||||
1. Unknown programs
|
||||
2. Known program unknown discriminators
|
||||
3. Anchor instruction logs
|
||||
4. Program data events
|
||||
5. Upstream fallbacks
|
||||
6. Regression suspects
|
||||
```
|
||||
|
||||
## API / services kb_lib suggérés
|
||||
|
||||
Créer des DTOs sous :
|
||||
|
||||
```text
|
||||
kb_lib/src/db/dtos/program_surface_candidate_summary.rs
|
||||
kb_lib/src/db/dtos/program_surface_candidate_sample.rs
|
||||
```
|
||||
|
||||
Créer des requêtes sous :
|
||||
|
||||
```text
|
||||
kb_lib/src/db/queries/program_surface_discovery.rs
|
||||
```
|
||||
|
||||
Créer éventuellement une façade :
|
||||
|
||||
```text
|
||||
kb_lib/src/program_surface_discovery.rs
|
||||
```
|
||||
|
||||
Rappel : si des requêtes DB sont ajoutées, mettre à jour les re-exports dans :
|
||||
|
||||
```text
|
||||
kb_lib/src/db.rs
|
||||
kb_lib/src/lib.rs
|
||||
```
|
||||
|
||||
## Table de statut optionnelle
|
||||
|
||||
Si utile, ajouter :
|
||||
|
||||
```text
|
||||
k_sol_program_surface_candidates
|
||||
```
|
||||
|
||||
Statuts possibles :
|
||||
|
||||
```text
|
||||
new
|
||||
reviewed
|
||||
accepted_for_future_decoder
|
||||
ignored
|
||||
promoted_manually
|
||||
rejected
|
||||
```
|
||||
|
||||
Ne jamais passer automatiquement à `promoted_manually`.
|
||||
|
||||
## Intégration avec 0.7.58
|
||||
|
||||
Demo4 doit intégrer explicitement la notion de source DB/merge si les tables `k_sol_db_merge_*` existent.
|
||||
|
||||
Exemples d’affichages utiles :
|
||||
|
||||
```text
|
||||
candidate observed in sources: pump_swap.db, pump_fees.db
|
||||
candidate observed only after final.db merge
|
||||
candidate correlated with replay decode failure
|
||||
candidate appears in transaction with multiple DEX protocols
|
||||
```
|
||||
|
||||
Objectif : rendre visibles les régressions cross-surface comme le cas PumpSwap/PumpFees.
|
||||
|
||||
## SQL de validation Demo4
|
||||
|
||||
Ajouter :
|
||||
|
||||
```text
|
||||
validation_sql/SQL_VALIDATION_DEMO4_PROGRAM_SURFACE_DISCOVERY_0_7_59.sql
|
||||
```
|
||||
|
||||
Checks :
|
||||
|
||||
```sql
|
||||
-- Demo4 queries should not create decoded/materialized rows
|
||||
SELECT COUNT(*) FROM k_sol_dex_decoded_events;
|
||||
SELECT COUNT(*) FROM k_sol_trade_events;
|
||||
|
||||
-- candidate status table should not auto-promote anything
|
||||
SELECT status, COUNT(*)
|
||||
FROM k_sol_program_surface_candidates
|
||||
GROUP BY status;
|
||||
```
|
||||
|
||||
Adapter selon schéma réel.
|
||||
|
||||
## Tests attendus
|
||||
|
||||
- requêtes unknown program sur fixture minimale ;
|
||||
- discriminants inconnus sur program connu ;
|
||||
- extraction Anchor `Instruction: Name` ;
|
||||
- hash Anchor discriminator ;
|
||||
- split success/failed ;
|
||||
- no write en mode read-only ;
|
||||
- export Markdown/CSV stable ;
|
||||
- table statut manuelle si implémentée.
|
||||
|
||||
## Critères de clôture 0.7.59
|
||||
|
||||
- `cargo test -p kb_lib` OK ;
|
||||
- `cargo test` UI/Tauri si existant OK ;
|
||||
- clippy `-D warnings` OK ;
|
||||
- Demo4 affiche les surfaces inconnues depuis `final.db` ;
|
||||
- aucun auto-decode métier ;
|
||||
- aucune auto-materialization ;
|
||||
- export exploitable pour préparer `0.7.60 meteora_damm_v1` ou une tranche future ;
|
||||
- README/ROADMAP/CHANGELOG mis à jour.
|
||||
|
||||
## Note finale
|
||||
|
||||
Demo4 ne remplace pas les prompts DEX. Il prépare les prochaines tranches en rendant les surfaces observées lisibles, priorisées et reproductibles.
|
||||
@@ -1,249 +1,18 @@
|
||||
<!-- file: docs/prompts/PROMPT_0_7_59_sqlite_db_transaction_merger_binary.md -->
|
||||
|
||||
# Prompt — 0.7.59 Binaire de fusion de bases SQLite transactionnelles
|
||||
# OBSOLETE — Prompt déplacé
|
||||
|
||||
## Contexte
|
||||
Ce prompt n'est plus la cible `0.7.59`.
|
||||
|
||||
Nous reprenons le workspace Rust `khadhroony-bobobot` après la clôture de `0.7.57 meteora_dlmm` et après/ou en parallèle de `0.7.58 demo4_program_surface_discovery`.
|
||||
|
||||
L’utilisateur possède plusieurs bases SQLite dédiées construites pendant les tranches Raydium, Pump et Meteora. L’objectif est d’éviter de rescanner/backfiller des signatures déjà présentes dans ces bases.
|
||||
|
||||
## Objectif
|
||||
|
||||
Ajouter un module binaire qui utilise `kb_lib` pour fusionner des données de corpus transactionnel depuis plusieurs fichiers SQLite `.db` vers une base SQLite de sortie unique.
|
||||
|
||||
Le merger doit copier suffisamment de données brutes transaction/instruction pour permettre un replay local dans la base consolidée, sans refaire les appels RPC.
|
||||
|
||||
Ce binaire est un outil de consolidation de corpus. Ce n’est pas un scanner blockchain.
|
||||
|
||||
## Forme recommandée
|
||||
|
||||
Créer un nouveau package workspace :
|
||||
Nouvel ordre validé :
|
||||
|
||||
```text
|
||||
kb_tools/
|
||||
Cargo.toml
|
||||
src/bin/kb_db_merge.rs
|
||||
0.7.58 -> sqlite_db_transaction_merger
|
||||
0.7.59 -> demo4_program_surface_discovery
|
||||
```
|
||||
|
||||
Le binaire doit dépendre de `kb_lib` et réutiliser autant que possible les fonctions de schéma/setup/query existantes.
|
||||
|
||||
Alternative acceptable si le workspace préfère ce pattern :
|
||||
Utiliser :
|
||||
|
||||
```text
|
||||
kb_lib/src/bin/kb_db_merge.rs
|
||||
docs/prompts/PROMPT_0_7_58_sqlite_db_transaction_merger_binary.md
|
||||
```
|
||||
|
||||
Préférer `kb_tools` si cela évite de mélanger du code CLI-only dans `kb_lib`.
|
||||
|
||||
## Interface CLI
|
||||
|
||||
Commande suggérée :
|
||||
|
||||
```bash
|
||||
cargo run -p kb_tools --bin kb_db_merge -- \
|
||||
--output ./merged_corpus.db \
|
||||
--input ./raydium.db \
|
||||
--input ./pump.db \
|
||||
--input ./meteora.db \
|
||||
--mode raw-corpus \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
Options requises ou utiles :
|
||||
|
||||
```text
|
||||
--output <path>
|
||||
--input <path> répétable
|
||||
--mode <mode>
|
||||
--dry-run optionnel
|
||||
--replace-output optionnel ; sinon refuser si output existe
|
||||
--source-label optionnel ou inféré depuis le nom de fichier
|
||||
--limit optionnel pour tests
|
||||
```
|
||||
|
||||
Modes initiaux :
|
||||
|
||||
```text
|
||||
raw-corpus
|
||||
full-copy-safe
|
||||
signatures-only
|
||||
```
|
||||
|
||||
## Mode `raw-corpus`
|
||||
|
||||
Mode par défaut recommandé.
|
||||
|
||||
Copier les données brutes canonique nécessaires au replay local sans RPC :
|
||||
|
||||
```text
|
||||
k_sol_chain_transactions
|
||||
k_sol_chain_instructions
|
||||
```
|
||||
|
||||
Si le schéma contient d’autres tables brutes/contextuelles strictement nécessaires, les inspecter avant de les ajouter. Ne copier que les tables sûres, sans duplication sémantique.
|
||||
|
||||
La base output doit ensuite pouvoir exécuter le replay/décodage local depuis les transactions persistées.
|
||||
|
||||
## Mode `full-copy-safe`
|
||||
|
||||
Mode optionnel pour plus tard.
|
||||
|
||||
Copier aussi des lignes décodées/matérialisées seulement si les foreign keys, versions de decoder et versions de schéma sont cohérentes.
|
||||
|
||||
Ne pas l’implémenter comme mode par défaut. Il est plus dangereux car les lignes matérialisées dépendent de la version du code.
|
||||
|
||||
## Mode `signatures-only`
|
||||
|
||||
Copier uniquement les signatures/slots dans une table de staging afin qu’un outil futur décide quoi importer/rejouer.
|
||||
|
||||
## Politique de déduplication
|
||||
|
||||
Identité primaire :
|
||||
|
||||
```text
|
||||
signature
|
||||
```
|
||||
|
||||
Règles :
|
||||
|
||||
- Une même signature dans plusieurs inputs doit produire une seule transaction dans l’output.
|
||||
- Si `meta_json`, `transaction_json`, `slot` ou `err_json` diffèrent pour une même signature, enregistrer un conflit ; ne pas écraser silencieusement.
|
||||
- Préférer la ligne brute la plus complète uniquement si le conflit est explicable et journalisé.
|
||||
- Conserver la provenance dans des tables d’audit de merge.
|
||||
|
||||
Tables suggérées :
|
||||
|
||||
```text
|
||||
k_sol_db_merge_sources
|
||||
k_sol_db_merge_transactions
|
||||
k_sol_db_merge_conflicts
|
||||
```
|
||||
|
||||
Champs source suggérés :
|
||||
|
||||
```text
|
||||
source_id
|
||||
source_path
|
||||
source_label
|
||||
source_schema_version
|
||||
source_created_at
|
||||
input_transaction_count
|
||||
copied_transaction_count
|
||||
skipped_duplicate_count
|
||||
conflict_count
|
||||
```
|
||||
|
||||
Pour chaque signature copiée :
|
||||
|
||||
```text
|
||||
signature
|
||||
slot
|
||||
source_id
|
||||
source_transaction_id
|
||||
copied_at
|
||||
copy_status
|
||||
conflict_status
|
||||
```
|
||||
|
||||
## Règles de sécurité
|
||||
|
||||
- Ne pas appeler RPC.
|
||||
- Ne pas backfiller.
|
||||
- Ne pas décoder DEX pendant le merge.
|
||||
- Ne pas matérialiser trades/candles pendant le merge.
|
||||
- Ne pas supposer une compatibilité de schéma sans inspection.
|
||||
- Ne pas utiliser `ATTACH` avec des chemins non validés/échappés.
|
||||
- Pas de `?`, `unwrap`, `expect` dans le code applicatif.
|
||||
- Les erreurs doivent être explicites, typées projet, et lisibles.
|
||||
- Le mode dry-run doit indiquer exactement ce qui serait copié, ignoré ou marqué conflictuel.
|
||||
|
||||
## Compatibilité de schéma
|
||||
|
||||
Le binaire doit inspecter `sqlite_master` et `PRAGMA table_info(...)` dans chaque DB input.
|
||||
|
||||
Tables requises pour `raw-corpus` :
|
||||
|
||||
```text
|
||||
k_sol_chain_transactions
|
||||
k_sol_chain_instructions
|
||||
```
|
||||
|
||||
Vérifier les colonnes requises par nom. Si une colonne optionnelle manque, l’indiquer clairement et continuer seulement si la copie reste suffisante pour un replay local fiable.
|
||||
|
||||
Si le schéma est incompatible, échouer proprement avec un résumé court.
|
||||
|
||||
## Stratégie de copie
|
||||
|
||||
Algorithme recommandé :
|
||||
|
||||
1. Ouvrir/créer la base output et initialiser le schéma courant via `kb_lib`.
|
||||
2. Pour chaque input DB :
|
||||
- inspecter le schéma ;
|
||||
- enregistrer la source ;
|
||||
- itérer les transactions par slot/signature ;
|
||||
- si la signature est absente de l’output, insérer la transaction et ses instructions enfants ;
|
||||
- si la signature existe, comparer les champs canoniques et ignorer ou enregistrer un conflit ;
|
||||
- préserver le mapping `source_transaction_id -> output_transaction_id` pour les instructions.
|
||||
3. Commit par batches.
|
||||
4. Imprimer un résumé final.
|
||||
|
||||
La taille de batch doit être configurable ou conservatrice.
|
||||
|
||||
## SQL de validation
|
||||
|
||||
Ajouter :
|
||||
|
||||
```text
|
||||
validation_sql/SQL_VALIDATION_DB_MERGE_0_7_59.sql
|
||||
```
|
||||
|
||||
Checks minimaux :
|
||||
|
||||
```sql
|
||||
-- duplicate signatures in output should be empty
|
||||
SELECT signature, COUNT(*)
|
||||
FROM k_sol_chain_transactions
|
||||
GROUP BY signature
|
||||
HAVING COUNT(*) > 1;
|
||||
|
||||
-- orphan instructions should be empty
|
||||
SELECT ins.id
|
||||
FROM k_sol_chain_instructions ins
|
||||
LEFT JOIN k_sol_chain_transactions tx ON tx.id = ins.transaction_id
|
||||
WHERE tx.id IS NULL;
|
||||
|
||||
-- conflicts summary
|
||||
SELECT *
|
||||
FROM k_sol_db_merge_conflicts
|
||||
ORDER BY id DESC
|
||||
LIMIT 100;
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
Ajouter des tests offline avec bases SQLite temporaires :
|
||||
|
||||
1. merge d’une DB vers un output vide ;
|
||||
2. merge de deux DBs avec signatures disjointes ;
|
||||
3. merge de deux DBs avec signature identique et contenu identique ;
|
||||
4. signature dupliquée avec conflit slot/meta et ligne conflict enregistrée ;
|
||||
5. instructions recopiées avec le nouveau `transaction_id` output ;
|
||||
6. dry-run sans écriture des lignes output ;
|
||||
7. table requise manquante -> erreur propre.
|
||||
|
||||
## Documentation
|
||||
|
||||
Mettre à jour :
|
||||
|
||||
```text
|
||||
README.md
|
||||
ROADMAP.md
|
||||
CHANGELOG.md
|
||||
validation_sql/SQL_VALIDATION_DB_MERGE_0_7_59.sql
|
||||
docs/reports/SQLITE_DB_TRANSACTION_MERGER_0_7_59.md
|
||||
```
|
||||
|
||||
## Résultat attendu
|
||||
|
||||
L’utilisateur peut consolider ses anciennes bases Raydium/Pump/Meteora dans une base output et relancer un replay local depuis les lignes brutes existantes, sans refaire les backfills RPC de signatures.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- file: docs/prompts/prompt_name_0_7_60_meteora_damm_next_dex.md -->
|
||||
<!-- file: docs/prompts/PROMPT_0_7_60_meteora_damm_next_dex.md -->
|
||||
|
||||
# Prompt — 0.7.60 Meteora DAMM v1 puis DAMM v2
|
||||
|
||||
@@ -34,14 +34,16 @@ Ne pas partager la classification de decoder d’une manière qui masque les dis
|
||||
|
||||
## Contexte
|
||||
|
||||
`0.7.57 meteora_dlmm` est clos. Les tranches intermédiaires planifiées sont :
|
||||
`0.7.57 meteora_dlmm` est clos.
|
||||
|
||||
Les tranches intermédiaires planifiées avant DAMM sont maintenant :
|
||||
|
||||
```text
|
||||
0.7.58 -> demo4_program_surface_discovery
|
||||
0.7.59 -> sqlite_db_transaction_merger
|
||||
0.7.58 -> sqlite_db_transaction_merger + validation anti-régression cross-DEX
|
||||
0.7.59 -> demo4_program_surface_discovery
|
||||
```
|
||||
|
||||
La prochaine tranche DEX doit reprendre la famille Meteora après DLMM/DBC, en commençant par DAMM v1.
|
||||
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 :
|
||||
|
||||
@@ -53,6 +55,27 @@ 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 :
|
||||
@@ -88,6 +111,7 @@ Règles :
|
||||
- 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
|
||||
|
||||
@@ -105,6 +129,7 @@ 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.
|
||||
@@ -118,16 +143,12 @@ Ne pas considérer les anciens résultats `0.7.36` ou `0.7.46` comme clôture fi
|
||||
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.
|
||||
9. Rejouer sur base fraîche avec :
|
||||
|
||||
```text
|
||||
skipDexDecode=no
|
||||
forceDexDecode=yes
|
||||
deferInstructionObservations=yes
|
||||
```
|
||||
|
||||
10. Clore seulement si les gates SQL sont propres.
|
||||
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
|
||||
|
||||
@@ -147,6 +168,16 @@ 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 :
|
||||
@@ -167,6 +198,8 @@ event mapping
|
||||
synthetic tests
|
||||
SQL validation
|
||||
rapport
|
||||
base dédiée
|
||||
validation final.db merge
|
||||
```
|
||||
|
||||
## Livrables attendus pour 0.7.60
|
||||
@@ -180,6 +213,7 @@ 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
|
||||
```
|
||||
|
||||
|
||||
@@ -34,14 +34,16 @@ Ne pas partager la classification de decoder d’une manière qui masque les dis
|
||||
|
||||
## Contexte
|
||||
|
||||
`0.7.57 meteora_dlmm` est clos. Les tranches intermédiaires planifiées sont :
|
||||
`0.7.57 meteora_dlmm` est clos.
|
||||
|
||||
Les tranches intermédiaires planifiées avant DAMM sont maintenant :
|
||||
|
||||
```text
|
||||
0.7.58 -> demo4_program_surface_discovery
|
||||
0.7.59 -> sqlite_db_transaction_merger
|
||||
0.7.58 -> sqlite_db_transaction_merger + validation anti-régression cross-DEX
|
||||
0.7.59 -> demo4_program_surface_discovery
|
||||
```
|
||||
|
||||
La prochaine tranche DEX doit reprendre la famille Meteora après DLMM/DBC, en commençant par DAMM v1.
|
||||
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 :
|
||||
|
||||
@@ -53,6 +55,27 @@ 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 :
|
||||
@@ -88,6 +111,7 @@ Règles :
|
||||
- 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
|
||||
|
||||
@@ -105,6 +129,7 @@ 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.
|
||||
@@ -118,16 +143,12 @@ Ne pas considérer les anciens résultats `0.7.36` ou `0.7.46` comme clôture fi
|
||||
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.
|
||||
9. Rejouer sur base fraîche avec :
|
||||
|
||||
```text
|
||||
skipDexDecode=no
|
||||
forceDexDecode=yes
|
||||
deferInstructionObservations=yes
|
||||
```
|
||||
|
||||
10. Clore seulement si les gates SQL sont propres.
|
||||
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
|
||||
|
||||
@@ -147,6 +168,16 @@ 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 :
|
||||
@@ -167,6 +198,8 @@ event mapping
|
||||
synthetic tests
|
||||
SQL validation
|
||||
rapport
|
||||
base dédiée
|
||||
validation final.db merge
|
||||
```
|
||||
|
||||
## Livrables attendus pour 0.7.60
|
||||
@@ -180,6 +213,7 @@ 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
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user