v0.1.0-pre.009

2026-07-23 21:19:45 +02:00
parent 12b42a31b8
commit 51ed3d11cf
22 changed files with 9580 additions and 86 deletions
--- a/kb-lib/src/decoder.rs
+++ b/kb-lib/src/decoder.rs
@@ -1,5 +1,5 @@
 // file: kb-lib/src/decoder.rs
-// version: 5
+// version: 6

 //! Consolidated decoder modules.

@@ -138,6 +138,8 @@ pub(crate) use self::spl::spl_token_entry_for_tag;
 /// Returns the first byte of one retained classic SPL Token payload.
 pub(crate) use self::spl::spl_token_payload_tag;

+/// Exact decoder for the Metaplex Token Metadata program.
+pub use self::metadata::MetadataMetaplexTokenMetadataDecoder;
 /// Exact byte length of one SPL ElGamal registry account.
 pub use self::spl::ELGAMAL_REGISTRY_ACCOUNT_LEN;
 /// Parsed SPL ElGamal public-key registry account.
--- a/kb-lib/src/decoder/metadata.rs
+++ b/kb-lib/src/decoder/metadata.rs
@@ -1,7 +1,10 @@
 // file: kb-lib/src/decoder/metadata.rs
-// version: 1
+// version: 2

 //! `metadata` decoder family.

 pub mod metaplex_token_metadata;
 pub mod spl_name_service;
+
+/// Exact decoder for the Metaplex Token Metadata program.
+pub use self::metaplex_token_metadata::MetadataMetaplexTokenMetadataDecoder;
--- a/kb-lib/src/decoder/metadata/metaplex_token_metadata.rs
+++ b/kb-lib/src/decoder/metadata/metaplex_token_metadata.rs
@@ -1,10 +1,223 @@
 // file: kb-lib/src/decoder/metadata/metaplex_token_metadata.rs
-// version: 1
+// version: 2

-//! Migration boundary for legacy crate `kb_decoder_metadata_metaplex_token_metadata`.
+//! Contextual instruction and bounded account decoder for Metaplex Token Metadata.

-/// Legacy crate name retained for migration and compatibility tracking.
-pub const LEGACY_CRATE: &str = "kb_decoder_metadata_metaplex_token_metadata";
+mod account;
+mod canonical;
+mod constants;
+mod decoder;
+mod instruction;

-/// Current porting status.
-pub const MIGRATION_STATUS: &str = "source-preserved-pending-port";
+/// Approve Collection Authority discriminator.
+pub(crate) use self::constants::APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Approve Use Authority discriminator.
+pub(crate) use self::constants::APPROVE_USE_AUTHORITY_DISCRIMINATOR;
+/// Bubblegum Set Collection Size discriminator.
+pub(crate) use self::constants::BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Burn discriminator.
+pub(crate) use self::constants::BURN_DISCRIMINATOR;
+/// Historical Burn Edition NFT discriminator.
+pub(crate) use self::constants::BURN_EDITION_NFT_DISCRIMINATOR;
+/// Historical Burn NFT discriminator.
+pub(crate) use self::constants::BURN_NFT_DISCRIMINATOR;
+/// Close Accounts discriminator.
+pub(crate) use self::constants::CLOSE_ACCOUNTS_DISCRIMINATOR;
+/// Close Escrow Account discriminator.
+pub(crate) use self::constants::CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Collect discriminator.
+pub(crate) use self::constants::COLLECT_DISCRIMINATOR;
+/// Convert Master Edition V1 to V2 discriminator.
+pub(crate) use self::constants::CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR;
+/// Modern Create discriminator.
+pub(crate) use self::constants::CREATE_DISCRIMINATOR;
+/// Create Escrow Account discriminator.
+pub(crate) use self::constants::CREATE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Master Edition discriminator.
+pub(crate) use self::constants::CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Create Master Edition V3 discriminator.
+pub(crate) use self::constants::CREATE_MASTER_EDITION_V3_DISCRIMINATOR;
+/// Historical Create Metadata Account discriminator.
+pub(crate) use self::constants::CREATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Metadata Account V2 discriminator.
+pub(crate) use self::constants::CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Create Metadata Account V3 discriminator.
+pub(crate) use self::constants::CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR;
+/// Delegate discriminator.
+pub(crate) use self::constants::DELEGATE_DISCRIMINATOR;
+/// Deprecated Create Master Edition discriminator.
+pub(crate) use self::constants::DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Deprecated Create Reservation List discriminator.
+pub(crate) use self::constants::DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR;
+/// Deprecated printing-token mint-new-edition discriminator.
+pub(crate) use self::constants::DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens discriminator.
+pub(crate) use self::constants::DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens Via Token discriminator.
+pub(crate) use self::constants::DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR;
+/// Deprecated Set Reservation List discriminator.
+pub(crate) use self::constants::DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR;
+/// Number of bytes retained in malformed-wire diagnostics.
+pub(crate) use self::constants::DIAGNOSTIC_PREFIX_BYTES;
+/// Stable event payload contract version.
+pub(crate) use self::constants::EVENT_VERSION;
+/// Freeze Delegated Account discriminator.
+pub(crate) use self::constants::FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Current pre-release instruction inventory.
+pub(crate) use self::constants::INSTRUCTION_ENTRIES;
+/// Lock discriminator.
+pub(crate) use self::constants::LOCK_DISCRIMINATOR;
+/// Maximum encoded base64 instruction payload size.
+pub(crate) use self::constants::MAX_BASE64_BYTES;
+/// Maximum number of instruction accounts accepted by this decoder.
+pub(crate) use self::constants::MAX_INSTRUCTION_ACCOUNTS;
+/// Tracing target for this decoder.
+/// Maximum retained instruction payload size.
+pub(crate) use self::constants::MAX_INSTRUCTION_BYTES;
+/// Migrate discriminator.
+pub(crate) use self::constants::MIGRATE_DISCRIMINATOR;
+/// Modern Mint discriminator.
+pub(crate) use self::constants::MINT_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Token discriminator.
+pub(crate) use self::constants::MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Vault Proxy discriminator.
+pub(crate) use self::constants::MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR;
+/// Modern Print discriminator.
+pub(crate) use self::constants::PRINT_DISCRIMINATOR;
+/// Puff Metadata discriminator.
+pub(crate) use self::constants::PUFF_METADATA_DISCRIMINATOR;
+/// Remove Creator Verification discriminator.
+pub(crate) use self::constants::REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR;
+/// Resize discriminator.
+pub(crate) use self::constants::RESIZE_DISCRIMINATOR;
+/// Revoke Collection Authority discriminator.
+pub(crate) use self::constants::REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Revoke discriminator.
+pub(crate) use self::constants::REVOKE_DISCRIMINATOR;
+/// Revoke Use Authority discriminator.
+pub(crate) use self::constants::REVOKE_USE_AUTHORITY_DISCRIMINATOR;
+/// Set And Verify Collection discriminator.
+pub(crate) use self::constants::SET_AND_VERIFY_COLLECTION_DISCRIMINATOR;
+/// Set And Verify Sized Collection Item discriminator.
+pub(crate) use self::constants::SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Set Collection Size discriminator.
+pub(crate) use self::constants::SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Set Token Standard discriminator.
+pub(crate) use self::constants::SET_TOKEN_STANDARD_DISCRIMINATOR;
+/// Sign Metadata discriminator.
+pub(crate) use self::constants::SIGN_METADATA_DISCRIMINATOR;
+/// Stable decoder surface code.
+pub(crate) use self::constants::SURFACE_CODE;
+/// Thaw Delegated Account discriminator.
+pub(crate) use self::constants::THAW_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Canonical tracing target for this crate.
+pub(crate) use self::constants::TRACING_TARGET;
+/// Transfer discriminator.
+pub(crate) use self::constants::TRANSFER_DISCRIMINATOR;
+/// Transfer Out Of Escrow discriminator.
+pub(crate) use self::constants::TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR;
+/// Unlock discriminator.
+pub(crate) use self::constants::UNLOCK_DISCRIMINATOR;
+/// Unverify Collection discriminator.
+pub(crate) use self::constants::UNVERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Unverify discriminator.
+pub(crate) use self::constants::UNVERIFY_DISCRIMINATOR;
+/// Unverify Sized Collection Item discriminator.
+pub(crate) use self::constants::UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Modern Update discriminator.
+pub(crate) use self::constants::UPDATE_DISCRIMINATOR;
+/// Historical Update Metadata Account discriminator.
+pub(crate) use self::constants::UPDATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Update Metadata Account V2 discriminator.
+pub(crate) use self::constants::UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Update Primary Sale Happened Via Token discriminator.
+pub(crate) use self::constants::UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR;
+/// Modern Use discriminator.
+pub(crate) use self::constants::USE_DISCRIMINATOR;
+/// Utilize discriminator.
+pub(crate) use self::constants::UTILIZE_DISCRIMINATOR;
+/// Verify Collection discriminator.
+pub(crate) use self::constants::VERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Verify discriminator.
+pub(crate) use self::constants::VERIFY_DISCRIMINATOR;
+/// Verify Sized Collection Item discriminator.
+pub(crate) use self::constants::VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Crate-root access to `ParsedInstruction` from `instruction`.
+pub(crate) use self::instruction::ParsedInstruction;
+/// Crate-root access to `decode` from `instruction`.
+pub(crate) use self::instruction::decode;
+/// Crate-root access to `entry_for_discriminator` from `instruction`.
+pub(crate) use self::instruction::entry_for_discriminator;
+/// Crate-root access to `payload_discriminator` from `instruction`.
+pub(crate) use self::instruction::payload_discriminator;
+
+/// Canonical projection shared by Collection and Use Authority records.
+pub use self::account::AuthorityRecordAccountSnapshot;
+/// Canonical projection shared by Metadata and Holder delegate records.
+pub use self::account::DelegateRecordAccountSnapshot;
+/// Supported edition account layout.
+pub use self::account::EditionAccountKind;
+/// Canonical bounded projection of one edition or master-edition account.
+pub use self::account::EditionAccountSnapshot;
+/// Supported Edition Marker account layout.
+pub use self::account::EditionMarkerAccountKind;
+/// Canonical bounded projection of one Edition Marker account.
+pub use self::account::EditionMarkerAccountSnapshot;
+/// Exhaustive published Metaplex account-key inventory.
+pub use self::account::METADATA_ACCOUNT_LAYOUT_AUDIT;
+/// Bounded error returned while decoding a Metadata account.
+pub use self::account::MetadataAccountDecodeError;
+/// One entry in the exhaustive published account-key audit.
+pub use self::account::MetadataAccountLayoutAuditEntry;
+/// Canonical bounded projection of one Metadata account.
+pub use self::account::MetadataAccountSnapshot;
+/// One bounded historical reservation entry.
+pub use self::account::ReservationEntrySnapshot;
+/// Historical Reservation List account generation.
+pub use self::account::ReservationListAccountKind;
+/// Canonical decode-only projection of a historical Reservation List account.
+pub use self::account::ReservationListAccountSnapshot;
+/// Canonical projection of one Token Owned Escrow account.
+pub use self::account::TokenOwnedEscrowAccountSnapshot;
+/// Authority form used by one Token Owned Escrow account.
+pub use self::account::TokenOwnedEscrowAuthorityKind;
+/// Canonical bounded projection of one programmable Token Record account.
+pub use self::account::TokenRecordAccountSnapshot;
+/// Decodes one Collection Authority Record account.
+pub use self::account::decode_collection_authority_record_account;
+/// Decodes and validates one edition or master-edition account snapshot.
+pub use self::account::decode_edition_account;
+/// Decodes and validates one Edition Marker account snapshot.
+pub use self::account::decode_edition_marker_account;
+/// Decodes one Holder Delegate Record account.
+pub use self::account::decode_holder_delegate_record_account;
+/// Decodes and validates one canonical Metadata account snapshot.
+pub use self::account::decode_metadata_account;
+/// Decodes one Metadata Delegate Record account.
+pub use self::account::decode_metadata_delegate_record_account;
+/// Decodes one historical Reservation List V1 or V2 account.
+pub use self::account::decode_reservation_list_account;
+/// Decodes one Token Owned Escrow account.
+pub use self::account::decode_token_owned_escrow_account;
+/// Decodes and validates one programmable Token Record account snapshot.
+pub use self::account::decode_token_record_account;
+/// Decodes one Use Authority Record account.
+pub use self::account::decode_use_authority_record_account;
+/// Stable identity and policy of one canonical account snapshot.
+pub use self::canonical::CanonicalAccountIdentity;
+/// Lifecycle class of one canonical account layout.
+pub use self::canonical::CanonicalAccountLifecycle;
+/// Provenance retained for one canonical account observation.
+pub use self::canonical::CanonicalAccountProvenance;
+/// Execution policy separated from historical materialization.
+pub use self::canonical::CanonicalExecutionPolicy;
+/// Materialization policy for active or historical state.
+pub use self::canonical::CanonicalMaterializationPolicy;
+/// Canonical account envelope used by materializers and replay.
+pub use self::canonical::CanonicalMetadataAccountSnapshot;
+/// Typed canonical Metaplex account state.
+pub use self::canonical::CanonicalMetadataAccountState;
+/// Origin of one canonical account observation.
+pub use self::canonical::CanonicalObservationSource;
+/// Exact Metaplex Token Metadata decoder.
+pub use self::decoder::MetadataMetaplexTokenMetadataDecoder;
--- a/kb-lib/src/decoder/metadata/metaplex_token_metadata/account.rs
+++ b/kb-lib/src/decoder/metadata/metaplex_token_metadata/account.rs
--- a/kb-lib/src/decoder/metadata/metaplex_token_metadata/canonical.rs
+++ b/kb-lib/src/decoder/metadata/metaplex_token_metadata/canonical.rs
@@ -0,0 +1,425 @@
+// file: kb-lib/src/decoder/metadata/metaplex_token_metadata/canonical.rs
+// version: 2
+
+//! Canonical Metaplex account identities, provenance and materialization policy.
+
+/// Lifecycle class of one decoded Metaplex account layout.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CanonicalAccountLifecycle {
+    /// Current account layout used by supported runtime flows.
+    Active,
+    /// Published account layout whose runtime surface is still experimental.
+    ActiveExperimental,
+    /// Historical account layout retained for ledger replay and backfill.
+    Historical,
+}
+
+/// Materialization policy attached to one canonical account snapshot.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CanonicalMaterializationPolicy {
+    /// Materialize the latest committed state of an active account.
+    ActiveState,
+    /// Materialize historical state with explicit lifecycle provenance.
+    HistoricalState,
+}
+
+/// Execution policy attached to one canonical account layout.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CanonicalExecutionPolicy {
+    /// The layout belongs to current operations that may later be executable.
+    CurrentCandidate,
+    /// The layout belongs to an experimental operation requiring explicit activation.
+    ExperimentalCandidate,
+    /// Historical state must never be exposed by an executor.
+    NeverHistorical,
+}
+
+/// Origin of one canonical account observation.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CanonicalObservationSource {
+    /// Account observed from a live subscription or direct live read.
+    Live,
+    /// Account reconstructed while replaying already stored transactions.
+    Replay,
+    /// Account discovered while backfilling historical ledger data.
+    Backfill,
+    /// Account read to repair a detected ingestion gap.
+    Repair,
+    /// Synthetic account used only by bounded validation tests.
+    Synthetic,
+}
+
+/// Provenance retained for one canonical account observation.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CanonicalAccountProvenance {
+    /// Observation source.
+    pub source: CanonicalObservationSource,
+    /// Slot associated with the account state when known.
+    pub slot: std::option::Option<u64>,
+    /// Provider write version when available.
+    pub write_version: std::option::Option<u64>,
+    /// Transaction signature responsible for the state when known.
+    pub signature: std::option::Option<String>,
+    /// Instruction index associated with the mutation when known.
+    pub instruction_index: std::option::Option<u32>,
+    /// Inner-instruction index associated with the mutation when known.
+    pub inner_instruction_index: std::option::Option<u32>,
+    /// Whether the source state is committed according to the caller's boundary.
+    pub committed: bool,
+}
+
+/// Stable identity and policy of one canonical Metaplex account snapshot.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CanonicalAccountIdentity {
+    /// Stable identity formed from program id and canonical account address.
+    pub stable_id: String,
+    /// Canonical Metaplex Token Metadata program id.
+    pub program_id: String,
+    /// Canonical account address.
+    pub account: String,
+    /// Published layout name.
+    pub layout: String,
+    /// Exact published `Key` discriminant.
+    pub discriminant: u8,
+    /// Internal canonical-model version.
+    pub canonical_version: u16,
+    /// Published lifecycle class.
+    pub lifecycle: CanonicalAccountLifecycle,
+    /// Materialization policy, including historical backfill state.
+    pub materialization: CanonicalMaterializationPolicy,
+    /// Execution policy separated from materialization.
+    pub execution: CanonicalExecutionPolicy,
+}
+
+/// Typed state carried by one canonical Metaplex account snapshot.
+#[derive(Clone, Debug, PartialEq)]
+pub enum CanonicalMetadataAccountState {
+    /// Metadata account state.
+    Metadata(crate::decoder::metadata::metaplex_token_metadata::MetadataAccountSnapshot),
+    /// Master Edition or printed Edition state.
+    Edition(crate::decoder::metadata::metaplex_token_metadata::EditionAccountSnapshot),
+    /// Edition Marker state.
+    EditionMarker(crate::decoder::metadata::metaplex_token_metadata::EditionMarkerAccountSnapshot),
+    /// Programmable Token Record state.
+    TokenRecord(crate::decoder::metadata::metaplex_token_metadata::TokenRecordAccountSnapshot),
+    /// Metadata or holder delegate state.
+    DelegateRecord(
+        crate::decoder::metadata::metaplex_token_metadata::DelegateRecordAccountSnapshot,
+    ),
+    /// Collection or use authority state.
+    AuthorityRecord(
+        crate::decoder::metadata::metaplex_token_metadata::AuthorityRecordAccountSnapshot,
+    ),
+    /// Token-owned escrow state.
+    TokenOwnedEscrow(
+        crate::decoder::metadata::metaplex_token_metadata::TokenOwnedEscrowAccountSnapshot,
+    ),
+    /// Historical Reservation List state.
+    ReservationList(
+        crate::decoder::metadata::metaplex_token_metadata::ReservationListAccountSnapshot,
+    ),
+}
+
+/// Canonical envelope used by future materializers and stateful replay.
+#[derive(Clone, Debug, PartialEq)]
+pub struct CanonicalMetadataAccountSnapshot {
+    /// Stable identity and lifecycle policy.
+    pub identity: CanonicalAccountIdentity,
+    /// Observation provenance.
+    pub provenance: CanonicalAccountProvenance,
+    /// Typed bounded state.
+    pub state: CanonicalMetadataAccountState,
+}
+
+fn canonical_identity(
+    account: &str,
+    layout: &str,
+    discriminant: u8,
+    lifecycle: CanonicalAccountLifecycle,
+) -> CanonicalAccountIdentity {
+    let program_id = kb_program_ids::METADATA_METAPLEX_TOKEN_METADATA_PROGRAM_ID.to_string();
+    let materialization = match lifecycle {
+        CanonicalAccountLifecycle::Historical => CanonicalMaterializationPolicy::HistoricalState,
+        CanonicalAccountLifecycle::Active | CanonicalAccountLifecycle::ActiveExperimental => {
+            CanonicalMaterializationPolicy::ActiveState
+        },
+    };
+    let execution = match lifecycle {
+        CanonicalAccountLifecycle::Historical => CanonicalExecutionPolicy::NeverHistorical,
+        CanonicalAccountLifecycle::Active => CanonicalExecutionPolicy::CurrentCandidate,
+        CanonicalAccountLifecycle::ActiveExperimental => {
+            CanonicalExecutionPolicy::ExperimentalCandidate
+        },
+    };
+    return CanonicalAccountIdentity {
+        stable_id: format!("{program_id}:{account}"),
+        program_id,
+        account: account.to_string(),
+        layout: layout.to_string(),
+        discriminant,
+        canonical_version: 1,
+        lifecycle,
+        materialization,
+        execution,
+    };
+}
+
+impl CanonicalMetadataAccountSnapshot {
+    /// Wraps one Metadata account snapshot with stable identity and provenance.
+    pub fn from_metadata(
+        snapshot: crate::decoder::metadata::metaplex_token_metadata::MetadataAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let identity = canonical_identity(
+            &snapshot.account,
+            "MetadataV1",
+            mpl_token_metadata::types::Key::MetadataV1 as u8,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::Metadata(snapshot),
+        };
+    }
+
+    /// Wraps one Edition or Master Edition snapshot with exact lifecycle policy.
+    pub fn from_edition(
+        snapshot: crate::decoder::metadata::metaplex_token_metadata::EditionAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant, lifecycle) = match snapshot.kind {
+            crate::decoder::metadata::metaplex_token_metadata::EditionAccountKind::MasterEditionV1 => (
+                "MasterEditionV1",
+                mpl_token_metadata::types::Key::MasterEditionV1 as u8,
+                CanonicalAccountLifecycle::Historical,
+            ),
+            crate::decoder::metadata::metaplex_token_metadata::EditionAccountKind::MasterEditionV2 => (
+                "MasterEditionV2",
+                mpl_token_metadata::types::Key::MasterEditionV2 as u8,
+                CanonicalAccountLifecycle::Active,
+            ),
+            crate::decoder::metadata::metaplex_token_metadata::EditionAccountKind::EditionV1 => (
+                "EditionV1",
+                mpl_token_metadata::types::Key::EditionV1 as u8,
+                CanonicalAccountLifecycle::Active,
+            ),
+        };
+        let identity = canonical_identity(&snapshot.account, layout, discriminant, lifecycle);
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::Edition(snapshot),
+        };
+    }
+
+    /// Wraps one Edition Marker snapshot with exact lifecycle policy.
+    pub fn from_edition_marker(
+        snapshot: crate::decoder::metadata::metaplex_token_metadata::EditionMarkerAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant, lifecycle) = match snapshot.kind {
+            crate::decoder::metadata::metaplex_token_metadata::EditionMarkerAccountKind::EditionMarkerV1 => (
+                "EditionMarker",
+                mpl_token_metadata::types::Key::EditionMarker as u8,
+                CanonicalAccountLifecycle::Active,
+            ),
+            crate::decoder::metadata::metaplex_token_metadata::EditionMarkerAccountKind::EditionMarkerV2 => (
+                "EditionMarkerV2",
+                mpl_token_metadata::types::Key::EditionMarkerV2 as u8,
+                CanonicalAccountLifecycle::ActiveExperimental,
+            ),
+        };
+        let identity = canonical_identity(&snapshot.account, layout, discriminant, lifecycle);
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::EditionMarker(snapshot),
+        };
+    }
+
+    /// Wraps one Token Record snapshot.
+    pub fn from_token_record(
+        snapshot: crate::decoder::metadata::metaplex_token_metadata::TokenRecordAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let identity = canonical_identity(
+            &snapshot.account,
+            "TokenRecord",
+            mpl_token_metadata::types::Key::TokenRecord as u8,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::TokenRecord(snapshot),
+        };
+    }
+
+    /// Wraps one Metadata or Holder Delegate snapshot.
+    pub fn from_delegate_record(
+        snapshot: crate::decoder::metadata::metaplex_token_metadata::DelegateRecordAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant) = if snapshot.kind == "MetadataDelegateRecord" {
+            ("MetadataDelegate", mpl_token_metadata::types::Key::MetadataDelegate as u8)
+        } else {
+            ("HolderDelegate", mpl_token_metadata::types::Key::HolderDelegate as u8)
+        };
+        let identity = canonical_identity(
+            &snapshot.account,
+            layout,
+            discriminant,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::DelegateRecord(snapshot),
+        };
+    }
+
+    /// Wraps one Collection or Use Authority snapshot.
+    pub fn from_authority_record(
+        snapshot: crate::decoder::metadata::metaplex_token_metadata::AuthorityRecordAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant) = if snapshot.kind == "CollectionAuthorityRecord" {
+            (
+                "CollectionAuthorityRecord",
+                mpl_token_metadata::types::Key::CollectionAuthorityRecord as u8,
+            )
+        } else {
+            ("UseAuthorityRecord", mpl_token_metadata::types::Key::UseAuthorityRecord as u8)
+        };
+        let identity = canonical_identity(
+            &snapshot.account,
+            layout,
+            discriminant,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::AuthorityRecord(snapshot),
+        };
+    }
+
+    /// Wraps one Token Owned Escrow snapshot.
+    pub fn from_token_owned_escrow(
+        snapshot: crate::decoder::metadata::metaplex_token_metadata::TokenOwnedEscrowAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let identity = canonical_identity(
+            &snapshot.account,
+            "TokenOwnedEscrow",
+            mpl_token_metadata::types::Key::TokenOwnedEscrow as u8,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::TokenOwnedEscrow(snapshot),
+        };
+    }
+
+    /// Wraps one historical Reservation List snapshot as materializable historical state.
+    pub fn from_reservation_list(
+        snapshot: crate::decoder::metadata::metaplex_token_metadata::ReservationListAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant) = match snapshot.kind {
+            crate::decoder::metadata::metaplex_token_metadata::ReservationListAccountKind::V1 => {
+                ("ReservationListV1", mpl_token_metadata::types::Key::ReservationListV1 as u8)
+            },
+            crate::decoder::metadata::metaplex_token_metadata::ReservationListAccountKind::V2 => {
+                ("ReservationListV2", mpl_token_metadata::types::Key::ReservationListV2 as u8)
+            },
+        };
+        let identity = canonical_identity(
+            &snapshot.account,
+            layout,
+            discriminant,
+            CanonicalAccountLifecycle::Historical,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::ReservationList(snapshot),
+        };
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn historical_state_is_materializable_but_never_executable() {
+        let snapshot = crate::decoder::metadata::metaplex_token_metadata::ReservationListAccountSnapshot {
+            account: "reservation-account".to_string(),
+            bump: 1,
+            kind: crate::decoder::metadata::metaplex_token_metadata::ReservationListAccountKind::V1,
+            master_edition: "master-edition".to_string(),
+            resource: "resource".to_string(),
+            supply_snapshot: std::option::Option::Some(7),
+            reservations: std::vec::Vec::new(),
+            total_reservation_spots: 0,
+            current_reservation_spots: 0,
+            payload_json: serde_json::json!({}),
+        };
+        let provenance = super::CanonicalAccountProvenance {
+            source: super::CanonicalObservationSource::Backfill,
+            slot: std::option::Option::Some(42),
+            write_version: std::option::Option::None,
+            signature: std::option::Option::Some("historical-signature".to_string()),
+            instruction_index: std::option::Option::Some(3),
+            inner_instruction_index: std::option::Option::None,
+            committed: true,
+        };
+        let canonical =
+            super::CanonicalMetadataAccountSnapshot::from_reservation_list(snapshot, provenance);
+        assert_eq!(canonical.identity.lifecycle, super::CanonicalAccountLifecycle::Historical);
+        assert_eq!(
+            canonical.identity.materialization,
+            super::CanonicalMaterializationPolicy::HistoricalState
+        );
+        assert_eq!(canonical.identity.execution, super::CanonicalExecutionPolicy::NeverHistorical);
+        assert_eq!(canonical.provenance.source, super::CanonicalObservationSource::Backfill);
+        assert!(canonical.identity.stable_id.ends_with(":reservation-account"));
+    }
+
+    #[test]
+    fn active_and_experimental_layouts_keep_distinct_policies() {
+        let metadata = crate::decoder::metadata::metaplex_token_metadata::MetadataAccountSnapshot {
+            account: "metadata-account".to_string(),
+            bump: 1,
+            mint: "mint".to_string(),
+            update_authority: "authority".to_string(),
+            name: "name".to_string(),
+            symbol: "symbol".to_string(),
+            uri: "uri".to_string(),
+            seller_fee_basis_points: 0,
+            primary_sale_happened: false,
+            is_mutable: true,
+            payload_json: serde_json::json!({}),
+        };
+        let provenance = super::CanonicalAccountProvenance {
+            source: super::CanonicalObservationSource::Live,
+            slot: std::option::Option::Some(1),
+            write_version: std::option::Option::Some(2),
+            signature: std::option::Option::None,
+            instruction_index: std::option::Option::None,
+            inner_instruction_index: std::option::Option::None,
+            committed: true,
+        };
+        let canonical =
+            super::CanonicalMetadataAccountSnapshot::from_metadata(metadata, provenance);
+        assert_eq!(canonical.identity.lifecycle, super::CanonicalAccountLifecycle::Active);
+        assert_eq!(
+            canonical.identity.materialization,
+            super::CanonicalMaterializationPolicy::ActiveState
+        );
+        assert_eq!(canonical.identity.execution, super::CanonicalExecutionPolicy::CurrentCandidate);
+        assert_eq!(canonical.identity.discriminant, 4);
+        assert_eq!(canonical.identity.canonical_version, 1);
+    }
+}
--- a/kb-lib/src/decoder/metadata/metaplex_token_metadata/constants.rs
+++ b/kb-lib/src/decoder/metadata/metaplex_token_metadata/constants.rs
@@ -0,0 +1,257 @@
+// file: kb-lib/src/decoder/metadata/metaplex_token_metadata/constants.rs
+// version: 29
+
+//! Internal constants for Metaplex Token Metadata decoding.
+
+/// Stable decoder surface code.
+pub(crate) const SURFACE_CODE: &str = "metadata_metaplex_token_metadata";
+/// Maximum retained instruction payload size.
+pub(crate) const MAX_INSTRUCTION_BYTES: usize = 16_384;
+/// Maximum encoded base64 instruction payload size.
+pub(crate) const MAX_BASE64_BYTES: usize = 21_852;
+/// Maximum number of instruction accounts accepted by this decoder.
+pub(crate) const MAX_INSTRUCTION_ACCOUNTS: usize = 64;
+/// Number of bytes retained in malformed-wire diagnostics.
+pub(crate) const DIAGNOSTIC_PREFIX_BYTES: usize = 32;
+/// Stable event payload contract version.
+pub(crate) const EVENT_VERSION: u32 = 1;
+/// Deprecated Create Master Edition discriminator.
+pub(crate) const DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR: u8 = 2;
+/// Deprecated Set Reservation List discriminator.
+pub(crate) const DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR: u8 = 5;
+/// Deprecated Create Reservation List discriminator.
+pub(crate) const DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR: u8 = 6;
+/// Deprecated Mint Printing Tokens Via Token discriminator.
+pub(crate) const DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR: u8 = 8;
+/// Deprecated Mint Printing Tokens discriminator.
+pub(crate) const DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR: u8 = 9;
+/// Historical Create Master Edition discriminator.
+pub(crate) const CREATE_MASTER_EDITION_DISCRIMINATOR: u8 = 10;
+/// Deprecated printing-token mint-new-edition discriminator.
+pub(crate) const DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR: u8 = 3;
+/// Historical Create Metadata Account discriminator.
+pub(crate) const CREATE_METADATA_ACCOUNT_DISCRIMINATOR: u8 = 0;
+/// Historical Update Metadata Account discriminator.
+pub(crate) const UPDATE_METADATA_ACCOUNT_DISCRIMINATOR: u8 = 1;
+/// Historical Create Metadata Account V2 discriminator.
+pub(crate) const CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR: u8 = 16;
+/// Create Metadata Account V3 discriminator.
+pub(crate) const CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR: u8 = 33;
+/// Update Metadata Account V2 discriminator.
+pub(crate) const UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR: u8 = 15;
+/// Verify Collection discriminator.
+pub(crate) const VERIFY_COLLECTION_DISCRIMINATOR: u8 = 18;
+/// Unverify Collection discriminator.
+pub(crate) const UNVERIFY_COLLECTION_DISCRIMINATOR: u8 = 22;
+/// Set And Verify Collection discriminator.
+pub(crate) const SET_AND_VERIFY_COLLECTION_DISCRIMINATOR: u8 = 25;
+/// Approve Collection Authority discriminator.
+pub(crate) const APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR: u8 = 23;
+/// Revoke Collection Authority discriminator.
+pub(crate) const REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR: u8 = 24;
+/// Verify Sized Collection Item discriminator.
+pub(crate) const VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR: u8 = 30;
+/// Unverify Sized Collection Item discriminator.
+pub(crate) const UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR: u8 = 31;
+/// Set And Verify Sized Collection Item discriminator.
+pub(crate) const SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR: u8 = 32;
+/// Sign Metadata discriminator.
+pub(crate) const SIGN_METADATA_DISCRIMINATOR: u8 = 7;
+/// Update Primary Sale Happened Via Token discriminator.
+pub(crate) const UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR: u8 = 4;
+/// Utilize discriminator.
+pub(crate) const UTILIZE_DISCRIMINATOR: u8 = 19;
+/// Approve Use Authority discriminator.
+pub(crate) const APPROVE_USE_AUTHORITY_DISCRIMINATOR: u8 = 20;
+/// Revoke Use Authority discriminator.
+pub(crate) const REVOKE_USE_AUTHORITY_DISCRIMINATOR: u8 = 21;
+/// Puff Metadata discriminator.
+pub(crate) const PUFF_METADATA_DISCRIMINATOR: u8 = 14;
+/// Freeze Delegated Account discriminator.
+pub(crate) const FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR: u8 = 26;
+/// Thaw Delegated Account discriminator.
+pub(crate) const THAW_DELEGATED_ACCOUNT_DISCRIMINATOR: u8 = 27;
+/// Remove Creator Verification discriminator.
+pub(crate) const REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR: u8 = 28;
+/// Set Token Standard discriminator.
+pub(crate) const SET_TOKEN_STANDARD_DISCRIMINATOR: u8 = 35;
+/// Mint New Edition From Master Edition Via Token discriminator.
+pub(crate) const MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR: u8 = 11;
+/// Mint New Edition From Master Edition Via Vault Proxy discriminator.
+pub(crate) const MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR: u8 = 13;
+/// Convert Master Edition V1 to V2 discriminator.
+pub(crate) const CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR: u8 = 12;
+/// Create Master Edition V3 discriminator.
+pub(crate) const CREATE_MASTER_EDITION_V3_DISCRIMINATOR: u8 = 17;
+/// Set Collection Size discriminator.
+pub(crate) const SET_COLLECTION_SIZE_DISCRIMINATOR: u8 = 34;
+/// Bubblegum Set Collection Size discriminator.
+pub(crate) const BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR: u8 = 36;
+/// Create Escrow Account discriminator.
+pub(crate) const CREATE_ESCROW_ACCOUNT_DISCRIMINATOR: u8 = 38;
+/// Close Escrow Account discriminator.
+pub(crate) const CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR: u8 = 39;
+/// Transfer Out Of Escrow discriminator.
+pub(crate) const TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR: u8 = 40;
+/// Collect discriminator.
+pub(crate) const COLLECT_DISCRIMINATOR: u8 = 54;
+/// Historical Burn NFT discriminator.
+pub(crate) const BURN_NFT_DISCRIMINATOR: u8 = 29;
+/// Historical Burn Edition NFT discriminator.
+pub(crate) const BURN_EDITION_NFT_DISCRIMINATOR: u8 = 37;
+/// Burn discriminator.
+pub(crate) const BURN_DISCRIMINATOR: u8 = 41;
+/// Lock discriminator.
+pub(crate) const LOCK_DISCRIMINATOR: u8 = 46;
+/// Unlock discriminator.
+pub(crate) const UNLOCK_DISCRIMINATOR: u8 = 47;
+/// Transfer discriminator.
+pub(crate) const TRANSFER_DISCRIMINATOR: u8 = 49;
+/// Close Accounts discriminator.
+pub(crate) const CLOSE_ACCOUNTS_DISCRIMINATOR: u8 = 57;
+/// Modern Create discriminator.
+pub(crate) const CREATE_DISCRIMINATOR: u8 = 42;
+/// Modern Mint discriminator.
+pub(crate) const MINT_DISCRIMINATOR: u8 = 43;
+/// Modern Print discriminator.
+pub(crate) const PRINT_DISCRIMINATOR: u8 = 55;
+/// Modern Update discriminator.
+pub(crate) const UPDATE_DISCRIMINATOR: u8 = 50;
+/// Modern Use discriminator.
+pub(crate) const USE_DISCRIMINATOR: u8 = 51;
+/// Modern Verify discriminator.
+pub(crate) const VERIFY_DISCRIMINATOR: u8 = 52;
+/// Modern Unverify discriminator.
+pub(crate) const UNVERIFY_DISCRIMINATOR: u8 = 53;
+/// Migrate discriminator.
+pub(crate) const MIGRATE_DISCRIMINATOR: u8 = 48;
+/// Resize discriminator.
+pub(crate) const RESIZE_DISCRIMINATOR: u8 = 56;
+/// Delegate discriminator.
+pub(crate) const DELEGATE_DISCRIMINATOR: u8 = 44;
+/// Revoke discriminator.
+pub(crate) const REVOKE_DISCRIMINATOR: u8 = 45;
+/// Current pre-release instruction inventory.
+pub(crate) const INSTRUCTION_ENTRIES: &[(u8, &str, bool)] = &[
+    (CREATE_METADATA_ACCOUNT_DISCRIMINATOR, "create_metadata_account", true),
+    (
+        DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR,
+        "deprecated_create_master_edition",
+        true,
+    ),
+    (
+        DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR,
+        "deprecated_mint_new_edition_from_master_edition_via_printing_token",
+        true,
+    ),
+    (UPDATE_METADATA_ACCOUNT_DISCRIMINATOR, "update_metadata_account", true),
+    (
+        UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR,
+        "update_primary_sale_happened_via_token",
+        false,
+    ),
+    (
+        DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR,
+        "deprecated_set_reservation_list",
+        true,
+    ),
+    (
+        DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR,
+        "deprecated_create_reservation_list",
+        true,
+    ),
+    (SIGN_METADATA_DISCRIMINATOR, "sign_metadata", false),
+    (
+        DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR,
+        "deprecated_mint_printing_tokens_via_token",
+        true,
+    ),
+    (
+        DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR,
+        "deprecated_mint_printing_tokens",
+        true,
+    ),
+    (CREATE_MASTER_EDITION_DISCRIMINATOR, "create_master_edition", true),
+    (PUFF_METADATA_DISCRIMINATOR, "puff_metadata", false),
+    (
+        MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR,
+        "mint_new_edition_from_master_edition_via_token",
+        false,
+    ),
+    (
+        MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR,
+        "mint_new_edition_from_master_edition_via_vault_proxy",
+        true,
+    ),
+    (
+        CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR,
+        "convert_master_edition_v1_to_v2",
+        true,
+    ),
+    (UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR, "update_metadata_account_v2", false),
+    (CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR, "create_metadata_account_v2", true),
+    (CREATE_MASTER_EDITION_V3_DISCRIMINATOR, "create_master_edition_v3", false),
+    (CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR, "create_metadata_account_v3", false),
+    (VERIFY_COLLECTION_DISCRIMINATOR, "verify_collection", false),
+    (UNVERIFY_COLLECTION_DISCRIMINATOR, "unverify_collection", false),
+    (SET_AND_VERIFY_COLLECTION_DISCRIMINATOR, "set_and_verify_collection", false),
+    (
+        APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR,
+        "approve_collection_authority",
+        false,
+    ),
+    (REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR, "revoke_collection_authority", false),
+    (
+        VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR,
+        "verify_sized_collection_item",
+        false,
+    ),
+    (
+        UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR,
+        "unverify_sized_collection_item",
+        false,
+    ),
+    (
+        SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR,
+        "set_and_verify_sized_collection_item",
+        false,
+    ),
+    (UTILIZE_DISCRIMINATOR, "utilize", false),
+    (APPROVE_USE_AUTHORITY_DISCRIMINATOR, "approve_use_authority", false),
+    (REVOKE_USE_AUTHORITY_DISCRIMINATOR, "revoke_use_authority", false),
+    (FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR, "freeze_delegated_account", true),
+    (THAW_DELEGATED_ACCOUNT_DISCRIMINATOR, "thaw_delegated_account", true),
+    (REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR, "remove_creator_verification", false),
+    (SET_TOKEN_STANDARD_DISCRIMINATOR, "set_token_standard", false),
+    (SET_COLLECTION_SIZE_DISCRIMINATOR, "set_collection_size", false),
+    (
+        BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR,
+        "bubblegum_set_collection_size",
+        false,
+    ),
+    (CREATE_ESCROW_ACCOUNT_DISCRIMINATOR, "create_escrow_account", false),
+    (CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR, "close_escrow_account", false),
+    (TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR, "transfer_out_of_escrow", false),
+    (BURN_NFT_DISCRIMINATOR, "burn_nft", true),
+    (BURN_EDITION_NFT_DISCRIMINATOR, "burn_edition_nft", true),
+    (BURN_DISCRIMINATOR, "burn", false),
+    (CREATE_DISCRIMINATOR, "create", false),
+    (MINT_DISCRIMINATOR, "mint", false),
+    (LOCK_DISCRIMINATOR, "lock", false),
+    (UNLOCK_DISCRIMINATOR, "unlock", false),
+    (TRANSFER_DISCRIMINATOR, "transfer", false),
+    (COLLECT_DISCRIMINATOR, "collect", false),
+    (PRINT_DISCRIMINATOR, "print", false),
+    (UPDATE_DISCRIMINATOR, "update", false),
+    (USE_DISCRIMINATOR, "use", false),
+    (VERIFY_DISCRIMINATOR, "verify", false),
+    (UNVERIFY_DISCRIMINATOR, "unverify", false),
+    (MIGRATE_DISCRIMINATOR, "migrate", false),
+    (RESIZE_DISCRIMINATOR, "resize", false),
+    (CLOSE_ACCOUNTS_DISCRIMINATOR, "close_accounts", false),
+    (DELEGATE_DISCRIMINATOR, "delegate", false),
+    (REVOKE_DISCRIMINATOR, "revoke", false),
+];
+
+/// Canonical tracing target for this decoder.
+pub(crate) const TRACING_TARGET: &str = "kb-lib.decoder.metadata.metaplex_token_metadata";
--- a/kb-lib/src/decoder/metadata/metaplex_token_metadata/decoder.rs
+++ b/kb-lib/src/decoder/metadata/metaplex_token_metadata/decoder.rs
--- a/kb-lib/src/decoder/metadata/metaplex_token_metadata/instruction.rs
+++ b/kb-lib/src/decoder/metadata/metaplex_token_metadata/instruction.rs
--- a/kb-lib/src/lib.rs
+++ b/kb-lib/src/lib.rs
@@ -1,5 +1,5 @@
 // file: kb-lib/src/lib.rs
-// version: 10
+// version: 11

 //! Consolidated decoder, executor, materializer and shared model library.
 #![warn(missing_docs)]
@@ -291,6 +291,8 @@ pub(crate) use crate::decoder::spl_token_payload_tag;
 pub use crate::decoder::ELGAMAL_REGISTRY_ACCOUNT_LEN;
 /// Parsed SPL ElGamal public-key registry account.
 pub use crate::decoder::ElGamalRegistryState;
+/// Exact decoder for the Metaplex Token Metadata program.
+pub use crate::decoder::MetadataMetaplexTokenMetadataDecoder;
 /// Exact decoder for the SPL Associated Token Account program.
 pub use crate::decoder::SplAssociatedTokenAccountDecoder;
 /// Exact decoder for the SPL ElGamal registry program.