0.1.0
This commit is contained in:
@@ -0,0 +1,288 @@
|
||||
<!-- file: prompts/019_v0_4_0_decoder_infrastructure.md -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Prompt v0.4.0 — infrastructure commune de décodage et matérialisation
|
||||
|
||||
## Statut
|
||||
|
||||
Prompt actif depuis la clôture de `0.3.4` le 7 juillet 2026.
|
||||
|
||||
## Précondition satisfaite
|
||||
|
||||
`0.3.4` est validée et inscrite dans `CHANGELOG.md`. Les validations finales ont confirmé `kb_pipeline` avec 24 tests, `kb_store_pg` avec 39 tests incluant le rollback PostgreSQL réel et `cargo clippy --all-targets` sans avertissement.
|
||||
|
||||
La fondation disponible est :
|
||||
|
||||
```text
|
||||
kb_sol_raw_transactions
|
||||
-> kb_sol_core_transactions
|
||||
-> kb_sol_core_account_keys
|
||||
-> kb_sol_core_instructions
|
||||
-> kb_sol_core_inner_instructions
|
||||
-> kb_sol_core_logs
|
||||
-> kb_sol_core_balance_changes
|
||||
-> kb_sol_ops_processing_ledger
|
||||
```
|
||||
|
||||
Les campagnes core disposent déjà de la sélection par signatures, pending, slots et programme, du skip version/hash, du force replay, de la concurrence bornée, de l’arrêt coopératif et de `demo_sql_replay_candidates`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Construire l’infrastructure générique permettant aux futurs décodeurs Solana Core, SPL et protocolaires de recevoir un input core contextualisé, de produire des observations décodées versionnées, puis de déclencher des matérialisations explicitement autorisées.
|
||||
|
||||
`0.4.0` ne doit pas encore devenir une version de décodage maximal d’un protocole précis. Elle stabilise les contrats, le dispatch, le ledger, les stores, la couverture et le replay communs.
|
||||
|
||||
## Principes obligatoires
|
||||
|
||||
### Indépendance
|
||||
|
||||
- un décodeur ne dépend pas de PostgreSQL, Tauri ou d’un fournisseur RPC ;
|
||||
- `kb_decoder_api` dépend uniquement des modèles et contrats backend-agnostiques nécessaires ;
|
||||
- `kb_materializer_api` reçoit des événements décodés stables et leur contexte ;
|
||||
- `kb_pipeline` orchestre sélection, dispatch, persistance, replay et arrêt ;
|
||||
- `kb_store_pg` implémente les repositories concrets.
|
||||
|
||||
### Input contextualisé
|
||||
|
||||
Le contrat de décodage doit fournir au minimum :
|
||||
|
||||
- signature, slot et statut on-chain de la transaction ;
|
||||
- `err_json` lorsque la transaction a échoué ;
|
||||
- instruction path stable ;
|
||||
- program ID ;
|
||||
- comptes résolus dans l’ordre original ;
|
||||
- payload brut déterministe et son hash ;
|
||||
- inner instructions descendantes utiles ;
|
||||
- logs reliés prudemment ;
|
||||
- changements de balances pertinents ;
|
||||
- version du contrat core.
|
||||
|
||||
Réutiliser ou faire évoluer `CoreInstructionReplayInput` au lieu de recréer un modèle parallèle par décodeur.
|
||||
|
||||
### Transactions échouées
|
||||
|
||||
Les transactions on-chain échouées doivent être décodées lorsqu’un input structurel existe.
|
||||
|
||||
Un événement décodé doit conserver explicitement :
|
||||
|
||||
```text
|
||||
transaction_failed
|
||||
transaction_error
|
||||
observation_committed = false lorsque la mutation a été annulée
|
||||
```
|
||||
|
||||
Une transaction échouée peut produire :
|
||||
|
||||
- une observation d’instruction tentée ;
|
||||
- une observation d’événement loggé avant l’erreur ;
|
||||
- une classification de l’échec ;
|
||||
- des métriques de compute et de surface appelée.
|
||||
|
||||
Elle ne doit pas produire automatiquement :
|
||||
|
||||
- un trade réussi ;
|
||||
- une modification de liquidité réussie ;
|
||||
- un changement de catalogue considéré comme confirmé ;
|
||||
- une candle normale issue d’un swap annulé.
|
||||
|
||||
Le matérialiseur doit appliquer une politique explicite par famille d’événement, et non une simple hypothèse basée sur la présence d’un log.
|
||||
|
||||
## Contrats de décodeur
|
||||
|
||||
Stabiliser dans `kb_decoder_api` :
|
||||
|
||||
- identité du décodeur ;
|
||||
- version ;
|
||||
- programmes et surfaces supportés ;
|
||||
- capacité à reconnaître un input ;
|
||||
- résultat `decoded`, `ignored`, `unsupported` ou `failed` ;
|
||||
- confiance et preuve de décodage ;
|
||||
- événements décodés typés ;
|
||||
- diagnostics sans `anyhow` ni `thiserror` ;
|
||||
- couverture déclarée des instructions, événements et discriminants.
|
||||
|
||||
Le dispatch doit être déterministe par :
|
||||
|
||||
```text
|
||||
program_id
|
||||
surface_code éventuel
|
||||
instruction_path
|
||||
payload/discriminator
|
||||
contexte inner/logs
|
||||
```
|
||||
|
||||
Aucun dispatch ne doit reposer sur le nom d’une crate ou sur un ordre implicite non documenté.
|
||||
|
||||
## Contrats de matérialisation
|
||||
|
||||
Stabiliser dans `kb_materializer_api` :
|
||||
|
||||
- identité et version du matérialiseur ;
|
||||
- familles d’événements acceptées ;
|
||||
- politique pour transaction réussie/échouée ;
|
||||
- sortie métier typée ;
|
||||
- idempotence et clés stables ;
|
||||
- résultat inséré, remplacé, ignoré ou refusé.
|
||||
|
||||
Le matérialiseur ne doit jamais modifier directement les tables core.
|
||||
|
||||
## Persistance et ledger
|
||||
|
||||
Définir les tables actives nécessaires avec le nommage :
|
||||
|
||||
```text
|
||||
kb_sol_decode_*
|
||||
kb_sol_mat_*
|
||||
kb_sol_ops_processing_ledger
|
||||
```
|
||||
|
||||
Ne pas créer de schema PostgreSQL applicatif explicite.
|
||||
|
||||
Le ledger doit distinguer au minimum :
|
||||
|
||||
```text
|
||||
stage = instruction_decode
|
||||
stage = event_materialization
|
||||
processor_name
|
||||
processor_version
|
||||
input_key
|
||||
input_hash
|
||||
status
|
||||
attempt_count
|
||||
error_code
|
||||
error_message
|
||||
```
|
||||
|
||||
Le skip doit dépendre de la version du processor et d’un hash déterministe de l’input pertinent. Le force replay doit remplacer uniquement les sorties appartenant au processor et à l’input ciblés.
|
||||
|
||||
## Couverture
|
||||
|
||||
Ajouter une matrice machine-readable permettant de comparer :
|
||||
|
||||
- entrées déclarées par le décodeur ;
|
||||
- entrées observées dans le corpus ;
|
||||
- entrées reconnues ;
|
||||
- entrées décodées ;
|
||||
- événements matérialisés ;
|
||||
- erreurs et inconnues ;
|
||||
- transactions réussies et échouées.
|
||||
|
||||
Ne pas considérer une surface clôturée tant que toutes les instructions et événements connus, y compris historiques et non directement liés au trading, ne sont pas classifiés.
|
||||
|
||||
## Orchestration `kb_pipeline`
|
||||
|
||||
Ajouter un pipeline versionné avec :
|
||||
|
||||
- sélection bornée des instructions core `pending`, `failed` ou `replay_requested` ;
|
||||
- sélection explicite par signatures, slots, program IDs et instruction paths ;
|
||||
- dispatch vers zéro, un ou plusieurs décodeurs compatibles selon la politique déclarée ;
|
||||
- concurrence bornée ;
|
||||
- arrêt coopératif ;
|
||||
- skip version/hash ;
|
||||
- force replay ;
|
||||
- résumé par processor et statut ;
|
||||
- persistance atomique des événements décodés et du ledger ;
|
||||
- appel optionnel des matérialiseurs après succès de persistance du décodage.
|
||||
|
||||
## Démo Tauri
|
||||
|
||||
Ajouter une fenêtre distincte, par exemple `demo_decode_replay`, sans surcharger `demo_core_extraction`.
|
||||
|
||||
Fonctions minimales :
|
||||
|
||||
- sélection de signatures copiées depuis `demo_sql_replay_candidates` ;
|
||||
- filtre program ID et instruction state ;
|
||||
- choix des décodeurs disponibles ;
|
||||
- version visible ;
|
||||
- force replay ;
|
||||
- journal et résumé ;
|
||||
- arrêt ;
|
||||
- liens vers diagnostics core, decode, ledger et couverture.
|
||||
|
||||
Aucun SQL libre.
|
||||
|
||||
## Tests obligatoires
|
||||
|
||||
Couvrir au minimum :
|
||||
|
||||
1. dispatch exact par program ID ;
|
||||
2. instruction inconnue classée sans faux décodage ;
|
||||
3. décodage réussi avec hash stable ;
|
||||
4. skip même version/hash ;
|
||||
5. replay après changement de version ;
|
||||
6. force replay sans duplication ;
|
||||
7. rollback des événements décodés et du ledger ;
|
||||
8. transaction échouée décodée comme observation non commitée ;
|
||||
9. refus de matérialiser un trade réussi depuis une transaction échouée ;
|
||||
10. arrêt coopératif et candidats non démarrés ;
|
||||
11. couverture déclarée contre couverture observée ;
|
||||
12. tests PostgreSQL optionnels sous `KB_POSTGRES_TEST_URL`.
|
||||
|
||||
Les tests unitaires doivent être offline.
|
||||
|
||||
## Hors périmètre
|
||||
|
||||
- décodage maximal System/SPL, prévu dans `0.4.1+` ;
|
||||
- Pump, Meteora, Raydium, Orca et autres protocoles ;
|
||||
- Helius `transactionSubscribe` ;
|
||||
- Yellowstone gRPC ;
|
||||
- wallet et trading ;
|
||||
- pools/paires déduits par heuristique depuis de simples account keys.
|
||||
|
||||
## Fichiers à lire en priorité
|
||||
|
||||
- `ROADMAP.md` ;
|
||||
- `RULES.md` ;
|
||||
- `docs/CORE_EXTRACTION_CONTRACTS.md` ;
|
||||
- `docs/CORE_EXTRACTION_SELECTION_AND_REPLAY.md` ;
|
||||
- `docs/INSTRUCTION_REPLAY_CONTRACTS.md` ;
|
||||
- `kb_decoder_api/` ;
|
||||
- `kb_materializer_api/` ;
|
||||
- `kb_store_core/src/dtos/core_dtos.rs` ;
|
||||
- `kb_store_core/src/repositories/storage_repositories.rs` ;
|
||||
- `kb_pipeline/src/core_extraction.rs` ;
|
||||
- `kb_store_pg/src/queries/core_extraction_queries.rs` ;
|
||||
- `kb_app_demo/src/demo_core_extraction.rs` ;
|
||||
- `kb_program_ids/src/lib.rs`.
|
||||
|
||||
## Règles de réalisation
|
||||
|
||||
- Rust 2024 ;
|
||||
- async-first ;
|
||||
- tracing obligatoire ;
|
||||
- erreurs explicites ;
|
||||
- aucun `?`, `unwrap`, `expect`, `anyhow` ou `thiserror` dans le code de production ;
|
||||
- aucun `use` sauf pour les traits ;
|
||||
- appels locaux via `crate::` ;
|
||||
- `#![warn(missing_docs)]`, `#![deny(unreachable_pub)]` et `#![forbid(unsafe_code)]` ;
|
||||
- documentation du code en anglais ;
|
||||
- documentation Markdown en français ;
|
||||
- headers `file` / `version` incrémentés à chaque modification ;
|
||||
- aucune ligne vide dans les corps de fonctions ou structures ;
|
||||
- TS-rs pour les types Tauri ;
|
||||
- ne pas modifier `CHANGELOG.md` avant validation complète.
|
||||
|
||||
## Validation attendue
|
||||
|
||||
```bash
|
||||
cargo test -p kb_decoder_api
|
||||
cargo test -p kb_materializer_api
|
||||
cargo test -p kb_store_core
|
||||
cargo test -p kb_pipeline
|
||||
KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
|
||||
cargo test -p kb_store_pg -- --nocapture
|
||||
cargo test -p kb_app_demo
|
||||
(cd kb_app_demo && npm run build)
|
||||
cargo clippy --all-targets
|
||||
cargo tauri dev -c kb_app_demo/tauri.conf.json
|
||||
```
|
||||
|
||||
## Livraison
|
||||
|
||||
Produire uniquement un zip delta :
|
||||
|
||||
```text
|
||||
khadhroony-bot2_v0.4.0-pre.001-delta.zip
|
||||
```
|
||||
|
||||
Le delta doit contenir `delta.md`, les fichiers ajoutés ou modifiés et la liste explicite des suppressions manuelles. Ne pas produire d’archive complète sauf demande explicite.
|
||||
Reference in New Issue
Block a user