khadhroony-bot3/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/README.md

kb_decoder_metadata_metaplex_token_metadata

Décodeur contextualisé dédié au programme Metaplex Token Metadata.

La crate suit la frontière commune des décodeurs opérationnels du workspace :

• constants.rs contient la surface, les discriminateurs, les bornes et la cible de tracing ;
• decoder.rs implémente ProtocolDecoder et InstructionDecoder ;
• instruction.rs contient le décodage Borsh borné, la résolution des comptes et les observations ;
• lib.rs réexporte le décodeur d’instructions et les types publics du parseur de comptes ;
• le Program ID provient exclusivement de kb_program_ids.

0.4.7-pre.002 active le décodage exact de CreateMetadataAccountV3 et UpdateMetadataAccountV2. 0.4.7-pre.003 ajoute VerifyCollection, UnverifyCollection et SetAndVerifyCollection. 0.4.7-pre.004 ajoute le groupe sized VerifySizedCollectionItem, UnverifySizedCollectionItem et SetAndVerifySizedCollectionItem, avec la metadata de collection writable et le collection_authority_record optionnel. 0.4.7-pre.005 ajoute l’administration historique/courante des autorités de collection avec ApproveCollectionAuthority et RevokeCollectionAuthority, y compris le record PDA, les autorités distinctes et les comptes système/rent optionnels. 0.4.7-pre.006 ajoute les usages et autorités d’usage avec ApproveUseAuthority, RevokeUseAuthority et Utilize, leurs compteurs u64, le use_authority_record, le burner, les comptes Token/ATA et les comptes système/rent. 0.4.7-pre.007 ajoute SignMetadata et UpdatePrimarySaleHappenedViaToken, avec creator/owner signataires, metadata writable et token account readonly. Les layouts proviennent de mpl-token-metadata 5.1.1. Le décodeur préserve outer/CPI, statut de transaction, comptes ordonnés, paramètres Borsh, provenance et hash du wire. Il refuse les payloads tronqués, suffixes, comptes invalides et discriminateurs inconnus.

Depuis pre.025, la crate traite le premier compte on-chain MetadataV1. Elle ne traite pas encore les autres comptes Metaplex Token Metadata, les metadata Token-2022 incorporées, Metaplex Core, Bubblegum ou les contenus JSON distants.

Groupe 0.4.7-pre.009

• PuffMetadata (14) : normalisation/padding de la metadata externe.
• RemoveCreatorVerification (28) : retrait explicite de la vérification d’un creator.
• SetTokenStandard (35) : classification du standard de token, avec edition optionnelle.

Le décodage conserve les comptes ordonnés, les flags signer/writable officiels, outer/CPI, les échecs non committés et le rejet des suffixes.

0.4.7-pre.009 — création metadata historique V2

• CreateMetadataAccountV2 (discriminant 16) est décodé comme surface historique.
• Le wire conserve DataV2 et is_mutable avec les mêmes bornes que V3.
• Le contrat de comptes reprend metadata, mint, mint authority, payer, update authority, System Program et rent optionnel.
• Cette instruction est décodable et matérialisable ultérieurement, mais restera non exécutable.

0.4.7-pre.010

Ajout du décodage historique non exécutable de CreateMetadataAccount (0) et UpdateMetadataAccount (1), avec layouts Data V1 bornés et comptes exacts.

0.4.7-pre.011

Ajout de CreateMasterEditionV3 (17) et ConvertMasterEditionV1ToV2 (12). Le premier conserve max_supply: Option<u64> et les autorités/payer/programmes exacts ; le second est classé historique et conserve les trois comptes writable de conversion. Le mint d’éditions imprimées et les edition markers restent planifiés pour la tranche suivante.

0.4.7-pre.012

Ajout de MintNewEditionFromMasterEditionViaToken (11) et de la variante historique MintNewEditionFromMasterEditionViaVaultProxy (13). Les deux wires conservent l’édition u64, le master edition, le nouvel edition account et l’edition marker. La variante Token conserve le propriétaire et le token account du master ; la variante Vault conserve l’autorité, le safety deposit et le Token Vault Program. La variante Vault reste définitivement non exécutable.

0.4.7-pre.013

Ajout de SetCollectionSize (34) et BubblegumSetCollectionSize (36). Les deux wires conservent size: u64. La variante directe exige une collection authority writable/signataire ; la variante Bubblegum exige une collection authority readonly/signataire et le bubblegum_signer readonly/signataire. Le record d’autorité de collection reste optionnel. Le bridge Bubblegum est décodé avec provenance Metaplex Token Metadata mais reste distinct de la future couverture complète Bubblegum de 0.4.9.

0.4.7-pre.014 — Delegate / Revoke programmables

• Delegate (44) et Revoke (45) décodés avec leurs enums Borsh exactes.
• Contrat positionnel de 14 comptes conservé, y compris les placeholders Metaplex des comptes optionnels.
• AuthorizationData est projeté lorsqu’il est présent ; validation sémantique différée au preflight stateful.

0.4.7-pre.015 — lifecycle programmable

Ajout de Transfer (49), Lock (46), Unlock (47), Burn (41) et CloseAccounts (57). Les enums Borsh modernes, comptes positionnels, placeholders optionnels, montants u64, outer/CPI et transactions échouées non committées sont conservés. La validation stateful des TokenRecord, rule sets, owners et PDA reste différée.

0.4.7-pre.016 — audit exhaustif et freeze/thaw historiques

• inventaire officiel recalé sur clients/rust/src/generated/instructions/mod.rs ;
• ajout de FreezeDelegatedAccount (26) et ThawDelegatedAccount (27) ;
• contrat exact de cinq comptes : delegate writable/signataire, token account writable, edition, mint et Token Program readonly ;
• ces deux surfaces restent historiques, decode-only et non exécutables ;
• les wrappers modernes et les opérations escrow/collect/resize/migrate encore absents restent explicitement planifiés avant le décodage des comptes.

0.4.7-pre.017 — burns NFT historiques et printing token

• BurnNft (29) conserve metadata, owner signataire, mint, token account, master edition, Token Program et collection metadata optionnelle.
• BurnEditionNft (37) conserve le print mint, le master mint, leurs token accounts, les comptes edition/master edition et l’edition marker.
• DeprecatedMintNewEditionFromMasterEditionViaPrintingToken (3) conserve les quinze comptes obligatoires et la reservation list optionnelle.
• Ces trois surfaces sont historiques, decode-only et définitivement non exécutables.

0.4.7-pre.018 — escrow et collecte

• CreateEscrowAccount (38) et CloseEscrowAccount (39) conservent escrow, metadata, mint, token account, edition, payer et comptes système/sysvar exacts.
• TransferOutOfEscrow (40) conserve amount: u64, les comptes source/destination de l’attribut, le mint et le token account liés à l’escrow, ainsi que l’autorité optionnelle.
• Collect (54) conserve l’autorité signataire et le destinataire readonly.
• Les quatre surfaces préservent outer/CPI et les transactions échouées non committées ; les owners, PDA et états escrow restent à valider lors du décodage stateful.

0.4.7-pre.019 — wrapper moderne Create

• Create (42) décode CreateArgs::V1, y compris metadata textuelle, royalties, creators, collection, uses, token standard, rule set, decimals et print supply.
• Le contrat de neuf positions conserve metadata, master edition optionnelle, mint signataire/writable, authority, payer, update authority, programmes système/sysvar et SPL Token Program optionnel.
• Les wrappers modernes Create, Mint, Print, Update, Use, Verify, Unverify, Resize et Migrate sont désormais décodés ; leurs validations owner/PDA restent stateful.

0.4.7-pre.020

Cette préversion ajoute le wrapper moderne Mint (43). Le décodeur conserve MintArgs::V1, le montant brut u64, AuthorizationData optionnelle et les quinze positions officielles, y compris les placeholders Metaplex utilisés pour les comptes optionnels absents. L’activation runtime, la validation stateful des PDA/rule sets et l’exécution restent différées.

0.4.7-pre.021 — wrapper moderne Print

• Print (55) décode les variantes PrintArgs::V1 et PrintArgs::V2, chacune conservant le numéro d’édition u64.
• Le contrat de dix-huit positions conserve les comptes edition metadata, edition, edition mint, token account, Token Record optionnel, master edition, edition marker, payer, propriétaire du master token account et programmes Token/ATA/System/Sysvar.
• PrintV1 et PrintV2 sont des builders spécialisés du même discriminant 55 et non deux discriminateurs supplémentaires.
• Les PDA edition/edition marker et les owners restent à valider lors du décodage stateful des comptes.

Update moderne

Le discriminant 50 décode UpdateArgs et toutes ses variantes publiées : V1, AsUpdateAuthorityV2, AsAuthorityItemDelegateV2, AsCollectionDelegateV2, AsDataDelegateV2, AsProgrammableConfigDelegateV2, AsDataItemDelegateV2, AsCollectionItemDelegateV2 et AsProgrammableConfigItemDelegateV2. Le contrat conserve onze positions, avec placeholders Metaplex readonly pour les comptes optionnels absents. La validation sémantique des PDA, delegates, owners et rule sets reste stateful.

Wrapper Use et vérifications modernes

Use (51) décode UseArgs::V1 et ses douze positions. Verify (52) et Unverify (53) décodent VerificationArgs::{CreatorV1,CollectionV1} avec huit positions et placeholders optionnels explicites. Les validations owner/PDA restent stateful.

0.4.7-pre.024 — inventaire d’instructions exhaustif

Resize (56) et Migrate (48) sont décodés avec leurs contrats positionnels exacts. L’audit de l’IDL 1.14.0 a également identifié puis couvert les six discriminateurs historiques manquants 2, 5, 6, 8, 9 et 10. Le registre contient désormais les 58 discriminateurs 0..=57 sans trou. Ces six surfaces historiques restent decode-only et non exécutables.

0.4.7-pre.025 — premier compte on-chain

La crate expose désormais decode_metadata_account pour le layout officiel Metadata. Le parseur refuse un owner étranger avant désérialisation, exige Key::MetadataV1, borne les données et les champs textuels, limite les creators, valide le PDA canonique [metadata, program_id, mint] et conserve le bump. Cette tranche ne couvre pas encore MasterEdition, Edition, EditionMarker, TokenRecord ni les records de délégation.

0.4.7-pre.026 — comptes edition et master edition

La crate expose decode_edition_account pour DeprecatedMasterEditionV1, MasterEditionV2 et EditionV1. Le décodeur vérifie l’owner avant parsing, exige le PDA commun [metadata, program_id, mint, edition], conserve le bump et projette supply/max supply, printing mints historiques, parent et numéro d’édition. MasterEditionV1 reste historique et decode-only ; MasterEditionV2 et EditionV1 alimenteront les futures projections stateful.

0.4.7-pre.027 — Edition Marker V1/V2

• EditionMarker conserve un ledger fixe de 31 octets, soit 248 éditions par groupe.
• Le groupe V1 est edition / 248 et le PDA utilise les seeds [metadata, program_id, mint, edition, groupe_decimal].
• EditionMarkerV2 conserve un Vec<u8> extensible et utilise un PDA unique [metadata, program_id, mint, edition, marker].
• Le décodeur projette l'index d'octet, le masque big-endian et l'état edition_taken pour l'édition demandée.
• V1 exige exactement 32 octets ; V2 exige une longueur Borsh exacte et borne le ledger à 1 048 576 octets.
• Owner étranger, mauvais PDA, discriminant inconnu, troncature et suffixe sont refusés avant toute projection stateful.

0.4.7-pre.028 — Token Record programmable

• TokenRecord exige le layout alloué exact de 80 octets et Key::TokenRecord.
• Le PDA est dérivé par [metadata, program_id, mint, token_record, token_account] et le bump stocké doit être identique au bump canonique.
• La projection conserve TokenState::{Unlocked,Locked,Listed}, la révision optionnelle du rule set, le delegate, son rôle et la destination optionnelle de locked transfer.
• Les rôles officiels Sale, Transfer, Utility, Staking, Standard, LockedTransfer et Migration sont conservés sans normalisation destructive.
• Owner étranger, mauvais PDA, bump incohérent, mauvais discriminant, troncature et suffixe sont refusés.

0.4.7-pre.029 — records de délégation et d’autorité

• MetadataDelegateRecord et HolderDelegateRecord exigent exactement 98 octets, leur discriminant Key, leur bump stocké et leur PDA canonique.
• Les huit seeds de rôles Metadata sont conservées sans regroupement : authority_item_delegate, collection_delegate, use_delegate, data_delegate, programmable_config_delegate, data_item_delegate, collection_item_delegate et prog_config_item_delegate.
• HolderDelegateRecord conserve le rôle print_delegate, le holder utilisé comme seed, le delegate et l’update authority stockée.
• CollectionAuthorityRecord valide [metadata, program_id, mint, collection_authority, authority] et conserve l’update authority optionnelle.
• UseAuthorityRecord valide [metadata, program_id, mint, user, authority], exige exactement 10 octets et conserve allowed_uses: u64.
• Owner étranger, longueur incorrecte, discriminant erroné, PDA ou bump incohérents sont refusés avant projection.

0.4.7-pre.030 — Token Owned Escrow stateful

• TokenOwnedEscrow conserve le base token mint, l’autorité TokenOwner ou Creator(Pubkey) et le bump stocké.
• Le PDA TokenOwner utilise [metadata, program_id, base_token, 0, escrow].
• Le PDA Creator utilise [metadata, program_id, base_token, 1, creator, escrow].
• Les longueurs Borsh exactes sont 35 octets pour TokenOwner et 67 octets pour Creator.
• Owner étranger, discriminant, longueur, PDA ou bump incohérents sont refusés.
• Les effets de CreateEscrowAccount, CloseEscrowAccount, TransferOutOfEscrow, Migrate et Resize sont décrits dans la matrice pour la future corrélation stateful ; ils ne sont pas encore matérialisés.

0.4.7-pre.031 — Reservation Lists historiques

• ReservationListV1 conserve le Master Edition, le supply snapshot optionnel et jusqu’à 200 entrées avec compteurs u8.
• ReservationListV2 conserve les mêmes identités, des compteurs u64 et les caches total_reservation_spots/current_reservation_spots.
• Le PDA exige le contexte resource et suit [metadata, program_id, master_edition, reservation, resource].
• Les tailles maximales historiques sont 6 949 octets pour V1 et 9 749 octets pour V2 ; seuls les suffixes de padding nuls sont tolérés.
• Ces comptes sont historiques et ne seront jamais exposés par l’exécuteur. Ils restent toutefois matérialisables comme état historique lors des backfills et replays, avec provenance explicite et sans écraser l’état actif.

0.4.7-pre.032 — audit exhaustif des comptes

• Les quinze variantes Key publiées, de Uninitialized (0) à HolderDelegate (14), sont inventoriées dans le code et la matrice.
• Les quatorze variantes représentant un compte réel sont reliées à un décodeur borné ; Uninitialized est une sentinelle explicitement rejetée.
• Les layouts historiques restent decode-only, EditionMarkerV2 reste classé actif/expérimental, et les comptes actifs restent éligibles aux futures matérialisations.
• Un test compare l’ordre et les discriminateurs Borsh du SDK épinglé à l’inventaire interne et à docs/METAPLEX_TOKEN_METADATA_MATRIX.json.
• Toute variante future absente de l’inventaire doit faire échouer l’audit avant toute activation runtime.

0.4.7-pre.033 — modèle canonique et provenance

• Chaque snapshot de compte est enveloppé dans une identité stable program_id:account_address, un nom de layout, son discriminant Key exact et une version canonique interne.
• Les layouts sont classés Active, ActiveExperimental ou Historical sans confondre cette classification avec leur politique d’exécution.
• Les états actifs et expérimentaux sont matérialisables comme état courant ; les états historiques sont matérialisables comme état historique lors d’un backfill ou replay.
• Les layouts historiques restent définitivement non exécutables, même lorsqu’ils sont matérialisés.
• La provenance conserve source, slot, write version, signature, index outer/inner et statut committed lorsque ces données sont disponibles.
• Les sources Live, Replay, Backfill, Repair et Synthetic restent distinctes afin d’éviter toute fusion silencieuse des observations.