v0.1.0-pre.074-fix001

This commit is contained in:
2026-08-01 09:08:19 +02:00
parent f1e9d6069b
commit 621bf3d2c4
8 changed files with 455 additions and 203 deletions

View File

@@ -1,5 +1,5 @@
<!-- file: RULES.md -->
<!-- version: 25 -->
<!-- version: 26 -->
# Index normatif de `khadhroony-bot3`
@@ -11,6 +11,7 @@ La lecture des documents suivants est obligatoire avant toute modification :
2. [`docs/rules/RULES_RUST.md`](docs/rules/RULES_RUST.md) — règles Rust réutilisables ;
3. [`docs/rules/RULES_SPECIFIC_KHADHROONY.md`](docs/rules/RULES_SPECIFIC_KHADHROONY.md) — architecture et conventions propres au workspace ;
4. [`docs/rules/CRATE_DOCUMENTATION_RULES.md`](docs/rules/CRATE_DOCUMENTATION_RULES.md) — contrat des `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md` de crates.
5. [`docs/rules/VERSION_DEVELOPMENT_LIFECYCLE.md`](docs/rules/VERSION_DEVELOPMENT_LIFECYCLE.md) — cadrage, prereleases, finalisation et archivage du plan de chaque version fonctionnelle.
Ces règles sont cumulatives. En cas de conflit, la règle la plus stricte sapplique. Une exception doit être explicite, locale, bornée et documentée.

View File

@@ -1,5 +1,5 @@
<!-- file: docs/IDEA_REMINDERS.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Rappels didées
@@ -32,3 +32,63 @@ Ce document regroupe les améliorations utiles mais non bloquantes pour la clôt
- Décider séparément si cette crate accepte uniquement des lectures ou aussi des opérations off-chain authentifiées/mutables, avec contrats de sécurité distincts.
- Borner tailles, types MIME, redirections, délais et schémas HTTP(S)/IPFS/Arweave.
- Ne pas coupler le fetch off-chain au décodage déterministe ni au replay canonique on-chain.
## Registre Program IDs, IDL et surfaces implémentées
- Analyser `olddocs/archivekbobobot/docs/SOLSCAN_ACCOUNT_SOURCE_MATRIX.md` et les documents équivalents de bot2.
- Construire un registre croisé contenant au minimum Program ID, protocole, source vérifiée, présence dIDL, provenance de lIDL et chemin local.
- Comparer ce registre avec les constantes de `kb-program-ids`.
- Comparer chaque entrée avec les décodeurs, exécuteurs et matérialisateurs réellement présents dans `kb-lib`.
- Distinguer les IDL provenant de Solscan, Solana Explorer, dépôts Git officiels ou autres sources vérifiées.
- Ne pas déclarer linventaire complet avant le rescan des archives bot2 et bobobot.
## Architecture future des workers et applications
Cette proposition doit être étudiée avant intégration au ROADMAP définitif.
### Worker W1 — acquisition temps réel
- Binaire long-running utilisant `kb-onchain-transport`.
- Écoute configurable de Program IDs, logs, comptes ou autres filtres.
- Support progressif WebSocket, gRPC et recours HTTP/RPC lorsque nécessaire.
- Écriture des signatures et transactions raw dans `kb-store`.
- Modification à chaud des abonnements.
- Notification fiable de larrivée de nouvelles données raw.
- Arrêt uniquement sur demande explicite ou erreur fatale contrôlée.
### Worker W2 — décodage et matérialisation temps réel
- Binaire recevant ou détectant les notifications de nouveaux raw.
- Exécution des décodeurs et matérialisateurs activés.
- Configuration à chaud des surfaces actives.
- Notification après décodage et matérialisation.
- Traitement uniquement des données reçues pendant son activité ; aucun rattrapage implicite des périodes darrêt.
### Application de rattrapage historique
- Application ou binaire séparé, éventuellement Tauri.
- Réutilisation des capacités Core extraction, decode replay et matérialisation.
- Traitement des raw non pris en charge en temps réel par W2.
- Coordination explicite pour éviter la concurrence ou la double prise en charge avec W2.
- Backfill ciblé pour combler des périodes manquantes.
- Décodage et matérialisation configurables comme dans W2.
### Pilotage W1/W2
- Application de contrôle permettant de modifier à chaud les filtres dacquisition, décodeurs et matérialisateurs.
- Diagnostics, état des workers, files dattente, erreurs et métriques.
- Contrats dadministration séparés des contrats de données.
### Applications consommatrices
- Application de trading consommant les événements temps réel de W2 et lhistorique de `kb-store`.
- Filtrage dévénements tels que nouveaux tokens, nouvelles paires, prix, migrations launchpad vers AMM, burns et changements de liquidité.
- Construction dhistoriques et OHLC depuis les matérialisations stockées.
- Application non trading utilisant la même combinaison temps réel et historique pour visualiser les autres matérialisations.
### Principe de déploiement progressif
- W1 doit pouvoir continuer à acquérir les raw pendant le développement de nouveaux décodeurs.
- W2 et les applications peuvent être redémarrés pour charger de nouvelles surfaces.
- Le rattrapage historique doit traiter les périodes non couvertes sans perturber le flux temps réel.
- Les frontières de notification, ownership de traitement, idempotence et reprise doivent être définies avant implémentation.

View File

@@ -1,5 +1,5 @@
<!-- file: docs/README.md -->
<!-- version: 7 -->
<!-- version: 8 -->
# Documentation active de Khadhroony Bot3

View File

@@ -1,5 +1,5 @@
<!-- file: docs/audits/V0_4_6_ALIGNMENT_AUDIT.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Audit ciblé dalignement `0.4.6`
@@ -243,59 +243,161 @@ Les différences suivantes sont des choix bot3 validés, pas des régressions :
- maintien de `kb-app-demo-desktop` comme package mixte ;
- maintien dun wallet minimal avant sa complétion en `0.5.x`.
## 9. Blocants démontrés avant passage officiel à `0.4.6`
## 9. Blocants ou vérifications à clôturer avant passage officiel à `0.4.6`
### 9.1 Desktop et contrat Tauri
La checklist historique contient encore de nombreuses tâches non cochées. Certaines sont déjà réalisées mais non réconciliées, certaines appartiennent à `0.4.7+`, et dautres restent réellement à vérifier.
Il reste à obtenir une validation explicite et complète de :
La liste suivante remplace la précédente liste trop restrictive.
1. la synchronisation des adaptateurs Tauri et des payloads TS-RS avec les APIs réutilisables ;
2. la couverture des cycles douverture, fermeture et réouverture des fenêtres concernées.
### 9.1 Réconciliation de la checklist historique
### 9.2 Cycle de vie WebSocket
Avant toute conclusion finale :
Le code place la session WebSocket dans `AppState`, distinctement de la fenêtre, et expose des commandes explicites de statut, connexion, désabonnement et déconnexion.
- confronter chaque tâche non cochée à létat actuel du code, des tests et de la documentation ;
- cocher les tâches déjà prouvées ;
- retirer ou archiver les formulations obsolètes ;
- transférer vers les TODO ou le ROADMAP les travaux `0.4.7+` ;
- ne conserver comme blocants `0.4.6` que les écarts encore démontrables.
Il reste néanmoins à valider explicitement :
La checklist demande encore un alignement final sur `0.4.7`, ce qui ne correspond plus à la trajectoire décidée : clôture de migration en `0.4.6`, puis reprise séparée de `0.4.7`.
1. que fermer `demo_ws` ne ferme pas une session active ;
2. que rouvrir `demo_ws` récupère létat courant ;
3. que larrêt intervient uniquement sur déconnexion explicite, fermeture de lapplication ou timeout prévu.
### 9.2 Preuves Devnet du périmètre `0.4.6`
Ces validations doivent être couvertes par des tests ou une campagne reproductible avant retrait des tâches du TODO.
La validation ATA, SPL Token classique et Token-2022 est documentée comme réalisée dans le prompt de reprise, alors que la checklist historique conserve ces tâches ouvertes.
### 9.3 Validation complète dans le workspace réel
Il faut :
Avant le changement de version, exécuter :
- rattacher les preuves disponibles aux tâches correspondantes ;
- fermer ATA classique, ATA Token-2022, SPL Token classique et les huit opérations Token-2022 réellement validées ;
- conserver ElGamal comme exception conditionnelle et non comme validation manquante bloquante ;
- vérifier si le replay System Transfer et Memo v4 après changement de nomenclature a déjà été exécuté ou doit être rejoué.
### 9.3 Nomenclature et contrats persistés
Vérifier avant alignement :
- laudit empêchant la réintroduction des anciennes identités persistées ;
- létat réel de la base Devnet après changement de nomenclature ;
- laudit Python final de nomenclature ;
- la cohérence entre matrices actives et registres compilés pour les surfaces `0.4.6`.
La réévaluation complète de chaque matrice lors de futures surfaces nest pas un blocant global `0.4.6`.
### 9.4 Règles et documentation active
Clôturer :
- la lecture croisée finale des règles ;
- la suppression des demandes historiques sans valeur normative ;
- la vérification quaucun document actif ne raconte encore la migration comme dépendance conceptuelle nécessaire ;
- la confirmation que les README et USAGE des onze crates correspondent à létat actuel ;
- la documentation de reconstruction PostgreSQL encore explicitement demandée par la checklist.
Linventaire complet Program IDs/IDL peut être traité ultérieurement, après rescan des archives, sauf lorsquune source est nécessaire pour valider une surface `0.4.6`.
### 9.5 Desktop, Tauri et interface
Vérifier explicitement :
- synchronisation Tauri/TS-RS ;
- cycles douverture, fermeture et réouverture ;
- séparateurs de menu ;
- absence de contrôles morts ou dupliqués ;
- correspondance entre options HTML, commandes Tauri et scénarios backend ;
- contrat de fenêtre pour Decode replay, Exécution Solana Core et Exécution SPL ;
- absence de logique métier substantielle restante dans `tauri.rs` ;
- tests unitaires placés dans les modules fonctionnels ;
- timeout HTTP et arrêt global de lapplication.
### 9.6 Cycle de vie WebSocket
Valider :
- fermer `demo_ws` ne ferme pas une session active ;
- rouvrir `demo_ws` récupère létat courant ;
- larrêt intervient uniquement sur déconnexion explicite, fermeture de lapplication ou timeout prévu ;
- les diagnostics et contrôles reflètent létat réel de la session.
### 9.7 Configuration, secrets et logging
Confirmer :
- seul `kb-config` charge `.env` ;
- ordre de priorité des variables et fichiers ;
- comportement `${VAR}` et `${VAR:-fallback}` ;
- absence de fuite de secrets ;
- résolution réelle de `HELIUS_API_KEY` ;
- absence de dépendance directe `dotenvy` dans les scénarios ;
- routes console `local_devnet` et `mainnet` ;
- targets `kb-lib.decoder.*`, `kb-lib.executor.*`, `kb-lib.materializer.*` ;
- absence de recréation de répertoires de logs danciennes crates.
### 9.8 PostgreSQL et fiabilité du pipeline
Décider et valider avant alignement :
- documentation des tables conservées, dérivées et de leur ordre de reconstruction ;
- contrôle des index et contraintes après reconstruction ;
- dimensionnement du pool ou justification du report ;
- retry borné pour les timeouts transitoires, ou preuve que ce correctif nest pas requis pour léquivalence `0.4.6` ;
- profils `local_devnet` et `mainnet` pendant la campagne finale.
### 9.9 Validation des surfaces desktop
Vérifier :
- Exécution Solana Core ;
- Exécution SPL ;
- options réellement exposées ;
- suppression des options mortes ;
- statut de `execute_devnet_spl_token_lifecycle` ;
- simulation, envoi, progression, résumé et diagnostics ;
- replay et matérialisation post-exécution pour les familles supportées.
### 9.10 Documentation opérateur minimale
Avant `0.4.6`, confirmer que la documentation active permet au minimum :
- création ou sélection du wallet de démonstration ;
- récupération de la clé publique ;
- saisie des champs desktop ;
- exécution des scénarios Solana Core et SPL ;
- compréhension des préconditions, signers, frais et résultats ;
- vérification du replay et des projections.
Les scénarios Metaplex appartiennent à `0.4.7`.
### 9.11 Validation finale du workspace
Exécuter dans le workspace réel :
```bash
cargo fmt --all
cargo test --workspace
cargo check --workspace
cargo clippy --all-targets
python3 scripts/audit_rust_workspace_rules.py
cargo test -p kb-pipeline-demo-scenarios
cargo test -p kb-app-demo-desktop
```
Exécuter également les tests ciblés de toute crate modifiée par les correctifs issus de cet audit.
Exécuter également :
La validation frontend doit utiliser :
- vérification des bindings TS-RS régénérés ;
- validation runtime de toutes les fenêtres ;
- validation HTTP, WebSocket, Backfill, Core extraction, Decode replay et SQL ;
- validation Solana Core et SPL sur Devnet ;
- vérification de larchive finale et absence de secrets ou artefacts exclus.
```bash
cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
```
## 10. Éléments explicitement reportés après `0.4.6`
## 10. Liste fermée des écarts à traiter
Ne doivent pas bloquer la version :
Avant `0.4.6`, traiter uniquement :
- validation Tauri/TS-RS ;
- validation des cycles de fenêtres ;
- validation du cycle de vie persistant de `demo_ws` ;
- éventuelles corrections directement révélées par ces validations ;
- exécution finale des commandes de validation du workspace.
Aucun nouvel audit complet des protocoles déjà validés nest requis.
- Metaplex Token Metadata complet, exécuteur et validations, pour `0.4.7` ;
- Anchor générique, pour `0.6.x` ;
- registre Program IDs/IDL complet après rescan historique ;
- workers W1/W2 et applications associées tant que leur version ROADMAP nest pas décidée ;
- wallet complet et split de configuration, pour `0.5.x` ;
- transports streaming avancés, pour `0.13.x` ;
- ElGamal réseau tant que son déploiement et ses preuves ne sont pas disponibles.
## 11. Conclusion
@@ -303,12 +405,12 @@ Aucun nouvel audit complet des protocoles déjà validés nest requis.
NOT_READY_FOR_0_4_6
```
Le périmètre fonctionnel historique de bot2 `0.4.6` est largement migré et les différences architecturales sont documentées. Le passage officiel reste bloqué par des validations desktop/WebSocket explicites et par la validation finale du workspace réel.
Le périmètre historique `0.4.6` paraît largement présent, mais la liste de cinq blocants précédemment publiée était incomplète. La checklist doit dabord être réconciliée et les familles de vérification des sections 9.2 à 9.11 doivent être clôturées ou explicitement reportées avec justification.
Après clôture de ces points, la conclusion pourra devenir :
La conclusion pourra devenir :
```text
READY_WITH_DOCUMENTED_EXCEPTIONS
```
Les exceptions documentées attendues sont le registre ElGamal non validé sur réseau et les travaux Metaplex Token Metadata réservés à `0.4.7`.
lorsque les vérifications restantes seront prouvées et que les seules exceptions seront explicitement documentées, notamment ElGamal non validé sur réseau et Metaplex réservé à `0.4.7`.

View File

@@ -0,0 +1,89 @@
<!-- file: docs/rules/VERSION_DEVELOPMENT_LIFECYCLE.md -->
<!-- version: 1 -->
# Cycle de développement dune version fonctionnelle
## 1. Objet
Toute nouvelle version fonctionnelle doit être préparée, exécutée et clôturée selon un cycle documentaire explicite.
La numérotation du plan suit la version réellement décidée. Le plan ne détermine pas artificiellement le numéro de version.
## 2. Première prerelease obligatoire
La première prerelease dune nouvelle version fonctionnelle, généralement `X.Y.Z-pre.001`, doit prioritairement :
- étudier les objectifs de la version ;
- inventorier les capacités existantes réutilisables ;
- identifier les dépendances et prérequis ;
- définir les éléments hors périmètre ;
- relever les risques, ambiguïtés et validations nécessaires ;
- produire un plan structuré des étapes de développement ;
- proposer un découpage approximatif des futures prereleases ;
- définir les critères de clôture fonctionnelle et documentaire.
Une version importante ne doit pas commencer directement par une modification fonctionnelle dispersée sans ce cadrage.
## 3. Plan temporaire de version
Lorsque la version contient plusieurs lots ou décisions architecturales, créer un document temporaire de planification.
Ce document peut contenir davantage dexplications que le ROADMAP général :
- pourquoi les étapes sont ordonnées ainsi ;
- alternatives examinées ;
- dépendances entre lots ;
- validations intermédiaires ;
- points de décision ;
- reports possibles ;
- critères darrêt ou de réorientation.
Le plan reste approximatif. Il peut évoluer lorsque le code, les tests ou les sources officielles révèlent de nouvelles contraintes.
## 4. Développement par prereleases
Chaque prerelease doit :
- traiter un lot cohérent ;
- mettre à jour les changelogs des crates réellement affectées ;
- retirer des TODO les tâches réellement terminées ;
- mettre à jour le plan temporaire lorsque lordre ou le périmètre change ;
- exécuter les validations exigées par les règles du workspace ;
- livrer un `delta.md` traçant les changements.
Les correctifs mineurs dune prerelease sont repliés dans son entrée de changelog. Un correctif substantiel peut recevoir une entrée dédiée selon les règles documentaires.
## 5. Dernière prerelease de finalisation
La dernière prerelease dune version fonctionnelle doit principalement :
- exécuter les validations finales ;
- corriger les écarts résiduels ;
- finaliser la documentation générale ;
- finaliser les documents des crates modifiées ou ajoutées ;
- supprimer des TODO les tâches clôturées ;
- reporter explicitement les tâches non réalisées ;
- transformer le plan temporaire en état final utile au ROADMAP ;
- mettre à jour le changelog général pour la version `X.Y.Z` ;
- préparer larchive ou la livraison finale.
Le ROADMAP conserve les objectifs et trajectoires utiles. Il ne doit pas devenir un journal détaillé des prereleases.
## 6. Archivage du plan
Après clôture de la version :
- le plan temporaire nest plus normatif ;
- ses informations durables doivent avoir été reprises dans le ROADMAP, les décisions, guides, TODO ou changelogs appropriés ;
- le plan doit être déplacé sous `olddocs/archivekbot3/` ;
- ses références actives doivent être corrigées avant archivage.
## 7. Arrêt anticipé dune version
Lorsquune version est interrompue pour une migration, une urgence ou un changement de priorité :
- documenter létat réellement atteint ;
- distinguer les capacités terminées des travaux incomplets ;
- reporter les tâches restantes vers une version identifiée ;
- mettre à jour les changelogs concernés ;
- archiver le plan après reprise de ses informations utiles.

View File

@@ -132,7 +132,7 @@ Comparer au minimum :
## 6. Checklist d'instructions IDL à inventorier
| Instruction | Discriminator hex |
|---|---|
|---------------------------------------------------|--------------------|
| `add_liquidity` | `b59d59438fb63448` |
| `add_liquidity2` | `e4a24e1c46db7473` |
| `add_liquidity_by_strategy` | `0703967f94283dc8` |
@@ -213,7 +213,7 @@ Comparer au minimum :
## 7. Checklist d'events Anchor IDL à inventorier
| Event | Discriminator hex |
|---|---|
|---------------------------------------------|--------------------|
| `AddLiquidity` | `1f5e7d5ae3343dba` |
| `CancelLimitOrderEvt` | `83eac285090ebdd1` |
| `ClaimFee` | `4b7a9a308c4a7ba3` |

View File

@@ -78,7 +78,7 @@ deferInstructionObservations=yes
## Matérialisation fee finale
| Event kind | Fee parents | Parents scalaires | Amount legs | Décision |
|---|---:|---:|---:|---|
|------------------------------------------------|------------:|------------------:|------------:|---------------------------------------------------------------|
| `meteora_dbc.claim_creator_trading_fee` | 8 | 8 | 8 | Mono-leg fiable. |
| `meteora_dbc.claim_partner_pool_creation_fee` | 10 | 10 | 10 | Mono-leg fiable. |
| `meteora_dbc.claim_protocol_fee` | 10 | 10 | 10 | Mono-leg fiable. |
@@ -119,7 +119,7 @@ La recovery `allowlisted_inner_spl_transfer` est volontairement non globale.
Elle a été testée sur anciennes bases pour enrichir les surfaces déjà connues :
| Surface testée | Résultat |
|---|---|
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `raydium_launchpad` | `claim_creator_fee`, `claim_platform_fee`, `claim_platform_fee_from_vault`, `collect_fee` enrichis en legs depuis CPI SPL. |
| `raydium_cpmm` | `collect_creator_fee` enrichi ; `collect_fund_fee` et `collect_protocol_fee` restent sans transfert réel exploitable dans le corpus testé. |
| `pump_swap` | `collect_coin_creator_fee` et certains `transfer_creator_fees_to_pump_v2` enrichis ; cas zero/no-transfer explicités. |

View File

@@ -51,7 +51,7 @@ Les `4 trades` et `16 candle upserts` du replay proviennent d'autres surfaces du
### Instructions observées et couvertes
| Instruction | Discriminator | Observation principale | Matérialisation |
|---|---:|---:|---|
|----------------------------------|-------------------:|---------------------------------:|-------------------------------|
| `sweep_buyback` | `8a21cc26cfa19fe2` | `96` | `k_sol_fee_events` |
| `create_fee_sharing_config` | `c34e564c6f34fbd5` | `42` observations / `36` decoded | `k_sol_pool_lifecycle_events` |
| `update_fee_shares` | `bd0d8863bba4ed23` | `26` observations / `16` decoded | `k_sol_pool_admin_events` |
@@ -70,7 +70,7 @@ Le discriminator `e445a52e51cb9a1d` est classé comme `pump_fees.anchor_self_cpi
Ces entrées n'ont pas de signature Solscan/corpus au moment de la clôture, mais restent décodables si des transactions futures apparaissent :
| Instruction | Discriminator | Classification | Target prévu |
|---|---:|---|---|
|-------------------------------|-------------------:|----------------|---------------------------|
| `reset_fee_sharing_config_v2` | `a9f511d15e5bf880` | admin_config | `k_sol_pool_admin_events` |
| `set_authority` | `85fa25156ea31a79` | admin_config | `k_sol_pool_admin_events` |
| `set_claim_rate_limit` | `b9d39faed4315804` | audit | decoded-only |
@@ -80,7 +80,7 @@ Ces entrées n'ont pas de signature Solscan/corpus au moment de la clôture, mai
### Anchor events IDL non observés mais testés synthétiquement
| Event Anchor | Discriminator | Statut |
|---|---:|---|
|--------------------------------|-------------------:|----------------------------|
| `SetAuthorityEvent` | `12af8442d0c957f2` | decoder + test synthétique |
| `SetClaimRateLimitEvent` | `0d8f8febb5133328` | decoder + test synthétique |
| `SetDisableFlagsEvent` | `0508b3413137917e` | decoder + test synthétique |
@@ -91,7 +91,7 @@ Ces entrées n'ont pas de signature Solscan/corpus au moment de la clôture, mai
Ces discriminators ont été trouvés par filtres Solscan, mais ne sont pas observés dans le corpus local final et ne sont pas dans l'IDL locale fournie. Ils restent conservés en coverage comme surfaces futures :
| Event | Discriminator | Statut |
|---|---:|---|
|----------------------------------------|-------------------:|----------------------------------|
| `revoke_fee_sharing_authority_event` | `7217653c0ebe993e` | `upstream_git_mapped_unverified` |
| `transfer_fee_sharing_authority_event` | `7c8fc6f54db808ec` | `upstream_git_mapped_unverified` |
@@ -100,7 +100,7 @@ Ces discriminators ont été trouvés par filtres Solscan, mais ne sont pas obse
Les écarts `observed_count > materialized_count` sont expliqués par des transactions failed ou par une politique decoded-only. La requête `09b` documente notamment :
| Entrée | Observed | Materialized | Explication |
|---|---:|---:|---|
|--------------------------------|---------:|-------------:|-------------------------|
| `get_fees` | `5` | `0` | decoded-only volontaire |
| `claim_social_fee_pda_v2` | `25` | `21` | `4` failed decoded |
| `create_fee_sharing_config` | `36` | `33` | `3` failed decoded |