From 5382cf8f435df93b13dd23732ee522d4e79ba635 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Fri, 31 Jul 2026 07:38:27 +0200 Subject: [PATCH] v0.1.0-pre.067 --- README.md | 147 ++++++------------ docs/DOCUMENTATION_REFACTOR_PLAN.md | 31 ++-- docs/README.md | 131 ++++++---------- docs/architecture/ARCHITECTURE.md | 107 +++++++++++++ docs/architecture/CRATE_MAP.md | 51 ++++++ docs/architecture/PIPELINE_ARCHITECTURE.md | 55 +++++++ docs/architecture/PROJECT_OBJECTIVES.md | 75 +++++++++ docs/architecture/STORAGE_ARCHITECTURE.md | 64 ++++++++ docs/architecture/SURFACE_CRATE_MATRIX.md | 35 +++++ ..._14_0.from_github_mpl-token-metadata.json} | 0 scripts/fetch_metaplex_token_metadata_idl.sh | 2 +- 11 files changed, 505 insertions(+), 193 deletions(-) create mode 100644 docs/architecture/ARCHITECTURE.md create mode 100644 docs/architecture/CRATE_MAP.md create mode 100644 docs/architecture/PIPELINE_ARCHITECTURE.md create mode 100644 docs/architecture/PROJECT_OBJECTIVES.md create mode 100644 docs/architecture/STORAGE_ARCHITECTURE.md create mode 100644 docs/architecture/SURFACE_CRATE_MATRIX.md rename idls/{metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_solscan.json => metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_github_mpl-token-metadata.json} (100%) diff --git a/README.md b/README.md index a50c528..3c3f5b0 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,64 @@ - + # Khadhroony Bot3 -Khadhroony Bot3 is the consolidated successor workspace to `khadhroony-bot2`. +`khadhroony-bot3` est le workspace Rust consolidé succédant à `khadhroony-bot2` pour l’acquisition, le stockage, le décodage, la matérialisation, la validation et l’exécution contrôlée d’opérations Solana. -## Workspace crates +## Architecture -- `kb-core`: foundation errors and shared primitives. -- `kb-config`: configuration contracts. -- `kb-lib`: all decoder, executor and materializer APIs and implementations. -- `kb-logging`: logging and tracing runtime. -- `kb-program-ids`: Solana program identifier registry. -- `kb-pipeline`: ingestion, decoding, materialization and execution orchestration. -- `kb-onchain-transport`: HTTP and WebSocket Solana transports. -- `kb-store`: store-neutral contracts and PostgreSQL implementation modules. -- `kb-wallet`: wallet and signer support. -- `kb-app-demo`: the only binary retained during the initial migration. +Le workspace contient 11 crates : -## Migration principle +- `kb-core` : erreurs et primitives transversales ; +- `kb-config` : chargement et validation de la configuration ; +- `kb-lib` : modèles, décodeurs, exécuteurs et matérialisateurs ; +- `kb-logging` : logging et tracing ; +- `kb-program-ids` : registre des programmes et comptes Solana connus ; +- `kb-pipeline` : backfill, extraction Core, replay et orchestration ; +- `kb-pipeline-demo-scenarios` : bibliothèque de scénarios et CLI ; +- `kb-onchain-transport` : transports RPC HTTP et WebSocket ; +- `kb-store` : contrats de stockage et adaptateur PostgreSQL ; +- `kb-wallet` : frontière de wallet et signataires, encore incomplète ; +- `kb-app-demo-desktop` : bibliothèque et application Tauri de démonstration. -The previous workspace is preserved under `migration/khadhroony-bot2-reference`. The new workspace compiles independently as a controlled scaffold. Public APIs are ported into `kb-lib` module by module, with compatibility recorded in `migration/module-map.json`. +La vue détaillée est disponible dans : -## Validation +- [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) ; +- [`docs/architecture/CRATE_MAP.md`](docs/architecture/CRATE_MAP.md) ; +- [`docs/architecture/PIPELINE_ARCHITECTURE.md`](docs/architecture/PIPELINE_ARCHITECTURE.md) ; +- [`docs/architecture/STORAGE_ARCHITECTURE.md`](docs/architecture/STORAGE_ARCHITECTURE.md) ; +- [`docs/architecture/SURFACE_CRATE_MATRIX.md`](docs/architecture/SURFACE_CRATE_MATRIX.md). + +## État fonctionnel + +La migration a repris un périmètre proche de `khadhroony-bot2 v0.4.6`, ainsi qu’une partie du travail `0.4.7` consacré à Metaplex Token Metadata. + +Le workspace bot3 n’est pas encore officiellement réaligné sur `0.4.6`. Cette décision dépend de l’audit ciblé prévu dans `docs/V0_4_6_ALIGNMENT_AUDIT.md`. + +Le registre ElGamal ne doit pas être présenté comme validé sur Devnet ou Mainnet. + +## Documentation + +L’index actif se trouve dans [`docs/README.md`](docs/README.md). + +Les règles normatives commencent dans [`RULES.md`](RULES.md). Les règles spécialisées sont placées sous [`docs/rules/`](docs/rules/). + +La documentation historique bot2 est conservée sous `olddocs/archivekbot2/`. Elle sert de source historique et n’est pas normative pour bot3. + +## Validation générale ```bash cargo fmt --all cargo check --workspace +cargo clippy --all-targets +python3 scripts/audit_rust_workspace_rules.py cargo test --workspace -cargo clippy --workspace --all-targets ``` -## État de migration `0.1.0-pre.001` +Les changements documentaires purs peuvent se limiter à l’audit des règles lorsque le delta ne modifie ni code ni configuration d’exécution. -- `kb-wallet` remplace définitivement le scaffold `kb_wallet`. -- `kb-core` conserve l’architecture de `kb_core` : implémentations dans `error.rs` et `module.rs`, façade et réexports dans `lib.rs`. -- Les prochaines APIs consolidées de `kb-lib` suivront la même règle : aucun contrat métier ne sera défini directement dans `lib.rs`. - -## Contrats consolidés - -À partir de `0.1.0-pre.002`, `kb-lib` porte les modèles et contrats fondamentaux autrefois répartis entre `kb_model`, `kb_decoder_api`, `kb_materializer_api` et `kb_execution_api`. Les implémentations restent dans des modules dédiés ; `kb-lib/src/lib.rs` ne contient que les déclarations de modules et les réexports publics. - -## Stockage consolidé - -À partir de `0.1.0-pre.003`, `kb-store` remplace le scaffold initial par une implémentation complète : - -- contrats store-neutral : DTO, entités, pagination, santé et traits de repository ; -- adaptateur PostgreSQL : connexion, initialisation idempotente, requêtes, diagnostics et replay ; -- façade unique dans `kb-store/src/lib.rs` ; -- modèle de replay partagé conservé dans `kb-lib`, sans duplication ; -- options PostgreSQL indépendantes de `kb-config`, adaptées par la frontière applicative. - -## Décodeurs consolidés - -`0.1.0-pre.004` porte le décodeur Solana Core dans `kb-lib`. `0.1.0-pre.005` ajoute SPL Memo v1, v3 et v4. `0.1.0-pre.006` ajoute le décodeur SPL Token classique avec ses 28 tags publiés, son wire borné, ses formes d’autorité et son `Batch` structuré. `0.1.0-pre.007` ajoute le programme SPL Associated Token Account avec ses trois instructions, sa forme historique `Create` vide et la validation canonique des PDA pour SPL Token classique et Token‑2022. - -`0.1.0-pre.008` porte le décodeur Token‑2022 maximal, son parseur d’états Mint/Account/Multisig et de TLV, ainsi que le programme indépendant du registre ElGamal. Les deux composants gardent des frontières et des targets de tracing distincts. Tous les décodeurs migrés utilisent les mêmes contrats contextualisés, la même façade publique et aucune dépendance inverse vers `kb-store`. - -`0.1.0-pre.009` porte le décodeur indépendant Metaplex Token Metadata. Il couvre les 58 discriminateurs d’instructions publiés `0..=57`, les 15 variantes de comptes `Key 0..=14`, les PDA officiels et les layouts courants, expérimentaux et historiques. Les metadata externes Metaplex restent séparées des metadata incorporées de Token‑2022, de Metaplex Core et de Bubblegum. - -`0.1.0-pre.012` restaure les 98 squelettes de décodeurs réservés sous forme de types `Dc*Decoder` implémentant `DcApiProtocolDecoder`. Les 97 surfaces identifiables déclarent leur Program ID exact dans `kb-program-ids`; Anchor reste volontairement sans identifiant statique. Ces squelettes répondent `Maybe` sans produire de faux événement et sont exposés uniquement par la façade `kb_lib`. - -## Matérialisateurs consolidés - -`0.1.0-pre.010` porte les quatre matérialisateurs Solana natifs dans `kb-lib` : - -- `MtLifecycleMaterializer` pour les comptes System, nonces, ALT, loaders, Feature Gate, contextes ZK et rapports Slashing ; -- `MtAdminMaterializer` pour les assignations, configurations et autorités, avec ses projections stateful Token‑2022 et registre ElGamal ; -- `MtComplianceAuditMaterializer` pour les écritures et copies bornées de bytecode ; -- `MtStakingMaterializer` pour les transitions Stake et Vote commitées. - -Les identités historiques des processors sont conservées pour la compatibilité des replays, tandis que les targets de tracing suivent désormais la hiérarchie `kb-lib.materializer.*`. Le contrat public `MtApiEventMaterializer`, ses modèles d’entrée et ses résultats restent réexportés à la racine de `kb-lib`, afin qu’un futur crate externe puisse fournir un matérialiseur sans dépendre d’une implémentation interne. - -`0.1.0-pre.011` termine le port des matérialisateurs réellement implémentés dans bot2 : - -- `MtTransactionAnnotationMaterializer` pour les Memo commitées ; -- `MtTokenAccountsMaterializer` pour les mutations SPL Token, le lifecycle ATA et les snapshots Token‑2022 ; -- `MtFeesMaterializer` pour les frais publics et confidentiels Token‑2022, sans prétendre déchiffrer les valeurs confidentielles ; -- `MtRiskMaterializer` pour les faits de risque SPL Token et ATA sans score arbitraire ; -- `MtMetadataMaterializer` pour les snapshots descriptifs Token‑2022 et Metaplex, sans fetch off-chain. - -Les modules de matérialisation sont privés. Tous les contrats, types concrets et helpers destinés aux consommateurs externes sont exposés exclusivement par `kb-lib/src/lib.rs`. Des tests aval distincts protègent les contrats d’extension `DcApiProtocolDecoder`, `MtApiEventMaterializer` et `ExApiInstructionExecutor`. - -`0.1.0-pre.013` remplace les 14 dernières frontières temporaires de matérialisation par des squelettes `Mt*Materializer`. Ils conservent le contrat historique `MtMaterializer`, implémentent également `MtApiEventMaterializer`, restent volontairement inactifs et ne produisent aucun faux événement via l’API bot3. Tous les types sont accessibles exclusivement depuis la façade `kb_lib`. - -`0.1.0-pre.014` confirme la parité de l’API publique `ExApi*` avec bot2 et remplace les 104 frontières temporaires d’exécution par des squelettes `Ex*Executor`. Chaque squelette référence uniquement ses Program IDs enregistrés, annonce `Maybe` sur sa surface et construit exclusivement un plan réservé à zéro instruction. Les exécuteurs opérationnels seront portés séparément, en commençant par Solana Core puis SPL. - -`0.1.0-pre.015` rend `ExSolanaCoreExecutor` fonctionnel. Il construit des plans déterministes pour 109 opérations natives réparties sur 18 surfaces, conserve les refus explicites des programmes historiques non exécutables et expose ses intents sous les préfixes bot3 `ExSolanaCore*` et `EX_SOLANA_CORE_*`. Les 103 autres exécuteurs restent réservés jusqu’à leur port fonctionnel. - -`0.1.0-pre.016` intègre le moteur transversal `ExSafetyChecker` et rend `ExSplMemoExecutor` fonctionnel. Memo v4 produit une instruction officielle bornée et soumise à simulation ; les générations historiques v1/v3 restent decode-only. Les 102 autres exécuteurs restent réservés jusqu’à leur port fonctionnel. - - -### Migration pipeline - -La tranche `0.1.0-pre.029` migre la planification et l’extraction core de `kb-pipeline`. - -### Pipeline migré - -`kb-pipeline` contient désormais l’extraction core et le replay contextuel de décodage avec matérialisation optionnelle. - - -### Backfill HTTP - -La tranche `0.1.0-pre.031` ajoute l’orchestration HTTP de backfill : signatures explicites ou historiques par adresse, pagination bornée, hydration via `getTransaction`, retries, annulation, reprise déterministe et persistance des observations. - -La migration de `kb-pipeline` couvre désormais le backfill, l'extraction core, le replay de décodage, la validation Token-2022 et les lectures stateful/préflight Token-2022 et ElGamal Registry. - - -### Migration `0.1.0-pre.037` - -`kb-pipeline` inclut désormais les contrôles stateful bornés des opérations Solana natives. - -## Recherche ciblée des exports TS-RS - -Pour éviter `node_modules`, limiter la recherche aux sources Rust : +La validation frontend desktop s’effectue uniquement avec : ```bash -find kb-config kb-lib kb-app-demo-desktop -type f -name '*.rs' -print0 \ - | xargs -0 grep -n 'export_to' +cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json ``` - -Le fichier `.env` optionnel est chargé depuis la racine du workspace, puis depuis `kb-app-demo-desktop/.env`. Les valeurs existantes de l'environnement ne sont pas remplacées. diff --git a/docs/DOCUMENTATION_REFACTOR_PLAN.md b/docs/DOCUMENTATION_REFACTOR_PLAN.md index d5c69f3..636cbcc 100644 --- a/docs/DOCUMENTATION_REFACTOR_PLAN.md +++ b/docs/DOCUMENTATION_REFACTOR_PLAN.md @@ -1,5 +1,5 @@ - + # Plan de refonte documentaire @@ -195,7 +195,20 @@ Validations obligatoires : python3 scripts/audit_rust_workspace_rules.py ``` -### Delta 5 — changelog général de transition +### Delta 5 — documentation générale bot3 (`v0.1.0-pre.067`) + +Travail : + +1. remplacer le README racine obsolète par une présentation stable ; +2. créer les objectifs et l’architecture générale ; +3. créer la carte des 11 crates ; +4. documenter les architectures pipeline et stockage ; +5. créer une matrice de responsabilités par surface sans dupliquer les matrices contractuelles ; +6. mettre à jour `docs/README.md`. + +Ces documents sont réécrits pour bot3 à partir du workspace actuel et des sources historiques vérifiées. + +### Delta 6 — changelog général de transition Travail : @@ -209,7 +222,7 @@ Travail : Le changelog ne doit pas affirmer que bot3 est déjà officiellement `0.4.6`. -### Delta 6 — roadmap général +### Delta 7 — roadmap général Reconstruire `ROADMAP.md` selon les séries suivantes : @@ -229,7 +242,7 @@ Reconstruire `ROADMAP.md` selon les séries suivantes : Le roadmap ne contient ni prereleases, ni correctifs `fix`, ni journal détaillé du passé. -### Delta 7 — documentation des crates fondamentales +### Delta 8 — documentation des crates fondamentales Ordre proposé : @@ -241,7 +254,7 @@ Ordre proposé : Pour chaque crate : auditer les exports publics, tests, erreurs, exemples existants et dépendances avant de rédiger les quatre fichiers. -### Delta 8 — documentation du noyau fonctionnel +### Delta 9 — documentation du noyau fonctionnel Ordre proposé : @@ -251,7 +264,7 @@ Ordre proposé : `kb-lib` devra être traité par sections cohérentes et liens vers les matrices, sans transformer son README en catalogue exhaustif de toutes les fonctions. -### Delta 9 — démonstrations et wallet +### Delta 10 — démonstrations et wallet Ordre proposé : @@ -265,7 +278,7 @@ Les TODO doivent expliciter : - les contraintes de validation Tauri ; - le statut d’ébauche de `kb-wallet` et son périmètre `0.5.x`. -### Delta 10 — réorganisation des documents actifs +### Delta 11 — réorganisation des documents actifs Travail : @@ -278,7 +291,7 @@ Travail : Aucun déplacement ne doit laisser de lien cassé. -### Delta 11 — refonte des prompts +### Delta 12 — refonte des prompts Travail : @@ -288,7 +301,7 @@ Travail : 4. migrer les informations bot3 utiles ; 5. archiver les deux prompts de migration actuels lorsque leurs informations ont été reprises. -### Delta 12 — audit d’alignement `0.4.6` +### Delta 13 — audit d’alignement `0.4.6` Créer : diff --git a/docs/README.md b/docs/README.md index c9cd6ba..8a66d3c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,84 +1,77 @@ - + -# Documentation de `khadhroony-bot3` +# Documentation active de Khadhroony Bot3 -## 1. Rôle +## 1. Statut -Ce répertoire contient la documentation active, normative ou encore utilisée de `khadhroony-bot3`. +Ce répertoire contient la documentation active, normative ou opérationnelle de `khadhroony-bot3`. -La documentation historique de `khadhroony-bot2` et les documents bot3 remplacés sont conservés séparément sous `olddocs/`. Un document archivé peut servir de source historique, mais il n’est pas normatif pour l’architecture bot3 actuelle. +La documentation historique de `khadhroony-bot2` est conservée sous `olddocs/archivekbot2/`. Elle ne doit être ni déplacée vers `docs/`, ni considérée comme normative. Tout nouveau document bot3 est réécrit après lecture du code, des tests, des matrices et des sources historiques pertinentes. -## 2. Documents de pilotage actifs +## 2. Architecture -| Document | Rôle | -|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| -| [`DOCUMENTATION_REFACTOR_AUDIT.md`](DOCUMENTATION_REFACTOR_AUDIT.md) | inventaire et écarts documentaires de la base `v0.1.0-pre.062` | -| [`DOCUMENTATION_REFACTOR_PLAN.md`](DOCUMENTATION_REFACTOR_PLAN.md) | séquence contrôlée de reconstruction documentaire et d’alignement `0.4.6` | -| [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md) | justification durable de la contrainte `wincode 0.5.x` et du contrôle du lockfile | -| [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) | critères normatifs de conservation et d’exclusion dans les archives documentaires | +- [`architecture/PROJECT_OBJECTIVES.md`](architecture/PROJECT_OBJECTIVES.md) : objectifs et limites du projet ; +- [`architecture/ARCHITECTURE.md`](architecture/ARCHITECTURE.md) : couches et flux principaux ; +- [`architecture/CRATE_MAP.md`](architecture/CRATE_MAP.md) : responsabilités des 11 crates ; +- [`architecture/PIPELINE_ARCHITECTURE.md`](architecture/PIPELINE_ARCHITECTURE.md) : orchestration, replay et exécution ; +- [`architecture/STORAGE_ARCHITECTURE.md`](architecture/STORAGE_ARCHITECTURE.md) : contrats de stockage et PostgreSQL ; +- [`architecture/SURFACE_CRATE_MATRIX.md`](architecture/SURFACE_CRATE_MATRIX.md) : répartition des responsabilités par surface. -## 3. Documents existants à reclasser +## 3. Règles -Les documents suivants restent temporairement à leur chemin actuel jusqu’au delta de réorganisation : +Le point d’entrée normatif unique est [`../RULES.md`](../RULES.md). + +Règles spécialisées : + +- [`rules/RULES_GENERAL.md`](rules/RULES_GENERAL.md) ; +- [`rules/RULES_RUST.md`](rules/RULES_RUST.md) ; +- [`rules/RULES_SPECIFIC_KHADHROONY.md`](rules/RULES_SPECIFIC_KHADHROONY.md) ; +- [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md). + +Modèles documentaires non génératifs : + +- [`templates/CRATE_README_TEMPLATE.md`](templates/CRATE_README_TEMPLATE.md) ; +- [`templates/CRATE_TODO_TEMPLATE.md`](templates/CRATE_TODO_TEMPLATE.md) ; +- [`templates/CRATE_USAGE_TEMPLATE.md`](templates/CRATE_USAGE_TEMPLATE.md) ; +- [`templates/CRATE_CHANGELOG_TEMPLATE.md`](templates/CRATE_CHANGELOG_TEMPLATE.md). + +## 4. Audits et décisions en cours + +- [`DOCUMENTATION_REFACTOR_AUDIT.md`](DOCUMENTATION_REFACTOR_AUDIT.md) ; +- [`DOCUMENTATION_REFACTOR_PLAN.md`](DOCUMENTATION_REFACTOR_PLAN.md) ; +- [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) ; +- [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md). + +Ces audits seront archivés sous `olddocs/archivekbot3/` lorsqu’ils auront été remplacés par des documents normatifs ou des rapports de clôture. + +## 5. Documents techniques actifs à reclasser + +Les documents suivants restent actifs mais seront reclassés progressivement après correction de leurs références : - `DEVNET_EXECUTION_GUIDE.md` ; - `PRE_062_DEVNET_VALIDATION_REPORT.md` ; -- `OPERATION_NAMING_CONVENTION.md` ; - `IDL_AUDIT.md` ; - `IDL_TO_KB_LIB_NOMENCLATURE.md` ; - `MISSING_PROGRAM_IDLS.md` ; +- `OPERATION_NAMING_CONVENTION.md` ; - `IDEA_REMINDERS.md`. -Leur présence à la racine de `docs/` est transitoire. Ils ne doivent pas être déplacés avant correction de leurs références. +Les idées de `IDEA_REMINDERS.md` ne doivent rejoindre un `TODO.md` de crate qu’après confirmation, attribution et reformulation en tâche vérifiable. -## 4. Arborescence cible +## 6. Matrices contractuelles + +Les matrices canoniques sont conservées sous : ```text -docs/ -├── README.md -├── architecture/ -├── audits/ -├── decisions/ -├── generated/ -├── guides/ -├── migrations/ -├── protocols/ -├── rules/ -└── validation/ +test-fixtures/contract-matrices/ ``` -Les répertoires sont créés lorsqu’un document réel doit y être classé. Aucun fichier factice n’est requis. +Elles peuvent être chargées directement par les tests unitaires ou d’intégration. Elles ne doivent pas être dupliquées sous `docs/`. Les documents actifs peuvent les référencer et expliquer leur rôle. -## 5. Archives historiques +## 7. Documentation par crate -### 5.1 Archive bot2 - -```text -olddocs/archivekbot2/ -``` - -Cette archive reproduit les chemins relatifs des fichiers sélectionnés selon leur fonction documentaire dans l’archive complète bot2 fournie pour la session. La sélection ne dépend pas de l’extension et suit [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md). Elle comprend notamment : - -- les documents racine historiques ; -- `docs/` ; -- `prompts/` ; -- les README, changelogs et autres documents des anciennes crates ; -- les matrices, schémas, exemples de configuration et IDL ayant une valeur documentaire démontrée. - -Les fichiers sont conservés sans adaptation de fond. Les liens relatifs peuvent viser l’ancienne arborescence bot2 et ne garantissent pas une navigation fonctionnelle depuis bot3. - -### 5.2 Archive bot3 - -```text -olddocs/archivekbot3/ -``` - -Cette archive recevra progressivement les audits, plans, prompts et documents bot3 remplacés qui conservent une valeur historique, décisionnelle ou de traçabilité. - -## 6. Contrat documentaire des crates - -Chaque crate doit finalement posséder exactement : +Chaque crate devra posséder : ```text README.md @@ -87,26 +80,4 @@ USAGE.md CHANGELOG.md ``` -`USAGE.md` est la convention retenue. La variante `USAGES.md` est obsolète. - -Le contenu attendu de chaque fichier est défini par [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md). Les modèles de `docs/templates/` servent uniquement d’aide à la rédaction. - -## 7. Règles de consultation - -Ordre recommandé : - -1. `RULES.md` à la racine du workspace ; -2. les règles secondaires à leur emplacement normatif courant ; -3. le présent index ; -4. les documents d’architecture ou de validation liés à la tâche ; -5. `olddocs/` uniquement pour l’historique ou la reprise contrôlée d’informations. - -## Règles et modèles documentaires - -- [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md) : contrat normatif des quatre documents de chaque crate ; -- [`templates/CRATE_README_TEMPLATE.md`](templates/CRATE_README_TEMPLATE.md) ; -- [`templates/CRATE_TODO_TEMPLATE.md`](templates/CRATE_TODO_TEMPLATE.md) ; -- [`templates/CRATE_USAGE_TEMPLATE.md`](templates/CRATE_USAGE_TEMPLATE.md) ; -- [`templates/CRATE_CHANGELOG_TEMPLATE.md`](templates/CRATE_CHANGELOG_TEMPLATE.md). - -Les modèles ne doivent jamais être remplis mécaniquement : la rédaction exige la lecture du code, des exports publics, des tests et des sources historiques pertinentes. +Leur création commencera après stabilisation des documents transversaux, par lots de crates. `USAGE.md` documentera les APIs publiques réelles et pourra signaler les tests particulièrement instructifs. diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md new file mode 100644 index 0000000..85790ea --- /dev/null +++ b/docs/architecture/ARCHITECTURE.md @@ -0,0 +1,107 @@ + + + +# Architecture générale + +## 1. Vue d’ensemble + +Le workspace est organisé en couches orientées responsabilités : + +```text +configuration ─────┐ +logging ───────────┼──────────────┐ +program IDs ───────┘ │ + v +transport -> store -> pipeline -> kb-lib + │ │ + v v + demo scenarios wallet/signers + │ │ + └────┬─────┘ + v + desktop demo application +``` + +Cette représentation indique les relations dominantes. Elle ne remplace pas le graphe exact des dépendances Cargo. + +## 2. Couches + +### 2.1 Fondations + +- `kb-core` fournit les erreurs et identités transversales minimales. +- `kb-config` charge, résout et valide la configuration. +- `kb-logging` initialise le logging et le tracing. +- `kb-program-ids` centralise les identifiants de programmes et comptes connus. + +### 2.2 Noyau métier + +`kb-lib` contient quatre familles principales : + +- modèles et contrats partagés ; +- décodeurs ; +- exécuteurs ; +- matérialisateurs. + +La façade publique est constituée par les réexports de `kb-lib/src/lib.rs`. Les modules internes conservent leurs frontières et leurs conventions de nommage. + +### 2.3 Acquisition et stockage + +- `kb-onchain-transport` fournit les clients HTTP/WebSocket, pools, rôles d’endpoints, méthodes RPC standard et contrats liés à l’exécution RPC. +- `kb-store` regroupe les contrats store-neutral et l’implémentation PostgreSQL. + +Les transports n’effectuent pas la matérialisation métier. Le stockage ne décide pas quelle surface protocolaire doit être décodée. + +### 2.4 Orchestration + +`kb-pipeline` orchestre : + +- backfill ; +- extraction Core ; +- replay de décodage ; +- matérialisation ; +- corrélation stateful ; +- préflight et orchestration d’exécution pour les surfaces prises en charge. + +Il dépend des contrats de `kb-lib`, des données de `kb-store` et des capacités de `kb-onchain-transport` sans absorber leurs responsabilités. + +### 2.5 Démonstrations et applications + +- `kb-pipeline-demo-scenarios` fournit une bibliothèque réutilisable et le binaire `kb-pipeline-demo-scenarios-cli`. +- `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop. +- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Son périmètre reste incomplet. + +## 3. Flux principal de données + +```text +Solana RPC / WebSocket + │ + v +kb-onchain-transport + │ + v +kb-store (données brutes/canoniques) + │ + v +kb-pipeline + │ + ├── extraction Core + ├── sélection des décodeurs + ├── décodage via kb-lib + ├── matérialisation via kb-lib + └── stockage des résultats +``` + +L’exécution suit un flux séparé : intention typée, construction, préflight, simulation, confirmation opérateur, envoi, confirmation et validation postérieure lorsque la surface le permet. + +## 4. Frontières obligatoires + +- Les IDs canoniques ne doivent pas être dispersés lorsqu’ils appartiennent au registre de `kb-program-ids`. +- Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par `kb-lib`. +- Les commandes Tauri et payloads frontend spécifiques restent dans `kb-app-demo-desktop`. +- Les scénarios réutilisables doivent migrer vers `kb-pipeline-demo-scenarios` plutôt que rester enfouis dans l’UI. +- Les fixtures contractuelles communes restent sous `test-fixtures/contract-matrices/` lorsqu’elles sont consommées par plusieurs tests. +- Les archives documentaires ne participent ni au build ni aux décisions normatives. + +## 5. État de migration + +L’architecture bot3 est largement alignée fonctionnellement sur le périmètre bot2 proche de `0.4.6`, avec des travaux `0.4.7` partiellement migrés. L’alignement officiel de version reste conditionné à l’audit ciblé prévu par `docs/V0_4_6_ALIGNMENT_AUDIT.md`. diff --git a/docs/architecture/CRATE_MAP.md b/docs/architecture/CRATE_MAP.md new file mode 100644 index 0000000..7ebd231 --- /dev/null +++ b/docs/architecture/CRATE_MAP.md @@ -0,0 +1,51 @@ + + + +# Carte des crates + +## 1. Inventaire + +| Crate | Type | Responsabilité principale | État documentaire | +|------------------------------|------------------------|--------------------------------------------------------------------|------------------------------------| +| `kb-core` | bibliothèque | erreurs, résultat et identité de module partagés | contrat par crate à créer | +| `kb-config` | bibliothèque | configuration JSON, environnement, validation et profils | contrat par crate à créer | +| `kb-lib` | bibliothèque | modèles, décodeurs, exécuteurs et matérialisateurs consolidés | contrat par crate à créer | +| `kb-logging` | bibliothèque | initialisation du logging et du tracing | contrat par crate à créer | +| `kb-program-ids` | bibliothèque | registre des programmes et comptes Solana connus | contrat par crate à créer | +| `kb-pipeline` | bibliothèque | backfill, extraction, replay, stateful, préflight et orchestration | contrat par crate à créer | +| `kb-pipeline-demo-scenarios` | bibliothèque + binaire | scénarios Devnet réutilisables et CLI | contrat par crate à créer | +| `kb-onchain-transport` | bibliothèque | transports RPC HTTP/WebSocket et pools d’endpoints | contrat par crate à créer | +| `kb-store` | bibliothèque | contrats de stockage et adaptateur PostgreSQL | contrat par crate à créer | +| `kb-wallet` | bibliothèque | wallet temporaire et frontière de signataire | ébauche à documenter explicitement | +| `kb-app-demo-desktop` | bibliothèque + binaire | application de démonstration Tauri | contrat par crate à créer | + +## 2. Consolidations principales depuis bot2 + +La migration a regroupé de nombreuses anciennes crates dans des frontières plus larges : + +- les modèles et APIs de décodage, matérialisation et exécution ont rejoint `kb-lib` ; +- les implémentations de stockage core et PostgreSQL ont rejoint `kb-store` ; +- les responsabilités de pipeline ont été réunies dans `kb-pipeline` ; +- les transports Solana sont réunis dans `kb-onchain-transport` ; +- l’application et sa bibliothèque sont réunies dans `kb-app-demo-desktop` ; +- les scénarios réutilisables ont été extraits dans `kb-pipeline-demo-scenarios`. + +Cette carte n’est pas une table de compatibilité exhaustive des anciennes crates. Les correspondances historiques détaillées seront synthétisées dans la documentation de migration et l’audit d’alignement. + +## 3. Crates mixtes + +### 3.1 `kb-pipeline-demo-scenarios` + +- bibliothèque Rust : `kb_pipeline_demo_scenarios` ; +- binaire : `kb-pipeline-demo-scenarios-cli` ; +- `autobins = false` évite une cible implicite concurrente. + +### 3.2 `kb-app-demo-desktop` + +- bibliothèque Rust : `kb_app_demo_desktop_lib` ; +- binaire : `kb-app-demo-desktop` ; +- le package reste volontairement unique. + +## 4. Relations documentaires + +Chaque crate devra disposer de `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md`. Les documents transversaux présents dans `docs/architecture/` évitent de répéter l’architecture complète dans chaque README. diff --git a/docs/architecture/PIPELINE_ARCHITECTURE.md b/docs/architecture/PIPELINE_ARCHITECTURE.md new file mode 100644 index 0000000..0f0ce7a --- /dev/null +++ b/docs/architecture/PIPELINE_ARCHITECTURE.md @@ -0,0 +1,55 @@ + + + +# Architecture du pipeline + +## 1. Responsabilité + +`kb-pipeline` coordonne des opérations qui traversent plusieurs crates sans devenir propriétaire de leurs implémentations : transport, stockage, contrats de décodage, matérialisation et exécution. + +## 2. Familles de traitements + +### 2.1 Backfill + +Le backfill sélectionne des signatures ou transactions selon une adresse, un programme, un rôle d’endpoint et des bornes explicites. Il gère progression, reprise, annulation et résultats partiels selon les contrats exposés par le pipeline. + +### 2.2 Extraction Core + +L’extraction Core transforme les transactions stockées en représentations d’instructions contextualisées nécessaires aux décodeurs. Elle constitue une phase distincte du replay de décodage. + +### 2.3 Replay de décodage + +Le replay sélectionne des candidats, applique les décodeurs compatibles de `kb-lib`, conserve diagnostics et preuves, puis déclenche les matérialisateurs demandés. La reprise doit préserver l’idempotence et les frontières de campagne. + +### 2.4 Traitements stateful + +Les modules stateful corrèlent instructions, comptes, états précédents et résultats de transaction lorsque le protocole l’exige. Les surfaces SPL Token, ATA, Token-2022 et registre ElGamal disposent de traitements spécialisés à des niveaux différents. + +### 2.5 Préflight et exécution + +Le pipeline assemble les contrôles préalables, plans préparés, signataires, preuves, simulation et validation postérieure. Les exécuteurs restent définis dans `kb-lib` ; le pipeline orchestre leur utilisation. + +## 3. Dépendances fonctionnelles + +```text +kb-onchain-transport -> acquisition et appels RPC +kb-store -> lecture/écriture canonique et replay +kb-lib -> contrats et implémentations métier +kb-config -> profils et paramètres opérationnels +kb-logging -> observabilité +kb-wallet -> signataires lorsque requis +``` + +## 4. Scénarios de démonstration + +`kb-pipeline-demo-scenarios` doit contenir les scénarios réutilisables hors UI. `kb-app-demo-desktop` adapte leurs requêtes, progrès et résultats en payloads Tauri. Une dépendance à l’application desktop dans le sens inverse serait incorrecte. + +## 5. Contrats de preuve + +Les tests unitaires, tests d’intégration et matrices de `test-fixtures/contract-matrices/` participent à la preuve contractuelle. Une matrice peut être à la fois une référence lisible et une fixture chargée par le code de test ; elle ne doit pas être dupliquée sous `docs/`. + +## 6. Limites connues + +- Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet. +- Certains scénarios restent à rendre pleinement autonomes hors desktop. +- La documentation détaillée des APIs publiques du pipeline sera produite dans `kb-pipeline/USAGE.md` après inventaire des exports. diff --git a/docs/architecture/PROJECT_OBJECTIVES.md b/docs/architecture/PROJECT_OBJECTIVES.md new file mode 100644 index 0000000..0b7a71c --- /dev/null +++ b/docs/architecture/PROJECT_OBJECTIVES.md @@ -0,0 +1,75 @@ + + + +# Objectifs du projet Khadhroony Bot3 + +## 1. Objet + +`khadhroony-bot3` est un workspace Rust modulaire destiné à acquérir, normaliser, décoder, matérialiser, valider et, lorsque le contrat le permet, exécuter des opérations Solana. + +Il succède à `khadhroony-bot2` en conservant les contrats fonctionnels validés tout en réduisant fortement le nombre de crates et en clarifiant les frontières entre modèles, traitements, stockage, transports, démonstrations et applications. + +## 2. Objectifs structurants + +Le projet vise à : + +- consolider les contrats et implémentations métier dans un noyau maintenable ; +- conserver des frontières explicites entre acquisition, stockage, pipeline et exécution ; +- produire des observations et matérialisations déterministes, traçables et rejouables ; +- appliquer des politiques de validation et de sécurité avant toute exécution ; +- permettre les campagnes historiques, le traitement temps réel et les validations Devnet ; +- conserver les preuves de couverture sous forme de tests, fixtures, matrices contractuelles et rapports de validation ; +- fournir des scénarios réutilisables indépendamment de l’application desktop ; +- préparer l’ajout progressif de protocoles Solana sans réintroduire une fragmentation excessive du workspace. + +## 3. Principes de conception + +### 3.1 Consolidation contrôlée + +La consolidation ne signifie pas l’effacement des frontières métier. `kb-lib` regroupe les modèles, décodeurs, exécuteurs et matérialisateurs dans des modules dédiés. `kb-store`, `kb-pipeline` et `kb-onchain-transport` restent des crates séparées parce qu’ils représentent des responsabilités opérationnelles différentes. + +### 3.2 Contrats explicites + +Les APIs publiques, erreurs, invariants, versions de contrats et statuts de validation doivent être explicites. Les comportements implicites, les chemins permissifs et les validations supposées sont évités. + +### 3.3 Rejeu et idempotence + +Les données acquises doivent pouvoir être rejouées. Les extractions, décodages et matérialisations doivent préserver la traçabilité et éviter les doubles effets lors d’un rejeu. + +### 3.4 Sécurité d’exécution + +La construction d’une instruction ne suffit pas à autoriser son envoi. Les exécuteurs, préflights, politiques de signataires, limites de frais, simulations et confirmations opérateur forment un contrat distinct. + +### 3.5 Documentation fondée sur le code + +La documentation active est réécrite pour bot3 à partir du code, des tests, des matrices et des validations actuels. `olddocs/archivekbot2/` sert de source historique non normative ; aucun document n’en est promu automatiquement. + +## 4. Périmètre actuel + +Le noyau migré couvre notamment : + +- Solana Core ; +- SPL Memo, avec exécution limitée à Memo v4 ; +- SPL Token classique ; +- SPL Associated Token Account ; +- Token-2022 ; +- registre SPL ElGamal au niveau de certaines couches internes, sans validation Devnet/Mainnet déclarée ; +- décodeur Metaplex Token Metadata partiellement repris pendant le développement de `0.4.7` ; +- acquisition HTTP et WebSocket ; +- stockage PostgreSQL ; +- replay, extraction Core, décodage, matérialisation et scénarios Devnet. + +## 5. Hors périmètre immédiat + +Ne sont pas considérés comme achevés : + +- l’intégralité de Metaplex Token Metadata ; +- un wallet utilisateur complet ; +- l’autonomie complète de tous les scénarios de démonstration ; +- tous les protocoles Anchor, SPL, Metaplex, AMM, launchpads et routers planifiés ; +- l’application de trading et les workers de production ; +- la validation réelle du registre ElGamal sur un cluster où son déploiement et ses prérequis sont confirmés. + +## 6. Critères généraux de qualité + +Une fonctionnalité n’est considérée comme livrée que si son niveau de preuve est indiqué : compilation, tests, matrice contractuelle, validation synthétique, simulation, Devnet ou Mainnet selon le cas. Une absence de validation externe doit rester visible et ne peut pas être transformée en affirmation de compatibilité. diff --git a/docs/architecture/STORAGE_ARCHITECTURE.md b/docs/architecture/STORAGE_ARCHITECTURE.md new file mode 100644 index 0000000..350b9a1 --- /dev/null +++ b/docs/architecture/STORAGE_ARCHITECTURE.md @@ -0,0 +1,64 @@ + + + +# Architecture du stockage + +## 1. Responsabilité de `kb-store` + +`kb-store` réunit : + +- les contrats store-neutral ; +- les DTO et entités persistées ; +- la pagination et les rapports de santé ; +- les traits de repositories ; +- l’implémentation PostgreSQL ; +- les migrations, requêtes et mécanismes de replay associés. + +La consolidation remplace l’ancien découpage entre plusieurs crates de stockage sans supprimer la séparation interne entre contrats et adaptateur PostgreSQL. + +## 2. Frontières + +### 2.1 Contrats store-neutral + +Les contrats ne doivent pas dépendre des détails SQL lorsqu’une abstraction stable est suffisante. Ils décrivent les entrées, sorties, identifiants, pages et erreurs nécessaires aux consommateurs. + +### 2.2 Adaptateur PostgreSQL + +Le module PostgreSQL possède : + +- la connexion et l’initialisation ; +- l’application idempotente des migrations ; +- les requêtes typées ; +- les diagnostics ; +- les opérations de replay et de sélection de candidats. + +### 2.3 Modèles partagés + +Les modèles métier communs restent dans `kb-lib` lorsqu’ils dépassent la seule persistance. `kb-store` ne doit pas créer une seconde définition concurrente d’un contrat partagé. + +## 3. Catégories de données + +Le stockage couvre plusieurs niveaux : + +- données brutes acquises ; +- transactions et instructions canoniques ; +- événements de décodage et diagnostics ; +- matérialisations ; +- états de campagne et candidats de replay ; +- informations opérationnelles et de santé. + +Les noms exacts de tables et APIs publiques seront documentés dans `kb-store/USAGE.md` à partir des exports et migrations actuels. + +## 4. Propriétés attendues + +- initialisation idempotente ; +- pagination bornée ; +- traçabilité des campagnes ; +- absence de double effet lors des replays ; +- validation stricte des entrées ; +- erreurs explicites ; +- séparation entre données brutes, résultats de décodage et matérialisations. + +## 5. Données de test + +Les fixtures privées, bases locales et preuves temporaires ne font pas partie des livraisons. Les matrices contractuelles partagées restent sous `test-fixtures/contract-matrices/` lorsqu’elles sont nécessaires aux tests. diff --git a/docs/architecture/SURFACE_CRATE_MATRIX.md b/docs/architecture/SURFACE_CRATE_MATRIX.md new file mode 100644 index 0000000..2287817 --- /dev/null +++ b/docs/architecture/SURFACE_CRATE_MATRIX.md @@ -0,0 +1,35 @@ + + + +# Matrice des responsabilités par surface + +## 1. Légende + +- **Contrat/implémentation** : responsabilité métier principale. +- **Orchestration** : coordination entre couches. +- **Persistance** : stockage et replay. +- **Transport** : acquisition ou appel RPC. +- **Présentation** : UI ou adaptation de démonstration. + +## 2. Matrice + +| Surface | `kb-lib` | `kb-pipeline` | `kb-store` | `kb-onchain-transport` | scénarios | desktop | +|-------------------------|-----------------------------------------|---------------------------------------------|------------------------|------------------------|-----------------------------------|----------------------------------------------| +| Solana Core | décodeurs, exécuteurs, matérialisateurs | extraction, replay, exécution | persistance | RPC | validations Devnet | panneaux fonctionnels | +| SPL Memo | décodage v1/v3/v4, exécution v4 | replay et exécution v4 | persistance | RPC | scénario Memo v4 | panneau Memo v4 | +| SPL Token classique | contrats et implémentations | stateful, préflight, orchestration | persistance | RPC | scénarios Devnet | panneaux fonctionnels | +| SPL ATA | contrats et implémentations | état et orchestration | persistance | RPC | scénarios classique/Token-2022 | panneaux fonctionnels | +| Token-2022 | contrats et implémentations | corrélation, preuves, préflight, validation | persistance | RPC | scénarios Devnet | panneaux fonctionnels | +| Registre ElGamal | implémentation partielle confirmée | traitement stateful à vérifier par API | persistance selon flux | acquisition de comptes | pas de validation réelle déclarée | présentation non raccordée fonctionnellement | +| Metaplex Token Metadata | décodeur partiellement migré | à compléter selon besoins | à compléter | acquisition standard | à créer/compléter | à créer/compléter | + +## 3. Interprétation + +Cette matrice décrit les responsabilités observées au niveau architectural. Elle ne déclare pas une couverture exhaustive de chaque instruction ou compte. La couverture détaillée reste démontrée par le code, les tests et les matrices sous `test-fixtures/contract-matrices/`. + +## 4. Statuts sensibles + +- Memo v1 et v3 restent non exécutables. +- Memo v4 est exécutable. +- Le registre ElGamal ne doit pas être présenté comme validé Devnet/Mainnet. +- Metaplex Token Metadata appartient au travail `0.4.7` commencé avant la migration et seulement partiellement repris dans bot3. diff --git a/idls/metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_solscan.json b/idls/metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_github_mpl-token-metadata.json similarity index 100% rename from idls/metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_solscan.json rename to idls/metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_github_mpl-token-metadata.json diff --git a/scripts/fetch_metaplex_token_metadata_idl.sh b/scripts/fetch_metaplex_token_metadata_idl.sh index 32df751..8118e6d 100755 --- a/scripts/fetch_metaplex_token_metadata_idl.sh +++ b/scripts/fetch_metaplex_token_metadata_idl.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash set -euo pipefail readonly URL="https://raw.githubusercontent.com/metaplex-foundation/mpl-token-metadata/main/idls/token_metadata.json" -readonly OUTPUT="idls/metaplex_token_metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.json" +readonly OUTPUT="idls/metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_github_mpl-token-metadata.json" curl --fail --location --silent --show-error "$URL" --output "$OUTPUT" python3 -m json.tool "$OUTPUT" >/dev/null printf 'Fetched %s\n' "$OUTPUT"