Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.4.8-pre.008

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-06 06:12:54 +02:00
parent 44088c71c9
commit f576fbade2
52 changed files with 3592 additions and 420 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/README.md -->
<!-- version: 18 -->
<!-- version: 21 -->
# Documentation active de Khadhroony Bot3
@@ -42,6 +42,9 @@ Modèles documentaires non génératifs :
- [`audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md`](audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md) ;
- [`audits/V0_4_8_PRE_007_METAPLEX_MATERIALIZER_STRUCTURE_AUDIT.md`](audits/V0_4_8_PRE_007_METAPLEX_MATERIALIZER_STRUCTURE_AUDIT.md) ;
- [`audits/V0_4_8_PRE_007_MATERIALIZER_CONVENTION_AUDIT.md`](audits/V0_4_8_PRE_007_MATERIALIZER_CONVENTION_AUDIT.md) ;
- [`audits/V0_4_8_PRE_008_METADATA_SOLANA_PROGRAM_PIPELINE_AUDIT.md`](audits/V0_4_8_PRE_008_METADATA_SOLANA_PROGRAM_PIPELINE_AUDIT.md) ;
- [`audits/V0_4_8_PRE_008_METADATA_AND_PIPELINE_NOMENCLATURE_AUDIT.md`](audits/V0_4_8_PRE_008_METADATA_AND_PIPELINE_NOMENCLATURE_AUDIT.md) ;
- [`audits/V0_4_8_PRE_008_SOLANA_PROGRAM_METADATA_HISTORICAL_REPLAY_FIX.md`](audits/V0_4_8_PRE_008_SOLANA_PROGRAM_METADATA_HISTORICAL_REPLAY_FIX.md) ;
- [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) ;
- [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md).
@@ -101,7 +104,9 @@ Les onze crates possèdent désormais `README.md`, `TODO.md`, `USAGE.md` et `CHA
- [`Audit contractuel 0.4.8-pre.002 — metadata`](audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md) ;
- [`Audit 0.4.8-pre.005 — instructions et historique Solana Program Metadata`](audits/V0_4_8_PRE_005_SOLANA_PROGRAM_METADATA_INSTRUCTION_HISTORY_AUDIT.md) ;
- [`Audit 0.4.8-pre.007 — structure du matérialiseur Metaplex Token Metadata`](audits/V0_4_8_PRE_007_METAPLEX_MATERIALIZER_STRUCTURE_AUDIT.md) ;
- [`Audit 0.4.8-pre.007 — conventions et structure de tous les matérialisateurs`](audits/V0_4_8_PRE_007_MATERIALIZER_CONVENTION_AUDIT.md).
- [`Audit 0.4.8-pre.007 — conventions et structure de tous les matérialisateurs`](audits/V0_4_8_PRE_007_MATERIALIZER_CONVENTION_AUDIT.md) ;
- [`Audit 0.4.8-pre.008 — pipeline Solana Program Metadata`](audits/V0_4_8_PRE_008_METADATA_SOLANA_PROGRAM_PIPELINE_AUDIT.md).
- [`Correctif 0.4.8-pre.008 — replay historique Solana Program Metadata`](audits/V0_4_8_PRE_008_SOLANA_PROGRAM_METADATA_HISTORICAL_REPLAY_FIX.md).
## Plans de version actifs

66
docs/audits/V0_4_8_PRE_007_MATERIALIZER_CONVENTION_AUDIT.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/audits/V0_4_8_PRE_007_MATERIALIZER_CONVENTION_AUDIT.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Audit des conventions et de la structure des matérialisateurs — `0.4.8-pre.007-fix-004`
@@ -45,37 +45,35 @@ Les identités runtime servent au code et au routage des logs. Les `processorNam
## 3. Inventaire audité
| Composant | Type principal ou API | Statut | Identité runtime | `processorName` |
|-------------------------|---------------------------------------|------------|--------------------------------------------------------|-------------------------------------------------|
| Administration | `MtAdminMaterializer` | actif | `kb-lib.materializer.admin` | `materializer.admin` |
| Bridge | `MtBridgeMaterializer` | réservé | `kb-lib.materializer.bridge` | `materializer.bridge` |
| Compliance audit | `MtComplianceAuditMaterializer` | actif | `kb-lib.materializer.compliance.audit` | `materializer.compliance.audit` |
| Fees | `MtFeesMaterializer` | actif | `kb-lib.materializer.fees` | `materializer.fees` |
| Governance | `MtGovernanceMaterializer` | réservé | `kb-lib.materializer.governance` | `materializer.governance` |
| Lending | `MtLendingMaterializer` | réservé | `kb-lib.materializer.lending` | `materializer.lending` |
| Lifecycle | `MtLifecycleMaterializer` | actif | `kb-lib.materializer.lifecycle` | `materializer.lifecycle` |
| Liquidity | `MtLiquidityMaterializer` | réservé | `kb-lib.materializer.liquidity` | `materializer.liquidity` |
| Metaplex Token Metadata | APIs de snapshots | state-only | `kb-lib.materializer.metadata.metaplex_token_metadata` | `materializer.metadata.metaplex_token_metadata` |
| Solana Program Metadata | `MtSolanaProgramMetadataMaterializer` | actif | `kb-lib.materializer.metadata.solana_program_metadata` | `materializer.metadata.solana_program_metadata` |
| Token-2022 metadata | API de snapshots | state-only | `kb-lib.materializer.metadata.token_2022` | `materializer.metadata.token_2022` |
| NFT | `MtNftMaterializer` | réservé | `kb-lib.materializer.nft` | `materializer.nft` |
| Oracle | `MtOracleMaterializer` | réservé | `kb-lib.materializer.oracle` | `materializer.oracle` |
| Orderbook | `MtOrderbookMaterializer` | réservé | `kb-lib.materializer.orderbook` | `materializer.orderbook` |
| Perpetuals | `MtPerpetualsMaterializer` | réservé | `kb-lib.materializer.perpetuals` | `materializer.perpetuals` |
| Pool state | `MtPoolStateMaterializer` | réservé | `kb-lib.materializer.pool.state` | `materializer.pool.state` |
| Rewards | `MtRewardsMaterializer` | réservé | `kb-lib.materializer.rewards` | `materializer.rewards` |
| Risk | `MtRiskMaterializer` | actif | `kb-lib.materializer.risk` | `materializer.risk` |
| Routing | `MtRoutingMaterializer` | réservé | `kb-lib.materializer.routing` | `materializer.routing` |
| Staking | `MtStakingMaterializer` | actif | `kb-lib.materializer.staking` | `materializer.staking` |
| Token accounts | `MtTokenAccountsMaterializer` | actif | `kb-lib.materializer.token.accounts` | `materializer.token.accounts` |
| Token metadata risk | `MtTokenMetadataRiskMaterializer` | réservé | `kb-lib.materializer.token.metadata_risk` | `materializer.token.metadata_risk` |
| Trades | `MtTradesMaterializer` | réservé | `kb-lib.materializer.trades` | `materializer.trades` |
| Transaction annotations | `MtTransactionAnnotationMaterializer` | actif | `kb-lib.materializer.transaction.annotations` | `materializer.transaction.annotations` |
| Vault | `MtVaultMaterializer` | réservé | `kb-lib.materializer.vault` | `materializer.vault` |
| Composant | Type principal ou API | Statut | Identité runtime | `processorName` |
|-------------------------|-----------------------------------------------|---------|--------------------------------------------------------|-------------------------------------------------|
| Administration | `MtAdminMaterializer` | actif | `kb-lib.materializer.admin` | `materializer.admin` |
| Bridge | `MtBridgeMaterializer` | réservé | `kb-lib.materializer.bridge` | `materializer.bridge` |
| Compliance audit | `MtComplianceAuditMaterializer` | actif | `kb-lib.materializer.compliance.audit` | `materializer.compliance.audit` |
| Fees | `MtFeesMaterializer` | actif | `kb-lib.materializer.fees` | `materializer.fees` |
| Governance | `MtGovernanceMaterializer` | réservé | `kb-lib.materializer.governance` | `materializer.governance` |
| Lending | `MtLendingMaterializer` | réservé | `kb-lib.materializer.lending` | `materializer.lending` |
| Lifecycle | `MtLifecycleMaterializer` | actif | `kb-lib.materializer.lifecycle` | `materializer.lifecycle` |
| Liquidity | `MtLiquidityMaterializer` | réservé | `kb-lib.materializer.liquidity` | `materializer.liquidity` |
| Metaplex Token Metadata | `MtMetadataMetaplexTokenMetadataMaterializer` | actif | `kb-lib.materializer.metadata.metaplex_token_metadata` | `materializer.metadata.metaplex_token_metadata` |
| Solana Program Metadata | `MtMetadataSolanaProgramMaterializer` | actif | `kb-lib.materializer.metadata.solana_program_metadata` | `materializer.metadata.solana_program_metadata` |
| Token-2022 metadata | `MtMetadataToken2022Materializer` | actif | `kb-lib.materializer.metadata.token_2022` | `materializer.metadata.token_2022` |
| NFT | `MtNftMaterializer` | réservé | `kb-lib.materializer.nft` | `materializer.nft` |
| Oracle | `MtOracleMaterializer` | réservé | `kb-lib.materializer.oracle` | `materializer.oracle` |
| Orderbook | `MtOrderbookMaterializer` | réservé | `kb-lib.materializer.orderbook` | `materializer.orderbook` |
| Perpetuals | `MtPerpetualsMaterializer` | réservé | `kb-lib.materializer.perpetuals` | `materializer.perpetuals` |
| Pool state | `MtPoolStateMaterializer` | réservé | `kb-lib.materializer.pool.state` | `materializer.pool.state` |
| Rewards | `MtRewardsMaterializer` | réservé | `kb-lib.materializer.rewards` | `materializer.rewards` |
| Risk | `MtRiskMaterializer` | actif | `kb-lib.materializer.risk` | `materializer.risk` |
| Routing | `MtRoutingMaterializer` | réservé | `kb-lib.materializer.routing` | `materializer.routing` |
| Staking | `MtStakingMaterializer` | actif | `kb-lib.materializer.staking` | `materializer.staking` |
| Token accounts | `MtTokenAccountsMaterializer` | actif | `kb-lib.materializer.token.accounts` | `materializer.token.accounts` |
| Token metadata risk | `MtTokenMetadataRiskMaterializer` | réservé | `kb-lib.materializer.token.metadata_risk` | `materializer.token.metadata_risk` |
| Trades | `MtTradesMaterializer` | réservé | `kb-lib.materializer.trades` | `materializer.trades` |
| Transaction annotations | `MtTransactionAnnotationMaterializer` | actif | `kb-lib.materializer.transaction.annotations` | `materializer.transaction.annotations` |
| Vault | `MtVaultMaterializer` | réservé | `kb-lib.materializer.vault` | `materializer.vault` |
Bilan : **25 composants nommés**, dont **9 matérialisateurs actifs**, **14 coquilles réservées** et **2 composants state-only**.
`MtMetadataMaterializer` reste un wrapper public de compatibilité vers `MtSolanaProgramMetadataMaterializer`. Il ne possède pas une identité distincte et ne crée pas un second propriétaire de projection.
Bilan après correction `pre.008` : **25 composants nommés**, dont **11 matérialisateurs actifs** et **14 coquilles réservées**. Les trois domaines metadata exposent des types spécialisés ; aucun wrapper metadata générique ne masque leur ownership.
## 4. Structure normalisée
@@ -161,7 +159,7 @@ Les 22 chemins retirés sont fournis dans `delete-files.txt` à la racine du del
## 10. Conclusion
Les matérialisateurs utilisent désormais une convention unique pour les identités runtime, les processeurs persistés, les tracing targets, les constantes, les façades et les coquilles réservées. Les différences restantes sont fonctionnelles et explicites : un composant peut être actif, réservé ou state-only, mais il ne change pas de convention structurelle ou de provenance selon son statut.
Les matérialisateurs utilisent désormais une convention unique pour les identités runtime, les processeurs persistés, les tracing targets, les constantes, les façades et les coquilles réservées. Un composant peut être actif ou réservé ; les APIs stateful restent des capacités de son matérialiseur spécialisé et ne constituent pas un type générique parallèle.
## 11. Correction des identités opérationnelles et du tracing
@@ -171,7 +169,7 @@ La compilation du workspace corrigé a révélé trois tracing targets déclaré
- `kb-lib.materializer.metadata.metaplex_token_metadata` ;
- `kb-lib.materializer.metadata.token_2022`.
Le composant state-only Token-2022 réexportait également `MT_METADATA_TOKEN_2022_COMPONENT_NAME` sans le consommer dans son implémentation. Cette situation ne signifiait pas que les snapshots Token-2022 n’étaient pas matérialisés : la fonction `materializer_metadata_materialize_token_2022_snapshot` produisait déjà les projections `TokenMetadata`, `TokenGroup` et `TokenGroupMember`. Elle révélait en revanche que l’identité runtime du composant n’était pas attachée à une opération observable.
Le composant de snapshots Token-2022 réexportait également `MT_METADATA_TOKEN_2022_COMPONENT_NAME` sans le consommer dans son implémentation. Cette situation ne signifiait pas que les snapshots Token-2022 n’étaient pas matérialisés : la fonction `materializer_metadata_materialize_token_2022_snapshot` produisait déjà les projections `TokenMetadata`, `TokenGroup` et `TokenGroupMember`. Elle révélait en revanche que l’identité runtime du composant n’était pas attachée à une opération observable.
Le correctif ajoute des événements structurés réels pour les chemins suivants :
@@ -186,4 +184,4 @@ L’audit mécanique refuse désormais :
- un `TRACING_TARGET_*` de `kb-lib` déclaré sans macro `tracing` réelle ;
- un `MT_*_COMPONENT_NAME` qui n’est consommé par aucun fichier d’implémentation du composant.
Les composants state-only restent distincts des matérialiseurs instructionnels : ils n’implémentent pas artificiellement `MtApiEventMaterializer`, mais leur identité runtime est désormais effectivement utilisée par leurs opérations de snapshot.
La correction `pre.008` ajoute les matérialiseurs instructionnels spécialisés Metaplex et Token-2022 parce que leurs instructions sont effectivement décodées. Leurs APIs de snapshots restent distinctes et autoritatives, tandis que les sorties d’instructions restent des faits committés non autoritatifs.

52
docs/audits/V0_4_8_PRE_008_METADATA_AND_PIPELINE_NOMENCLATURE_AUDIT.md Normal file
View File

@@ -0,0 +1,52 @@
<!-- file: docs/audits/V0_4_8_PRE_008_METADATA_AND_PIPELINE_NOMENCLATURE_AUDIT.md -->
<!-- version: 1 -->
# Audit de nomenclature metadata et pipeline
## 1. Objet
Cet audit corrige deux dérives révélées après l’intégration pipeline de `0.4.8-pre.008` : un matérialiseur Solana Program Metadata nommé hors de la hiérarchie `MtMetadata*`, et des modules `kb-pipeline` préfixés uniformément par `solana_` malgré des domaines Metaplex ou SPL distincts.
## 2. Matérialiseurs metadata
La surface publique canonique comprend désormais exactement trois types spécialisés :
| Domaine | Type | Processor |
|---------------------------|-----------------------------------------------|-------------------------------------------------|
| Metaplex Token Metadata | `MtMetadataMetaplexTokenMetadataMaterializer` | `materializer.metadata.metaplex_token_metadata` |
| Solana Program Metadata | `MtMetadataSolanaProgramMaterializer` | `materializer.metadata.solana_program_metadata` |
| Token-2022 metadata/group | `MtMetadataToken2022Materializer` | `materializer.metadata.token_2022` |
Le type `MtSolanaProgramMetadataMaterializer` et le wrapper `MtMetadataMaterializer` sont supprimés. Chaque type implémente les contrats legacy et contextuel, possède ses constantes, son tracing target et son ownership instructionnel. Les helpers `state.rs` et `account.rs` restent séparés : ils produisent les snapshots autoritatifs, alors que les matérialiseurs d’instructions produisent des faits committés non autoritatifs.
Les neuf instructions incorporées Token Metadata et Token Group sont classées sous `MdEventFamily::Metadata`. Cette classification évite de confier les changements d’autorité propres aux interfaces metadata au matérialiseur d’administration générique.
## 3. Registre desktop
`demo_decode_replay` enregistre les trois types spécialisés. Un test construit une observation représentative de chaque domaine et vérifie qu’elle possède exactement un propriétaire dans le registre runtime.
## 4. Nomenclature `kb-pipeline`
Les modules privés suivent la hiérarchie suivante :
- `metadata_metaplex_token_metadata_*` ;
- `metadata_solana_program_*` ;
- `spl_ata_stateful` ;
- `spl_elgamal_registry_stateful` ;
- `spl_token_stateful` ;
- `spl_token_2022_*` ;
- `solana_stateful` uniquement pour les contrats Solana Core transversaux.
Les fonctions et structures publiques restent inchangées. Le renommage est donc structurel et documentaire, sans rupture volontaire de l’API consommée par le desktop ou les futurs scénarios Devnet.
## 5. Fichiers remplacés
Les anciens fichiers `solana_*` de `kb-pipeline`, l’ancien test externe et l’ancienne matrice sont listés dans `delete-files.txt`. Leur suppression est obligatoire après extraction du delta.
## 6. Garde-fous
- les exports racine couvrent les trois matérialiseurs spécialisés ;
- le test externe n’utilise que la façade `kb_lib::*` ;
- les familles Token-2022 metadata/group sont testées exhaustivement ;
- le test externe pipeline utilise des assertions de compilation `const` ;
- l’audit des règles vérifie les façades, les exports, les constantes et la nomenclature des composants.

113
docs/audits/V0_4_8_PRE_008_METADATA_SOLANA_PROGRAM_PIPELINE_AUDIT.md Normal file
View File

@@ -0,0 +1,113 @@
<!-- file: docs/audits/V0_4_8_PRE_008_METADATA_SOLANA_PROGRAM_PIPELINE_AUDIT.md -->
<!-- version: 2 -->
# Audit du pipeline Solana Program Metadata — `0.4.8-pre.008`
## 1. Objet
Cet audit ferme la frontière réutilisable de Solana Program Metadata dans `kb-pipeline` sans introduire de fixture, de wallet de démonstration ni de dépendance envers `kb-pipeline-demo-scenarios`.
La surface couverte est le programme :
```text
ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S
```
## 2. Séparation des responsabilités
| Crate ou composant | Responsabilité en `pre.008` |
|-----------------------------------------------|----------------------------------------------------------------------------------------|
| `kb-lib` | modèles, décodage, matérialisation, intents, builders, exécuteur et safety commun |
| `kb-pipeline` | lectures stateful, préflight, readiness simulation-first et postconditions |
| `kb-pipeline-demo-scenarios` | aucune modification ; fixture et parcours Devnet réservés à `pre.009` |
| `kb-app-demo-desktop/demo_decode_replay` | enregistrement générique du décodeur et du matérialiseur pour la validation historique |
| `kb-app-demo-desktop/demo_execution_metadata` | aucune modification ; intégration `ProgM6…` réservée à `pre.009` |
## 3. Lectures stateful
Le pipeline distingue explicitement :
- compte absent ;
- compte présent mais vide ou intégralement nul ;
- compte `Buffer` initialisé ;
- compte `Metadata` initialisé.
Les réponses RPC doivent être confirmées, non exécutables, complètes et sous la borne maximale. Un état initialisé doit être détenu par `ProgM6…`. Le décodage et la projection autoritative sont délégués aux APIs publiques de `kb-lib`.
## 4. Préflight
Le préflight lie l’intent typé au plan préparé et contrôle :
- le Program ID et le code d’opération exacts ;
- l’unique instruction du plan ;
- l’approbation explicite des mutations sensibles ;
- la décision de `ExSafetyChecker` ;
- les snapshots confirmés et non dupliqués ;
- l’état du compte cible ;
- les sources `Buffer` ;
- l’autorité explicite ou le contexte canonical ;
- le préfinancement rent des opérations d’allocation ou d’agrandissement.
Une décision `Deny` bloque le traitement. Une décision `RequireConfirmation` reste exécutable mais doit être satisfaite dans l’enveloppe de readiness.
## 5. Readiness et postconditions
La readiness refuse :
- un plan non lié au préflight ;
- un message non simulé ou simulé sous un autre hash ;
- une simulation en échec ;
- un signer requis non résolu ;
- une soumission sans confirmation opérateur ;
- une soumission depuis un plan `dry_run`.
Les neuf opérations possèdent une postcondition stateful :
| Opération | Postcondition principale |
|----------------|-----------------------------------------------------------------|
| `Write` | octets attendus au bon offset du `Buffer` |
| `Initialize` | état `Metadata`, PDA, seed, descripteurs et contenu compatibles |
| `SetAuthority` | autorité finale exacte ou supprimée |
| `SetData` | descripteurs et contenu final compatibles |
| `SetImmutable` | `mutable = false` |
| `Trim` | même type d’état et taille non croissante |
| `Close` | compte absent |
| `Allocate` | état `Buffer`, autorité, seed et canonicité compatibles |
| `Extend` | même type d’état et taille augmentée exactement |
Une lecture finale absente du rapport produit `NotApplicable`, jamais `Confirmed`.
## 6. Validation historique prévue
La validation historique opérateur suit :
1. `demo_backfill` sur un échantillon borné de signatures ;
2. extraction Core ;
3. decode replay ciblé sur `ProgM6…` et `metadata.solana_program_metadata` ;
4. matérialisation via `materializer.metadata.solana_program_metadata` ;
5. lecture bornée des événements matérialisés.
Cette validation précède les scénarios Devnet de `pre.009` et ne dépend pas de leur fixture.
## 7. Matrice
La matrice machine-readable est :
```text
test-fixtures/contract-matrices/METADATA_SOLANA_PROGRAM_PIPELINE_MATRIX.json
```
Elle distingue explicitement la crate généraliste du package de scénarios et ferme l’inventaire des neuf opérations.
## 8. Correction de nomenclature `pre.008`
Les modules privés de `kb-pipeline` sont renommés selon leur domaine :
- `metadata_metaplex_token_metadata_*` pour Metaplex Token Metadata ;
- `metadata_solana_program_*` pour Solana Program Metadata ;
- `spl_ata_stateful` et `spl_elgamal_registry_stateful` pour les programmes SPL correspondants ;
- `spl_token_stateful` et `spl_token_2022_*` pour SPL Token et Token-2022 ;
- `solana_stateful` reste réservé aux primitives Solana Core transversales.
Les fonctions et structures publiques restent stables. La matrice et le test externe suivent la même nomenclature de fichier.
Le registre de replay desktop utilise désormais trois matérialiseurs metadata spécialisés : `MtMetadataMetaplexTokenMetadataMaterializer`, `MtMetadataSolanaProgramMaterializer` et `MtMetadataToken2022Materializer`. Aucun wrapper générique `MtMetadataMaterializer` n’est conservé.

54
docs/audits/V0_4_8_PRE_008_SOLANA_PROGRAM_METADATA_HISTORICAL_REPLAY_FIX.md Normal file
View File

@@ -0,0 +1,54 @@
<!-- file: docs/audits/V0_4_8_PRE_008_SOLANA_PROGRAM_METADATA_HISTORICAL_REPLAY_FIX.md -->
<!-- version: 1 -->
# Correctif du replay historique Solana Program Metadata
## 1. Validation ayant révélé le défaut
La validation Mainnet a importé deux pages de 100 transactions du programme `ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S`, puis extrait 200 transactions et rejoué 582 instructions. Le processeur `metadata.solana_program_metadata` a reconnu et dispatché 132 instructions, mais les 132 ont terminé en échec de décodage.
Les surfaces observées étaient :
| Instruction | Observations |
|-----------------|-------------:|
| `write` | 88 |
| `allocate` | 15 |
| `initialize` | 11 |
| `set_authority` | 7 |
| `close` | 5 |
| `set_data` | 5 |
| `set_immutable` | 1 |
| `trim` | 0 |
| `extend` | 0 |
Le fait que toutes les instructions observées échouent malgré des discriminants reconnus et des transactions réussies indique un défaut transversal après reconnaissance, et non sept défauts wire indépendants.
## 2. Cause
`MdCoreInstructionReplayInput.account_keys_json` est produit depuis l’en-tête du message Solana. Ses champs `signer` et `writable` représentent donc les privilèges globaux de chaque clé pour l’ensemble de la transaction.
Le décodeur comparait ces champs par égalité avec les privilèges minimaux documentés pour chaque position de l’instruction. Cette égalité est invalide : une autorité peut être readonly dans le contrat de l’instruction tout en étant writable au niveau du message parce qu’elle est aussi fee payer ou intervient comme compte writable dans une autre instruction.
Le programme on-chain vérifie les privilèges nécessaires, notamment `authority.is_signer()`, mais ne refuse pas un sur-ensemble de privilèges fourni par le message.
## 3. Correction
La validation applique désormais les règles suivantes :
- un compte déclaré signer doit être signer dans le message ;
- un compte déclaré writable doit être writable dans le message ;
- un compte déclaré readonly peut être globalement writable ;
- un compte déclaré non-signer peut être globalement signer ;
- les positions, rôles, placeholders optionnels et contrats de source restent vérifiés séparément ;
- l’absence d’un privilège requis reste un échec fermé.
Une régression couvre les neuf instructions stables avec une autorité globalement signer et writable.
## 4. Validation à rejouer
Après application du correctif, relancer les 132 entrées en échec, de préférence avec le replay forcé limité au programme `ProgM6…`. Le résultat attendu est :
- `decoded = 132` ;
- `failed = 0` ;
- une matérialisation pour chaque instruction committée ;
- `trim` et `extend` restent non observés dans cet échantillon et devront être couverts par les scénarios Devnet.

45
docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md
View File

@@ -1,11 +1,11 @@
<!-- file: docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md -->
<!-- version: 10 -->
<!-- version: 13 -->
# 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`, réconcilié après l’audit contractuel de `0.4.8-pre.002`, les modèles de `pre.003`, les décodeurs de comptes de `pre.004`, le décodeur d’instructions de `pre.005`, la matérialisation de `pre.006` et l’exécuteur de `pre.007`. 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`, réconcilié après l’audit contractuel de `0.4.8-pre.002`, les modèles de `pre.003`, les décodeurs de comptes de `pre.004`, le décodeur d’instructions de `pre.005`, la matérialisation de `pre.006`, l’exécuteur de `pre.007` et l’orchestration généraliste de `pre.008`. 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.
@@ -274,23 +274,37 @@ Résultat durable : les neuf instructions stables possèdent une opération typ
- aucune opération stable classée deprecated ou replaced faute de preuve officielle ;
- financement de rent volontairement laissé à la fixture et à l’orchestration RPC : le programme exige que les comptes à allouer ou étendre soient préfinancés.
Travaux parallèles intégrés : les fonctions de matérialisation Metaplex existaient déjà dans `materializer/metadata/core.rs`; il ne s’agissait donc pas d’un oubli fonctionnel de `0.4.6/0.4.7`. Elles sont déplacées dans un sous-module dédié sans changement de clé métier. Token-2022 reçoit également son composant state-only dédié. L’audit est ensuite étendu à l’ensemble de `src/materializer` : 25 identités sont harmonisées, les façades deviennent pures, les implémentations utilisent `materializer.rs`, les constantes sont centralisées et les coquilles réservées ne produisent plus de faux événements legacy. Les constats sont consignés dans `docs/audits/V0_4_8_PRE_007_METAPLEX_MATERIALIZER_STRUCTURE_AUDIT.md` et `docs/audits/V0_4_8_PRE_007_MATERIALIZER_CONVENTION_AUDIT.md`. Un audit transversal de toutes les surfaces déjà livrées est planifié en `0.5.x` pour vérifier les règles de décodage exhaustif, propriété de matérialisation, exécution des opérations dangereuses via `ExSafetyChecker`, dépréciation officielle et versions remplacées decode-only.
Travaux parallèles intégrés : les fonctions de matérialisation Metaplex existaient déjà dans `materializer/metadata/core.rs`; il ne s’agissait donc pas d’un oubli fonctionnel de `0.4.6/0.4.7`. Elles sont déplacées dans un sous-module dédié sans changement de clé métier. Token-2022 reçoit également son composant dédié de snapshots, puis `pre.008` ajoute son matérialiseur instructionnel spécialisé ainsi que celui de Metaplex. L’audit est ensuite étendu à l’ensemble de `src/materializer` : 25 identités sont harmonisées, les façades deviennent pures, les implémentations utilisent `materializer.rs`, les constantes sont centralisées et les coquilles réservées ne produisent plus de faux événements legacy. Les constats sont consignés dans `docs/audits/V0_4_8_PRE_007_METAPLEX_MATERIALIZER_STRUCTURE_AUDIT.md` et `docs/audits/V0_4_8_PRE_007_MATERIALIZER_CONVENTION_AUDIT.md`. Un audit transversal de toutes les surfaces déjà livrées est planifié en `0.5.x` pour vérifier les règles de décodage exhaustif, propriété de matérialisation, exécution des opérations dangereuses via `ExSafetyChecker`, dépréciation officielle et versions remplacées decode-only.
### `0.4.8-pre.008` — pipeline stateful Solana Program Metadata
### `0.4.8-pre.008` — pipeline stateful Solana Program Metadata — code terminé, replay historique à revalider
- simulation, soumission, confirmation, lectures avant/après, postconditions, replay et matérialisation.
- lectures RPC bornées des comptes absents, non initialisés, `Buffer` et `Metadata` ;
- décodage et matérialisation autoritative des états via `kb-lib` ;
- préflight des neuf opérations, vérification des sources Buffer, autorités, canonicité et preuves de rent ;
- passage par `ExSafetyChecker`, readiness simulation-first, résolution des signers et autorisation de soumission ;
- postconditions avant/après des neuf opérations, sans succès inventé lorsqu’une lecture manque ;
- matrice pipeline machine-readable ;
- enregistrement du décodeur et des trois matérialiseurs metadata spécialisés dans le replay générique desktop pour le futur test `demo_backfill` ;
- nomenclature interne `metadata_*`, `spl_*` et `solana_*` alignée sur les domaines de `kb-lib` ;
- aucune modification de `kb-pipeline-demo-scenarios` ni de `demo_execution_metadata`.
- audit consigné dans `docs/audits/V0_4_8_PRE_008_METADATA_SOLANA_PROGRAM_PIPELINE_AUDIT.md`.
- première campagne historique : 200 transactions importées, 582 instructions rejouées et 132 instructions `ProgM6…` reconnues ; toutes ont été rejetées à tort parce que le décodeur comparait les privilèges globaux du message par égalité avec les minima de l’instruction ;
- `pre.008-fix-002` remplace cette égalité par une validation de minima et ajoute une régression sur les neuf instructions ; la campagne des 132 entrées doit être rejouée avant d’ouvrir `pre.009`.
### `0.4.8-pre.009` — campagne Devnet Solana Program Metadata
### `0.4.8-pre.009` — campagne Devnet et desktop Solana Program Metadata
- fixture Rust native ;
- scénarios réutilisables ;
- fixture Rust native et comptes préfinancés ;
- scénarios réutilisables dans `kb-pipeline-demo-scenarios` ;
- appels RPC de simulation, soumission, confirmation, lectures avant/après et replay ;
- adaptation du sous-panneau `ProgM6…` de `demo_execution_metadata` pour consommer les runners réutilisables ;
- validation historique préalable via `demo_backfill`, Core extraction et decode replay sur un échantillon de signatures ;
- preuves RPC et rapport intermédiaire.
### `0.4.8-pre.010` — complétude Token-2022 Token Metadata
- implémentation des écarts confirmés de `Initialize`, `UpdateField`, `RemoveKey`, `UpdateAuthority` et `Emit` ;
- conservation du matérialiseur d’état dédié `metadata/token_2022/` pour les extensions `TokenMetadata`, `TokenGroup` et `TokenGroupMember` ;
- ajout d’une matérialisation explicite des cinq observations d’instructions `spl-token-metadata-interface`, actuellement absente ;
- fermeture des écarts d’intents/builders/exécution confirmés pour `UpdateAuthority` et `Emit`, après réaudit des cinq instructions `Initialize`, `UpdateField`, `RemoveKey`, `UpdateAuthority` et `Emit` ;
- conservation des snapshots dédiés `metadata/token_2022/` pour `TokenMetadata`, `TokenGroup` et `TokenGroupMember` ;
- validation de la matérialisation instructionnelle spécialisée déjà ajoutée en `pre.008` pour les interfaces Token Metadata et Token Group ;
- maintien de `InitializeMetadataPointer` et `UpdateMetadataPointer` dans le matérialiseur d’administration qui en possède déjà les faits ;
- tests synthétiques et stateful.
@@ -299,11 +313,12 @@ Travaux parallèles intégrés : les fonctions de matérialisation Metaplex exis
- fixture mint ;
- simulations, soumissions sûres, confirmations, postconditions, replay et matérialisation.
### `0.4.8-pre.012` — desktop metadata
### `0.4.8-pre.012` — finalisation desktop metadata
- accordéons ou sous-panneaux séparés pour `ProgM6…`, Token-2022 et Metaplex ;
- réutilisation du JsonViewer commun pour les résultats intégralement JSON ;
- préparation, simulation, soumission, lectures et preuves ;
- compléter le sous-panneau Token-2022 après les travaux de `pre.010` et `pre.011` ;
- conserver des accordéons ou sous-panneaux séparés pour `ProgM6…`, Token-2022 et Metaplex ;
- réutiliser le JsonViewer commun pour les résultats intégralement JSON ;
- réconcilier préparation, simulation, soumission, lectures et preuves des trois domaines ;
- aucun bouton de fetch URI.
### `0.4.8-pre.013` — stockage, matrices et réconciliation transversale