v0.4.8-pre.002

2026-08-05 14:02:33 +02:00
parent 3e7e943d1c
commit 0078956d48
6 changed files with 268 additions and 101 deletions
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,5 @@
 # file: Cargo.toml
-# version: 23
+# version: 24

 [workspace]
 resolver = "3"
@@ -18,7 +18,7 @@ members = [
 ]

 [workspace.package]
-version = "0.4.8-pre.1"
+version = "0.4.8-pre.2"
 edition = "2024"
 license = "MIT"
 repository = "https://git.sasedev.com/Sasedev/khadhroony-bot3"
--- a/docs/IDL_AUDIT.md
+++ b/docs/IDL_AUDIT.md
@@ -1,5 +1,5 @@
 <!-- file: docs/IDL_AUDIT.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->

 # Audit des IDL v3

@@ -8,6 +8,10 @@
 - Contenu JSON modifié : **non**
 - Collision de noms v3 : **0**

+## Audit ciblé Solana Program Metadata — `0.4.8-pre.002`
+
+La copie officielle `metadata.ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S.solana_program_metadata.V0_0_0.from_github_solana_program.json` a été réauditée contre l’IDL Codama publiée par `solana-program/program-metadata`. Le Program ID, la version déclarée `0.0.0`, les trois PDA, les deux comptes, les neuf instructions, les types et les cinq erreurs concordent. Le JSON local reste inchangé et conserve l’empreinte inventoriée. Voir `audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md`.
+
 ## Inventaire

 | Nom v3                                                                                                                | Program ID déclaré                             | Version déclarée | Instructions | SHA-256                                                            |
--- a/docs/IDL_TO_KB_LIB_NOMENCLATURE.md
+++ b/docs/IDL_TO_KB_LIB_NOMENCLATURE.md
@@ -1,5 +1,5 @@
 <!-- file: docs/IDL_TO_KB_LIB_NOMENCLATURE.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->

 # Correspondance IDL ↔ `kb-lib`

@@ -7,7 +7,7 @@ Ce tableau constitue la cible de classification pour les futurs décodeurs et ex
 Il ne signifie pas que tous les modules proposés sont déjà implémentés.

 | IDL v3                                                                                                                | Module actuel                                  | Module cible                                   | Action Rust                                                               |
-|-----------------------------------------------------------------------------------------------------------------------|------------------------------------------------|------------------------------------------------|---------------------------------------------------------------------|
+|-----------------------------------------------------------------------------------------------------------------------|------------------------------------------------|------------------------------------------------|---------------------------------------------------------------------------|
 | `adapter.DecZY86MU5Gj7kppfUCEmd4LbXXuyZH1yHaP2NTqdiZB.saber_decimal_wrapper.V0_0_0.from_solscan.json`                 | `adapter/saber_decimal_wrapper`                | `adapter/saber_decimal_wrapper`                | Aucune                                                                    |
 | `adapter.TwRapQCDhWkZRrDaHfZGuHxkZ91gHDRkyuzNqeU5MgR.spl_token_wrap.V0_1_0.from_github_solana_program.json`           | `—`                                            | `adapter/spl_token_wrap`                       | Créer `adapter/spl_token_wrap`                                            |
 | `amm.2wT8Yq49kHgDzXuPxZSaeLaH1qbmGXtEyPy64bL7aD3c.lifinity_swap_v2.V0_1_1.from_solscan.json`                          | `amm/lifinity_swap_v2`                         | `amm/lifinity_swap_v2`                         | Aucune                                                                    |
@@ -51,7 +51,7 @@ Il ne signifie pas que tous les modules proposés sont déjà implémentés.
 | `lending.KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD.kamino.V1_23_0.from_solscan.json`                                | `lending/kamino`                               | `lending/kamino`                               | Aucune                                                                    |
 | `lending.MFv2hWf31Z9kbCa1snEPYctwafyhdvnV7FZnsebVacA.marginfi_v2.V0_1_8.from_solscan.json`                            | `lending/marginfi_v2`                          | `lending/marginfi_v2`                          | Aucune                                                                    |
 | `lock.LockrWmn6K5twhz3y9w1dQERbmgSaRkfnTeTKbpofwE.raydium_lp.V0_1_0.from_solscan.json`                                | `lock/raydium_lp`                              | `lock/raydium_lp`                              | Aucune                                                                    |
-| `metadata.ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S.solana_program_metadata.V0_0_0.from_github_solana_program.json` | `—`                                            | `metadata/solana_program_metadata`             | Créer `metadata/solana_program_metadata`                            |
+| `metadata.ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S.solana_program_metadata.V0_0_0.from_github_solana_program.json` | `metadata/solana_program_metadata`             | `metadata/solana_program_metadata`             | Remplacer le décodeur et l’exécuteur réservés par l’implémentation réelle |
 | `metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_solscan.json`              | `metadata/metaplex_token_metadata`             | `metadata/metaplex_token_metadata`             | Aucune                                                                    |
 | `nft.BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY.metaplex_bubblegum.V0_12_0.from_solscan.json`                       | `nft/metaplex_bubblegum`                       | `nft/metaplex_bubblegum`                       | Aucune                                                                    |
 | `nft.TCMPhJdwDryooaGtiocG1u3xcYbRpiJzb283XfCZsDp.tensor_cnft.V2_0_1.from_solscan.json`                                | `—`                                            | `nft/tensor_cnft`                              | Créer `nft/tensor_cnft`                                                   |
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,5 @@
 <!-- file: docs/README.md -->
-<!-- version: 14 -->
+<!-- version: 15 -->

 # Documentation active de Khadhroony Bot3

@@ -39,6 +39,7 @@ Modèles documentaires non génératifs :
 ## 4. Audits et décisions actifs

 - [`audits/V0_4_7_PRE_016_DOCUMENTATION_AND_HEADERS_AUDIT.md`](audits/V0_4_7_PRE_016_DOCUMENTATION_AND_HEADERS_AUDIT.md) ;
+- [`audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md`](audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md) ;
 - [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) ;
 - [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md).

--- a/docs/audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md
+++ b/docs/audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md
@@ -0,0 +1,160 @@
+<!-- file: docs/audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md -->
+<!-- version: 1 -->
+
+# Audit contractuel `0.4.8-pre.002` — Solana Program Metadata et Token-2022
+
+## 1. Portée
+
+Cet audit ferme la phase documentaire préalable au code de `0.4.8`. Il compare l’état réel du workspace à deux sources officielles distinctes :
+
+- `solana-program/program-metadata` pour le programme `ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S` ;
+- `solana-program/token-metadata` et l’implémentation Token-2022 pour `spl-token-metadata-interface`.
+
+Aucun code fonctionnel n’est ajouté par cette prerelease.
+
+## 2. Sources de vérité retenues
+
+| Surface                   | Source officielle                                                                                   | Décision                                                                                                |
+|---------------------------|-----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| Solana Program Metadata   | dépôt `https://github.com/solana-program/program-metadata`, `README.md`, `idl.json` et sources Rust | l’IDL Codama et les sources du programme sont contractuelles ; la copie locale reste brute              |
+| Token Metadata interface  | dépôt `https://github.com/solana-program/token-metadata`, crate `spl-token-metadata-interface`      | les cinq discriminateurs et formats Borsh de l’interface sont contractuels                              |
+| Implémentation Token-2022 | dépôt `https://github.com/solana-program/token-2022`                                                | Token-2022 est l’implémentation ciblée par le workspace ; aucun Program ID metadata autonome n’est créé |
+
+L’audit a été réalisé le 5 août 2026. Les implémentations futures doivent continuer à pinner leurs dépendances Cargo et ne pas dépendre implicitement de l’état mouvant de la branche `main`.
+
+## 3. Validation de l’IDL Solana Program Metadata
+
+Copie locale auditée :
+
+```text
+idls/metadata.ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S.solana_program_metadata.V0_0_0.from_github_solana_program.json
+```
+
+Résultat :
+
+- standard : Codama `1.0.0` ;
+- nom déclaré : `programMetadata` ;
+- Program ID déclaré : `ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S` ;
+- version déclarée par la source : `0.0.0` ;
+- comptes : `Buffer` et `Metadata` ;
+- instructions : 9 ;
+- PDA : `canonical`, `nonCanonical` et helper conditionnel `metadata` ;
+- erreurs : 5 ;
+- SHA-256 de la copie locale : `e6874f519d2ecaa8d92e2d58d1caabc130352c98b5a829375efd31636dbbc7a1`.
+
+La structure, le Program ID, la version déclarée, les PDA, les comptes et les neuf instructions concordent avec l’IDL officielle consultée. La version `0.0.0` est conservée telle qu’elle est déclarée ; elle ne doit pas être interprétée comme une version fonctionnelle inventée par Khadhroony.
+
+## 4. Contrat Solana Program Metadata
+
+### 4.1 PDA
+
+| PDA | Seeds |
+|---|---|
+| canonical | `[program, seed]` |
+| non-canonical | `[program, authority, seed]` |
+| metadata | helper conditionnel sélectionnant l’une des deux dérivations selon la présence d’une autorité tierce |
+
+`seed` est une chaîne UTF-8 de taille fixe 16 octets dans l’IDL. Le code doit distinguer longueur en octets et nombre de caractères Unicode.
+
+### 4.2 Comptes
+
+`Buffer` contient : discriminateur, programme optionnel zeroable, autorité optionnelle zeroable, indicateur canonical, seed paddé à l’offset 14 et données restantes.
+
+`Metadata` contient : discriminateur, programme, autorité optionnelle zeroable, indicateurs mutable et canonical, seed, encodage, compression, format, source de données, longueur de données paddée à l’offset 5 et données restantes.
+
+Discriminateurs de compte : `Empty = 0`, `Buffer = 1`, `Metadata = 2`.
+
+### 4.3 Types fermés
+
+- `Encoding` : `None`, `Utf8`, `Base58`, `Base64` ;
+- `Compression` : `None`, `Gzip`, `Zlib` ;
+- `Format` : `None`, `Json`, `Yaml`, `Toml` ;
+- `DataSource` : `Direct`, `Url`, `External` ;
+- `ExternalData` : adresse, offset `u32`, longueur optionnelle zeroable `u32`.
+
+Ces valeurs décrivent uniquement les données on-chain. `Url` ne déclenche aucun téléchargement et `External` ne transforme pas automatiquement un autre compte en observation canonique.
+
+### 4.4 Instructions
+
+| Discriminant | Instruction | Comptes | Arguments |
+|---:|---|---|---|
+| `0` | `write` | `buffer` (writable)<br>`authority` (signer)<br>`sourceBuffer` (optional) | `offset: u32`<br>`data: Option<bytes>` |
+| `1` | `initialize` | `metadata` (writable)<br>`authority` (signer)<br>`program`<br>`programData` (optional)<br>`system` (optional) | `seed: Seed`<br>`encoding: Encoding`<br>`compression: Compression`<br>`format: Format`<br>`dataSource: DataSource`<br>`data: Option<bytes>` |
+| `2` | `setAuthority` | `account` (writable)<br>`authority` (signer)<br>`program` (optional)<br>`programData` (optional) | `newAuthority: Option<pubkey>` |
+| `3` | `setData` | `metadata` (writable)<br>`authority` (signer)<br>`buffer` (writable, optional)<br>`program` (optional)<br>`programData` (optional) | `encoding: Encoding`<br>`compression: Compression`<br>`format: Format`<br>`dataSource: DataSource`<br>`data: Option<bytes>` |
+| `4` | `setImmutable` | `metadata` (writable)<br>`authority` (signer)<br>`program` (optional)<br>`programData` (optional) | — |
+| `5` | `trim` | `account` (writable)<br>`authority` (signer)<br>`program` (optional)<br>`programData` (optional)<br>`destination` (writable)<br>`rent` | — |
+| `6` | `close` | `account` (writable)<br>`authority` (signer)<br>`program` (optional)<br>`programData` (optional)<br>`destination` (writable) | — |
+| `7` | `allocate` | `buffer` (writable)<br>`authority` (signer)<br>`program` (optional)<br>`programData` (optional)<br>`system` (optional) | `seed: Option<Seed>` |
+| `8` | `extend` | `account` (writable)<br>`authority` (signer)<br>`program` (optional)<br>`programData` (optional) | `length: u16` |
+
+### 4.5 Erreurs officielles
+
+| Code | Erreur |
+|---:|---|
+| 0 | `NotExecutableAccount` |
+| 1 | `InvalidProgramState` |
+| 2 | `InvalidProgramDataAccount` |
+| 3 | `ImmutableMetadataAccount` |
+| 4 | `InvalidDataLength` |
+
+## 5. Décisions de modèles et de validation `ProgM6…`
+
+- le namespace reste `metadata/solana_program_metadata` ;
+- `pre.003` doit introduire des modèles publics propres à cette surface ;
+- aucune dépendance au modèle Metaplex ou Token-2022 ne doit être créée ;
+- le décodeur doit borner explicitement seed, tailles, offsets et longueurs avant allocation ;
+- les options zeroable et les options Borsh préfixées sont deux contrats distincts ;
+- les builders devront reproduire exactement les discriminateurs `u8` et les encodages little-endian ;
+- les comptes optionnels du programme/program-data ne doivent pas être inventés lorsqu’ils sont absents ;
+- la fixture Devnet doit utiliser un programme upgradeable contrôlé pour valider le chemin canonical ;
+- un autre programme quelconque peut être ciblé pour le chemin non-canonical, puisque l’autorité tierce signe ce chemin ;
+- les opérations irréversibles, notamment `SetImmutable`, seront soumises uniquement sur des fixtures jetables dédiées.
+
+## 6. Matrice de couverture Token-2022 réelle
+
+| Capacité | Décodage wire | Intent public | Builder | Exécution | Lecture stateful | Matérialisation | Scénario dédié | Desktop | Devnet confirmé |
+|---|---|---|---|---|---|---|---|---|---|
+| `Initialize` | oui | oui | oui | oui, via builder générique | état extension lisible | extension observée | non dédié | non dédié | non établi |
+| `UpdateField` | oui | oui | oui | oui, via builder générique | état extension lisible | extension observée | non dédié | non dédié | non établi |
+| `RemoveKey` | oui | oui | oui | oui, via builder générique | état extension lisible | extension observée | non dédié | non dédié | non établi |
+| `UpdateAuthority` | oui | non | non | non | état extension lisible | extension observée | non | non | non |
+| `Emit` | oui | non | non | non | résultat de retour non orchestré | non dédiée | non | non | non |
+
+Constats complémentaires :
+
+- les cinq discriminateurs sont déjà reconnus dans `kb-lib/src/decoder/spl/token_2022/wire.rs` ;
+- le décodeur impose la consommation exacte du payload et rejette les trailing bytes ;
+- `UpdateField` prend déjà en charge `Name`, `Symbol`, `Uri` et une clé libre ;
+- `RemoveKey` décode déjà le booléen `idempotent` ;
+- `UpdateAuthority` décode déjà l’autorité nullable ;
+- `Emit` décode déjà les bornes optionnelles `start` et `end` ;
+- les intents/builders actuels s’arrêtent à `Initialize`, `UpdateField` et `RemoveKey` ;
+- le stateful Token-2022 sait relire l’extension `token_metadata`, mais il n’existe pas encore de parcours d’exécution et de postconditions propre aux cinq opérations ;
+- aucune preuve Devnet spécifique à cette matrice n’est actuellement conservée.
+
+## 7. Découpage fonctionnel confirmé
+
+`pre.003` reste consacré aux modèles Solana Program Metadata. Les phases suivantes conservent la séparation prévue : comptes, instructions, matérialisation, builders/exécuteur, pipeline, campagne Devnet, puis complétude Token-2022.
+
+La complétude Token-2022 devra au minimum ajouter :
+
+- intents et builders `UpdateTokenMetadataAuthority` et `EmitTokenMetadata` ;
+- politique de capacité et de signataires ;
+- validation des bornes de `Emit` ;
+- lecture et vérification post-exécution de l’update authority ;
+- capture exploitable du retour de `Emit` ;
+- campagne synthétique et Devnet dédiée ;
+- parcours desktop séparé de `ProgM6…`.
+
+## 8. Critère de clôture de `pre.002`
+
+Le contrat est considéré fermé pour commencer le code lorsque :
+
+- les deux surfaces restent distinctes ;
+- l’IDL officielle locale est validée sans réécriture ;
+- les comptes, PDA, types, erreurs et neuf instructions sont inventoriés ;
+- la matrice Token-2022 distingue décodage déjà complet et exécution incomplète ;
+- les fixtures Devnet nécessaires sont décidées avant leur implémentation.
+
+Ces conditions sont remplies. `0.4.8-pre.003` peut commencer par les modèles Solana Program Metadata.
--- a/docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md
+++ b/docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md
@@ -1,11 +1,11 @@
 <!-- file: docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->

 # Plan `0.4.8` — Solana Program Metadata et complétude Token-2022

 ## 1. Statut et rôle

-Ce document est le livrable principal de `0.4.8-pre.001`. Il constitue le plan vivant de la version et reste modifiable lorsque l’audit du code, des interfaces officielles, de l’IDL ou des validations Devnet impose un ajustement.
+Ce document est le livrable principal de `0.4.8-pre.001` et a été réconcilié après l’audit contractuel de `0.4.8-pre.002`. Il constitue le plan vivant de la version et reste modifiable lorsque l’audit du code, des interfaces officielles, de l’IDL ou des validations Devnet impose un ajustement.

 Il doit être maintenu pendant chaque prerelease, puis archivé pendant la dernière prerelease après transfert des décisions durables vers le ROADMAP, les matrices, les guides, les rapports, les TODO et les changelogs concernés.

@@ -178,7 +178,9 @@ Le découpage est volontairement fin. Il peut être fusionné ou subdivisé pour

 Critère : aucun code fonctionnel, plan complet incluant Devnet et report off-chain explicite.

-### `0.4.8-pre.002` — audit contractuel et matrice d’écarts
+### `0.4.8-pre.002` — audit contractuel et matrice d’écarts — terminé
+
+Résultat durable : le décodeur Token-2022 couvre déjà les cinq payloads wire ; les manques principaux sont les intents/builders `UpdateAuthority` et `Emit`, puis l’orchestration stateful, les scénarios, le desktop et les preuves Devnet. Le contrat `ProgM6…` est fermé par `docs/audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md`.

 - lecture complète des documents des crates concernées ;
 - audit de l’IDL `ProgM6…` contre les sources officielles ;