0.5.1-pre.002

ks-lib/CHANGELOG.md

@@ -0,0 +1,230 @@
+<!-- file: ks-lib/CHANGELOG.md -->
+<!-- version: 51 -->
+
+# CHANGELOG — ks-lib
+
+## `0.5.1-pre.002`
+
+- renomme physiquement `kb-lib` en `ks-lib` et l'identifiant Rust public `kb_lib` en `ks_lib` dans les consommateurs et tests d'API externe ;
+- conserve volontairement les identités runtime/persistées `kb-lib.*` pour `0.5.1-pre.003`, afin de séparer le renommage Cargo de la migration de provenance/replay.
+
+## `0.4.8-pre.015` — réconciliation des matrices Metadata
+
+- `pre.015-delta-fix-001` retire du rustdoc public de l’inventaire Metaplex la provenance obsolète `0.4.7-pre.005` et décrit désormais la surface comme l’inventaire audité courant ;
+- ajoute un test d’API externe qui parcourt les 35 opérations Metaplex depuis les seuls exports crate-root, vérifie les 15 opérations explicitement deprecated et refuse un Program ID étranger ;
+- retire du TODO les validations réseau complémentaires Metaplex déjà closes en `pre.013`, sans supprimer le réaudit transversal prévu pour `0.5.x` ;
+- le delta initial réconcilie les métadonnées de progression de la matrice contractuelle Metaplex Token Metadata avec la surface réellement clôturée en `pre.013` ;
+- conserve intactes les 58 lignes du contrat d’instructions, les inventaires de comptes et les matrices historiques fermées.
+
+## `0.4.8-pre.013` — exactitude des builders Metaplex courants
+
+- `pre.013-delta-fix-033` aligne la validation du décodeur `Update` sur les privilèges runtime globaux : l’authority doit signer et les comptes mutables doivent rester writable, mais un même wallet utilisé comme authority et fee payer peut apparaître writable à la position authority lors du replay Core ; le test `modern_update_variants_accept_transaction_privilege_supersets` couvre cette forme sans augmenter le nombre total de tests.
+- `pre.013-delta-fix-032` corrige le contrat des comptes optionnels terminaux des instructions escrow historiques `CreateEscrowAccount` et `TransferOutOfEscrow` : lorsque `authority=None`, aucun placeholder Metaplex n’est ajouté en fin de liste, conformément aux builders officiels et au handler qui déduit la présence de l’autorité à partir du nombre de comptes ; les comptes optionnels positionnels des instructions courantes conservent leurs placeholders. Le test de builder existant couvre désormais les formes escrow sans authority et avec authority explicite.
+- `pre.013-delta-fix-029` aligne le décodeur courant `Use` sur les privilèges minimaux du builder `mpl-token-metadata 5.1.1` : l’autorité et le payer doivent signer, Metadata doit être writable, et les comptes optionnels réellement présents (`delegate_record`, `token`, `edition`) restent writable ; les privilèges globaux supplémentaires hérités du fee payer ne provoquent plus de faux rejet.
+- `pre.013-delta-fix-027` normalise la projection JSON canonique des comptes `TokenRecord` : `delegate` et `locked_transfer` sont désormais exposés en chaînes base58, comme les champs typés du snapshot, au lieu de dépendre de la représentation Serde interne de `solana_pubkey::Pubkey` ; la régression existante verrouille explicitement ces deux projections et `delegate_role`.
+- `pre.013-delta-fix-026` corrige le replay des opérations pNFT `Delegate`/`Revoke` et `Lock`/`Unlock` sur la frontière des privilèges globaux de transaction : le décodeur vérifie désormais uniquement les minima signer/writable réellement requis au lieu de rejeter les sur-ensembles hérités lorsqu’un même compte occupe aussi le rôle de fee payer ;
+- conserve l’exigence writable des comptes optionnels réellement mutés (`delegate_record`, `token_record`, `token`) lorsqu’ils ne sont pas le placeholder positionnel du programme Token Metadata ;
+- ajoute une régression reproduisant `Delegate/Revoke` avec l’autorité également fee payer et `Lock/Unlock` avec le token owner également fee payer, sans relâcher les refus de signer/writable obligatoires manquants.
+- `pre.013-delta-fix-025` corrige la lecture stateful des Master Edition pNFT compactes : les deux octets finaux de l’allocation 20 octets sont des champs sémantiques Metaplex (`fee flag`, puis `TokenStandard`) et ne sont plus traités comme du padding nul ;
+- conserve une validation fermée : les octets réservés intermédiaires doivent rester nuls, le fee flag est borné à `0/1`, et le trailer Master Edition n’accepte que `NonFungible(0)` ou `ProgrammableNonFungible(4)` ;
+- ajoute une régression reproduisant une Master Edition V2 compacte `supply=0,max_supply=0` avec trailer pNFT, ainsi que les refus d’un fee flag, d’un token standard ou d’un octet réservé invalides.
+- `pre.013-delta-fix-022` corrige la régression `modern_print_accepts_transaction_privilege_supersets` : un `edition_token_record` réellement fourni reste writable conformément au builder `Print` courant ; le test continue d'exercer les privilèges globaux supplémentaires sans retirer un minimum obligatoire ;
+- aucun assouplissement du décodeur `Print` n'est introduit par ce correctif.
+- `pre.013-delta-fix-021` corrige le décodage des comptes `Edition` réellement alloués par le programme courant : `Edition::LEN` décrit 41 octets sérialisés, tandis que les allocations Metaplex connues sont 42 octets en forme compacte et 241 octets en forme historique ;
+- accepte uniquement la sérialisation exacte ou ces allocations connues avec padding nul, refuse les longueurs/paddings inconnus et verrouille aussi les allocations connues de Master Edition après l’élargissement de la borne nécessaire aux anciennes Edition ;
+- ajoute une régression couvrant Edition compacte/historique, Master Edition compacte/historique, longueur inconnue et padding non nul.
+- `pre.013-delta-fix-018` corrige `Verify`/`Unverify` sur la même frontière de privilèges globaux déjà rencontrée pour `Create`/`Mint` : l'autorité peut être writable dans le message parce qu'elle est aussi fee payer, sans que l'AccountMeta Metaplex exige ce privilège ; le décodeur vérifie désormais uniquement les minima signer/writable réellement requis ;
+- aligne `Unverify` sur les 7 positions du wrapper courant `mpl-token-metadata 5.1.1` au lieu d'exiger artificiellement 8 comptes, et ajoute une régression couvrant `Verify` et `Unverify` lorsque l'autorité fee payer hérite du privilège writable global ;
+- `pre.013-delta-fix-009` corrige le décodeur des opérations courantes `Create` et `Mint` pour interpréter les flags signer/writable comme des privilèges globaux de transaction : seuls les privilèges requis constituent désormais des minima, sans rejeter les sur-ensembles légitimes dus au fee payer ou à un même wallet présent sous plusieurs rôles ;
+- accepte explicitement `Create.mint_as_signer = false` pour un mint préexistant et ne force plus `update_authority_as_signer = true`, conformément aux booléens exposés par le SDK courant ;
+- conserve l’exigence writable pour un master edition/token record réellement fourni, tout en distinguant ces comptes des placeholders Metaplex positionnels ;
+- ajoute deux régressions couvrant le `Create` à mint préexistant et le `Mint` où token owner, authority et payer héritent de privilèges transactionnels supérieurs.
+- `pre.013-delta-fix-004` ferme l’audit des comptes positionnels réellement optionnels du SDK courant pour `CreateEscrowAccount`, `TransferOutOfEscrow`, `Mint`, `Migrate`, `Use`, `Print` et `Resize` ;
+- expose ces optionalités dans les intents publics et encode une absence avec le placeholder readonly du programme Metaplex, conformément au contrat Kinobi déjà attendu par le décodeur et la matrice ;
+- conserve explicitement requis les comptes système/programmes qui ne sont que defaultables par le builder mais restent présents dans la struct d’instruction courante ;
+- ajoute des régressions sur les positions optionnelles de `Mint`, `Migrate`, `Use`, `Print` et `Resize`, ainsi que sur l’autorité optionnelle d’escrow ;
+- intègre les deux `return` ajoutés lors de la validation locale de `fix-003` dans les closures de génération de pubkeys de test, afin que l’archive reproduise l’état Clippy réellement validé ;
+- migre `Print` et `Resize` depuis les account metas figées de l’IDL historique vers les builders officiels `mpl-token-metadata 5.1.1` ;
+- rétablit le contrat signer courant de `Print` : `edition_mint`, `edition_mint_authority`, `payer` et `master_token_account_owner` sont désormais déclarés signataires conformément au SDK officiel ;
+- rétablit le contrat signer courant de `Resize` : `payer` est writable + signer, tandis que l’autorité fournie reste signer ;
+- ajoute des régressions directes sur l’ordre, le discriminator et les flags signer/writable de ces deux opérations avant toute campagne Devnet associée.
+
+## `0.4.8-pre.011` — complétude Token-2022 Token Metadata
+
+- ajoute les intents et builders exacts `UpdateTokenMetadataAuthority` et `EmitTokenMetadata` ;
+- encode l’autorité nullable via le contrat officiel et borne les plages `Emit` à 1 024 octets ;
+- conserve le `returnData` de simulation et expose le parseur strict de la valeur `TokenMetadata` ;
+- corrige le feature-gating TS-RS du `serde_json::Value` exposé par le résultat de simulation afin que le derive `TS` et la régénération des bindings utilisent `JsonValue` ;
+- refuse les plages `Emit` ouvertes avec `start` sans `end`, dont la taille ne peut pas être bornée avant simulation ;
+- aligne le test de parité de la matrice d’exécution sur les cinq opérations de `spl-token-metadata-interface`, en rattachant également `UpdateAuthority` et `Emit` à l’entrée `token_metadata` ;
+- extrait le mapping capacités → familles de matrice dans un helper testé directement, afin de rendre explicite et vérifiable le rattachement de `update_token_metadata_authority` et `emit_token_metadata` à `token_metadata` ;
+- ajoute les régressions de clôture couvrant l’autorité nullable `None`, la forme `Emit` complète sans plage et la plage maximale exactement égale à 1 024 octets.
+- corrige dans `pre.011-fix-006` les deux attentes de nommage de ces régressions afin de vérifier les codes d’opération canoniques `spl.token_2022.update_token_metadata_authority` et `spl.token_2022.emit_token_metadata`.
+
+## 0.4.8-pre.008 — matérialiseurs metadata spécialisés
+
+- corrige le décodeur Solana Program Metadata pour interpréter les flags `signer` et `writable` du replay comme des privilèges globaux de message : les privilèges requis sont désormais des minima, et les sur-ensembles légitimes dus au fee payer ou à d’autres instructions ne sont plus rejetés ;
+- ajoute une régression couvrant les neuf instructions avec une autorité signer et writable au niveau du message, tout en conservant le refus des privilèges requis manquants ;
+- corrige la déclaration Rust de `MT_METADATA_METAPLEX_TOKEN_METADATA_ACCEPTED_FAMILIES` livrée dans `pre.008-fix-001`.
+- remplace le type ambigu `MtSolanaProgramMetadataMaterializer` par `MtMetadataSolanaProgramMaterializer` et retire le wrapper générique `MtMetadataMaterializer` ;
+- ajoute `MtMetadataMetaplexTokenMetadataMaterializer` et `MtMetadataToken2022Materializer`, chacun avec ses deux contrats, son identité, son tracing target et un ownership instructionnel exact ;
+- conserve séparément les APIs de snapshots Metaplex, Solana Program Metadata et Token-2022, sans confondre fait d’instruction et état autoritatif ;
+- classe les neuf instructions incorporées Token Metadata et Token Group sous la famille `Metadata`, afin qu’elles soient possédées par le matérialiseur metadata spécialisé plutôt que par un composant d’administration générique ;
+- étend les tests de façade publique et les contrats d’inventaire aux trois matérialiseurs metadata spécialisés.
+
+## 0.4.8-pre.007 — exécuteur Solana Program Metadata et structure Metaplex
+
+- ajoute `ExMetadataSolanaProgramMetadataExecutor`, les intents typés, les helpers de PDA et les builders wire exacts des neuf instructions stables `0..8` ;
+- conserve une sélection explicite canonical/non-canonical au lieu de l’inférer de la présence de `ProgramData`, pour couvrir aussi les contrats des loaders antérieurs ;
+- conserve toutes les opérations courantes comme exécutables, y compris `Write`, `SetAuthority`, `SetData`, `SetImmutable`, `Trim` et `Close`, avec approbation destructive explicite plutôt qu’une suppression de capacité ;
+- soumet chaque plan préparé au cadre commun `ExSafetyChecker` et impose simulation, signataires autorisés, plafonds et quatre postconditions canoniques ;
+- ajoute la matrice d’exécution, le test de parité des capacités et le test d’API externe depuis la façade de crate ;
+- retire l’exécuteur Solana Program Metadata de l’inventaire réservé ;
+- corrige le total attendu du test d’inventaire des exécuteurs réservés de `104` à `103`, conformément au retrait de `ExMetadataSolanaProgramMetadataExecutor` de cet inventaire ;
+- confirme que les neuf opérations stables sont courantes et qu’aucune annotation `#[deprecated]` n’est justifiée par les sources officielles actuelles ;
+- sépare les matérialisations Metaplex Token Metadata dans un sous-module dédié sans modifier les clés ni la sémantique métier des projections déjà livrées, et consigne le constat dans un audit structurel dédié ;
+- corrige la confusion entre identité runtime `kb-lib.*` et `processorName` persisté : Metaplex utilise désormais `materializer.metadata.metaplex_token_metadata`, Solana Program Metadata `materializer.metadata.solana_program_metadata` et Token-2022 `materializer.metadata.token_2022` ;
+- porte les schémas de projection Metaplex et Token-2022 à la version `2` pour refléter cette correction de provenance ;
+- extrait la matérialisation Token-2022 de `metadata/core.rs` vers le composant dédié `metadata/token_2022/` sans modifier la fonction publique ni les clés de sortie ;
+- confirme que les états `TokenMetadata`, `TokenGroup` et `TokenGroupMember` sont matérialisés, que les metadata pointers appartiennent déjà au matérialiseur d’administration et que les cinq faits d’instructions `spl-token-metadata-interface` restent à fermer en `pre.010` ;
+- inscrit dans le TODO et le ROADMAP `0.5.x` un audit transversal des règles de complétude decoder/materializer/executor, de la sécurité et des statuts deprecated/replaced.
+- harmonise les 25 composants de matérialisation autour des paires `MT_*_COMPONENT_NAME` / `MT_*_PROCESSOR_NAME`, avec relation exacte entre identité runtime `kb-lib.materializer.*` et processeur persisté `materializer.*` ;
+- ajoute la provenance persistée manquante aux sorties `admin`, `compliance.audit`, `fees`, `lifecycle` et `staking`, puis porte leurs contrats à `projectionVersion = 2` ;
+- remplace les implémentations génériques `core.rs` par des `materializer.rs`, transforme les fichiers parents en façades pures et déplace toutes les familles, surfaces, tables et identités vers les `constants.rs` réexportés jusqu’à la racine de crate ;
+- rend les 14 matérialisateurs réservés réellement neutres sur les deux traits : famille vide constante, refus legacy, liste d’événements vide et résultat contextuel `Ignored` ;
+- aligne les routes de logging d’exemple sur `compliance.audit`, `transaction.annotations` et `token.accounts`, et ajoute des audits mécaniques empêchant la réintroduction de noms, constantes ou façades non conformes ;
+- prépare la spécialisation complète des matérialiseurs metadata, finalisée en `0.4.8-pre.008` sans wrapper générique ambigu.
+- corrige les warnings de contrats opérationnels en ajoutant des événements `tracing` réels aux matérialisations `fees`, Metaplex Token Metadata et metadata Token-2022, avec `component_name`, `processor_name`, statut, identité de compte ou d’instruction et nombre de sorties ;
+- consomme désormais l’identité runtime `MT_METADATA_TOKEN_2022_COMPONENT_NAME` dans les opérations de snapshot, puis étend les audits pour refuser tout tracing target opérationnel déclaré mais inutilisé ainsi que toute identité de composant absente de son implémentation.
+
+## 0.4.8-pre.006 — matérialisation Solana Program Metadata
+
+- active `MtMetadataMaterializer` comme matérialiseur contextualisé de la surface exacte `metadata.solana_program_metadata` ;
+- matérialise les neuf instructions stables comme faits de mutation committés, sans leur attribuer l’autorité de l’état final ;
+- matérialise les snapshots `Buffer` et `Metadata` comme états autoritatifs bornés, avec conservation intégrale des données directes et Buffer en base64 et SHA-256 ;
+- conserve les URL et références `External` comme données on-chain sans fetch distant ni lecture implicite du compte référencé ;
+- refuse les instructions échouées ou non committées et ignore les programmes, familles ou entrées étrangers ;
+- ferme une matrice de onze projections : deux états de comptes et neuf faits d’instructions ;
+- confirme que les neuf instructions stables sont courantes, non dépréciées et non remplacées ; l’ancien nom pré-stable du tag `5` reste une provenance de `Trim` seulement ;
+- ajoute les helpers publics de matérialisation d’états et le test d’API externe correspondant.
+- corrige le helper de test de snapshot afin d’utiliser les variantes wire existantes `Encoding::Utf8` et `Format::Json`.
+- précise que les opérations destructrices, irréversibles ou écrasantes restent exécutables : leur progression vers simulation, signature et envoi doit être gouvernée par le cadre commun `ExSafetyChecker`, et non supprimée du périmètre de l’exécuteur.
+- validation reçue le 5 août 2026 : `cargo fmt`, `cargo check --workspace`, `cargo clippy --all-targets`, audit workspace et 667 tests unitaires `ks-lib` réussis, avec les tests d’API externes et les doc-tests.
+
+## 0.4.8-pre.005 — instructions Solana Program Metadata
+
+- active `DcMetadataSolanaProgramMetadataDecoder` pour les neuf discriminants stables `0..8` ;
+- décode les arguments, comptes positionnels, signers, flags writable et sources inline ou Buffer avec des bornes explicites ;
+- conserve les formes runtime actuelles non produites par le SDK, notamment `SetData` sur trois octets et les suffixes ignorés de `SetImmutable`, `Trim` et `Close` ;
+- distingue comptes restants acceptés par le runtime et longueurs de comptes exactes ;
+- documente le nom pré-stable `WithdrawExcessLamports` du tag `5` sans créer une entrée historique distincte de `Trim` ;
+- ajoute la matrice d’instructions, l’audit historique, les tests positifs/négatifs et le test de façade publique ;
+- retire le décodeur Solana Program Metadata de l’inventaire des décodeurs réservés.
+- aligne la structure du composant sur les règles du workspace : façade limitée aux sous-modules et réexports, implémentation déplacée dans `decoder.rs`, constantes centralisées dans `constants.rs` et accès internes via `crate::`.
+- corrige les vecteurs négatifs `Initialize` afin de placer explicitement les valeurs invalides après les 16 octets du seed et de vérifier séparément `Encoding`, `Compression`, `Format` et `DataSource`.
+- validation reçue le 5 août 2026 : `cargo fmt`, `cargo check --workspace`, `cargo clippy --all-targets`, audit workspace et 660 tests unitaires `ks-lib` réussis, ainsi que les tests d’API externes et la matrice de nomenclature.
+
+## 0.4.8-pre.004 — comptes Solana Program Metadata
+
+- ajoute les décodeurs publics bornés des comptes `Buffer` et `Metadata` ainsi que leur sélection par discriminateur ;
+- valide le propriétaire `ProgM6…`, la borne Solana de 10 MiB et les headers fixes de 96 octets ;
+- valide les PDA metadata canonical et non-canonical sans inventer de PDA stable pour les Buffers à autorité mutable ou alloués par keypair ;
+- décode les sources `Direct`, `Url` et `External` sans lecture off-chain ni lecture implicite du compte référencé ;
+- distingue `data_length` de la capacité allouée restante, compatible avec l’instruction `Extend` ;
+- ajoute une matrice contractuelle machine-readable, les tests de bornes, de données malformées et de façade publique ;
+- applique le retour explicite requis par Clippy dans le test de longueur wire du modèle externe.
+- corrige l’ombre portée de `metadata_program` dans trois tests de comptes afin d’éviter l’inférence récursive `Option<_>` signalée par `E0275`.
+
+## 0.4.8-pre.003 — modèles Solana Program Metadata
+
+- ajoute les constantes publiques des layouts fixes `Buffer`, `Metadata`, seed et référence externe ;
+- ajoute les enums wire fermées, les cinq erreurs custom officielles et les conversions fail-closed ;
+- ajoute les modèles bornés du seed, des données directes, URL et externes sans résolution off-chain ;
+- ajoute les sérialisations wire sûres, les représentations JSON stables et les tests de façade publique ;
+- conserve le décodeur Solana Program Metadata au statut réservé jusqu’aux phases comptes et instructions.
+
+## 0.4.7-pre.016 — clôture documentaire Metaplex
+
+- généralise la documentation d’usage de la surface Metaplex ;
+- reporte explicitement les validations Devnet spécialisées sans dégrader le statut des builders et tests existants.
+
+## 0.4.7-pre.011 — réouverture des validations réseau
+
+### Documentation
+
+- réorganisation de `README.md`, `USAGE.md`, `TODO.md` et du changelog selon leur rôle documentaire ;
+- suppression des tâches Metaplex terminées du TODO ;
+- maintien des campagnes réseau hors du TODO de `ks-lib`, la surface de builders étant achevée.
+
+## 0.4.7-pre.006 — fermeture de l’exécuteur Metaplex
+
+- fermeture des 35 opérations officiellement constructibles : 20 courantes et 15 dépréciées ;
+- ajout des éditions, use authority, escrow, mint, migrate, use, collect, print et resize ;
+- conservation des 22 instructions remplacées en decode-only et de Bubblegum comme frontière externe ;
+- extension des tests unitaires d’intent, builder, capability, PDA et signers.
+
+## 0.4.7-pre.005 — programmable NFTs et délégations
+
+- ajout des wrappers officiels `Burn`, `Delegate`, `Revoke`, `Lock`, `Unlock`, `Transfer` et `CloseAccounts` ;
+- validation des comptes Token Authorization Rules et maintien de la simulation obligatoire.
+
+## 0.4.7-pre.004 — collections, créateurs et autorités
+
+- ajout des wrappers courants `Verify` et `Unverify` ;
+- ajout de `SetCollectionSize` comme opération dépréciée soumise à approbation explicite.
+
+## 0.4.7-pre.003 — fondations de l’exécuteur Metaplex
+
+- remplacement de l’exécuteur réservé par une surface typée ;
+- ajout des builders `Create`, `Update`, `PuffMetadata` et `SetTokenStandard` ;
+- correction des dépendances Solana modulaires, suppression des opérateurs `?` introduits et ajout des tests de parité ;
+- classification des opérations courantes, remplacées et obsolètes constructibles.
+
+## 0.4.7-pre.002 — contrat Metaplex fermé
+
+- classification exhaustive des 58 discriminants ;
+- propriété unique des faits metadata, admin, lifecycle et risk/compliance ;
+- séparation contractuelle avec Token-2022.
+
+## 0.4.6
+
+- alignement de la crate sur la version fonctionnelle bot3 `0.4.6` ;
+- clôture des tâches de migration applicables et report explicite des évolutions ultérieures dans le TODO.
+
+## 0.1.0-pre.072
+
+- reclassement du TODO selon les blocants avant `0.4.6`, les travaux `0.4.7`, les versions ultérieures et les dépendances conditionnelles.
+
+## 0.1.0-pre.070
+
+- enrichissement de `USAGE.md` avec plusieurs exemples couvrant les familles d’API publiques significatives.
+
+## 0.1.0-pre.069
+
+### Documentation
+
+- ajout de `README.md`, `TODO.md`, `USAGE.md` et du présent changelog selon les normes bot3 ;
+- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
+- retrait des limitations et travaux futurs du changelog ;
+- correction de la frontière entre historique, TODO et limites durables d’utilisation ;
+- réécriture de `TODO.md` sous forme de tâches uniquement ;
+- correction des exemples de `USAGE.md` afin de ne pas utiliser l’opérateur `?`.
+
+## 0.1.0
+
+### Migré
+
+- consolidation des modèles, décodeurs, exécuteurs et matérialisateurs issus de nombreuses crates bot2 dans une façade unique ;
+- migration des surfaces Solana Core, SPL Memo, SPL Token, SPL ATA, Token-2022, registre ElGamal et du décodeur Metaplex Token Metadata ;
+- migration des contrats de replay, de sécurité et de matérialisation.
+
+### Modifié
+
+- adoption de Rust 2024, de `#![forbid(unsafe_code)]`, `#![deny(unreachable_pub)]` et des conventions strictes d’exports, d’erreurs et de tracing ;
+- remplacement des anciennes frontières de crates par des modules privés et des réexports publics contrôlés.
+
+### Validation
+
+- tests unitaires des décodeurs, exécuteurs, matérialisateurs et contrats consolidés ;
+- matrices contractuelles chargées par les tests concernés ;
+- validations Devnet conservées pour les scénarios explicitement couverts pendant la migration.

ks-lib/Cargo.toml

@@ -0,0 +1,59 @@
+# file: ks-lib/Cargo.toml
+# version: 16
+
+[package]
+name = "ks-lib"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+
+[dependencies]
+bytemuck.workspace = true
+base64.workspace = true
+borsh.workspace = true
+borsh_0_10.workspace = true
+bs58.workspace = true
+ks-core = { path = "../ks-core" }
+ks-program-ids = { path = "../ks-program-ids" }
+mpl-token-metadata.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+solana-address-lookup-table-interface.workspace = true
+solana-compute-budget-interface.workspace = true
+solana-feature-gate-interface.workspace = true
+solana-hash.workspace = true
+solana-instruction.workspace = true
+solana-transaction.workspace = true
+solana-signer.workspace = true
+solana-nonce.workspace = true
+solana-message.workspace = true
+solana-keypair.workspace = true
+solana-loader-v3-interface.workspace = true
+solana-pubkey.workspace = true
+solana-sdk-ids.workspace = true
+solana-stake-interface.workspace = true
+solana-system-interface.workspace = true
+solana-vote-interface.workspace = true
+solana-zk-elgamal-proof-interface.workspace = true
+solana-zk-sdk-pod.workspace = true
+spl-associated-token-account-interface.workspace = true
+spl-elgamal-registry-interface.workspace = true
+spl-token-group-interface.workspace = true
+spl-token-metadata-interface.workspace = true
+spl-token-2022-interface.workspace = true
+spl-token-confidential-transfer-proof-extraction.workspace = true
+spl-token-interface.workspace = true
+spl-memo-interface.workspace = true
+tracing.workspace = true
+ts-rs.workspace = true
+wincode.workspace = true
+
+[dev-dependencies]
+solana-ed25519-program.workspace = true
+solana-secp256k1-program.workspace = true
+solana-secp256r1-program.workspace = true
+
+[lints]
+workspace = true

ks-lib/README.md

@@ -0,0 +1,107 @@
+<!-- file: ks-lib/README.md -->
+<!-- version: 29 -->
+
+# ks-lib
+
+`ks-lib` est la bibliothèque fonctionnelle consolidée de `khadhroony-bot3`. Elle fournit les modèles, décodeurs, matérialisateurs, exécuteurs et contrats de sécurité indépendants du transport, du stockage et de l’interface utilisateur.
+
+## Périmètre
+
+La crate couvre actuellement Solana Core, SPL Memo, SPL Token classique, SPL Associated Token Account, Token-2022, le registre SPL ElGamal et Metaplex Token Metadata. Elle expose également les modèles wire bornés, les décodeurs de comptes `Buffer` et `Metadata`, le décodeur contextualisé des neuf instructions stables et la matérialisation exhaustive de Solana Program Metadata.
+
+Pour Solana Program Metadata, la surface publique fondatrice comprend :
+
+- les tailles fixes officielles des headers, seeds et références externes ;
+- les enums fermées de discriminateur, encodage, compression, format et source ;
+- le seed brut de 16 octets avec helpers UTF-8 bornés ;
+- les données directes, URL et références vers un autre compte sans résolution off-chain ;
+- les cinq erreurs custom officielles et les erreurs de conversion fail-closed ;
+- les snapshots bornés `Buffer` et `Metadata`, avec validation du propriétaire, des PDA metadata, des longueurs logiques et des trois sources de données ;
+- une politique explicite où les octets situés après `data_length` sont conservés comme capacité allouée et jamais assimilés au contenu logique ;
+- les neuf instructions stables `Write`, `Initialize`, `SetAuthority`, `SetData`, `SetImmutable`, `Trim`, `Close`, `Allocate` et `Extend` ;
+- les formes runtime actuelles non produites par le SDK, notamment `SetData` sans remplacement de données et les suffixes ignorés de `SetImmutable`, `Trim` et `Close` ;
+- une frontière historique où l’ancien nom pré-stable `WithdrawExcessLamports` du tag `5` reste une provenance de `Trim`, sans dixième entrée de couverture ;
+- une sélection canonical/non-canonical explicite dans les intents `Initialize` et `Allocate`, indépendante de la seule présence de `ProgramData` ;
+- deux projections d’état autoritatives pour `Buffer` et `Metadata`, avec conservation bornée du contenu on-chain ;
+- neuf faits de mutation d’instructions committées, non autoritatifs vis-à-vis de l’état final et réconciliables avec les snapshots post-exécution ;
+- une classification où les neuf instructions stables sont courantes, sans opération officiellement remplacée ou obsolète à annoter `Deprecated` ;
+- un exécuteur typé couvrant les neuf opérations, avec dérivation des PDA, wire exact, comptes ordonnés, signataires, approbation explicite des mutations dangereuses et évaluation commune par `ExSafetyChecker`.
+
+Pour Metaplex Token Metadata, elle fournit :
+
+- le décodage des 58 discriminants et des principales familles de comptes ;
+- la propriété unique des faits metadata, admin, lifecycle et risk/compliance ;
+- 20 opérations courantes exécutables ;
+- 15 opérations obsolètes encore constructibles, exposées comme dépréciées et soumises à une approbation explicite ;
+- 22 versions remplacées conservées en décodage uniquement et redirigées vers leur remplacement canonique final ;
+- une frontière explicite avec Bubblegum et avec les metadata incorporées de Token-2022 ;
+- un sous-module de matérialisation dédié `materializer/metadata/metaplex_token_metadata`, qui conserve les projections d’état déjà livrées sans modifier leurs clés ni leur sémantique persistée.
+
+## Architecture des matérialisateurs
+
+L’arbre `src/materializer` suit un contrat homogène :
+
+- une façade limitée aux déclarations de sous-modules et réexports ;
+- un `constants.rs` propriétaire des identités, familles, surfaces, versions de projection et tracing targets ;
+- un `materializer.rs` pour les implémentations de traits ;
+- des fichiers `state.rs` ou `account.rs` uniquement lorsque la projection stateful l’exige ;
+- une identité runtime `kb-lib.materializer.*` distincte du `processorName` persisté `materializer.*` ;
+- des coquilles réservées réellement inactives sur les deux contrats legacy et contextuel.
+
+L’inventaire audité comprend 25 composants nommés : onze matérialisateurs actifs et quatorze coquilles réservées. Les composants metadata Metaplex Token Metadata, Solana Program Metadata et Token-2022 possèdent chacun un type spécialisé, une identité propre et leurs APIs de snapshots lorsque leur état on-chain l’exige. Le détail est consigné dans [l’audit de convention des matérialisateurs](../olddocs/archivekbot3/docs/audits/V0_4_8_PRE_007_MATERIALIZER_CONVENTION_AUDIT.md).
+
+## Responsabilités
+
+- reconnaître et décoder des instructions contextualisées ;
+- décoder les comptes on-chain pris en charge ;
+- produire des observations et diagnostics typés ;
+- matérialiser les faits stables et prouvés ;
+- construire des plans d’exécution bornés ;
+- déclarer les comptes, signers, coûts et confirmations nécessaires ;
+- appliquer les garde-fous fail-closed avant simulation, signature ou envoi ;
+- exposer des modèles indépendants du RPC, de PostgreSQL et de Tauri.
+
+## Hors périmètre
+
+`ks-lib` ne sélectionne aucun endpoint, ne lit pas directement un RPC, ne persiste aucune donnée, ne gère pas les secrets de wallet et ne soumet aucune transaction.
+
+## Surface publique principale
+
+- contrats `DcApi*` et décodeurs concrets `Dc*Decoder` ;
+- parseurs de comptes et d’états bornés ;
+- contrats `MtApi*` et matérialisateurs concrets ;
+- contrats `ExApi*`, politiques de sécurité et exécuteurs `Ex*Executor` ;
+- `ExMetadataMetaplexTokenMetadataExecutor`, `ExMetaplexTokenMetadataExecutionIntent` et `ExMetaplexTokenMetadataOperation` ;
+- `DcMetadataSolanaProgramMetadataDecoder`, modèles `DcMetadataSpm*`, constantes `DC_METADATA_SPM_*`, fonctions `decoder_metadata_solana_program_metadata_decode_*_account` et helpers `materializer_metadata_materialize_solana_program_metadata_*_snapshot` ;
+- `ExMetadataSolanaProgramMetadataExecutor`, `ExMetadataSpmExecutionIntent`, `ExMetadataSpmOperation`, les helpers de PDA et les constantes `EX_METADATA_SPM_*_OPERATION` ;
+- modèles canoniques `Md*` réexportés par la façade.
+
+Les exemples d’appel et invariants sont documentés dans [USAGE.md](USAGE.md).
+
+## Relations avec le workspace
+
+- dépend de `ks-core` et `ks-program-ids` ;
+- est consommée par `ks-pipeline`, `ks-store`, `ks-onchain-transport`, `ks-pipeline-demo-scenarios` et `kb-app-demo-desktop` ;
+- ne dépend jamais de `ks-store`, `ks-pipeline` ni d’une application.
+
+## Statut et limites
+
+La surface fonctionnelle Metaplex de la crate est achevée. Les campagnes Devnet restantes relèvent de `ks-pipeline-demo-scenarios` et de `kb-app-demo-desktop`, non d’un manque de builder dans `ks-lib`.
+
+Pour Solana Program Metadata, les modèles wire, les décodeurs bornés de comptes, le décodeur contextualisé, la matérialisation des deux comptes et des neuf instructions stables, ainsi que l’exécuteur typé des neuf opérations sont actifs. `Buffer` accepte tout reliquat comme données allouées sans inventer de PDA stable après changement d’autorité ; `Metadata` valide la dérivation canonical ou non-canonical et distingue le contenu logique de la capacité ajoutée par `Extend`. Les instructions produisent des faits committés non autoritatifs ; les snapshots post-exécution restent la source de l’état final. Les variantes qui dépendent de l’état du compte restent des intentions wire jusqu’aux lectures stateful prévues, et aucune forme pré-stable n’est déclarée compatible réseau sans preuve de cluster.
+
+Le registre ElGamal n’est pas déclaré validé réellement sur réseau.
+
+## Documentation
+
+- [Guide d’utilisation](USAGE.md)
+- [Travaux restant à réaliser](TODO.md)
+- [Historique des changements](CHANGELOG.md)
+- [Matrice contractuelle Metaplex](../test-fixtures/contract-matrices/METAPLEX_TOKEN_METADATA_MATRIX.json)
+- [Matrice des comptes Solana Program Metadata](../test-fixtures/contract-matrices/SOLANA_PROGRAM_METADATA_ACCOUNT_MATRIX.json)
+- [Matrice des instructions Solana Program Metadata](../test-fixtures/contract-matrices/SOLANA_PROGRAM_METADATA_INSTRUCTION_MATRIX.json)
+- [Matrice de matérialisation Solana Program Metadata](../test-fixtures/contract-matrices/SOLANA_PROGRAM_METADATA_MATERIALIZATION_MATRIX.json)
+- [Matrice d’exécution Solana Program Metadata](../test-fixtures/contract-matrices/SOLANA_PROGRAM_METADATA_EXECUTOR_MATRIX.json)
+- [Audit de l’inventaire et de l’historique des instructions](../olddocs/archivekbot3/docs/audits/V0_4_8_PRE_005_SOLANA_PROGRAM_METADATA_INSTRUCTION_HISTORY_AUDIT.md)
+
+- complétude d’exécution des cinq instructions Token-2022 Token Metadata, y compris `UpdateAuthority` et `Emit` ;

ks-lib/TODO.md

@@ -0,0 +1,25 @@
+<!-- file: ks-lib/TODO.md -->
+<!-- version: 16 -->
+
+# TODO — ks-lib
+
+## `0.5.x` — audit transversal décodage, matérialisation, exécution et sécurité
+
+- [ ] Inventaire - recenser chaque surface courante, historique, remplacée et officiellement obsolète de tous les décodeurs déjà livrés.
+- [ ] Décodage - vérifier que chaque décodeur couvre exhaustivement son contrat officiel, y compris les formes historiques qui restent observables.
+- [ ] Matérialisation - vérifier que chaque état ou fait décodé possède exactement un propriétaire de matérialisation, sans omission ni double projection.
+- [ ] Exécution - vérifier que chaque opération courante, destructive, irréversible ou écrasante officiellement constructible possède un builder et une capacité d’exécution.
+- [ ] Sécurité - vérifier que chaque plan exécutable traverse `ExSafetyChecker`, déclare ses signataires, plafonds, confirmations et postconditions, sans supprimer une opération au seul motif qu’elle est dangereuse.
+- [ ] Dépréciation - annoter `#[deprecated]` les opérations officiellement obsolètes mais encore constructibles, conserver leur statut exécutable avec approbation explicite et laisser les versions officiellement remplacées en decode-only.
+- [ ] Matrices et documentation - réconcilier statuts, fact ownership, capacités, approbations opérateur, tests de parité, README, USAGE et changelogs pour Solana Core, SPL, Metaplex et les surfaces ajoutées avant `0.5.x`.
+
+## Report conditionnel — registre SPL ElGamal
+
+- [ ] Réseau - confirmer si le registre est déployé et utilisable sur Devnet ou Mainnet.
+- [ ] Fixture - préparer une preuve `PubkeyValidity` et un compte `Proof Context State` valides si un réseau exploitable est confirmé.
+- [ ] Validation - exécuter une validation réseau réelle avant de déclarer la surface validée.
+
+## Versions ultérieures
+
+- [ ] Surfaces - remplacer les décodeurs et exécuteurs réservés selon le ROADMAP.
+- [ ] Anchor - implémenter l’infrastructure générique des conventions Anchor dans la série `0.6.x`.

ks-lib/USAGE.md

@@ -0,0 +1,422 @@
+<!-- file: ks-lib/USAGE.md -->
+<!-- version: 17 -->
+
+# Utilisation de ks-lib
+
+## Objectif
+
+Ce guide présente les familles d’API publiques significatives de `ks-lib`. Les helpers privés, éléments `pub(crate)` et modules non réexportés ne font pas partie du contrat consommateur.
+
+## Dépendance
+
+```toml
+[dependencies]
+ks-lib = { path = "../ks-lib" }
+```
+
+Toutes les fonctions retournant `ks_core::Result<T>` utilisent le contrat d’erreur structuré du workspace.
+
+## Décodage contextualisé
+
+`DcApiInstructionDecoder` définit la reconnaissance et le décodage d’une instruction contextualisée. Les décodeurs concrets sont des valeurs sans état.
+
+```rust
+use ks_lib::{DcApiInstructionDecoder, DcSolanaCoreDecoder};
+
+let decoder = DcSolanaCoreDecoder;
+let recognition = DcApiInstructionDecoder::recognize(&decoder, &input);
+let result = DcApiInstructionDecoder::decode(&decoder, &input);
+```
+
+Le consommateur doit vérifier le résultat typé et ses diagnostics. Une transaction échouée peut produire une intention structurée, mais pas une mutation committée.
+
+```rust
+let execution = DcApiInstructionDecoder::decode(&decoder, &input);
+
+match execution {
+    Ok(result) => {
+        println!("status={:?}", result.status);
+        println!("observations={}", result.observations.len());
+        println!("diagnostics={}", result.diagnostics.len());
+    },
+    Err(error) => return Err(error),
+}
+```
+
+Décodeurs fonctionnels principaux :
+
+- `DcSolanaCoreDecoder` ;
+- `DcSplMemoDecoder` ;
+- `DcSplTokenDecoder` ;
+- `DcSplAssociatedTokenAccountDecoder` ;
+- `DcSplToken2022Decoder` ;
+- `DcSplElgamalRegistryDecoder` ;
+- `DcMetadataMetaplexTokenMetadataDecoder` ;
+- `DcMetadataSolanaProgramMetadataDecoder`.
+
+Les types réservés `Dc*Decoder` ne doivent pas être interprétés comme des décodeurs complets : ils publient une compatibilité conservatrice et aucune observation fonctionnelle.
+
+## Lecture d’états Token-2022 et ElGamal
+
+```rust
+let state = match ks_lib::decoder_spl_token_2022_parse_token_2022_state(
+    ks_lib::DcToken2022StateKind::Account,
+    &account_data,
+) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+println!("parsed token-2022 state: {state:#?}");
+```
+
+```rust
+let registry = match ks_lib::decoder_spl_elgamal_registry_parse_elgamal_registry_state(
+    &account_data,
+) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+println!("parsed registry state: {registry:#?}");
+```
+
+Les parseurs vérifient les bornes et formats qu’ils annoncent. Ils ne reconstruisent pas un état historique depuis un RPC courant.
+
+## Modèles, comptes et instructions Solana Program Metadata
+
+Les modèles `DcMetadataSpm*` représentent uniquement le contrat on-chain du programme `ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S`. Ils ne téléchargent jamais les URL et ne lisent pas automatiquement les comptes référencés par `External`.
+
+```rust
+let seed_result = ks_lib::DcMetadataSpmSeed::from_utf8("idl");
+let seed = match seed_result {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error.to_string()),
+};
+let external = ks_lib::DcMetadataSpmExternalData::from_zeroable_length(
+    solana_pubkey::Pubkey::new_from_array([7_u8; 32]),
+    128,
+    4096,
+);
+let data = ks_lib::DcMetadataSpmData::External(external);
+let wire_bytes = match data.to_wire_bytes() {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error.to_string()),
+};
+assert_eq!(seed.as_bytes().len(), ks_lib::DC_METADATA_SPM_SEED_BYTES);
+assert_eq!(wire_bytes.len(), ks_lib::DC_METADATA_SPM_EXTERNAL_DATA_BYTES);
+```
+
+Le champ `length` externe suit le contrat zeroable : la valeur wire `0` devient `None` et signifie que la référence porte sur tout le compte à partir de `offset`. Les contenus `Direct` et `Url` doivent être non vides, et toute longueur doit rester représentable par le `u32` du header.
+
+Les trois fonctions publiques de comptes vérifient le propriétaire `ProgM6…`, la borne maximale de données et les layouts fixes :
+
+- `decoder_metadata_solana_program_metadata_decode_account` sélectionne `Buffer` ou `Metadata` depuis le discriminateur ;
+- `decoder_metadata_solana_program_metadata_decode_buffer_account` conserve tous les octets alloués après le header, sans prétendre qu’un Buffer garde un PDA vérifiable après une modification d’autorité ;
+- `decoder_metadata_solana_program_metadata_decode_metadata_account` valide le PDA canonical ou non-canonical, `data_length`, les enums fermées et les contraintes propres à `Direct`, `Url` et `External`.
+
+```rust
+let snapshot = match ks_lib::decoder_metadata_solana_program_metadata_decode_account(
+    metadata_account.as_str(),
+    account_owner.as_str(),
+    &account_data,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error.to_string()),
+};
+
+match snapshot {
+    ks_lib::DcMetadataSpmAccountSnapshot::Buffer(value) => {
+        println!("buffer bytes={}", value.allocated_data_bytes);
+    },
+    ks_lib::DcMetadataSpmAccountSnapshot::Metadata(value) => {
+        println!("metadata program={}", value.program);
+        println!("logical bytes={}", value.data_length);
+        println!("reserved capacity={}", value.trailing_capacity_bytes);
+    },
+}
+```
+
+Une URL est seulement décodée comme chaîne UTF-8 on-chain. Aucune requête HTTP, IPFS ou Arweave n’est effectuée. Une référence `External` est seulement décodée en adresse, offset et longueur zeroable ; le compte référencé n’est pas lu.
+
+Le décodeur `DcMetadataSolanaProgramMetadataDecoder` reconnaît le Program ID `ProgM6…` et les neuf tags stables `0..8`. Il conserve les différences utiles entre le wire SDK et le runtime actuel, sans interpréter un suffixe ignoré comme un nouvel argument.
+
+```rust
+let decoder = ks_lib::DcMetadataSolanaProgramMetadataDecoder;
+let recognition = ks_lib::DcApiInstructionDecoder::recognize(&decoder, &input);
+if !recognition.compatible {
+    return std::result::Result::Err("instruction incompatible".to_string());
+}
+let result = ks_lib::DcApiInstructionDecoder::decode(&decoder, &input);
+println!("status={:?}", result.status);
+```
+
+Le tag `5` est toujours publié comme `trim`. Son ancien nom pré-stable `withdraw_excess_lamports` est conservé uniquement comme provenance, car aucune release stable ne l’expose comme instruction distincte. Les URL et références externes restent des données on-chain ; le décodeur ne réalise aucun fetch.
+
+Les trois domaines metadata disposent de matérialiseurs instructionnels spécialisés :
+
+- `MtMetadataMetaplexTokenMetadataMaterializer` pour les observations Metaplex de famille metadata ;
+- `MtMetadataSolanaProgramMaterializer` pour les neuf instructions stables de `ProgM6…` ;
+- `MtMetadataToken2022Materializer` pour les instructions incorporées Token Metadata et Token Group de Token-2022.
+
+Chaque type possède son propre `componentName`, son propre `processorName`, ses familles acceptées et un ownership exact. Les transactions échouées sont refusées. Les faits d’instructions ne remplacent jamais les snapshots autoritatifs lus après exécution.
+
+```rust
+let materializer = ks_lib::MtMetadataSolanaProgramMaterializer;
+if ks_lib::MtApiEventMaterializer::accepts_observation(&materializer, &observation) {
+    let result = ks_lib::MtApiEventMaterializer::materialize(&materializer, &observation);
+    println!("materialization status={:?}", result.status);
+}
+```
+
+Les trois helpers d’état acceptent les snapshots déjà validés par le décodeur :
+
+- `materializer_metadata_materialize_solana_program_metadata_account_snapshot` distribue `Buffer` ou `Metadata` ;
+- `materializer_metadata_materialize_solana_program_metadata_buffer_snapshot` conserve tous les octets du Buffer sous une forme bornée avec base64 et SHA-256 ;
+- `materializer_metadata_materialize_solana_program_metadata_metadata_snapshot` conserve le contenu direct, l’URL ou la référence externe, ainsi que l’autorité, la mutabilité, le format et la capacité allouée.
+
+```rust
+let output = match ks_lib::materializer_metadata_materialize_solana_program_metadata_account_snapshot(
+    slot,
+    &snapshot,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+println!("projection={}", output.payload_json);
+```
+
+Une URL reste une chaîne observée avec `fetched = false`. Une référence externe reste une adresse, un offset et une longueur avec `accountRead = false`. La matérialisation canonique ne réalise aucun enrichissement off-chain.
+
+## Comptes Metaplex Token Metadata
+
+Les fonctions `decoder_metadata_metaplex_token_metadata_decode_*_account` décodent les familles de comptes publiques prises en charge. Le consommateur doit fournir les données et le contexte attendus par la signature exacte de la fonction concernée. Les parseurs conservent les variantes historiques et refusent les longueurs, propriétaires ou suffixes incompatibles.
+
+```rust
+let metadata = match ks_lib::decoder_metadata_metaplex_token_metadata_decode_metadata_account(
+    metadata_account.as_str(),
+    metadata_owner.as_str(),
+    &account_data,
+) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+println!("metadata mint={}", metadata.mint);
+println!("metadata name={}", metadata.name);
+```
+
+```rust
+let edition = match ks_lib::decoder_metadata_metaplex_token_metadata_decode_edition_account(
+    edition_account.as_str(),
+    metadata_owner.as_str(),
+    mint.as_str(),
+    &account_data,
+) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+println!("edition kind={:?}", edition.kind);
+println!("edition parent={:?}", edition.parent);
+```
+
+Les signatures exactes doivent être vérifiées lors de l’utilisation : certaines familles exigent un contexte ou une identité canonique supplémentaire.
+
+## Exécution typée
+
+`ExApiTypedInstructionExecutor` produit un `ExApiPreparedExecutionPlan` à partir d’une intention et d’une politique explicites. Les exécuteurs concrets incluent notamment :
+
+- `ExSolanaCoreExecutor` ;
+- `ExSplMemoExecutor` pour Memo v4 ;
+- `ExSplTokenExecutor` ;
+- `ExSplAssociatedTokenAccountExecutor` ;
+- `ExSplToken2022Executor` ;
+- `ExSplElgamalRegistryExecutor` ;
+- `ExMetadataSolanaProgramMetadataExecutor`.
+
+```rust
+use ks_lib::{ExApiTypedInstructionExecutor, ExSplMemoExecutor};
+
+let executor = ExSplMemoExecutor;
+let plan = ExApiTypedInstructionExecutor::build_prepared_plan(
+    &executor,
+    &intent,
+);
+```
+
+Le plan ne signe et n’envoie rien. La simulation, la confirmation opérateur, la soumission et la confirmation réseau appartiennent aux couches d’orchestration et de transport.
+
+```rust
+let plan = match ExApiTypedInstructionExecutor::build_prepared_plan(
+    &executor,
+    &intent,
+) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+println!("instructions={}", plan.instructions.len());
+println!("required_signers={}", plan.required_signers.len());
+```
+
+Memo v1 et v3 restent non exécutables. Memo v4 est la seule génération exécutable.
+
+
+## Exécution Solana Program Metadata
+
+`ExMetadataSolanaProgramMetadataExecutor` couvre les neuf opérations stables `Write`, `Initialize`, `SetAuthority`, `SetData`, `SetImmutable`, `Trim`, `Close`, `Allocate` et `Extend`. Les helpers publics dérivent les PDA canonical et non-canonical ; l’appelant doit toujours fournir et vérifier le compte attendu avant construction du plan.
+
+Les mutations écrasantes, destructrices ou irréversibles ne sont pas retirées de l’API. Elles exigent `allow_destructive_operation = true`, puis le plan complet est évalué par `ExSafetyChecker`. Cette approbation locale ne remplace ni la simulation RPC, ni la confirmation opérateur, ni les postconditions stateful.
+
+```rust
+let intent = ks_lib::ExMetadataSpmExecutionIntent {
+    intent_id: "extend-program-metadata".to_string(),
+    fee_payer: authority.clone(),
+    policy,
+    allow_destructive_operation: false,
+    operation: ks_lib::ExMetadataSpmOperation::Extend {
+        account: metadata_account,
+        authority,
+        length: 256,
+        program_context: std::option::Option::None,
+    },
+};
+let executor = ks_lib::ExMetadataSolanaProgramMetadataExecutor;
+let plan = match ks_lib::ExApiTypedInstructionExecutor::build_prepared_plan(
+    &executor,
+    &intent,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+```
+
+`Initialize` et `Allocate` n’inventent pas le financement préalable nécessaire à l’exemption de rent. La préparation de fixture ou l’orchestration stateful doit calculer le financement depuis le RPC, préfinancer le PDA ou le compte keypair, puis simuler le message exact avant soumission.
+
+Les contenus inline sont volontairement bornés à 1 024 octets par le workspace. Les contenus plus grands passent par un compte `Buffer` préfinancé, écrit par segments puis consommé par `Initialize` ou `SetData`.
+Pour `Initialize` et les allocations de Buffer PDA, le booléen `canonical` est fourni explicitement. La présence de `program_data` ne suffit pas à déterminer la dérivation, car les programmes issus de loaders antérieurs peuvent être canoniques sans compte ProgramData.
+
+## Exécution Metaplex Token Metadata
+
+La surface publique repose sur :
+
+- `ExMetadataMetaplexTokenMetadataExecutor` ;
+- `ExMetaplexTokenMetadataExecutionIntent` ;
+- `ExMetaplexTokenMetadataOperation` ;
+- les constantes `EX_METAPLEX_TOKEN_METADATA_*_OPERATION` ;
+- `EX_METAPLEX_TOKEN_METADATA_SUPPORTED_OPERATION_CODES` et `EX_METAPLEX_TOKEN_METADATA_DEPRECATED_OPERATION_CODES`.
+
+Les comptes `Edition` Token Metadata doivent être décodés selon leur contenu Borsh **et** leur allocation on-chain. Le SDK `mpl-token-metadata 5.1.1` expose `Edition::LEN = 41`, tandis que le programme courant peut allouer 42 octets et les comptes historiques 241 octets. Le décodeur accepte seulement ces formes connues avec padding nul ; une longueur inconnue ou un padding non nul est refusé.
+
+Le consommateur construit un intent typé, puis appelle `ExApiTypedInstructionExecutor::build_prepared_plan`. Le plan retourné contient les instructions, comptes et signers requis, mais n’effectue ni simulation ni envoi.
+
+Les opérations courantes utilisent leur wrapper canonique final. Les versions remplacées ne possèdent pas de builder public distinct. Les opérations obsolètes encore constructibles exigent que l’intent autorise explicitement l’exécution dépréciée ; leurs variantes Rust sont marquées `#[deprecated]`.
+
+Avant utilisation du plan, le consommateur doit transmettre celui-ci au préflight et à l’orchestration de `ks-pipeline`.
+
+### Prérequis des opérations Metaplex
+
+Les builders n’inventent aucun compte ni état préalable. L’appelant doit fournir des comptes cohérents avec l’opération :
+
+- `Create` NFT classique : mint SPL classique existant, owner `Tokenkeg...`, `decimals = 0`, supply initiale nulle, mint authority et freeze authority correspondant à `authority`, PDA metadata et master edition dérivés du mint, `spl_token_program` explicite et `print_supply` renseigné ;
+- `Update` : metadata existante, update authority courante et comptes programmables éventuels cohérents avec le token standard ;
+- `Verify` / `Unverify` : metadata existante et autorité correspondant exactement au créateur, à la collection ou au delegate visé par `VerificationArgs` ;
+- `Delegate` / `Revoke`, `Lock` / `Unlock`, `Transfer` : token account, token record, delegate record, edition et rule set requis par la variante exacte ;
+- `Burn`, `CloseAccounts` et opérations d’escrow : comptes de destination, token records et autorités de fermeture explicitement fournis ;
+- `Mint`, `Print`, `Migrate`, `Use`, `Collect` et `Resize` : état préalable spécifique déjà créé et compatible avec la variante demandée.
+
+Une simulation réseau échouée ne constitue pas une validation de l’opération. Les logs du programme doivent être conservés et la précondition manquante doit être corrigée avant toute soumission.
+
+## Sécurité
+
+Les types `ExSafetyChecker`, `ExSafetyDecision`, `ExSafetyEvaluation` et `ExSafetyViolation` permettent d’évaluer un plan avant son utilisation. Une décision conservatrice doit être respectée par le consommateur ; elle ne doit pas être contournée par l’application.
+
+```rust
+let evaluation = match checker.evaluate_prepared_plan(&plan) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+match evaluation.decision {
+    ks_lib::ExSafetyDecision::Allow => {
+        println!("execution plan accepted");
+    },
+    ks_lib::ExSafetyDecision::Deny => {
+        for violation in evaluation.violations {
+            eprintln!("safety violation: {violation:#?}");
+        }
+    },
+}
+```
+
+## Matérialisation
+
+`MtApiEventMaterializer` définit le contrat public de matérialisation. Les résultats `MtApiMaterializerExecutionResult` contiennent les sorties et diagnostics sans dépendre d’un backend de stockage.
+
+```rust
+let result = ks_lib::MtApiEventMaterializer::materialize(
+    &materializer,
+    &decoded_observation,
+);
+
+println!("status={:?}", result.status);
+println!("outputs={}", result.outputs.len());
+println!("diagnostics={}", result.diagnostics.len());
+```
+
+Les fonctions stateful publiques comprennent notamment :
+
+- `materializer_admin_materialize_token_2022_state_snapshots` ;
+- `materializer_admin_materialize_elgamal_registry_state_snapshot` ;
+- `materializer_token_materialize_token_2022_state_snapshot` ;
+- `materializer_metadata_materialize_token_2022_snapshot` ;
+- `materializer_metadata_materialize_metaplex_metadata_snapshot` ;
+- `materializer_metadata_materialize_metaplex_account_snapshot`.
+
+## Contrat de replay
+
+`MdCoreInstructionReplayInput` représente une instruction extraite avec son contexte transactionnel. Il constitue la frontière entre l’extraction Core, le pipeline de replay et les décodeurs.
+
+```rust
+let recognition = DcApiInstructionDecoder::recognize(&decoder, &replay_input);
+
+if recognition.compatible {
+    let decoded = DcApiInstructionDecoder::decode(&decoder, &replay_input);
+    if let Err(error) = decoded {
+        return Err(error);
+    }
+}
+```
+
+## Tests et matrices utiles
+
+Les tests unitaires du décodeur Metaplex et du décodeur Solana Core chargent directement certaines matrices de [`../test-fixtures/contract-matrices/`](../test-fixtures/contract-matrices/). Ils vérifient notamment l’égalité entre les entrées compilées et les contrats JSON, les discriminants, les bornes et les comportements historiques.
+
+Les tests des exécuteurs comparent les instructions produites aux builders officiels et vérifient signers, comptes ordonnés, coûts et politiques de sécurité.
+
+## Limites
+
+- aucune persistance ni acquisition réseau ;
+- aucun chargement dynamique des IDL en production ;
+- les squelettes réservés ne sont pas des implémentations ;
+
+## Parcours de validation Metaplex Token Metadata sur Devnet
+
+La validation de l’exécuteur ne doit pas utiliser un produit cartésien artificiel entre tous les types d’assets et toutes les opérations. Les campagnes doivent sélectionner un parcours cohérent composé d’une fixture, d’un état initial, d’opérations applicables et d’un état terminal attendu.
+
+Les familles actuelles sont le NFT classique, le pNFT, le SFT, le fungible et le parcours collection parent/membre. Une collection est une relation et un état supplémentaire, pas un token standard indépendant. Les opérations incompatibles avec une famille doivent être classées `not_applicable`; les opérations valides mais sans fixture doivent être classées `unsupported`.
+
+Pour un NFT classique créé par le runner :
+
+- le mint SPL classique possède `decimals = 0` et `supply = 0` avant `Create` ;
+- la mint authority et la freeze authority sont toutes deux le wallet du profil ;
+- `spl_token_program` est fourni explicitement ;
+- `print_supply` vaut `Zero` ;
+- un mint dont le PDA metadata est déjà créé ne peut pas être réutilisé pour un second `Create`.
+
+La matérialisation Metaplex est optionnelle. Lorsqu’elle est activée après une soumission confirmée, chaque compte déclaré dans les lectures de postcondition est relu, validé, décodé canoniquement puis projeté comme snapshot d’état. Aucun contenu URI off-chain n’est téléchargé par ce parcours.
+
+## Token-2022 Token Metadata complet
+
+Les opérations `InitializeTokenMetadata`, `UpdateTokenMetadataField`, `RemoveTokenMetadataKey`, `UpdateTokenMetadataAuthority` et `EmitTokenMetadata` sont constructibles. `EmitTokenMetadata` est en lecture seule et ne réclame pas une matérialisation post-exécution.

ks-lib/src/decoder.rs

@@ -0,0 +1,941 @@
+// file: ks-lib/src/decoder.rs
+// version: 18
+
+//! Consolidated decoder modules.
+
+mod adapter;
+mod amm;
+mod anchor;
+mod api;
+mod bridge;
+mod clmm;
+mod cpmm;
+mod dlmm;
+mod fees;
+mod governance;
+mod launchpad;
+mod lending;
+mod lock;
+mod metadata;
+mod nft;
+mod orderbook;
+mod perpetuals;
+mod router;
+mod rwa;
+mod solana;
+mod spl;
+mod stable;
+mod staking;
+mod storage;
+mod strategy;
+mod treasury;
+mod vault;
+mod vesting;
+mod wallet;
+mod weighted;
+
+/// Reserved `kb-lib.decoder.adapter.saber_decimal_wrapper` decoder.
+pub use self::adapter::DcAdapterSaberDecimalWrapperDecoder;
+/// Reserved `kb-lib.decoder.adapter.spl_token_wrap` decoder.
+pub use self::adapter::DcAdapterSplTokenWrapDecoder;
+/// Reserved `kb-lib.decoder.amm.aldrin_v1` decoder.
+pub use self::amm::DcAmmAldrinV1Decoder;
+/// Reserved `kb-lib.decoder.amm.aldrin_v2` decoder.
+pub use self::amm::DcAmmAldrinV2Decoder;
+/// Reserved `kb-lib.decoder.amm.alphaq` decoder.
+pub use self::amm::DcAmmAlphaqDecoder;
+/// Reserved `kb-lib.decoder.amm.believe` decoder.
+pub use self::amm::DcAmmBelieveDecoder;
+/// Reserved `kb-lib.decoder.amm.bonk_swap` decoder.
+pub use self::amm::DcAmmBonkSwapDecoder;
+/// Reserved `kb-lib.decoder.amm.fluxbeam` decoder.
+pub use self::amm::DcAmmFluxbeamDecoder;
+/// Reserved `kb-lib.decoder.amm.goon_fi` decoder.
+pub use self::amm::DcAmmGoonFiDecoder;
+/// Reserved `kb-lib.decoder.amm.goosefx_gamma` decoder.
+pub use self::amm::DcAmmGoosefxGammaDecoder;
+/// Reserved `kb-lib.decoder.amm.goosefx_v2` decoder.
+pub use self::amm::DcAmmGoosefxV2Decoder;
+/// Reserved `kb-lib.decoder.amm.guac_swap` decoder.
+pub use self::amm::DcAmmGuacSwapDecoder;
+/// Reserved `kb-lib.decoder.amm.lifinity_swap_v2` decoder.
+pub use self::amm::DcAmmLifinitySwapV2Decoder;
+/// Reserved `kb-lib.decoder.amm.metadao_v0_5` decoder.
+pub use self::amm::DcAmmMetadaoV05Decoder;
+/// Reserved `kb-lib.decoder.amm.meteora_damm_v1` decoder.
+pub use self::amm::DcAmmMeteoraDammV1Decoder;
+/// Reserved `kb-lib.decoder.amm.meteora_damm_v2` decoder.
+pub use self::amm::DcAmmMeteoraDammV2Decoder;
+/// Reserved `kb-lib.decoder.amm.obric_v2` decoder.
+pub use self::amm::DcAmmObricV2Decoder;
+/// Reserved `kb-lib.decoder.amm.one_dex` decoder.
+pub use self::amm::DcAmmOneDexDecoder;
+/// Reserved `kb-lib.decoder.amm.pump_swap` decoder.
+pub use self::amm::DcAmmPumpSwapDecoder;
+/// Reserved `kb-lib.decoder.amm.raydium_lp_v4` decoder.
+pub use self::amm::DcAmmRaydiumLpV4Decoder;
+/// Reserved `kb-lib.decoder.amm.solfi` decoder.
+pub use self::amm::DcAmmSolfiDecoder;
+/// Reserved `kb-lib.decoder.amm.solfi_v2` decoder.
+pub use self::amm::DcAmmSolfiV2Decoder;
+/// Reserved `kb-lib.decoder.amm.vertigo` decoder.
+pub use self::amm::DcAmmVertigoDecoder;
+/// Reserved `kb-lib.decoder.amm.woofi` decoder.
+pub use self::amm::DcAmmWoofiDecoder;
+/// Reserved `kb-lib.decoder.amm.zero_fi` decoder.
+pub use self::amm::DcAmmZeroFiDecoder;
+/// Reserved `kb-lib.decoder.amm.zora` decoder.
+pub use self::amm::DcAmmZoraDecoder;
+/// Reserved `kb-lib.decoder.anchor` decoder.
+pub use self::anchor::DcAnchorDecoder;
+/// Current contextual core instruction input contract version.
+pub use self::api::DC_API_CORE_INSTRUCTION_INPUT_CONTRACT_VERSION;
+/// Stable contextual decoded observation.
+pub use self::api::DcApiDecodedObservation;
+/// Machine-readable decoder coverage declaration.
+pub use self::api::DcApiDecoderCoverageDeclaration;
+/// Declared decoder coverage entry kind.
+pub use self::api::DcApiDecoderCoverageEntryKind;
+/// Structured decoder diagnostic.
+pub use self::api::DcApiDecoderDiagnostic;
+/// Complete decoder execution result.
+pub use self::api::DcApiDecoderExecutionResult;
+/// Stable decoder identity.
+pub use self::api::DcApiDecoderIdentity;
+/// Decoder terminal result status.
+pub use self::api::DcApiDecoderOutcomeStatus;
+/// Explicit decoding proof.
+pub use self::api::DcApiDecoderProof;
+/// Decoding proof category.
+pub use self::api::DcApiDecoderProofKind;
+/// Deterministic decoder recognition result.
+pub use self::api::DcApiDecoderRecognition;
+/// Exposes the decoder support level.
+pub use self::api::DcApiDecoderSupport;
+/// One statically declared decoder surface.
+pub use self::api::DcApiDecoderSurface;
+/// Initial decoder implementation placeholder for API-level tests.
+pub use self::api::DcApiInitialDecoder;
+/// Contextual instruction decoder contract.
+pub use self::api::DcApiInstructionDecoder;
+/// Exposes the common protocol decoder trait.
+pub use self::api::DcApiProtocolDecoder;
+/// Computes the deterministic contextual input hash.
+pub use self::api::decoder_api_contextual_input_hash;
+/// Returns true when a decoder declares the exact program id.
+pub use self::api::decoder_api_decoder_handles_program_id;
+/// Computes a deterministic lowercase SHA-256 hash for one JSON value.
+pub use self::api::decoder_api_deterministic_json_hash;
+/// Extracts the first eight payload bytes as hexadecimal when available.
+pub use self::api::decoder_api_discriminator_8_hex;
+/// Reserved `kb-lib.decoder.bridge.circle_cctp_token_messenger_minter` decoder.
+pub use self::bridge::DcBridgeCircleCctpTokenMessengerMinterDecoder;
+/// Reserved `kb-lib.decoder.bridge.circle_cctp_token_messenger_minter_v2` decoder.
+pub use self::bridge::DcBridgeCircleCctpTokenMessengerMinterV2Decoder;
+/// Reserved `kb-lib.decoder.bridge.layer_zero_endpoint` decoder.
+pub use self::bridge::DcBridgeLayerZeroEndpointDecoder;
+/// Reserved `kb-lib.decoder.bridge.layer_zero_executor` decoder.
+pub use self::bridge::DcBridgeLayerZeroExecutorDecoder;
+/// Reserved `kb-lib.decoder.clmm.byreal` decoder.
+pub use self::clmm::DcClmmByrealDecoder;
+/// Reserved `kb-lib.decoder.clmm.fusion` decoder.
+pub use self::clmm::DcClmmFusionDecoder;
+/// Reserved `kb-lib.decoder.clmm.orca_whirlpool` decoder.
+pub use self::clmm::DcClmmOrcaWhirlpoolDecoder;
+/// Reserved `kb-lib.decoder.clmm.pancake_swap` decoder.
+pub use self::clmm::DcClmmPancakeSwapDecoder;
+/// Reserved `kb-lib.decoder.clmm.raydium` decoder.
+pub use self::clmm::DcClmmRaydiumDecoder;
+/// Reserved `kb-lib.decoder.clmm.stabble` decoder.
+pub use self::clmm::DcClmmStabbleDecoder;
+/// Reserved `kb-lib.decoder.cpmm.raydium` decoder.
+pub use self::cpmm::DcCpmmRaydiumDecoder;
+/// Reserved `kb-lib.decoder.dlmm.meteora` decoder.
+pub use self::dlmm::DcDlmmMeteoraDecoder;
+/// Reserved `kb-lib.decoder.fees.bags_fee_share_v1` decoder.
+pub use self::fees::DcFeesBagsFeeShareV1Decoder;
+/// Reserved `kb-lib.decoder.fees.bags_fee_share_v2` decoder.
+pub use self::fees::DcFeesBagsFeeShareV2Decoder;
+/// Reserved `kb-lib.decoder.admin.pump_fees` decoder.
+pub use self::fees::DcFeesPumpFeesDecoder;
+/// Reserved `kb-lib.decoder.governance.metadao_bid_wall` decoder.
+pub use self::governance::DcGovernanceMetadaoBidWallDecoder;
+/// Reserved `kb-lib.decoder.amm.metadao_futarchy_amm` decoder.
+pub use self::governance::DcGovernanceMetadaoFutarchyDecoder;
+/// Reserved `kb-lib.decoder.governance.squads_multisig` decoder.
+pub use self::governance::DcGovernanceSquadsMultisigDecoder;
+/// Reserved `kb-lib.decoder.launchpad.boop_fun` decoder.
+pub use self::launchpad::DcLaunchpadBoopFunDecoder;
+/// Reserved `kb-lib.decoder.launchpad.metadao_ico` decoder.
+pub use self::launchpad::DcLaunchpadMetadaoIcoDecoder;
+/// Reserved `kb-lib.decoder.launchpad.meteora_dbc` decoder.
+pub use self::launchpad::DcLaunchpadMeteoraDbcDecoder;
+/// Reserved `kb-lib.decoder.launchpad.moonit` decoder.
+pub use self::launchpad::DcLaunchpadMoonitDecoder;
+/// Reserved `kb-lib.decoder.launchpad.orca_wavebreak` decoder.
+pub use self::launchpad::DcLaunchpadOrcaWavebreakDecoder;
+/// Reserved `kb-lib.decoder.launchpad.printr` decoder.
+pub use self::launchpad::DcLaunchpadPrintrDecoder;
+/// Reserved `kb-lib.decoder.launchpad.pump_fun` decoder.
+pub use self::launchpad::DcLaunchpadPumpFunDecoder;
+/// Reserved `kb-lib.decoder.launchpad.pump_pumpup_ai` decoder.
+pub use self::launchpad::DcLaunchpadPumpPumpupAiDecoder;
+/// Reserved `kb-lib.decoder.launchpad.raydium_launchlab` decoder.
+pub use self::launchpad::DcLaunchpadRaydiumLaunchlabDecoder;
+/// Reserved `kb-lib.decoder.amm.virtuals` decoder.
+pub use self::launchpad::DcLaunchpadVirtualsDecoder;
+/// Reserved `kb-lib.decoder.lending.clone` decoder.
+pub use self::lending::DcLendingCloneDecoder;
+/// Reserved `kb-lib.decoder.lending.jupiter_lend_borrow` decoder.
+pub use self::lending::DcLendingJupiterLendBorrowDecoder;
+/// Reserved `kb-lib.decoder.lending.jupiter_lend_earn` decoder.
+pub use self::lending::DcLendingJupiterLendEarnDecoder;
+/// Reserved `kb-lib.decoder.lending.jupiter_lend_flash_loan` decoder.
+pub use self::lending::DcLendingJupiterLendFlashLoanDecoder;
+/// Reserved `kb-lib.decoder.lending.jupiter_lend_liquidity` decoder.
+pub use self::lending::DcLendingJupiterLendLiquidityDecoder;
+/// Reserved `kb-lib.decoder.lending.kamino` decoder.
+pub use self::lending::DcLendingKaminoDecoder;
+/// Reserved `kb-lib.decoder.lending.marginfi_v2` decoder.
+pub use self::lending::DcLendingMarginfiV2Decoder;
+/// Reserved `kb-lib.decoder.lock.raydium_lp` decoder.
+pub use self::lock::DcLockRaydiumLpDecoder;
+/// Approve Collection Authority discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Approve Use Authority discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_APPROVE_USE_AUTHORITY_DISCRIMINATOR;
+/// Bubblegum Set Collection Size discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Burn discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_BURN_DISCRIMINATOR;
+/// Historical Burn Edition NFT discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_BURN_EDITION_NFT_DISCRIMINATOR;
+/// Historical Burn NFT discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_BURN_NFT_DISCRIMINATOR;
+/// Close Accounts discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CLOSE_ACCOUNTS_DISCRIMINATOR;
+/// Close Escrow Account discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Collect discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_COLLECT_DISCRIMINATOR;
+/// Convert Master Edition V1 to V2 discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR;
+/// Modern Create discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CREATE_DISCRIMINATOR;
+/// Create Escrow Account discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CREATE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Master Edition discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Create Master Edition V3 discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CREATE_MASTER_EDITION_V3_DISCRIMINATOR;
+/// Historical Create Metadata Account discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Metadata Account V2 discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Create Metadata Account V3 discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR;
+/// Delegate discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_DELEGATE_DISCRIMINATOR;
+/// Deprecated Create Master Edition discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Deprecated Create Reservation List discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR;
+/// Deprecated printing-token mint-new-edition discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens Via Token discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR;
+/// Deprecated Set Reservation List discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR;
+/// Number of bytes retained in malformed-wire diagnostics.
+pub(crate) use self::metadata::DC_METADATA_MTM_DIAGNOSTIC_PREFIX_BYTES;
+/// Stable event payload contract version.
+pub(crate) use self::metadata::DC_METADATA_MTM_EVENT_VERSION;
+/// Freeze Delegated Account discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Current pre-release instruction inventory.
+pub(crate) use self::metadata::DC_METADATA_MTM_INSTRUCTION_ENTRIES;
+/// Lock discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_LOCK_DISCRIMINATOR;
+/// Maximum encoded base64 instruction payload size.
+pub(crate) use self::metadata::DC_METADATA_MTM_MAX_BASE64_BYTES;
+/// Maximum number of instruction accounts accepted by this decoder.
+pub(crate) use self::metadata::DC_METADATA_MTM_MAX_INSTRUCTION_ACCOUNTS;
+/// Maximum retained instruction payload size.
+pub(crate) use self::metadata::DC_METADATA_MTM_MAX_INSTRUCTION_BYTES;
+/// Exhaustive published Metaplex account-key inventory.
+pub use self::metadata::DC_METADATA_MTM_METADATA_ACCOUNT_LAYOUT_AUDIT;
+/// Migrate discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_MIGRATE_DISCRIMINATOR;
+/// Modern Mint discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_MINT_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Token discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Vault Proxy discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR;
+/// Modern Print discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_PRINT_DISCRIMINATOR;
+/// Puff Metadata discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_PUFF_METADATA_DISCRIMINATOR;
+/// Remove Creator Verification discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR;
+/// Resize discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_RESIZE_DISCRIMINATOR;
+/// Revoke Collection Authority discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Revoke discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_REVOKE_DISCRIMINATOR;
+/// Revoke Use Authority discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_REVOKE_USE_AUTHORITY_DISCRIMINATOR;
+/// Set And Verify Collection discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_SET_AND_VERIFY_COLLECTION_DISCRIMINATOR;
+/// Set And Verify Sized Collection Item discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Set Collection Size discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Set Token Standard discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_SET_TOKEN_STANDARD_DISCRIMINATOR;
+/// Sign Metadata discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_SIGN_METADATA_DISCRIMINATOR;
+/// Stable decoder surface code.
+pub(crate) use self::metadata::DC_METADATA_MTM_SURFACE_CODE;
+/// Thaw Delegated Account discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_THAW_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Transfer discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_TRANSFER_DISCRIMINATOR;
+/// Transfer Out Of Escrow discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR;
+/// Unlock discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_UNLOCK_DISCRIMINATOR;
+/// Unverify Collection discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_UNVERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Unverify discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_UNVERIFY_DISCRIMINATOR;
+/// Unverify Sized Collection Item discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Modern Update discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_UPDATE_DISCRIMINATOR;
+/// Historical Update Metadata Account discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Update Metadata Account V2 discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Update Primary Sale Happened Via Token discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR;
+/// Modern Use discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_USE_DISCRIMINATOR;
+/// Utilize discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_UTILIZE_DISCRIMINATOR;
+/// Verify Collection discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_VERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Verify discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_VERIFY_DISCRIMINATOR;
+/// Verify Sized Collection Item discriminator.
+pub(crate) use self::metadata::DC_METADATA_MTM_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Account contract for `Allocate`.
+pub(crate) use self::metadata::DC_METADATA_SPM_ALLOCATE_ACCOUNT_CONTRACTS;
+/// Exact fixed byte length of one Buffer account header.
+pub use self::metadata::DC_METADATA_SPM_BUFFER_HEADER_BYTES;
+/// Account contract for `Close`.
+pub(crate) use self::metadata::DC_METADATA_SPM_CLOSE_ACCOUNT_CONTRACTS;
+/// Surfaces handled by the Solana Program Metadata decoder.
+pub(crate) use self::metadata::DC_METADATA_SPM_DECODER_SURFACES;
+/// Maximum instruction prefix retained in hexadecimal diagnostics.
+pub(crate) use self::metadata::DC_METADATA_SPM_DIAGNOSTIC_PREFIX_BYTES;
+/// Stable event schema version for decoded Solana Program Metadata instructions.
+pub(crate) use self::metadata::DC_METADATA_SPM_EVENT_VERSION;
+/// Account contract for `Extend`.
+pub(crate) use self::metadata::DC_METADATA_SPM_EXTEND_ACCOUNT_CONTRACTS;
+/// Exact byte length of one external-account data reference.
+pub use self::metadata::DC_METADATA_SPM_EXTERNAL_DATA_BYTES;
+/// Account contract for `Initialize`.
+pub(crate) use self::metadata::DC_METADATA_SPM_INITIALIZE_ACCOUNT_CONTRACTS;
+/// Current stable instruction inventory for program releases 1.0.0 and 1.0.1.
+pub(crate) use self::metadata::DC_METADATA_SPM_INSTRUCTION_ENTRIES;
+/// Maximum Solana account-data length accepted by bounded account decoders.
+pub use self::metadata::DC_METADATA_SPM_MAX_ACCOUNT_BYTES;
+/// Maximum instruction-account count accepted by the contextual decoder.
+pub(crate) use self::metadata::DC_METADATA_SPM_MAX_INSTRUCTION_ACCOUNTS;
+/// Maximum retained instruction payload accepted by the contextual decoder.
+pub(crate) use self::metadata::DC_METADATA_SPM_MAX_INSTRUCTION_BYTES;
+/// Exact fixed byte length of one Metadata account header.
+pub use self::metadata::DC_METADATA_SPM_METADATA_HEADER_BYTES;
+/// Program ids handled by the Solana Program Metadata decoder.
+pub(crate) use self::metadata::DC_METADATA_SPM_PROGRAM_IDS;
+/// Exact byte length of one Solana Program Metadata seed.
+pub use self::metadata::DC_METADATA_SPM_SEED_BYTES;
+/// Account contract for `SetAuthority`.
+pub(crate) use self::metadata::DC_METADATA_SPM_SET_AUTHORITY_ACCOUNT_CONTRACTS;
+/// Account contract for `SetData`.
+pub(crate) use self::metadata::DC_METADATA_SPM_SET_DATA_ACCOUNT_CONTRACTS;
+/// Account contract for `SetImmutable`.
+pub(crate) use self::metadata::DC_METADATA_SPM_SET_IMMUTABLE_ACCOUNT_CONTRACTS;
+/// Stable Solana Program Metadata decoder surface code.
+pub(crate) use self::metadata::DC_METADATA_SPM_SURFACE_CODE;
+/// Account contract for `Trim`.
+pub(crate) use self::metadata::DC_METADATA_SPM_TRIM_ACCOUNT_CONTRACTS;
+/// Account contract for `Write`.
+pub(crate) use self::metadata::DC_METADATA_SPM_WRITE_ACCOUNT_CONTRACTS;
+/// Exact decoder for the Metaplex Token Metadata program.
+pub use self::metadata::DcMetadataMetaplexTokenMetadataDecoder;
+/// Canonical projection shared by Collection and Use Authority records.
+pub use self::metadata::DcMetadataMtmAuthorityRecordAccountSnapshot;
+/// Stable identity and policy of one canonical account snapshot.
+pub use self::metadata::DcMetadataMtmCanonicalAccountIdentity;
+/// Lifecycle class of one canonical account layout.
+pub use self::metadata::DcMetadataMtmCanonicalAccountLifecycle;
+/// Provenance retained for one canonical account observation.
+pub use self::metadata::DcMetadataMtmCanonicalAccountProvenance;
+/// Execution policy separated from historical materialization.
+pub use self::metadata::DcMetadataMtmCanonicalExecutionPolicy;
+/// Materialization policy for active or historical state.
+pub use self::metadata::DcMetadataMtmCanonicalMaterializationPolicy;
+/// Canonical account envelope used by materializers and replay.
+pub use self::metadata::DcMetadataMtmCanonicalMetadataAccountSnapshot;
+/// Typed canonical Metaplex account state.
+pub use self::metadata::DcMetadataMtmCanonicalMetadataAccountState;
+/// Origin of one canonical account observation.
+pub use self::metadata::DcMetadataMtmCanonicalObservationSource;
+/// Canonical projection shared by Metadata and Holder delegate records.
+pub use self::metadata::DcMetadataMtmDelegateRecordAccountSnapshot;
+/// Supported edition account layout.
+pub use self::metadata::DcMetadataMtmEditionAccountKind;
+/// Canonical bounded projection of one edition or master-edition account.
+pub use self::metadata::DcMetadataMtmEditionAccountSnapshot;
+/// Supported Edition Marker account layout.
+pub use self::metadata::DcMetadataMtmEditionMarkerAccountKind;
+/// Canonical bounded projection of one Edition Marker account.
+pub use self::metadata::DcMetadataMtmEditionMarkerAccountSnapshot;
+/// Bounded error returned while decoding a Metadata account.
+pub use self::metadata::DcMetadataMtmMetadataAccountDecodeError;
+/// One entry in the exhaustive published account-key audit.
+pub use self::metadata::DcMetadataMtmMetadataAccountLayoutAuditEntry;
+/// Canonical bounded projection of one Metadata account.
+pub use self::metadata::DcMetadataMtmMetadataAccountSnapshot;
+/// One bounded historical reservation entry.
+pub use self::metadata::DcMetadataMtmReservationEntrySnapshot;
+/// Historical Reservation List account generation.
+pub use self::metadata::DcMetadataMtmReservationListAccountKind;
+/// Canonical decode-only projection of a historical Reservation List account.
+pub use self::metadata::DcMetadataMtmReservationListAccountSnapshot;
+/// Canonical projection of one Token Owned Escrow account.
+pub use self::metadata::DcMetadataMtmTokenOwnedEscrowAccountSnapshot;
+/// Authority form used by one Token Owned Escrow account.
+pub use self::metadata::DcMetadataMtmTokenOwnedEscrowAuthorityKind;
+/// Canonical bounded projection of one programmable Token Record account.
+pub use self::metadata::DcMetadataMtmTokenRecordAccountSnapshot;
+/// Solana Program Metadata instruction decoder; account decoders are active.
+pub use self::metadata::DcMetadataSolanaProgramMetadataDecoder;
+/// Reserved `kb-lib.decoder.metadata.spl_name_service` decoder.
+pub use self::metadata::DcMetadataSplNameServiceDecoder;
+/// Error returned while decoding a Solana Program Metadata account.
+pub use self::metadata::DcMetadataSpmAccountDecodeError;
+/// Solana Program Metadata account discriminator.
+pub use self::metadata::DcMetadataSpmAccountDiscriminator;
+/// Supported bounded Solana Program Metadata account projection.
+pub use self::metadata::DcMetadataSpmAccountSnapshot;
+/// Bounded projection of one Solana Program Metadata Buffer account.
+pub use self::metadata::DcMetadataSpmBufferAccountSnapshot;
+/// Compression declared for Solana Program Metadata content.
+pub use self::metadata::DcMetadataSpmCompression;
+/// Typed Solana Program Metadata content without off-chain resolution.
+pub use self::metadata::DcMetadataSpmData;
+/// On-chain source used for Solana Program Metadata content.
+pub use self::metadata::DcMetadataSpmDataSource;
+/// Encoding declared for Solana Program Metadata content.
+pub use self::metadata::DcMetadataSpmEncoding;
+/// Fixed external-account data reference.
+pub use self::metadata::DcMetadataSpmExternalData;
+/// Format declared for Solana Program Metadata content.
+pub use self::metadata::DcMetadataSpmFormat;
+/// Expected account role and privileges for one instruction position.
+pub(crate) use self::metadata::DcMetadataSpmInstructionAccountContract;
+/// Bounded projection of one initialized Solana Program Metadata account.
+pub use self::metadata::DcMetadataSpmMetadataAccountSnapshot;
+/// Bounded Solana Program Metadata model conversion error.
+pub use self::metadata::DcMetadataSpmModelError;
+/// Official Solana Program Metadata custom error.
+pub use self::metadata::DcMetadataSpmProgramError;
+/// Exact fixed-size Solana Program Metadata seed.
+pub use self::metadata::DcMetadataSpmSeed;
+/// Canonical tracing target for this crate.
+pub(crate) use self::metadata::TRACING_TARGET_DECODER_METADATA_METAPLEX_TOKEN_METADATA;
+/// Canonical tracing target for the Solana Program Metadata decoder.
+pub(crate) use self::metadata::TRACING_TARGET_DECODER_METADATA_SOLANA_PROGRAM_METADATA;
+/// Crate-root access to `decode` from `instruction`.
+pub(crate) use self::metadata::decoder_metadata_metaplex_token_metadata_decode;
+/// Decodes one Collection Authority Record account.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_collection_authority_record_account;
+/// Decodes and validates one edition or master-edition account snapshot.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_edition_account;
+/// Decodes and validates one Edition Marker account snapshot.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_edition_marker_account;
+/// Decodes one Holder Delegate Record account.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_holder_delegate_record_account;
+/// Decodes and validates one canonical Metadata account snapshot.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_metadata_account;
+/// Decodes one Metadata Delegate Record account.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_metadata_delegate_record_account;
+/// Decodes one historical Reservation List V1 or V2 account.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_reservation_list_account;
+/// Decodes one Token Owned Escrow account.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_token_owned_escrow_account;
+/// Decodes and validates one programmable Token Record account snapshot.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_token_record_account;
+/// Decodes one Use Authority Record account.
+pub use self::metadata::decoder_metadata_metaplex_token_metadata_decode_use_authority_record_account;
+/// Crate-root access to `entry_for_discriminator` from `instruction`.
+pub(crate) use self::metadata::decoder_metadata_metaplex_token_metadata_entry_for_discriminator;
+/// Crate-root access to `payload_discriminator` from `instruction`.
+pub(crate) use self::metadata::decoder_metadata_metaplex_token_metadata_payload_discriminator;
+/// Decodes one bounded Solana Program Metadata instruction.
+pub(crate) use self::metadata::decoder_metadata_solana_program_metadata_decode;
+/// Decodes one supported Solana Program Metadata account by its discriminator.
+pub use self::metadata::decoder_metadata_solana_program_metadata_decode_account;
+/// Decodes one Solana Program Metadata Buffer account.
+pub use self::metadata::decoder_metadata_solana_program_metadata_decode_buffer_account;
+/// Decodes one initialized Solana Program Metadata account.
+pub use self::metadata::decoder_metadata_solana_program_metadata_decode_metadata_account;
+/// Returns the stable entry matching one Solana Program Metadata discriminator.
+pub(crate) use self::metadata::decoder_metadata_solana_program_metadata_entry_for_discriminator;
+/// Returns the first byte of one retained Solana Program Metadata payload.
+pub(crate) use self::metadata::decoder_metadata_solana_program_metadata_payload_discriminator;
+/// Reserved `kb-lib.decoder.nft.metaplex_bubblegum` decoder.
+pub use self::nft::DcNftMetaplexBubblegumDecoder;
+/// Reserved `kb-lib.decoder.nft.tensor_cnft` decoder.
+pub use self::nft::DcNftTensorCnftDecoder;
+/// Reserved `kb-lib.decoder.orderbook.jupiter_limit_order` decoder.
+pub use self::orderbook::DcOrderbookJupiterLimitOrderDecoder;
+/// Reserved `kb-lib.decoder.orderbook.jupiter_limit_order_v2` decoder.
+pub use self::orderbook::DcOrderbookJupiterLimitOrderV2Decoder;
+/// Reserved `kb-lib.decoder.orderbook.openbook_v2` decoder.
+pub use self::orderbook::DcOrderbookOpenbookV2Decoder;
+/// Reserved `kb-lib.decoder.perpetuals.drift_v2` decoder.
+pub use self::perpetuals::DcPerpetualsDriftV2Decoder;
+/// Reserved `kb-lib.decoder.perpetuals.jupiter` decoder.
+pub use self::perpetuals::DcPerpetualsJupiterDecoder;
+/// Reserved `kb-lib.decoder.perpetuals.phoenix_eternal` decoder.
+pub use self::perpetuals::DcPerpetualsPhoenixEternalDecoder;
+/// Reserved `kb-lib.decoder.perpetuals.zeta` decoder.
+pub use self::perpetuals::DcPerpetualsZetaDecoder;
+/// Reserved `kb-lib.decoder.router.dflow_aggregator_v4` decoder.
+pub use self::router::DcRouterDflowAggregatorV4Decoder;
+/// Reserved `kb-lib.decoder.router.jupiter_aggregator_v4` decoder.
+pub use self::router::DcRouterJupiterAggregatorV4Decoder;
+/// Reserved `kb-lib.decoder.router.jupiter_aggregator_v6` decoder.
+pub use self::router::DcRouterJupiterAggregatorV6Decoder;
+/// Reserved `kb-lib.decoder.router.okx_labs_v1` decoder.
+pub use self::router::DcRouterOkxLabsV1Decoder;
+/// Reserved `kb-lib.decoder.router.okx_labs_v2` decoder.
+pub use self::router::DcRouterOkxLabsV2Decoder;
+/// Reserved `kb-lib.decoder.rwa.ondo_global_markets` decoder.
+pub use self::rwa::DcRwaOndoGlobalMarketsDecoder;
+pub(crate) use self::solana::DC_SOLANA_CORE_ADDRESS_LOOKUP_TABLE_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_BPF_LOADER_DEPRECATED_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_BPF_LOADER_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_BPF_LOADER_UPGRADEABLE_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_COMPUTE_BUDGET_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_CONFIG_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_ED25519_PUBLIC_KEY_BYTES;
+pub(crate) use self::solana::DC_SOLANA_CORE_ED25519_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_FEATURE_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_LOADER_V4_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_MAX_NATIVE_INSTRUCTION_PAYLOAD_BYTES;
+pub(crate) use self::solana::DC_SOLANA_CORE_NATIVE_EVENT_VERSION;
+pub(crate) use self::solana::DC_SOLANA_CORE_NATIVE_LOADER_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_PRECOMPILE_COMPONENT_PREFIX_BYTES;
+pub(crate) use self::solana::DC_SOLANA_CORE_PROTOCOL_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_SECP256K1_ETHEREUM_ADDRESS_BYTES;
+pub(crate) use self::solana::DC_SOLANA_CORE_SECP256K1_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_SECP256R1_MAX_SIGNATURES;
+pub(crate) use self::solana::DC_SOLANA_CORE_SECP256R1_PUBLIC_KEY_BYTES;
+pub(crate) use self::solana::DC_SOLANA_CORE_SECP256R1_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_SIGNATURE_BYTES;
+pub(crate) use self::solana::DC_SOLANA_CORE_SLASHING_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_STAKE_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_SYSTEM_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_U8_OFFSETS_BYTES;
+pub(crate) use self::solana::DC_SOLANA_CORE_U16_OFFSETS_BYTES;
+pub(crate) use self::solana::DC_SOLANA_CORE_VOTE_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_ZK_ELGAMAL_PROOF_SURFACE_CODE;
+pub(crate) use self::solana::DC_SOLANA_CORE_ZK_TOKEN_PROOF_SURFACE_CODE;
+pub(crate) use self::solana::DcSolanaCoreAccountRole;
+/// Runtime-native Solana decoder with phased maximal native coverage.
+pub use self::solana::DcSolanaCoreDecoder;
+pub(crate) use self::solana::DcSolanaCoreResolvedInstructionPayload;
+pub(crate) use self::solana::TRACING_TARGET_DECODER_SOLANA_CORE;
+pub(crate) use self::solana::decoder_solana_core_address_lookup_table_coverage;
+pub(crate) use self::solana::decoder_solana_core_address_lookup_table_decode;
+pub(crate) use self::solana::decoder_solana_core_address_lookup_table_recognize;
+pub(crate) use self::solana::decoder_solana_core_bounded_hexadecimal_prefix;
+pub(crate) use self::solana::decoder_solana_core_bounded_slice;
+pub(crate) use self::solana::decoder_solana_core_compute_budget_coverage;
+pub(crate) use self::solana::decoder_solana_core_compute_budget_decode;
+pub(crate) use self::solana::decoder_solana_core_compute_budget_recognize;
+pub(crate) use self::solana::decoder_solana_core_config_coverage;
+pub(crate) use self::solana::decoder_solana_core_config_decode;
+pub(crate) use self::solana::decoder_solana_core_config_recognize;
+pub(crate) use self::solana::decoder_solana_core_decode_instruction_data;
+pub(crate) use self::solana::decoder_solana_core_decoded_payload_length;
+pub(crate) use self::solana::decoder_solana_core_decoded_payload_sha256;
+pub(crate) use self::solana::decoder_solana_core_decoded_result;
+pub(crate) use self::solana::decoder_solana_core_failed_result;
+pub(crate) use self::solana::decoder_solana_core_feature_coverage;
+pub(crate) use self::solana::decoder_solana_core_feature_decode;
+pub(crate) use self::solana::decoder_solana_core_feature_recognize;
+pub(crate) use self::solana::decoder_solana_core_hash_bytes;
+pub(crate) use self::solana::decoder_solana_core_hexadecimal_prefix;
+pub(crate) use self::solana::decoder_solana_core_loaders_coverage;
+pub(crate) use self::solana::decoder_solana_core_loaders_decode;
+pub(crate) use self::solana::decoder_solana_core_loaders_recognize;
+pub(crate) use self::solana::decoder_solana_core_payload_hash;
+pub(crate) use self::solana::decoder_solana_core_precompiles_coverage;
+pub(crate) use self::solana::decoder_solana_core_precompiles_decode;
+pub(crate) use self::solana::decoder_solana_core_precompiles_recognize;
+pub(crate) use self::solana::decoder_solana_core_read_u32_le;
+pub(crate) use self::solana::decoder_solana_core_read_u64_le;
+pub(crate) use self::solana::decoder_solana_core_resolve_accounts;
+pub(crate) use self::solana::decoder_solana_core_resolve_u8_instruction_payload;
+pub(crate) use self::solana::decoder_solana_core_resolve_u16_instruction_payload;
+pub(crate) use self::solana::decoder_solana_core_slashing_coverage;
+pub(crate) use self::solana::decoder_solana_core_slashing_decode;
+pub(crate) use self::solana::decoder_solana_core_slashing_recognize;
+pub(crate) use self::solana::decoder_solana_core_stake_coverage;
+pub(crate) use self::solana::decoder_solana_core_stake_decode;
+pub(crate) use self::solana::decoder_solana_core_stake_recognize;
+pub(crate) use self::solana::decoder_solana_core_system_coverage;
+pub(crate) use self::solana::decoder_solana_core_system_decode;
+pub(crate) use self::solana::decoder_solana_core_system_recognize;
+pub(crate) use self::solana::decoder_solana_core_target_outer_instruction_index;
+pub(crate) use self::solana::decoder_solana_core_unsupported_result;
+pub(crate) use self::solana::decoder_solana_core_vote_coverage;
+pub(crate) use self::solana::decoder_solana_core_vote_decode;
+pub(crate) use self::solana::decoder_solana_core_vote_recognize;
+pub(crate) use self::solana::decoder_solana_core_zk_elgamal_coverage;
+pub(crate) use self::solana::decoder_solana_core_zk_elgamal_decode;
+pub(crate) use self::solana::decoder_solana_core_zk_elgamal_recognize;
+pub(crate) use self::solana::decoder_solana_core_zk_token_proof_coverage;
+pub(crate) use self::solana::decoder_solana_core_zk_token_proof_decode;
+pub(crate) use self::solana::decoder_solana_core_zk_token_proof_recognize;
+/// Current stable Associated Token Account decoded event contract version.
+pub(crate) use self::spl::DC_SPL_ATA_EVENT_VERSION;
+/// Exact Associated Token Account instructions published by the official interface.
+pub(crate) use self::spl::DC_SPL_ATA_INSTRUCTION_ENTRIES;
+/// Maximum retained account-key text length for the Associated Token Account decoder.
+pub(crate) use self::spl::DC_SPL_ATA_MAX_ACCOUNT_KEY_BYTES;
+/// Maximum retained instruction account count for the Associated Token Account decoder.
+pub(crate) use self::spl::DC_SPL_ATA_MAX_ACCOUNTS;
+/// Maximum retained semantic diagnostic count for the Associated Token Account decoder.
+pub(crate) use self::spl::DC_SPL_ATA_MAX_DIAGNOSTICS;
+/// Maximum retained Associated Token Account instruction payload size.
+pub(crate) use self::spl::DC_SPL_ATA_MAX_INSTRUCTION_BYTES;
+/// Maximum retained transaction account-key count for the Associated Token Account decoder.
+pub(crate) use self::spl::DC_SPL_ATA_MAX_TRANSACTION_KEYS;
+/// Stable protocol and surface code for the Associated Token Account program.
+pub(crate) use self::spl::DC_SPL_ATA_SURFACE_CODE;
+/// Exact byte length of one SPL ElGamal registry account.
+pub use self::spl::DC_SPL_ELGAMAL_REGISTRY_ACCOUNT_LEN;
+/// Current stable SPL ElGamal registry event contract version.
+pub(crate) use self::spl::DC_SPL_ELGAMAL_REGISTRY_EVENT_VERSION;
+/// Maximum retained SPL ElGamal registry instruction payload size.
+pub(crate) use self::spl::DC_SPL_ELGAMAL_REGISTRY_MAX_INSTRUCTION_BYTES;
+/// Stable SPL ElGamal registry surface code.
+pub(crate) use self::spl::DC_SPL_ELGAMAL_REGISTRY_SURFACE_CODE;
+/// Maximum payload prefix retained for bounded diagnostics.
+pub(crate) use self::spl::DC_SPL_MEMO_DIAGNOSTIC_PREFIX_BYTES;
+/// Current stable Memo decoded event contract version.
+pub(crate) use self::spl::DC_SPL_MEMO_EVENT_VERSION;
+/// Maximum decoded instruction data retained as a complete Memo payload.
+pub(crate) use self::spl::DC_SPL_MEMO_MAX_PAYLOAD_BYTES;
+/// Stable protocol code shared by Memo generations.
+pub(crate) use self::spl::DC_SPL_MEMO_PROTOCOL_CODE;
+/// Stable Memo v1 surface code.
+pub(crate) use self::spl::DC_SPL_MEMO_V1_SURFACE_CODE;
+/// Stable Memo v3 surface code.
+pub(crate) use self::spl::DC_SPL_MEMO_V3_SURFACE_CODE;
+/// Stable Memo v4 surface code.
+pub(crate) use self::spl::DC_SPL_MEMO_V4_SURFACE_CODE;
+/// Maximum prefix retained in bounded Token-2022 diagnostics.
+pub(crate) use self::spl::DC_SPL_TOKEN_2022_DIAGNOSTIC_PREFIX_BYTES;
+/// Current stable Token-2022 decoded event contract version.
+pub(crate) use self::spl::DC_SPL_TOKEN_2022_EVENT_VERSION;
+/// Exact top-level instruction inventory published by the resolved Token-2022 interface.
+pub(crate) use self::spl::DC_SPL_TOKEN_2022_INSTRUCTION_ENTRIES;
+/// Maximum total account metas consumed by one Token-2022 batch.
+pub(crate) use self::spl::DC_SPL_TOKEN_2022_MAX_BATCH_ACCOUNTS;
+/// Maximum decoded sub-instructions in one Token-2022 batch.
+pub(crate) use self::spl::DC_SPL_TOKEN_2022_MAX_BATCH_INSTRUCTIONS;
+/// Maximum retained Token-2022 instruction payload size.
+pub(crate) use self::spl::DC_SPL_TOKEN_2022_MAX_INSTRUCTION_BYTES;
+/// Maximum retained UTF-8 string size for embedded Token Metadata instructions.
+pub(crate) use self::spl::DC_SPL_TOKEN_2022_MAX_METADATA_STRING_BYTES;
+/// Stable Token-2022 surface code.
+pub(crate) use self::spl::DC_SPL_TOKEN_2022_SURFACE_CODE;
+/// Maximum prefix retained in bounded classic SPL Token diagnostics.
+pub(crate) use self::spl::DC_SPL_TOKEN_DIAGNOSTIC_PREFIX_BYTES;
+/// Current stable classic SPL Token decoded event contract version.
+pub(crate) use self::spl::DC_SPL_TOKEN_EVENT_VERSION;
+/// One exact classic SPL Token instruction entry published by the official interface.
+pub(crate) use self::spl::DC_SPL_TOKEN_INSTRUCTION_ENTRIES;
+/// Maximum total account metas consumed by one classic SPL Token batch.
+pub(crate) use self::spl::DC_SPL_TOKEN_MAX_BATCH_ACCOUNTS;
+/// Maximum decoded sub-instructions in one classic SPL Token batch.
+pub(crate) use self::spl::DC_SPL_TOKEN_MAX_BATCH_INSTRUCTIONS;
+/// Maximum retained classic SPL Token instruction payload size.
+pub(crate) use self::spl::DC_SPL_TOKEN_MAX_INSTRUCTION_BYTES;
+/// Stable protocol and surface code for the classic SPL Token program.
+pub(crate) use self::spl::DC_SPL_TOKEN_SURFACE_CODE;
+/// Reserved `kb-lib.decoder.spl.account_compression` decoder.
+pub use self::spl::DcSplAccountCompressionDecoder;
+/// Exact decoder for the SPL Associated Token Account program.
+pub use self::spl::DcSplAssociatedTokenAccountDecoder;
+/// One parsed SPL ElGamal registry instruction.
+pub(crate) use self::spl::DcSplElGamalRegistryParsedRegistryInstruction;
+/// Parsed SPL ElGamal public-key registry account.
+pub use self::spl::DcSplElGamalRegistryState;
+/// Exact decoder for the SPL ElGamal registry program.
+pub use self::spl::DcSplElgamalRegistryDecoder;
+/// Exact decoder for the three registered SPL Memo generations.
+pub use self::spl::DcSplMemoDecoder;
+/// Reserved `kb-lib.decoder.spl.noop` decoder.
+pub use self::spl::DcSplNoopDecoder;
+/// Reserved `kb-lib.decoder.spl.single_pool` decoder.
+pub use self::spl::DcSplSinglePoolDecoder;
+/// Reserved `kb-lib.decoder.spl.stake_pool` decoder.
+pub use self::spl::DcSplStakePoolDecoder;
+/// Exact decoder for the Token-2022 program.
+pub use self::spl::DcSplToken2022Decoder;
+/// Exact decoder for the classic SPL Token program.
+pub use self::spl::DcSplTokenDecoder;
+/// Parsed Token-2022 Mint, Account, or Multisig state.
+pub use self::spl::DcToken2022State;
+/// Exact Token-2022 base account state kind.
+pub use self::spl::DcToken2022StateKind;
+/// One exact Token-2022 TLV entry.
+pub use self::spl::DcToken2022TlvEntry;
+/// Canonical tracing target for the Associated Token Account decoder.
+pub(crate) use self::spl::TRACING_TARGET_DECODER_SPL_ATA;
+/// Canonical tracing target for the SPL ElGamal registry decoder.
+pub(crate) use self::spl::TRACING_TARGET_DECODER_SPL_ELGAMAL_REGISTRY;
+/// Canonical tracing target for the SPL Memo decoder.
+pub(crate) use self::spl::TRACING_TARGET_DECODER_SPL_MEMO;
+/// Canonical tracing target for the classic SPL Token decoder.
+pub(crate) use self::spl::TRACING_TARGET_DECODER_SPL_TOKEN;
+/// Canonical tracing target for the Token-2022 decoder.
+pub(crate) use self::spl::TRACING_TARGET_DECODER_SPL_TOKEN_2022;
+/// Decodes one bounded Associated Token Account instruction.
+pub(crate) use self::spl::decoder_spl_associated_token_account_decode;
+/// Returns the exact entry matching an Associated Token Account wire.
+pub(crate) use self::spl::decoder_spl_associated_token_account_entry;
+/// Reads one bounded Associated Token Account payload.
+pub(crate) use self::spl::decoder_spl_associated_token_account_payload;
+/// Decodes one bounded SPL ElGamal registry instruction.
+pub(crate) use self::spl::decoder_spl_elgamal_registry_decode;
+/// Decodes one bounded SPL ElGamal registry instruction payload.
+pub(crate) use self::spl::decoder_spl_elgamal_registry_decode_payload;
+/// Parses one exact SPL ElGamal registry instruction.
+pub(crate) use self::spl::decoder_spl_elgamal_registry_parse;
+/// Parses one exact SPL ElGamal registry account.
+pub use self::spl::decoder_spl_elgamal_registry_parse_elgamal_registry_state;
+/// Decodes one bounded SPL Memo instruction.
+pub(crate) use self::spl::decoder_spl_memo_decode;
+/// Decodes one bounded Token-2022 instruction.
+pub(crate) use self::spl::decoder_spl_token_2022_decode;
+/// Returns the exact entry matching one Token-2022 tag.
+pub(crate) use self::spl::decoder_spl_token_2022_entry_for_tag;
+/// Parses one Token-2022 Mint, Account, or Multisig state.
+pub use self::spl::decoder_spl_token_2022_parse_token_2022_state;
+/// Parses one exact Token Metadata interface value.
+pub use self::spl::decoder_spl_token_2022_parse_token_metadata_value;
+/// Returns the first byte of one retained Token-2022 payload.
+pub(crate) use self::spl::decoder_spl_token_2022_payload_tag;
+/// Decodes one bounded classic SPL Token instruction.
+pub(crate) use self::spl::decoder_spl_token_decode;
+/// Returns the published entry matching one classic SPL Token tag.
+pub(crate) use self::spl::decoder_spl_token_entry_for_tag;
+/// Returns the first byte of one retained classic SPL Token payload.
+pub(crate) use self::spl::decoder_spl_token_payload_tag;
+/// Reserved `kb-lib.decoder.stable.swap_hylo_exchange` decoder.
+pub use self::stable::DcStableSwapHyloExchangeDecoder;
+/// Reserved `kb-lib.decoder.stable.swap_jupiter_stable` decoder.
+pub use self::stable::DcStableSwapJupiterStableDecoder;
+/// Reserved `kb-lib.decoder.stable.swap_numeraire` decoder.
+pub use self::stable::DcStableSwapNumeraireDecoder;
+/// Reserved `kb-lib.decoder.stable.swap_stabble` decoder.
+pub use self::stable::DcStableSwapStabbleDecoder;
+/// Reserved `kb-lib.decoder.staking.jito_tip_distribution` decoder.
+pub use self::staking::DcStakingJitoTipDistributionDecoder;
+/// Reserved `kb-lib.decoder.staking.kamino_farm` decoder.
+pub use self::staking::DcStakingKaminoFarmDecoder;
+/// Reserved `kb-lib.decoder.staking.marinade_finance` decoder.
+pub use self::staking::DcStakingMarinadeFinanceDecoder;
+/// Reserved `kb-lib.decoder.staking.solayer` decoder.
+pub use self::staking::DcStakingSolayerDecoder;
+/// Reserved `kb-lib.decoder.storage.solana_record` decoder.
+pub use self::storage::DcStorageSolanaRecordDecoder;
+/// Reserved `kb-lib.decoder.router.jupiter_dca` decoder.
+pub use self::strategy::DcStrategyJupiterDcaDecoder;
+/// Reserved `kb-lib.decoder.treasury.helium_treasury_management` decoder.
+pub use self::treasury::DcTreasuryHeliumTreasuryManagementDecoder;
+/// Reserved `kb-lib.decoder.vault.carrot_defi` decoder.
+pub use self::vault::DcVaultCarrotDefiDecoder;
+/// Reserved `kb-lib.decoder.vault.hylo_stability_pool` decoder.
+pub use self::vault::DcVaultHyloStabilityPoolDecoder;
+/// Reserved `kb-lib.decoder.vault.kamino` decoder.
+pub use self::vault::DcVaultKaminoDecoder;
+/// Reserved `kb-lib.decoder.vault.kamino_v2` decoder.
+pub use self::vault::DcVaultKaminoV2Decoder;
+/// Reserved `kb-lib.decoder.vault.kamino_yvaults` decoder.
+pub use self::vault::DcVaultKaminoYvaultsDecoder;
+/// Reserved `kb-lib.decoder.vault.meteora` decoder.
+pub use self::vault::DcVaultMeteoraDecoder;
+/// Reserved `kb-lib.decoder.admin.jupiter_lock` decoder.
+pub use self::vesting::DcVestingJupiterLockDecoder;
+/// Reserved `kb-lib.decoder.vesting.streamflow` decoder.
+pub use self::vesting::DcVestingStreamflowDecoder;
+/// Reserved `kb-lib.decoder.wallet.jupiter_apepro_smart_wallet` decoder.
+pub use self::wallet::DcWalletJupiterApeproSmartWalletDecoder;
+/// Reserved `kb-lib.decoder.weighted.swap_stabble` decoder.
+pub use self::weighted::DcWeightedSwapStabbleDecoder;
+#[cfg(test)]
+mod reserved_decoder_tests {
+    #[test]
+    fn every_reserved_decoder_exposes_only_registered_program_ids() {
+        let decoders: [&dyn crate::DcApiProtocolDecoder; 104] = [
+            &crate::DcAdapterSaberDecimalWrapperDecoder,
+            &crate::DcAdapterSplTokenWrapDecoder,
+            &crate::DcGovernanceSquadsMultisigDecoder,
+            &crate::DcNftTensorCnftDecoder,
+            &crate::DcPerpetualsPhoenixEternalDecoder,
+            &crate::DcStakingJitoTipDistributionDecoder,
+            &crate::DcStorageSolanaRecordDecoder,
+            &crate::DcVestingJupiterLockDecoder,
+            &crate::DcFeesPumpFeesDecoder,
+            &crate::DcAmmAldrinV1Decoder,
+            &crate::DcAmmAldrinV2Decoder,
+            &crate::DcAmmAlphaqDecoder,
+            &crate::DcAmmBelieveDecoder,
+            &crate::DcAmmBonkSwapDecoder,
+            &crate::DcAmmFluxbeamDecoder,
+            &crate::DcAmmGoonFiDecoder,
+            &crate::DcAmmGoosefxGammaDecoder,
+            &crate::DcAmmGoosefxV2Decoder,
+            &crate::DcAmmGuacSwapDecoder,
+            &crate::DcAmmLifinitySwapV2Decoder,
+            &crate::DcGovernanceMetadaoFutarchyDecoder,
+            &crate::DcAmmMetadaoV05Decoder,
+            &crate::DcAmmMeteoraDammV1Decoder,
+            &crate::DcAmmMeteoraDammV2Decoder,
+            &crate::DcAmmObricV2Decoder,
+            &crate::DcAmmOneDexDecoder,
+            &crate::DcAmmPumpSwapDecoder,
+            &crate::DcAmmRaydiumLpV4Decoder,
+            &crate::DcAmmSolfiDecoder,
+            &crate::DcAmmSolfiV2Decoder,
+            &crate::DcAmmVertigoDecoder,
+            &crate::DcLaunchpadVirtualsDecoder,
+            &crate::DcAmmWoofiDecoder,
+            &crate::DcAmmZeroFiDecoder,
+            &crate::DcAmmZoraDecoder,
+            &crate::DcAnchorDecoder,
+            &crate::DcBridgeCircleCctpTokenMessengerMinterDecoder,
+            &crate::DcBridgeCircleCctpTokenMessengerMinterV2Decoder,
+            &crate::DcBridgeLayerZeroEndpointDecoder,
+            &crate::DcBridgeLayerZeroExecutorDecoder,
+            &crate::DcClmmByrealDecoder,
+            &crate::DcClmmFusionDecoder,
+            &crate::DcClmmOrcaWhirlpoolDecoder,
+            &crate::DcClmmPancakeSwapDecoder,
+            &crate::DcClmmRaydiumDecoder,
+            &crate::DcClmmStabbleDecoder,
+            &crate::DcCpmmRaydiumDecoder,
+            &crate::DcDlmmMeteoraDecoder,
+            &crate::DcFeesBagsFeeShareV1Decoder,
+            &crate::DcFeesBagsFeeShareV2Decoder,
+            &crate::DcGovernanceMetadaoBidWallDecoder,
+            &crate::DcLaunchpadBoopFunDecoder,
+            &crate::DcLaunchpadMetadaoIcoDecoder,
+            &crate::DcLaunchpadMeteoraDbcDecoder,
+            &crate::DcLaunchpadMoonitDecoder,
+            &crate::DcLaunchpadOrcaWavebreakDecoder,
+            &crate::DcLaunchpadPrintrDecoder,
+            &crate::DcLaunchpadPumpFunDecoder,
+            &crate::DcLaunchpadPumpPumpupAiDecoder,
+            &crate::DcLaunchpadRaydiumLaunchlabDecoder,
+            &crate::DcLendingCloneDecoder,
+            &crate::DcLendingJupiterLendBorrowDecoder,
+            &crate::DcLendingJupiterLendEarnDecoder,
+            &crate::DcLendingJupiterLendFlashLoanDecoder,
+            &crate::DcLendingJupiterLendLiquidityDecoder,
+            &crate::DcLendingKaminoDecoder,
+            &crate::DcLendingMarginfiV2Decoder,
+            &crate::DcLockRaydiumLpDecoder,
+            &crate::DcMetadataSplNameServiceDecoder,
+            &crate::DcNftMetaplexBubblegumDecoder,
+            &crate::DcOrderbookJupiterLimitOrderDecoder,
+            &crate::DcOrderbookJupiterLimitOrderV2Decoder,
+            &crate::DcOrderbookOpenbookV2Decoder,
+            &crate::DcPerpetualsDriftV2Decoder,
+            &crate::DcPerpetualsJupiterDecoder,
+            &crate::DcPerpetualsZetaDecoder,
+            &crate::DcRouterDflowAggregatorV4Decoder,
+            &crate::DcRouterJupiterAggregatorV4Decoder,
+            &crate::DcRouterJupiterAggregatorV6Decoder,
+            &crate::DcStrategyJupiterDcaDecoder,
+            &crate::DcRouterOkxLabsV1Decoder,
+            &crate::DcRouterOkxLabsV2Decoder,
+            &crate::DcRwaOndoGlobalMarketsDecoder,
+            &crate::DcSplAccountCompressionDecoder,
+            &crate::DcSplNoopDecoder,
+            &crate::DcSplSinglePoolDecoder,
+            &crate::DcSplStakePoolDecoder,
+            &crate::DcStableSwapHyloExchangeDecoder,
+            &crate::DcStableSwapJupiterStableDecoder,
+            &crate::DcStableSwapNumeraireDecoder,
+            &crate::DcStableSwapStabbleDecoder,
+            &crate::DcStakingKaminoFarmDecoder,
+            &crate::DcStakingMarinadeFinanceDecoder,
+            &crate::DcStakingSolayerDecoder,
+            &crate::DcTreasuryHeliumTreasuryManagementDecoder,
+            &crate::DcVaultCarrotDefiDecoder,
+            &crate::DcVaultHyloStabilityPoolDecoder,
+            &crate::DcVaultKaminoDecoder,
+            &crate::DcVaultKaminoV2Decoder,
+            &crate::DcVaultKaminoYvaultsDecoder,
+            &crate::DcVaultMeteoraDecoder,
+            &crate::DcVestingStreamflowDecoder,
+            &crate::DcWalletJupiterApeproSmartWalletDecoder,
+            &crate::DcWeightedSwapStabbleDecoder,
+        ];
+        let mut names = std::collections::BTreeSet::new();
+        for decoder in decoders {
+            assert!(names.insert(decoder.decoder_name()));
+            if decoder.decoder_name() == "kb-lib.decoder.anchor" {
+                assert!(decoder.program_ids().is_empty());
+                continue;
+            }
+            assert_eq!(decoder.program_ids().len(), 1);
+            for program_id in decoder.program_ids() {
+                assert!(ks_program_ids::find_registered_program_id(program_id).is_some());
+                let observation = crate::MdProgramObservation {
+                    signature: crate::MdSignature("signature".to_string()),
+                    slot: crate::MdSlot(1),
+                    instruction_path: crate::MdInstructionPath("0".to_string()),
+                    program_id: crate::MdProgramId((*program_id).to_string()),
+                    discriminator_8: std::option::Option::None,
+                    data_len: 0,
+                    accounts_len: 0,
+                    failed: false,
+                };
+                assert_eq!(
+                    decoder.supports_observation(&observation),
+                    crate::DcApiDecoderSupport::Maybe
+                );
+                let decode_result = decoder.decode_observation(&observation);
+                assert!(decode_result.is_ok());
+                assert!(decode_result.is_ok_and(|events| return events.is_empty()));
+            }
+        }
+        assert_eq!(names.len(), 104);
+    }
+}

ks-lib/src/decoder/adapter.rs

@@ -0,0 +1,12 @@
+// file: ks-lib/src/decoder/adapter.rs
+// version: 6
+
+//! `adapter` decoder family.
+
+mod saber_decimal_wrapper;
+mod spl_token_wrap;
+
+/// Reserved `kb-lib.decoder.adapter.saber_decimal_wrapper` decoder.
+pub use self::saber_decimal_wrapper::DcAdapterSaberDecimalWrapperDecoder;
+/// Reserved `kb-lib.decoder.adapter.spl_token_wrap` decoder.
+pub use self::spl_token_wrap::DcAdapterSplTokenWrapDecoder;

ks-lib/src/decoder/adapter/saber_decimal_wrapper.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/adapter/saber_decimal_wrapper.rs
+// version: 5
+
+//! Reserved protocol decoder for `adapter_saber_decimal_wrapper`.
+
+/// Reserved decoder for the `adapter_saber_decimal_wrapper` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAdapterSaberDecimalWrapperDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAdapterSaberDecimalWrapperDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.adapter.saber_decimal_wrapper";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::ADAPTER_SABER_DECIMAL_WRAPPER_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/adapter/spl_token_wrap.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/adapter/spl_token_wrap.rs
+// version: 2
+
+//! Reserved protocol decoder for `adapter_spl_token_wrap`.
+
+/// Reserved decoder for the `adapter_spl_token_wrap` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAdapterSplTokenWrapDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAdapterSplTokenWrapDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.adapter.spl_token_wrap";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::ADAPTER_SPL_TOKEN_WRAP_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm.rs

@@ -0,0 +1,78 @@
+// file: ks-lib/src/decoder/amm.rs
+// version: 6
+
+//! `amm` decoder family.
+
+mod aldrin_v1;
+mod aldrin_v2;
+mod alphaq;
+mod believe;
+mod bonk_swap;
+mod fluxbeam;
+mod goon_fi;
+mod goosefx_gamma;
+mod goosefx_v2;
+mod guac_swap;
+mod lifinity_swap_v2;
+mod metadao_v0_5;
+mod meteora_damm_v1;
+mod meteora_damm_v2;
+mod obric_v2;
+mod one_dex;
+mod pump_swap;
+mod raydium_lp_v4;
+mod solfi;
+mod solfi_v2;
+mod vertigo;
+mod woofi;
+mod zero_fi;
+mod zora;
+
+/// Reserved `kb-lib.decoder.amm.aldrin_v1` decoder.
+pub use self::aldrin_v1::DcAmmAldrinV1Decoder;
+/// Reserved `kb-lib.decoder.amm.aldrin_v2` decoder.
+pub use self::aldrin_v2::DcAmmAldrinV2Decoder;
+/// Reserved `kb-lib.decoder.amm.alphaq` decoder.
+pub use self::alphaq::DcAmmAlphaqDecoder;
+/// Reserved `kb-lib.decoder.amm.believe` decoder.
+pub use self::believe::DcAmmBelieveDecoder;
+/// Reserved `kb-lib.decoder.amm.bonk_swap` decoder.
+pub use self::bonk_swap::DcAmmBonkSwapDecoder;
+/// Reserved `kb-lib.decoder.amm.fluxbeam` decoder.
+pub use self::fluxbeam::DcAmmFluxbeamDecoder;
+/// Reserved `kb-lib.decoder.amm.goon_fi` decoder.
+pub use self::goon_fi::DcAmmGoonFiDecoder;
+/// Reserved `kb-lib.decoder.amm.goosefx_gamma` decoder.
+pub use self::goosefx_gamma::DcAmmGoosefxGammaDecoder;
+/// Reserved `kb-lib.decoder.amm.goosefx_v2` decoder.
+pub use self::goosefx_v2::DcAmmGoosefxV2Decoder;
+/// Reserved `kb-lib.decoder.amm.guac_swap` decoder.
+pub use self::guac_swap::DcAmmGuacSwapDecoder;
+/// Reserved `kb-lib.decoder.amm.lifinity_swap_v2` decoder.
+pub use self::lifinity_swap_v2::DcAmmLifinitySwapV2Decoder;
+/// Reserved `kb-lib.decoder.amm.metadao_v0_5` decoder.
+pub use self::metadao_v0_5::DcAmmMetadaoV05Decoder;
+/// Reserved `kb-lib.decoder.amm.meteora_damm_v1` decoder.
+pub use self::meteora_damm_v1::DcAmmMeteoraDammV1Decoder;
+/// Reserved `kb-lib.decoder.amm.meteora_damm_v2` decoder.
+pub use self::meteora_damm_v2::DcAmmMeteoraDammV2Decoder;
+/// Reserved `kb-lib.decoder.amm.obric_v2` decoder.
+pub use self::obric_v2::DcAmmObricV2Decoder;
+/// Reserved `kb-lib.decoder.amm.one_dex` decoder.
+pub use self::one_dex::DcAmmOneDexDecoder;
+/// Reserved `kb-lib.decoder.amm.pump_swap` decoder.
+pub use self::pump_swap::DcAmmPumpSwapDecoder;
+/// Reserved `kb-lib.decoder.amm.raydium_lp_v4` decoder.
+pub use self::raydium_lp_v4::DcAmmRaydiumLpV4Decoder;
+/// Reserved `kb-lib.decoder.amm.solfi` decoder.
+pub use self::solfi::DcAmmSolfiDecoder;
+/// Reserved `kb-lib.decoder.amm.solfi_v2` decoder.
+pub use self::solfi_v2::DcAmmSolfiV2Decoder;
+/// Reserved `kb-lib.decoder.amm.vertigo` decoder.
+pub use self::vertigo::DcAmmVertigoDecoder;
+/// Reserved `kb-lib.decoder.amm.woofi` decoder.
+pub use self::woofi::DcAmmWoofiDecoder;
+/// Reserved `kb-lib.decoder.amm.zero_fi` decoder.
+pub use self::zero_fi::DcAmmZeroFiDecoder;
+/// Reserved `kb-lib.decoder.amm.zora` decoder.
+pub use self::zora::DcAmmZoraDecoder;

ks-lib/src/decoder/amm/aldrin_v1.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/aldrin_v1.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_aldrin_v1`.
+
+/// Reserved decoder for the `amm_aldrin_v1` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmAldrinV1Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmAldrinV1Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.aldrin_v1";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_ALDRIN_V1_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/aldrin_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/aldrin_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_aldrin_v2`.
+
+/// Reserved decoder for the `amm_aldrin_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmAldrinV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmAldrinV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.aldrin_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_ALDRIN_V2_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/alphaq.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/alphaq.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_alphaq`.
+
+/// Reserved decoder for the `amm_alphaq` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmAlphaqDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmAlphaqDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.alphaq";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_ALPHAQ_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/believe.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/believe.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_believe`.
+
+/// Reserved decoder for the `amm_believe` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmBelieveDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmBelieveDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.believe";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_BELIEVE_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/bonk_swap.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/bonk_swap.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_bonk_swap`.
+
+/// Reserved decoder for the `amm_bonk_swap` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmBonkSwapDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmBonkSwapDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.bonk_swap";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_BONK_SWAP_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/fluxbeam.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/fluxbeam.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_fluxbeam`.
+
+/// Reserved decoder for the `amm_fluxbeam` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmFluxbeamDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmFluxbeamDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.fluxbeam";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_FLUXBEAM_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/goon_fi.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/goon_fi.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_goon_fi`.
+
+/// Reserved decoder for the `amm_goon_fi` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmGoonFiDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmGoonFiDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.goon_fi";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_GOON_FI_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/goosefx_gamma.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/goosefx_gamma.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_goosefx_gamma`.
+
+/// Reserved decoder for the `amm_goosefx_gamma` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmGoosefxGammaDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmGoosefxGammaDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.goosefx_gamma";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_GOOSEFX_GAMMA_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/goosefx_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/goosefx_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_goosefx_v2`.
+
+/// Reserved decoder for the `amm_goosefx_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmGoosefxV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmGoosefxV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.goosefx_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_GOOSEFX_V2_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/guac_swap.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/guac_swap.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_guac_swap`.
+
+/// Reserved decoder for the `amm_guac_swap` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmGuacSwapDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmGuacSwapDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.guac_swap";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_GUAC_SWAP_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/lifinity_swap_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/lifinity_swap_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_lifinity_swap_v2`.
+
+/// Reserved decoder for the `amm_lifinity_swap_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmLifinitySwapV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmLifinitySwapV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.lifinity_swap_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_LIFINITY_SWAP_V2_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/metadao_v0_5.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/metadao_v0_5.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_metadao_v0_5`.
+
+/// Reserved decoder for the `amm_metadao_v0_5` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmMetadaoV05Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmMetadaoV05Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.metadao_v0_5";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_METADAO_V0_5_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/meteora_damm_v1.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/meteora_damm_v1.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_meteora_damm_v1`.
+
+/// Reserved decoder for the `amm_meteora_damm_v1` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmMeteoraDammV1Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmMeteoraDammV1Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.meteora_damm_v1";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_METEORA_DAMM_V1_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/meteora_damm_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/meteora_damm_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_meteora_damm_v2`.
+
+/// Reserved decoder for the `amm_meteora_damm_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmMeteoraDammV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmMeteoraDammV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.meteora_damm_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_METEORA_DAMM_V2_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/obric_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/obric_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_obric_v2`.
+
+/// Reserved decoder for the `amm_obric_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmObricV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmObricV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.obric_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_OBRIC_V2_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/one_dex.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/one_dex.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_one_dex`.
+
+/// Reserved decoder for the `amm_one_dex` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmOneDexDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmOneDexDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.one_dex";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_ONE_DEX_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/pump_swap.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/pump_swap.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_pump_swap`.
+
+/// Reserved decoder for the `amm_pump_swap` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmPumpSwapDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmPumpSwapDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.pump_swap";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_PUMP_SWAP_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/raydium_lp_v4.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/raydium_lp_v4.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_raydium_lp_v4`.
+
+/// Reserved decoder for the `amm_raydium_lp_v4` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmRaydiumLpV4Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmRaydiumLpV4Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.raydium_lp_v4";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_RAYDIUM_LP_V4_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/solfi.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/solfi.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_solfi`.
+
+/// Reserved decoder for the `amm_solfi` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmSolfiDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmSolfiDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.solfi";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_SOLFI_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/solfi_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/solfi_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_solfi_v2`.
+
+/// Reserved decoder for the `amm_solfi_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmSolfiV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmSolfiV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.solfi_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_SOLFI_V2_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/vertigo.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/vertigo.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_vertigo`.
+
+/// Reserved decoder for the `amm_vertigo` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmVertigoDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmVertigoDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.vertigo";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_VERTIGO_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/woofi.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/woofi.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_woofi`.
+
+/// Reserved decoder for the `amm_woofi` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmWoofiDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmWoofiDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.woofi";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_WOOFI_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/zero_fi.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/zero_fi.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_zero_fi`.
+
+/// Reserved decoder for the `amm_zero_fi` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmZeroFiDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmZeroFiDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.zero_fi";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_ZERO_FI_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/amm/zora.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/amm/zora.rs
+// version: 5
+
+//! Reserved protocol decoder for `amm_zora`.
+
+/// Reserved decoder for the `amm_zora` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAmmZoraDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAmmZoraDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.amm.zora";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::AMM_ZORA_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/anchor.rs

@@ -0,0 +1,9 @@
+// file: ks-lib/src/decoder/anchor.rs
+// version: 5
+
+//! `anchor` decoder family.
+
+mod core;
+
+/// Reserved `kb-lib.decoder.anchor` decoder.
+pub use self::core::DcAnchorDecoder;

ks-lib/src/decoder/anchor/core.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/anchor/core.rs
+// version: 5
+
+//! Reserved protocol decoder for `anchor`.
+
+/// Reserved decoder for the `anchor` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcAnchorDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcAnchorDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.anchor";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/api.rs

@@ -0,0 +1,48 @@
+// file: ks-lib/src/decoder/api.rs
+// version: 7
+
+//! Decoder contracts.
+
+mod contracts;
+mod decoder;
+
+/// Current contextual core instruction input contract version.
+pub use self::contracts::DC_API_CORE_INSTRUCTION_INPUT_CONTRACT_VERSION;
+/// Stable contextual decoded observation.
+pub use self::contracts::DcApiDecodedObservation;
+/// Machine-readable decoder coverage declaration.
+pub use self::contracts::DcApiDecoderCoverageDeclaration;
+/// Declared decoder coverage entry kind.
+pub use self::contracts::DcApiDecoderCoverageEntryKind;
+/// Structured decoder diagnostic.
+pub use self::contracts::DcApiDecoderDiagnostic;
+/// Complete decoder execution result.
+pub use self::contracts::DcApiDecoderExecutionResult;
+/// Stable decoder identity.
+pub use self::contracts::DcApiDecoderIdentity;
+/// Decoder terminal result status.
+pub use self::contracts::DcApiDecoderOutcomeStatus;
+/// Explicit decoding proof.
+pub use self::contracts::DcApiDecoderProof;
+/// Decoding proof category.
+pub use self::contracts::DcApiDecoderProofKind;
+/// Deterministic decoder recognition result.
+pub use self::contracts::DcApiDecoderRecognition;
+/// One statically declared decoder surface.
+pub use self::contracts::DcApiDecoderSurface;
+/// Contextual instruction decoder contract.
+pub use self::contracts::DcApiInstructionDecoder;
+/// Computes the deterministic contextual input hash.
+pub use self::contracts::decoder_api_contextual_input_hash;
+/// Returns true when a decoder declares the exact program id.
+pub use self::contracts::decoder_api_decoder_handles_program_id;
+/// Computes a deterministic lowercase SHA-256 hash for one JSON value.
+pub use self::contracts::decoder_api_deterministic_json_hash;
+/// Extracts the first eight payload bytes as hexadecimal when available.
+pub use self::contracts::decoder_api_discriminator_8_hex;
+/// Exposes the decoder support level.
+pub use self::decoder::DcApiDecoderSupport;
+/// Initial decoder implementation placeholder for API-level tests.
+pub use self::decoder::DcApiInitialDecoder;
+/// Exposes the common protocol decoder trait.
+pub use self::decoder::DcApiProtocolDecoder;

ks-lib/src/decoder/api/contracts.rs

@@ -0,0 +1,580 @@
+// file: ks-lib/src/decoder/api/contracts.rs
+// version: 9
+
+//! Backend-neutral contextual instruction decoder contracts.
+
+use sha2::Digest; // rust-rules: trait-import
+
+/// Current contextual core instruction input contract version.
+pub const DC_API_CORE_INSTRUCTION_INPUT_CONTRACT_VERSION: u32 =
+    crate::MD_CORE_REPLAY_INPUT_CONTRACT_VERSION;
+
+/// Stable identity of one contextual instruction decoder.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct DcApiDecoderIdentity {
+    /// Stable lower snake case processor name.
+    pub name: std::string::String,
+    /// Semantic or deterministic implementation version.
+    pub version: std::string::String,
+}
+
+impl DcApiDecoderIdentity {
+    /// Builds a validated decoder identity.
+    pub fn new(
+        name: impl std::convert::Into<std::string::String>,
+        version: impl std::convert::Into<std::string::String>,
+    ) -> ks_core::Result<Self> {
+        let value = Self {
+            name: name.into(),
+            version: version.into(),
+        };
+        if value.name.trim().is_empty() || value.version.trim().is_empty() {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "decoder identity fields must not be empty",
+            ));
+        }
+        return std::result::Result::Ok(value);
+    }
+}
+
+/// One statically declared Solana surface supported by a decoder.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct DcApiDecoderSurface {
+    /// Exact Solana program identifier.
+    pub program_id: &'static str,
+    /// Stable surface code.
+    pub surface_code: &'static str,
+    /// Explicit dispatch priority, where larger values win.
+    pub priority: u16,
+}
+
+/// Declared decoder coverage entry kind.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub enum DcApiDecoderCoverageEntryKind {
+    /// Program instruction entry.
+    Instruction,
+    /// Program event entry.
+    Event,
+    /// Raw discriminator entry.
+    Discriminator,
+}
+
+/// Machine-readable decoder coverage declaration.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct DcApiDecoderCoverageDeclaration {
+    /// Solana program identifier.
+    pub program_id: std::string::String,
+    /// Optional stable surface code.
+    pub surface_code: std::option::Option<std::string::String>,
+    /// Entry kind.
+    pub entry_kind: DcApiDecoderCoverageEntryKind,
+    /// Stable instruction, event or discriminator code.
+    pub entry_code: std::string::String,
+    /// Optional normalized lowercase hexadecimal discriminator.
+    pub discriminator_hex: std::option::Option<std::string::String>,
+    /// Whether the entry is historical or deprecated but still supported.
+    pub historical: bool,
+}
+
+impl DcApiDecoderCoverageDeclaration {
+    /// Builds a validated coverage declaration.
+    pub fn new(
+        program_id: impl std::convert::Into<std::string::String>,
+        surface_code: std::option::Option<std::string::String>,
+        entry_kind: DcApiDecoderCoverageEntryKind,
+        entry_code: impl std::convert::Into<std::string::String>,
+        discriminator_hex: std::option::Option<std::string::String>,
+        historical: bool,
+    ) -> ks_core::Result<Self> {
+        let value = Self {
+            program_id: program_id.into(),
+            surface_code,
+            entry_kind,
+            entry_code: entry_code.into(),
+            discriminator_hex,
+            historical,
+        };
+        if value.program_id.trim().is_empty() || value.entry_code.trim().is_empty() {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "decoder coverage program id and entry code must not be empty",
+            ));
+        }
+        if value
+            .surface_code
+            .as_deref()
+            .is_some_and(|surface| return surface.trim().is_empty())
+        {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "decoder coverage surface code must not be empty when present",
+            ));
+        }
+        if value
+            .discriminator_hex
+            .as_deref()
+            .is_some_and(|discriminator| return discriminator.trim().is_empty())
+        {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "decoder coverage discriminator must not be empty when present",
+            ));
+        }
+        return std::result::Result::Ok(value);
+    }
+}
+
+/// Deterministic recognition result used by dispatch.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct DcApiDecoderRecognition {
+    /// Whether the decoder is compatible with the input.
+    pub compatible: bool,
+    /// Whether recognition is exact rather than program-only.
+    pub exact: bool,
+    /// Explicit priority used after program and surface matching.
+    pub priority: u16,
+    /// Optional recognized surface code.
+    pub surface_code: std::option::Option<std::string::String>,
+    /// Optional recognized instruction or discriminator code.
+    pub entry_code: std::option::Option<std::string::String>,
+    /// Optional normalized lowercase hexadecimal discriminator.
+    pub discriminator_hex: std::option::Option<std::string::String>,
+}
+
+impl DcApiDecoderRecognition {
+    /// Builds a non-compatible recognition result.
+    pub fn incompatible() -> Self {
+        return Self {
+            compatible: false,
+            exact: false,
+            priority: 0,
+            surface_code: std::option::Option::None,
+            entry_code: std::option::Option::None,
+            discriminator_hex: std::option::Option::None,
+        };
+    }
+
+    /// Builds a compatible recognition result.
+    pub fn compatible(
+        exact: bool,
+        priority: u16,
+        surface_code: std::option::Option<std::string::String>,
+        entry_code: std::option::Option<std::string::String>,
+        discriminator_hex: std::option::Option<std::string::String>,
+    ) -> Self {
+        return Self {
+            compatible: true,
+            exact,
+            priority,
+            surface_code,
+            entry_code,
+            discriminator_hex,
+        };
+    }
+}
+
+/// Decoder terminal result status.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub enum DcApiDecoderOutcomeStatus {
+    /// At least one stable decoded observation was produced.
+    Decoded,
+    /// The decoder intentionally ignored a recognized input.
+    Ignored,
+    /// The input belongs to the program but its entry is unsupported.
+    Unsupported,
+    /// Decoding failed and diagnostics were produced.
+    Failed,
+}
+
+/// Proof category attached to one decoded observation.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub enum DcApiDecoderProofKind {
+    /// Exact instruction discriminator match.
+    ExactDiscriminator,
+    /// Exact binary layout decode.
+    ExactLayout,
+    /// Exact IDL-based decode.
+    Idl,
+    /// Manually verified exact decode.
+    Manual,
+    /// Correlation with runtime logs.
+    LogCorrelation,
+    /// Balance delta evidence.
+    BalanceDelta,
+    /// Heuristic evidence that must not be treated as exact.
+    Heuristic,
+    /// Audit-only classification.
+    Audit,
+    /// Unknown or unclassified evidence.
+    Unknown,
+}
+
+/// Explicit proof attached to one decoded observation.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct DcApiDecoderProof {
+    /// Proof category.
+    pub kind: DcApiDecoderProofKind,
+    /// Decoder confidence.
+    pub confidence: crate::MdDecoderConfidence,
+    /// Stable evidence strings, hashes or classifier codes.
+    pub evidence: std::vec::Vec<std::string::String>,
+}
+
+/// Structured decoder diagnostic without third-party error wrappers.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct DcApiDecoderDiagnostic {
+    /// Stable machine-readable diagnostic code.
+    pub code: std::string::String,
+    /// Human-readable diagnostic message.
+    pub message: std::string::String,
+    /// Whether retrying the same version and input may succeed.
+    pub retriable: bool,
+}
+
+impl DcApiDecoderDiagnostic {
+    /// Builds a validated decoder diagnostic.
+    pub fn new(
+        code: impl std::convert::Into<std::string::String>,
+        message: impl std::convert::Into<std::string::String>,
+        retriable: bool,
+    ) -> ks_core::Result<Self> {
+        let value = Self {
+            code: code.into(),
+            message: message.into(),
+            retriable,
+        };
+        if value.code.trim().is_empty() || value.message.trim().is_empty() {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "decoder diagnostic code and message must not be empty",
+            ));
+        }
+        return std::result::Result::Ok(value);
+    }
+}
+
+/// Stable contextual decoded observation persisted by the decode pipeline.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct DcApiDecodedObservation {
+    /// Stable processor-owned event key within one input.
+    pub event_key: std::string::String,
+    /// Shared typed protocol event identity.
+    pub event: crate::MdDecodedProtocolEvent,
+    /// Typed event payload serialized as deterministic JSON.
+    pub payload_json: serde_json::Value,
+    /// Whether the source transaction failed on-chain.
+    pub transaction_failed: bool,
+    /// Optional transaction error JSON.
+    pub transaction_error: std::option::Option<serde_json::Value>,
+    /// Whether the observed state mutation was committed on-chain.
+    pub observation_committed: bool,
+    /// Explicit decoding proof.
+    pub proof: DcApiDecoderProof,
+}
+
+impl DcApiDecodedObservation {
+    /// Validates failed transaction commit semantics and stable identity fields.
+    pub fn validate(&self) -> ks_core::Result<()> {
+        if self.event_key.trim().is_empty() {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "decoded observation event key must not be empty",
+            ));
+        }
+        if self.transaction_failed && self.observation_committed {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "failed transaction observations must not be marked committed",
+            ));
+        }
+        if self.event.signature.0.trim().is_empty()
+            || self.event.instruction_path.0.trim().is_empty()
+            || self.event.program_id.0.trim().is_empty()
+            || self.event.event_code.0.trim().is_empty()
+        {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "decoded observation event identity fields must not be empty",
+            ));
+        }
+        return std::result::Result::Ok(());
+    }
+}
+
+/// Complete explicit result produced by one decoder invocation.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct DcApiDecoderExecutionResult {
+    /// Terminal decoder status.
+    pub status: DcApiDecoderOutcomeStatus,
+    /// Optional recognized instruction or discriminator code.
+    pub recognized_entry_code: std::option::Option<std::string::String>,
+    /// Decoded observations.
+    pub observations: std::vec::Vec<DcApiDecodedObservation>,
+    /// Structured diagnostics.
+    pub diagnostics: std::vec::Vec<DcApiDecoderDiagnostic>,
+}
+
+impl DcApiDecoderExecutionResult {
+    /// Builds an unsupported result with no false decoded observation.
+    pub fn unsupported(entry_code: std::option::Option<std::string::String>) -> Self {
+        return Self {
+            status: DcApiDecoderOutcomeStatus::Unsupported,
+            recognized_entry_code: entry_code,
+            observations: std::vec::Vec::new(),
+            diagnostics: std::vec::Vec::new(),
+        };
+    }
+
+    /// Builds an ignored result.
+    pub fn ignored(entry_code: std::option::Option<std::string::String>) -> Self {
+        return Self {
+            status: DcApiDecoderOutcomeStatus::Ignored,
+            recognized_entry_code: entry_code,
+            observations: std::vec::Vec::new(),
+            diagnostics: std::vec::Vec::new(),
+        };
+    }
+
+    /// Validates status and observation consistency.
+    pub fn validate(&self) -> ks_core::Result<()> {
+        if self.status == DcApiDecoderOutcomeStatus::Decoded && self.observations.is_empty() {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "decoded status requires at least one observation",
+            ));
+        }
+        if self.status != DcApiDecoderOutcomeStatus::Decoded && !self.observations.is_empty() {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "non-decoded status must not contain observations",
+            ));
+        }
+        if self.status == DcApiDecoderOutcomeStatus::Failed && self.diagnostics.is_empty() {
+            return std::result::Result::Err(ks_core::Error::invalid_state(
+                "failed decoder status requires at least one diagnostic",
+            ));
+        }
+        for observation in &self.observations {
+            let validation_result = observation.validate();
+            if let std::result::Result::Err(error) = validation_result {
+                return std::result::Result::Err(error);
+            }
+        }
+        return std::result::Result::Ok(());
+    }
+}
+
+/// Contextual instruction decoder contract used by the common pipeline.
+pub trait DcApiInstructionDecoder: std::marker::Send + std::marker::Sync {
+    /// Returns the stable decoder identity.
+    fn identity(&self) -> DcApiDecoderIdentity;
+    /// Returns every exact Solana surface supported by the decoder.
+    fn surfaces(&self) -> &'static [DcApiDecoderSurface];
+    /// Returns the machine-readable declared coverage matrix.
+    fn coverage(&self) -> std::vec::Vec<DcApiDecoderCoverageDeclaration>;
+    /// Recognizes one contextual core instruction for deterministic dispatch.
+    fn recognize(&self, input: &crate::MdCoreInstructionReplayInput) -> DcApiDecoderRecognition;
+    /// Decodes one recognized contextual core instruction.
+    fn decode(&self, input: &crate::MdCoreInstructionReplayInput) -> DcApiDecoderExecutionResult;
+}
+
+/// Returns true when a decoder declares the exact program id.
+pub fn decoder_api_decoder_handles_program_id(
+    decoder: &dyn DcApiInstructionDecoder,
+    program_id: &str,
+) -> bool {
+    for surface in decoder.surfaces() {
+        if surface.program_id == program_id {
+            return true;
+        }
+    }
+    return false;
+}
+
+/// Computes a deterministic lowercase SHA-256 hash for one contextual input.
+pub fn decoder_api_contextual_input_hash(
+    input: &crate::MdCoreInstructionReplayInput,
+) -> ks_core::Result<std::string::String> {
+    let serialization_result = serde_json::to_value(input);
+    let mut value = match serialization_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return std::result::Result::Err(ks_core::Error::json(format!(
+                "cannot serialize contextual decoder input: {error}"
+            )));
+        },
+    };
+    return crate::decoder_api_deterministic_json_hash(&mut value);
+}
+
+/// Computes a deterministic lowercase SHA-256 hash for one JSON value.
+pub fn decoder_api_deterministic_json_hash(
+    value: &mut serde_json::Value,
+) -> ks_core::Result<std::string::String> {
+    sort_json_value(value);
+    let bytes_result = serde_json::to_vec(value);
+    let bytes = match bytes_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return std::result::Result::Err(ks_core::Error::json(format!(
+                "cannot serialize deterministic JSON bytes: {error}"
+            )));
+        },
+    };
+    let digest = sha2::Sha256::digest(bytes);
+    let mut output = std::string::String::with_capacity(64);
+    for byte in digest {
+        output.push_str(format!("{byte:02x}").as_str());
+    }
+    return std::result::Result::Ok(output);
+}
+
+/// Extracts the first eight payload bytes as normalized lowercase hexadecimal when available.
+pub fn decoder_api_discriminator_8_hex(
+    input: &crate::MdCoreInstructionReplayInput,
+) -> std::option::Option<std::string::String> {
+    let payload = match &input.instruction_payload_json {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::option::Option::None,
+    };
+    let encoded = match payload.get("dataBase64").and_then(serde_json::Value::as_str) {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::option::Option::None,
+    };
+    let decoded_result =
+        base64::Engine::decode(&base64::engine::general_purpose::STANDARD, encoded.as_bytes());
+    let decoded = match decoded_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_error) => return std::option::Option::None,
+    };
+    if decoded.len() < 8 {
+        return std::option::Option::None;
+    }
+    let mut output = std::string::String::with_capacity(16);
+    for byte in &decoded[..8] {
+        output.push_str(format!("{byte:02x}").as_str());
+    }
+    return std::option::Option::Some(output);
+}
+
+fn sort_json_value(value: &mut serde_json::Value) {
+    match value {
+        serde_json::Value::Object(map) => {
+            let mut entries = std::mem::take(map).into_iter().collect::<std::vec::Vec<_>>();
+            entries.sort_by(|left, right| return left.0.cmp(&right.0));
+            for (key, mut child) in entries {
+                sort_json_value(&mut child);
+                map.insert(key, child);
+            }
+        },
+        serde_json::Value::Array(values) => {
+            for child in values {
+                sort_json_value(child);
+            }
+        },
+        _ => (),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    fn replay_input() -> crate::MdCoreInstructionReplayInput {
+        let result = crate::MdCoreInstructionReplayInput::new(
+            "signature:0",
+            "signature",
+            42,
+            "0",
+            "program",
+            false,
+            std::option::Option::None,
+            serde_json::json!([{"accountIndex": 0, "accountKey": "account"}]),
+            serde_json::json!([{"accountIndex": 0, "accountKey": "account"}]),
+            std::option::Option::Some(serde_json::json!({"dataBase64": "AQIDBAUGBwg="})),
+            std::option::Option::Some("payload-hash".to_string()),
+            serde_json::json!([{
+                "instructionIndex": 0,
+                "instructionPath": "0",
+                "programId": "program",
+                "payloadJson": {"dataBase64": "AQIDBAUGBwg="},
+                "payloadHash": "payload-hash"
+            }]),
+            serde_json::json!([]),
+            serde_json::json!([]),
+            serde_json::json!([]),
+        );
+        return match result {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => panic!("unexpected replay input error: {error}"),
+        };
+    }
+
+    #[test]
+    fn contextual_input_hash_is_stable() {
+        let first = crate::decoder_api_contextual_input_hash(&replay_input());
+        let second = crate::decoder_api_contextual_input_hash(&replay_input());
+        assert!(first.is_ok());
+        assert_eq!(first, second);
+    }
+
+    #[test]
+    fn contextual_input_hash_changes_when_outer_context_changes() {
+        let first = replay_input();
+        let mut second = replay_input();
+        second.outer_instructions_json = serde_json::json!([{
+            "instructionIndex": 0,
+            "instructionPath": "0",
+            "programId": "program",
+            "payloadJson": {"dataBase64": "CAcGBQQDAgE="},
+            "payloadHash": "different-payload-hash"
+        }]);
+        let first_hash = crate::decoder_api_contextual_input_hash(&first);
+        let second_hash = crate::decoder_api_contextual_input_hash(&second);
+        assert!(first_hash.is_ok());
+        assert!(second_hash.is_ok());
+        assert_ne!(first_hash, second_hash);
+    }
+
+    #[test]
+    fn contextual_input_serialization_is_deterministic_with_outer_context() {
+        let first_result = serde_json::to_string(&replay_input());
+        let first = match first_result {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => panic!("unexpected serialization error: {error}"),
+        };
+        let second_result = serde_json::to_string(&replay_input());
+        let second = match second_result {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => panic!("unexpected serialization error: {error}"),
+        };
+        assert_eq!(first, second);
+    }
+
+    #[test]
+    fn discriminator_uses_first_eight_bytes() {
+        let value = crate::decoder_api_discriminator_8_hex(&replay_input());
+        assert_eq!(value.as_deref(), std::option::Option::Some("0102030405060708"));
+    }
+
+    #[test]
+    fn failed_observation_cannot_be_committed() {
+        let observation = crate::DcApiDecodedObservation {
+            event_key: "event".to_string(),
+            event: crate::MdDecodedProtocolEvent {
+                signature: crate::MdSignature("signature".to_string()),
+                slot: crate::MdSlot(42),
+                instruction_path: crate::MdInstructionPath("0".to_string()),
+                program_id: crate::MdProgramId("program".to_string()),
+                protocol_code: crate::MdProtocolCode("solana".to_string()),
+                surface_code: crate::MdSurfaceCode("system_program".to_string()),
+                event_code: crate::MdEventCode("system_program.attempt".to_string()),
+                event_name: crate::MdEventName("attempt".to_string()),
+                event_family: crate::MdEventFamily::Audit,
+                source_kind: crate::MdEventSourceKind::Instruction,
+                confidence: crate::MdDecoderConfidence::Exact,
+            },
+            payload_json: serde_json::json!({}),
+            transaction_failed: true,
+            transaction_error: std::option::Option::Some(
+                serde_json::json!({"InstructionError": [0, "Custom"]}),
+            ),
+            observation_committed: true,
+            proof: crate::DcApiDecoderProof {
+                kind: crate::DcApiDecoderProofKind::ExactLayout,
+                confidence: crate::MdDecoderConfidence::Exact,
+                evidence: std::vec!["layout".to_string()],
+            },
+        };
+        assert!(observation.validate().is_err());
+    }
+}

ks-lib/src/decoder/api/decoder.rs

@@ -0,0 +1,79 @@
+// file: ks-lib/src/decoder/api/decoder.rs
+// version: 7
+
+//! Shared decoder contracts for protocol decoder crates.
+
+/// Decoder support level for a program observation.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum DcApiDecoderSupport {
+    /// The decoder does not support the observation.
+    No,
+    /// The decoder may support the observation after deeper inspection.
+    Maybe,
+    /// The decoder explicitly supports the observation.
+    Yes,
+}
+
+/// Common trait implemented by every protocol decoder crate.
+pub trait DcApiProtocolDecoder {
+    /// Returns the stable decoder name.
+    fn decoder_name(&self) -> &'static str;
+    /// Returns the decoder implementation version.
+    fn decoder_version(&self) -> &'static str;
+    /// Returns the Solana program ids handled by this decoder.
+    fn program_ids(&self) -> &'static [&'static str];
+    /// Checks whether the decoder handles a program id.
+    fn handles_program_id(&self, program_id: &crate::MdProgramId) -> bool {
+        for candidate in self.program_ids() {
+            if program_id.0.as_str() == *candidate {
+                return true;
+            }
+        }
+        return false;
+    }
+    /// Checks whether the decoder supports a generic program observation.
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> DcApiDecoderSupport;
+    /// Decodes a generic program observation into protocol events.
+    fn decode_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>>;
+}
+
+/// Initial decoder implementation placeholder for API-level tests.
+#[derive(Clone, Debug, Default)]
+pub struct DcApiInitialDecoder;
+
+impl DcApiProtocolDecoder for DcApiInitialDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.api";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> DcApiDecoderSupport {
+        if DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return DcApiDecoderSupport::Maybe;
+        }
+        return DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/bridge.rs

@@ -0,0 +1,18 @@
+// file: ks-lib/src/decoder/bridge.rs
+// version: 5
+
+//! `bridge` decoder family.
+
+mod circle_cctp_token_messenger_minter;
+mod circle_cctp_token_messenger_minter_v2;
+mod layer_zero_endpoint;
+mod layer_zero_executor;
+
+/// Reserved `kb-lib.decoder.bridge.circle_cctp_token_messenger_minter` decoder.
+pub use self::circle_cctp_token_messenger_minter::DcBridgeCircleCctpTokenMessengerMinterDecoder;
+/// Reserved `kb-lib.decoder.bridge.circle_cctp_token_messenger_minter_v2` decoder.
+pub use self::circle_cctp_token_messenger_minter_v2::DcBridgeCircleCctpTokenMessengerMinterV2Decoder;
+/// Reserved `kb-lib.decoder.bridge.layer_zero_endpoint` decoder.
+pub use self::layer_zero_endpoint::DcBridgeLayerZeroEndpointDecoder;
+/// Reserved `kb-lib.decoder.bridge.layer_zero_executor` decoder.
+pub use self::layer_zero_executor::DcBridgeLayerZeroExecutorDecoder;

ks-lib/src/decoder/bridge/circle_cctp_token_messenger_minter.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/bridge/circle_cctp_token_messenger_minter.rs
+// version: 5
+
+//! Reserved protocol decoder for `bridge_circle_cctp_token_messenger_minter`.
+
+/// Reserved decoder for the `bridge_circle_cctp_token_messenger_minter` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcBridgeCircleCctpTokenMessengerMinterDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcBridgeCircleCctpTokenMessengerMinterDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.bridge.circle_cctp_token_messenger_minter";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::BRIDGE_CIRCLE_CCTP_TOKEN_MESSENGER_MINTER_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/bridge/circle_cctp_token_messenger_minter_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/bridge/circle_cctp_token_messenger_minter_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `bridge_circle_cctp_token_messenger_minter_v2`.
+
+/// Reserved decoder for the `bridge_circle_cctp_token_messenger_minter_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcBridgeCircleCctpTokenMessengerMinterV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcBridgeCircleCctpTokenMessengerMinterV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.bridge.circle_cctp_token_messenger_minter_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::BRIDGE_CIRCLE_CCTP_TOKEN_MESSENGER_MINTER_V2_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/bridge/layer_zero_endpoint.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/bridge/layer_zero_endpoint.rs
+// version: 5
+
+//! Reserved protocol decoder for `bridge_layer_zero_endpoint`.
+
+/// Reserved decoder for the `bridge_layer_zero_endpoint` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcBridgeLayerZeroEndpointDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcBridgeLayerZeroEndpointDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.bridge.layer_zero_endpoint";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::BRIDGE_LAYER_ZERO_ENDPOINT_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/bridge/layer_zero_executor.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/bridge/layer_zero_executor.rs
+// version: 5
+
+//! Reserved protocol decoder for `bridge_layer_zero_executor`.
+
+/// Reserved decoder for the `bridge_layer_zero_executor` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcBridgeLayerZeroExecutorDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcBridgeLayerZeroExecutorDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.bridge.layer_zero_executor";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::BRIDGE_LAYER_ZERO_EXECUTOR_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/clmm.rs

@@ -0,0 +1,24 @@
+// file: ks-lib/src/decoder/clmm.rs
+// version: 5
+
+//! `clmm` decoder family.
+
+mod byreal;
+mod fusion;
+mod orca_whirlpool;
+mod pancake_swap;
+mod raydium;
+mod stabble;
+
+/// Reserved `kb-lib.decoder.clmm.byreal` decoder.
+pub use self::byreal::DcClmmByrealDecoder;
+/// Reserved `kb-lib.decoder.clmm.fusion` decoder.
+pub use self::fusion::DcClmmFusionDecoder;
+/// Reserved `kb-lib.decoder.clmm.orca_whirlpool` decoder.
+pub use self::orca_whirlpool::DcClmmOrcaWhirlpoolDecoder;
+/// Reserved `kb-lib.decoder.clmm.pancake_swap` decoder.
+pub use self::pancake_swap::DcClmmPancakeSwapDecoder;
+/// Reserved `kb-lib.decoder.clmm.raydium` decoder.
+pub use self::raydium::DcClmmRaydiumDecoder;
+/// Reserved `kb-lib.decoder.clmm.stabble` decoder.
+pub use self::stabble::DcClmmStabbleDecoder;

ks-lib/src/decoder/clmm/byreal.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/clmm/byreal.rs
+// version: 5
+
+//! Reserved protocol decoder for `clmm_byreal`.
+
+/// Reserved decoder for the `clmm_byreal` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcClmmByrealDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcClmmByrealDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.clmm.byreal";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::CLMM_BYREAL_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/clmm/fusion.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/clmm/fusion.rs
+// version: 5
+
+//! Reserved protocol decoder for `clmm_fusion`.
+
+/// Reserved decoder for the `clmm_fusion` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcClmmFusionDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcClmmFusionDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.clmm.fusion";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::CLMM_FUSION_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/clmm/orca_whirlpool.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/clmm/orca_whirlpool.rs
+// version: 5
+
+//! Reserved protocol decoder for `clmm_orca_whirlpool`.
+
+/// Reserved decoder for the `clmm_orca_whirlpool` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcClmmOrcaWhirlpoolDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcClmmOrcaWhirlpoolDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.clmm.orca_whirlpool";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::CLMM_ORCA_WHIRLPOOL_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/clmm/pancake_swap.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/clmm/pancake_swap.rs
+// version: 5
+
+//! Reserved protocol decoder for `clmm_pancake_swap`.
+
+/// Reserved decoder for the `clmm_pancake_swap` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcClmmPancakeSwapDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcClmmPancakeSwapDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.clmm.pancake_swap";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::CLMM_PANCAKE_SWAP_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/clmm/raydium.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/clmm/raydium.rs
+// version: 5
+
+//! Reserved protocol decoder for `clmm_raydium`.
+
+/// Reserved decoder for the `clmm_raydium` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcClmmRaydiumDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcClmmRaydiumDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.clmm.raydium";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::CLMM_RAYDIUM_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/clmm/stabble.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/clmm/stabble.rs
+// version: 5
+
+//! Reserved protocol decoder for `clmm_stabble`.
+
+/// Reserved decoder for the `clmm_stabble` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcClmmStabbleDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcClmmStabbleDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.clmm.stabble";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::CLMM_STABBLE_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/cpmm.rs

@@ -0,0 +1,9 @@
+// file: ks-lib/src/decoder/cpmm.rs
+// version: 5
+
+//! `cpmm` decoder family.
+
+mod raydium;
+
+/// Reserved `kb-lib.decoder.cpmm.raydium` decoder.
+pub use self::raydium::DcCpmmRaydiumDecoder;

ks-lib/src/decoder/cpmm/raydium.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/cpmm/raydium.rs
+// version: 5
+
+//! Reserved protocol decoder for `cpmm_raydium`.
+
+/// Reserved decoder for the `cpmm_raydium` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcCpmmRaydiumDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcCpmmRaydiumDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.cpmm.raydium";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::CPMM_RAYDIUM_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/dlmm.rs

@@ -0,0 +1,9 @@
+// file: ks-lib/src/decoder/dlmm.rs
+// version: 5
+
+//! `dlmm` decoder family.
+
+mod meteora;
+
+/// Reserved `kb-lib.decoder.dlmm.meteora` decoder.
+pub use self::meteora::DcDlmmMeteoraDecoder;

ks-lib/src/decoder/dlmm/meteora.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/dlmm/meteora.rs
+// version: 5
+
+//! Reserved protocol decoder for `dlmm_meteora`.
+
+/// Reserved decoder for the `dlmm_meteora` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcDlmmMeteoraDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcDlmmMeteoraDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.dlmm.meteora";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::DLMM_METEORA_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/fees.rs

@@ -0,0 +1,15 @@
+// file: ks-lib/src/decoder/fees.rs
+// version: 6
+
+//! `fees` decoder family.
+
+mod bags_fee_share_v1;
+mod bags_fee_share_v2;
+mod pump_fees;
+
+/// Reserved `kb-lib.decoder.fees.bags_fee_share_v1` decoder.
+pub use self::bags_fee_share_v1::DcFeesBagsFeeShareV1Decoder;
+/// Reserved `kb-lib.decoder.fees.bags_fee_share_v2` decoder.
+pub use self::bags_fee_share_v2::DcFeesBagsFeeShareV2Decoder;
+/// Reserved `kb-lib.decoder.fees.pump_fees` decoder.
+pub use self::pump_fees::DcFeesPumpFeesDecoder;

ks-lib/src/decoder/fees/bags_fee_share_v1.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/fees/bags_fee_share_v1.rs
+// version: 5
+
+//! Reserved protocol decoder for `fees_bags_fee_share_v1`.
+
+/// Reserved decoder for the `fees_bags_fee_share_v1` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcFeesBagsFeeShareV1Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcFeesBagsFeeShareV1Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.fees.bags_fee_share_v1";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::FEES_BAGS_FEE_SHARE_V1_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/fees/bags_fee_share_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/fees/bags_fee_share_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `fees_bags_fee_share_v2`.
+
+/// Reserved decoder for the `fees_bags_fee_share_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcFeesBagsFeeShareV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcFeesBagsFeeShareV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.fees.bags_fee_share_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::FEES_BAGS_FEE_SHARE_V2_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/fees/pump_fees.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/fees/pump_fees.rs
+// version: 5
+
+//! Reserved protocol decoder for `fees_pump_fees`.
+
+/// Reserved decoder for the `fees_pump_fees` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcFeesPumpFeesDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcFeesPumpFeesDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.fees.pump_fees";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::FEES_PUMP_FEES_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/governance.rs

@@ -0,0 +1,15 @@
+// file: ks-lib/src/decoder/governance.rs
+// version: 6
+
+//! `governance` decoder family.
+
+mod metadao_bid_wall;
+mod metadao_futarchy;
+mod squads_multisig;
+
+/// Reserved `kb-lib.decoder.governance.metadao_bid_wall` decoder.
+pub use self::metadao_bid_wall::DcGovernanceMetadaoBidWallDecoder;
+/// Reserved `kb-lib.decoder.governance.metadao_futarchy` decoder.
+pub use self::metadao_futarchy::DcGovernanceMetadaoFutarchyDecoder;
+/// Reserved `kb-lib.decoder.governance.squads_multisig` decoder.
+pub use self::squads_multisig::DcGovernanceSquadsMultisigDecoder;

ks-lib/src/decoder/governance/metadao_bid_wall.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/governance/metadao_bid_wall.rs
+// version: 5
+
+//! Reserved protocol decoder for `governance_metadao_bid_wall`.
+
+/// Reserved decoder for the `governance_metadao_bid_wall` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcGovernanceMetadaoBidWallDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcGovernanceMetadaoBidWallDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.governance.metadao_bid_wall";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::GOVERNANCE_METADAO_BID_WALL_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/governance/metadao_futarchy.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/governance/metadao_futarchy.rs
+// version: 5
+
+//! Reserved protocol decoder for `governance_metadao_futarchy`.
+
+/// Reserved decoder for the `governance_metadao_futarchy` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcGovernanceMetadaoFutarchyDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcGovernanceMetadaoFutarchyDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.governance.metadao_futarchy";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::GOVERNANCE_METADAO_FUTARCHY_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/governance/squads_multisig.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/governance/squads_multisig.rs
+// version: 2
+
+//! Reserved protocol decoder for `governance_squads_multisig`.
+
+/// Reserved decoder for the `governance_squads_multisig` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcGovernanceSquadsMultisigDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcGovernanceSquadsMultisigDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.governance.squads_multisig";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::GOVERNANCE_SQUADS_MULTISIG_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad.rs

@@ -0,0 +1,36 @@
+// file: ks-lib/src/decoder/launchpad.rs
+// version: 6
+
+//! `launchpad` decoder family.
+
+mod boop_fun;
+mod metadao_ico;
+mod meteora_dbc;
+mod moonit;
+mod orca_wavebreak;
+mod printr;
+mod pump_fun;
+mod pump_pumpup_ai;
+mod raydium_launchlab;
+mod virtuals;
+
+/// Reserved `kb-lib.decoder.launchpad.boop_fun` decoder.
+pub use self::boop_fun::DcLaunchpadBoopFunDecoder;
+/// Reserved `kb-lib.decoder.launchpad.metadao_ico` decoder.
+pub use self::metadao_ico::DcLaunchpadMetadaoIcoDecoder;
+/// Reserved `kb-lib.decoder.launchpad.meteora_dbc` decoder.
+pub use self::meteora_dbc::DcLaunchpadMeteoraDbcDecoder;
+/// Reserved `kb-lib.decoder.launchpad.moonit` decoder.
+pub use self::moonit::DcLaunchpadMoonitDecoder;
+/// Reserved `kb-lib.decoder.launchpad.orca_wavebreak` decoder.
+pub use self::orca_wavebreak::DcLaunchpadOrcaWavebreakDecoder;
+/// Reserved `kb-lib.decoder.launchpad.printr` decoder.
+pub use self::printr::DcLaunchpadPrintrDecoder;
+/// Reserved `kb-lib.decoder.launchpad.pump_fun` decoder.
+pub use self::pump_fun::DcLaunchpadPumpFunDecoder;
+/// Reserved `kb-lib.decoder.launchpad.pump_pumpup_ai` decoder.
+pub use self::pump_pumpup_ai::DcLaunchpadPumpPumpupAiDecoder;
+/// Reserved `kb-lib.decoder.launchpad.raydium_launchlab` decoder.
+pub use self::raydium_launchlab::DcLaunchpadRaydiumLaunchlabDecoder;
+/// Reserved `kb-lib.decoder.launchpad.virtuals` decoder.
+pub use self::virtuals::DcLaunchpadVirtualsDecoder;

ks-lib/src/decoder/launchpad/boop_fun.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/boop_fun.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_boop_fun`.
+
+/// Reserved decoder for the `launchpad_boop_fun` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadBoopFunDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadBoopFunDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.boop_fun";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_BOOP_FUN_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad/metadao_ico.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/metadao_ico.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_metadao_ico`.
+
+/// Reserved decoder for the `launchpad_metadao_ico` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadMetadaoIcoDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadMetadaoIcoDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.metadao_ico";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_METADAO_ICO_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad/meteora_dbc.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/meteora_dbc.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_meteora_dbc`.
+
+/// Reserved decoder for the `launchpad_meteora_dbc` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadMeteoraDbcDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadMeteoraDbcDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.meteora_dbc";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_METEORA_DBC_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad/moonit.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/moonit.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_moonit`.
+
+/// Reserved decoder for the `launchpad_moonit` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadMoonitDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadMoonitDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.moonit";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_MOONIT_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad/orca_wavebreak.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/orca_wavebreak.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_orca_wavebreak`.
+
+/// Reserved decoder for the `launchpad_orca_wavebreak` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadOrcaWavebreakDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadOrcaWavebreakDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.orca_wavebreak";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_ORCA_WAVEBREAK_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad/printr.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/printr.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_printr`.
+
+/// Reserved decoder for the `launchpad_printr` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadPrintrDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadPrintrDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.printr";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_PRINTR_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad/pump_fun.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/pump_fun.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_pump_fun`.
+
+/// Reserved decoder for the `launchpad_pump_fun` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadPumpFunDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadPumpFunDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.pump_fun";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_PUMP_FUN_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad/pump_pumpup_ai.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/pump_pumpup_ai.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_pump_pumpup_ai`.
+
+/// Reserved decoder for the `launchpad_pump_pumpup_ai` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadPumpPumpupAiDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadPumpPumpupAiDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.pump_pumpup_ai";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_PUMP_PUMPUP_AI_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad/raydium_launchlab.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/raydium_launchlab.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_raydium_launchlab`.
+
+/// Reserved decoder for the `launchpad_raydium_launchlab` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadRaydiumLaunchlabDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadRaydiumLaunchlabDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.raydium_launchlab";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_RAYDIUM_LAUNCHLAB_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/launchpad/virtuals.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/launchpad/virtuals.rs
+// version: 5
+
+//! Reserved protocol decoder for `launchpad_virtuals`.
+
+/// Reserved decoder for the `launchpad_virtuals` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLaunchpadVirtualsDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLaunchpadVirtualsDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.launchpad.virtuals";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LAUNCHPAD_VIRTUALS_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/lending.rs

@@ -0,0 +1,27 @@
+// file: ks-lib/src/decoder/lending.rs
+// version: 5
+
+//! `lending` decoder family.
+
+mod clone;
+mod jupiter_lend_borrow;
+mod jupiter_lend_earn;
+mod jupiter_lend_flash_loan;
+mod jupiter_lend_liquidity;
+mod kamino;
+mod marginfi_v2;
+
+/// Reserved `kb-lib.decoder.lending.clone` decoder.
+pub use self::clone::DcLendingCloneDecoder;
+/// Reserved `kb-lib.decoder.lending.jupiter_lend_borrow` decoder.
+pub use self::jupiter_lend_borrow::DcLendingJupiterLendBorrowDecoder;
+/// Reserved `kb-lib.decoder.lending.jupiter_lend_earn` decoder.
+pub use self::jupiter_lend_earn::DcLendingJupiterLendEarnDecoder;
+/// Reserved `kb-lib.decoder.lending.jupiter_lend_flash_loan` decoder.
+pub use self::jupiter_lend_flash_loan::DcLendingJupiterLendFlashLoanDecoder;
+/// Reserved `kb-lib.decoder.lending.jupiter_lend_liquidity` decoder.
+pub use self::jupiter_lend_liquidity::DcLendingJupiterLendLiquidityDecoder;
+/// Reserved `kb-lib.decoder.lending.kamino` decoder.
+pub use self::kamino::DcLendingKaminoDecoder;
+/// Reserved `kb-lib.decoder.lending.marginfi_v2` decoder.
+pub use self::marginfi_v2::DcLendingMarginfiV2Decoder;

ks-lib/src/decoder/lending/clone.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/lending/clone.rs
+// version: 5
+
+//! Reserved protocol decoder for `lending_clone`.
+
+/// Reserved decoder for the `lending_clone` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLendingCloneDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLendingCloneDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.lending.clone";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LENDING_CLONE_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/lending/jupiter_lend_borrow.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/lending/jupiter_lend_borrow.rs
+// version: 5
+
+//! Reserved protocol decoder for `lending_jupiter_lend_borrow`.
+
+/// Reserved decoder for the `lending_jupiter_lend_borrow` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLendingJupiterLendBorrowDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLendingJupiterLendBorrowDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.lending.jupiter_lend_borrow";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LENDING_JUPITER_LEND_BORROW_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/lending/jupiter_lend_earn.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/lending/jupiter_lend_earn.rs
+// version: 5
+
+//! Reserved protocol decoder for `lending_jupiter_lend_earn`.
+
+/// Reserved decoder for the `lending_jupiter_lend_earn` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLendingJupiterLendEarnDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLendingJupiterLendEarnDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.lending.jupiter_lend_earn";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LENDING_JUPITER_LEND_EARN_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/lending/jupiter_lend_flash_loan.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/lending/jupiter_lend_flash_loan.rs
+// version: 5
+
+//! Reserved protocol decoder for `lending_jupiter_lend_flash_loan`.
+
+/// Reserved decoder for the `lending_jupiter_lend_flash_loan` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLendingJupiterLendFlashLoanDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLendingJupiterLendFlashLoanDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.lending.jupiter_lend_flash_loan";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LENDING_JUPITER_LEND_FLASH_LOAN_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/lending/jupiter_lend_liquidity.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/lending/jupiter_lend_liquidity.rs
+// version: 5
+
+//! Reserved protocol decoder for `lending_jupiter_lend_liquidity`.
+
+/// Reserved decoder for the `lending_jupiter_lend_liquidity` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLendingJupiterLendLiquidityDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLendingJupiterLendLiquidityDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.lending.jupiter_lend_liquidity";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LENDING_JUPITER_LEND_LIQUIDITY_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/lending/kamino.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/lending/kamino.rs
+// version: 5
+
+//! Reserved protocol decoder for `lending_kamino`.
+
+/// Reserved decoder for the `lending_kamino` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLendingKaminoDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLendingKaminoDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.lending.kamino";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LENDING_KAMINO_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/lending/marginfi_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/lending/marginfi_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `lending_marginfi_v2`.
+
+/// Reserved decoder for the `lending_marginfi_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLendingMarginfiV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLendingMarginfiV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.lending.marginfi_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LENDING_MARGINFI_V2_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/lock.rs

@@ -0,0 +1,9 @@
+// file: ks-lib/src/decoder/lock.rs
+// version: 5
+
+//! `lock` decoder family.
+
+mod raydium_lp;
+
+/// Reserved `kb-lib.decoder.lock.raydium_lp` decoder.
+pub use self::raydium_lp::DcLockRaydiumLpDecoder;

ks-lib/src/decoder/lock/raydium_lp.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/lock/raydium_lp.rs
+// version: 5
+
+//! Reserved protocol decoder for `lock_raydium_lp`.
+
+/// Reserved decoder for the `lock_raydium_lp` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcLockRaydiumLpDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcLockRaydiumLpDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.lock.raydium_lp";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::LOCK_RAYDIUM_LP_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/metadata.rs

@@ -0,0 +1,310 @@
+// file: ks-lib/src/decoder/metadata.rs
+// version: 12
+
+//! `metadata` decoder family.
+
+mod metaplex_token_metadata;
+mod solana_program_metadata;
+mod spl_name_service;
+
+/// Exhaustive published Metaplex account-key inventory.
+pub use self::metaplex_token_metadata::DC_METADATA_MTM_METADATA_ACCOUNT_LAYOUT_AUDIT;
+/// Exact decoder for the Metaplex Token Metadata program.
+pub use self::metaplex_token_metadata::DcMetadataMetaplexTokenMetadataDecoder;
+/// Canonical projection shared by Collection and Use Authority records.
+pub use self::metaplex_token_metadata::DcMetadataMtmAuthorityRecordAccountSnapshot;
+/// Stable identity and policy of one canonical account snapshot.
+pub use self::metaplex_token_metadata::DcMetadataMtmCanonicalAccountIdentity;
+/// Lifecycle class of one canonical account layout.
+pub use self::metaplex_token_metadata::DcMetadataMtmCanonicalAccountLifecycle;
+/// Provenance retained for one canonical account observation.
+pub use self::metaplex_token_metadata::DcMetadataMtmCanonicalAccountProvenance;
+/// Execution policy separated from historical materialization.
+pub use self::metaplex_token_metadata::DcMetadataMtmCanonicalExecutionPolicy;
+/// Materialization policy for active or historical state.
+pub use self::metaplex_token_metadata::DcMetadataMtmCanonicalMaterializationPolicy;
+/// Canonical account envelope used by materializers and replay.
+pub use self::metaplex_token_metadata::DcMetadataMtmCanonicalMetadataAccountSnapshot;
+/// Typed canonical Metaplex account state.
+pub use self::metaplex_token_metadata::DcMetadataMtmCanonicalMetadataAccountState;
+/// Origin of one canonical account observation.
+pub use self::metaplex_token_metadata::DcMetadataMtmCanonicalObservationSource;
+/// Canonical projection shared by Metadata and Holder delegate records.
+pub use self::metaplex_token_metadata::DcMetadataMtmDelegateRecordAccountSnapshot;
+/// Supported edition account layout.
+pub use self::metaplex_token_metadata::DcMetadataMtmEditionAccountKind;
+/// Canonical bounded projection of one edition or master-edition account.
+pub use self::metaplex_token_metadata::DcMetadataMtmEditionAccountSnapshot;
+/// Supported Edition Marker account layout.
+pub use self::metaplex_token_metadata::DcMetadataMtmEditionMarkerAccountKind;
+/// Canonical bounded projection of one Edition Marker account.
+pub use self::metaplex_token_metadata::DcMetadataMtmEditionMarkerAccountSnapshot;
+/// Bounded error returned while decoding a Metadata account.
+pub use self::metaplex_token_metadata::DcMetadataMtmMetadataAccountDecodeError;
+/// One entry in the exhaustive published account-key audit.
+pub use self::metaplex_token_metadata::DcMetadataMtmMetadataAccountLayoutAuditEntry;
+/// Canonical bounded projection of one Metadata account.
+pub use self::metaplex_token_metadata::DcMetadataMtmMetadataAccountSnapshot;
+/// One bounded historical reservation entry.
+pub use self::metaplex_token_metadata::DcMetadataMtmReservationEntrySnapshot;
+/// Historical Reservation List account generation.
+pub use self::metaplex_token_metadata::DcMetadataMtmReservationListAccountKind;
+/// Canonical decode-only projection of a historical Reservation List account.
+pub use self::metaplex_token_metadata::DcMetadataMtmReservationListAccountSnapshot;
+/// Canonical projection of one Token Owned Escrow account.
+pub use self::metaplex_token_metadata::DcMetadataMtmTokenOwnedEscrowAccountSnapshot;
+/// Authority form used by one Token Owned Escrow account.
+pub use self::metaplex_token_metadata::DcMetadataMtmTokenOwnedEscrowAuthorityKind;
+/// Canonical bounded projection of one programmable Token Record account.
+pub use self::metaplex_token_metadata::DcMetadataMtmTokenRecordAccountSnapshot;
+/// Decodes one Collection Authority Record account.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_collection_authority_record_account;
+/// Decodes and validates one edition or master-edition account snapshot.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_edition_account;
+/// Decodes and validates one Edition Marker account snapshot.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_edition_marker_account;
+/// Decodes one Holder Delegate Record account.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_holder_delegate_record_account;
+/// Decodes and validates one canonical Metadata account snapshot.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_metadata_account;
+/// Decodes one Metadata Delegate Record account.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_metadata_delegate_record_account;
+/// Decodes one historical Reservation List V1 or V2 account.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_reservation_list_account;
+/// Decodes one Token Owned Escrow account.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_token_owned_escrow_account;
+/// Decodes and validates one programmable Token Record account snapshot.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_token_record_account;
+/// Decodes one Use Authority Record account.
+pub use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode_use_authority_record_account;
+/// Exact fixed byte length of one Buffer account header.
+pub use self::solana_program_metadata::DC_METADATA_SPM_BUFFER_HEADER_BYTES;
+/// Exact byte length of one external-account data reference.
+pub use self::solana_program_metadata::DC_METADATA_SPM_EXTERNAL_DATA_BYTES;
+/// Maximum Solana account-data length accepted by bounded account decoders.
+pub use self::solana_program_metadata::DC_METADATA_SPM_MAX_ACCOUNT_BYTES;
+/// Exact fixed byte length of one Metadata account header.
+pub use self::solana_program_metadata::DC_METADATA_SPM_METADATA_HEADER_BYTES;
+/// Exact byte length of one Solana Program Metadata seed.
+pub use self::solana_program_metadata::DC_METADATA_SPM_SEED_BYTES;
+/// Exact Solana Program Metadata instruction and account decoder.
+pub use self::solana_program_metadata::DcMetadataSolanaProgramMetadataDecoder;
+/// Error returned while decoding a Solana Program Metadata account.
+pub use self::solana_program_metadata::DcMetadataSpmAccountDecodeError;
+/// Solana Program Metadata account discriminator.
+pub use self::solana_program_metadata::DcMetadataSpmAccountDiscriminator;
+/// Supported bounded Solana Program Metadata account projection.
+pub use self::solana_program_metadata::DcMetadataSpmAccountSnapshot;
+/// Bounded projection of one Solana Program Metadata Buffer account.
+pub use self::solana_program_metadata::DcMetadataSpmBufferAccountSnapshot;
+/// Compression declared for Solana Program Metadata content.
+pub use self::solana_program_metadata::DcMetadataSpmCompression;
+/// Typed Solana Program Metadata content without off-chain resolution.
+pub use self::solana_program_metadata::DcMetadataSpmData;
+/// On-chain source used for Solana Program Metadata content.
+pub use self::solana_program_metadata::DcMetadataSpmDataSource;
+/// Encoding declared for Solana Program Metadata content.
+pub use self::solana_program_metadata::DcMetadataSpmEncoding;
+/// Fixed external-account data reference.
+pub use self::solana_program_metadata::DcMetadataSpmExternalData;
+/// Format declared for Solana Program Metadata content.
+pub use self::solana_program_metadata::DcMetadataSpmFormat;
+/// Bounded projection of one initialized Solana Program Metadata account.
+pub use self::solana_program_metadata::DcMetadataSpmMetadataAccountSnapshot;
+/// Bounded Solana Program Metadata model conversion error.
+pub use self::solana_program_metadata::DcMetadataSpmModelError;
+/// Official Solana Program Metadata custom error.
+pub use self::solana_program_metadata::DcMetadataSpmProgramError;
+/// Exact fixed-size Solana Program Metadata seed.
+pub use self::solana_program_metadata::DcMetadataSpmSeed;
+/// Decodes one supported Solana Program Metadata account by its discriminator.
+pub use self::solana_program_metadata::decoder_metadata_solana_program_metadata_decode_account;
+/// Decodes one Solana Program Metadata Buffer account.
+pub use self::solana_program_metadata::decoder_metadata_solana_program_metadata_decode_buffer_account;
+/// Decodes one initialized Solana Program Metadata account.
+pub use self::solana_program_metadata::decoder_metadata_solana_program_metadata_decode_metadata_account;
+/// Reserved `kb-lib.decoder.metadata.spl_name_service` decoder.
+pub use self::spl_name_service::DcMetadataSplNameServiceDecoder;
+
+/// Approve Collection Authority discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Approve Use Authority discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_APPROVE_USE_AUTHORITY_DISCRIMINATOR;
+/// Bubblegum Set Collection Size discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Burn discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_BURN_DISCRIMINATOR;
+/// Historical Burn Edition NFT discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_BURN_EDITION_NFT_DISCRIMINATOR;
+/// Historical Burn NFT discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_BURN_NFT_DISCRIMINATOR;
+/// Close Accounts discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CLOSE_ACCOUNTS_DISCRIMINATOR;
+/// Close Escrow Account discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Collect discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_COLLECT_DISCRIMINATOR;
+/// Convert Master Edition V1 to V2 discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR;
+/// Modern Create discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CREATE_DISCRIMINATOR;
+/// Create Escrow Account discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CREATE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Master Edition discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Create Master Edition V3 discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CREATE_MASTER_EDITION_V3_DISCRIMINATOR;
+/// Historical Create Metadata Account discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Metadata Account V2 discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Create Metadata Account V3 discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR;
+/// Delegate discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_DELEGATE_DISCRIMINATOR;
+/// Deprecated Create Master Edition discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Deprecated Create Reservation List discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR;
+/// Deprecated printing-token mint-new-edition discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens Via Token discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR;
+/// Deprecated Set Reservation List discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR;
+/// Number of bytes retained in malformed-wire diagnostics.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_DIAGNOSTIC_PREFIX_BYTES;
+/// Stable event payload contract version.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_EVENT_VERSION;
+/// Freeze Delegated Account discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Current pre-release instruction inventory.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_INSTRUCTION_ENTRIES;
+/// Lock discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_LOCK_DISCRIMINATOR;
+/// Maximum encoded base64 instruction payload size.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_MAX_BASE64_BYTES;
+/// Maximum number of instruction accounts accepted by this decoder.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_MAX_INSTRUCTION_ACCOUNTS;
+/// Maximum retained instruction payload size.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_MAX_INSTRUCTION_BYTES;
+/// Migrate discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_MIGRATE_DISCRIMINATOR;
+/// Modern Mint discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_MINT_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Token discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Vault Proxy discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR;
+/// Modern Print discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_PRINT_DISCRIMINATOR;
+/// Puff Metadata discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_PUFF_METADATA_DISCRIMINATOR;
+/// Remove Creator Verification discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR;
+/// Resize discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_RESIZE_DISCRIMINATOR;
+/// Revoke Collection Authority discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Revoke discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_REVOKE_DISCRIMINATOR;
+/// Revoke Use Authority discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_REVOKE_USE_AUTHORITY_DISCRIMINATOR;
+/// Set And Verify Collection discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_SET_AND_VERIFY_COLLECTION_DISCRIMINATOR;
+/// Set And Verify Sized Collection Item discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Set Collection Size discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Set Token Standard discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_SET_TOKEN_STANDARD_DISCRIMINATOR;
+/// Sign Metadata discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_SIGN_METADATA_DISCRIMINATOR;
+/// Stable decoder surface code.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_SURFACE_CODE;
+/// Thaw Delegated Account discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_THAW_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Transfer discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_TRANSFER_DISCRIMINATOR;
+/// Transfer Out Of Escrow discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR;
+/// Unlock discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_UNLOCK_DISCRIMINATOR;
+/// Unverify Collection discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_UNVERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Unverify discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_UNVERIFY_DISCRIMINATOR;
+/// Unverify Sized Collection Item discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Modern Update discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_UPDATE_DISCRIMINATOR;
+/// Historical Update Metadata Account discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Update Metadata Account V2 discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Update Primary Sale Happened Via Token discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR;
+/// Modern Use discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_USE_DISCRIMINATOR;
+/// Utilize discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_UTILIZE_DISCRIMINATOR;
+/// Verify Collection discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_VERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Verify discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_VERIFY_DISCRIMINATOR;
+/// Verify Sized Collection Item discriminator.
+pub(crate) use self::metaplex_token_metadata::DC_METADATA_MTM_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Canonical tracing target for this crate.
+pub(crate) use self::metaplex_token_metadata::TRACING_TARGET_DECODER_METADATA_METAPLEX_TOKEN_METADATA;
+/// Crate-root access to `decode` from `instruction`.
+pub(crate) use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_decode;
+/// Crate-root access to `entry_for_discriminator` from `instruction`.
+pub(crate) use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_entry_for_discriminator;
+/// Crate-root access to `payload_discriminator` from `instruction`.
+pub(crate) use self::metaplex_token_metadata::decoder_metadata_metaplex_token_metadata_payload_discriminator;
+/// Account contract for `Allocate`.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_ALLOCATE_ACCOUNT_CONTRACTS;
+/// Account contract for `Close`.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_CLOSE_ACCOUNT_CONTRACTS;
+/// Surfaces handled by the Solana Program Metadata decoder.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_DECODER_SURFACES;
+/// Maximum instruction prefix retained in hexadecimal diagnostics.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_DIAGNOSTIC_PREFIX_BYTES;
+/// Stable event schema version for decoded Solana Program Metadata instructions.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_EVENT_VERSION;
+/// Account contract for `Extend`.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_EXTEND_ACCOUNT_CONTRACTS;
+/// Account contract for `Initialize`.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_INITIALIZE_ACCOUNT_CONTRACTS;
+/// Current stable instruction inventory for program releases 1.0.0 and 1.0.1.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_INSTRUCTION_ENTRIES;
+/// Maximum instruction-account count accepted by the contextual decoder.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_MAX_INSTRUCTION_ACCOUNTS;
+/// Maximum retained instruction payload accepted by the contextual decoder.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_MAX_INSTRUCTION_BYTES;
+/// Program ids handled by the Solana Program Metadata decoder.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_PROGRAM_IDS;
+/// Account contract for `SetAuthority`.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_SET_AUTHORITY_ACCOUNT_CONTRACTS;
+/// Account contract for `SetData`.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_SET_DATA_ACCOUNT_CONTRACTS;
+/// Account contract for `SetImmutable`.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_SET_IMMUTABLE_ACCOUNT_CONTRACTS;
+/// Stable Solana Program Metadata decoder surface code.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_SURFACE_CODE;
+/// Account contract for `Trim`.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_TRIM_ACCOUNT_CONTRACTS;
+/// Account contract for `Write`.
+pub(crate) use self::solana_program_metadata::DC_METADATA_SPM_WRITE_ACCOUNT_CONTRACTS;
+/// Expected account role and privileges for one instruction position.
+pub(crate) use self::solana_program_metadata::DcMetadataSpmInstructionAccountContract;
+/// Canonical tracing target for the Solana Program Metadata decoder.
+pub(crate) use self::solana_program_metadata::TRACING_TARGET_DECODER_METADATA_SOLANA_PROGRAM_METADATA;
+/// Decodes one bounded Solana Program Metadata instruction.
+pub(crate) use self::solana_program_metadata::decoder_metadata_solana_program_metadata_decode;
+/// Returns the stable entry matching one Solana Program Metadata discriminator.
+pub(crate) use self::solana_program_metadata::decoder_metadata_solana_program_metadata_entry_for_discriminator;
+/// Returns the first byte of one retained Solana Program Metadata payload.
+pub(crate) use self::solana_program_metadata::decoder_metadata_solana_program_metadata_payload_discriminator;

ks-lib/src/decoder/metadata/metaplex_token_metadata.rs

@@ -0,0 +1,220 @@
+// file: ks-lib/src/decoder/metadata/metaplex_token_metadata.rs
+// version: 5
+
+//! Contextual instruction and bounded account decoder for Metaplex Token Metadata.
+
+mod account;
+mod canonical;
+mod constants;
+mod decoder;
+mod instruction;
+
+/// Exhaustive published Metaplex account-key inventory.
+pub use self::account::DC_METADATA_MTM_METADATA_ACCOUNT_LAYOUT_AUDIT;
+/// Canonical projection shared by Collection and Use Authority records.
+pub use self::account::DcMetadataMtmAuthorityRecordAccountSnapshot;
+/// Canonical projection shared by Metadata and Holder delegate records.
+pub use self::account::DcMetadataMtmDelegateRecordAccountSnapshot;
+/// Supported edition account layout.
+pub use self::account::DcMetadataMtmEditionAccountKind;
+/// Canonical bounded projection of one edition or master-edition account.
+pub use self::account::DcMetadataMtmEditionAccountSnapshot;
+/// Supported Edition Marker account layout.
+pub use self::account::DcMetadataMtmEditionMarkerAccountKind;
+/// Canonical bounded projection of one Edition Marker account.
+pub use self::account::DcMetadataMtmEditionMarkerAccountSnapshot;
+/// Bounded error returned while decoding a Metadata account.
+pub use self::account::DcMetadataMtmMetadataAccountDecodeError;
+/// One entry in the exhaustive published account-key audit.
+pub use self::account::DcMetadataMtmMetadataAccountLayoutAuditEntry;
+/// Canonical bounded projection of one Metadata account.
+pub use self::account::DcMetadataMtmMetadataAccountSnapshot;
+/// One bounded historical reservation entry.
+pub use self::account::DcMetadataMtmReservationEntrySnapshot;
+/// Historical Reservation List account generation.
+pub use self::account::DcMetadataMtmReservationListAccountKind;
+/// Canonical decode-only projection of a historical Reservation List account.
+pub use self::account::DcMetadataMtmReservationListAccountSnapshot;
+/// Canonical projection of one Token Owned Escrow account.
+pub use self::account::DcMetadataMtmTokenOwnedEscrowAccountSnapshot;
+/// Authority form used by one Token Owned Escrow account.
+pub use self::account::DcMetadataMtmTokenOwnedEscrowAuthorityKind;
+/// Canonical bounded projection of one programmable Token Record account.
+pub use self::account::DcMetadataMtmTokenRecordAccountSnapshot;
+/// Decodes one Collection Authority Record account.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_collection_authority_record_account;
+/// Decodes and validates one edition or master-edition account snapshot.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_edition_account;
+/// Decodes and validates one Edition Marker account snapshot.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_edition_marker_account;
+/// Decodes one Holder Delegate Record account.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_holder_delegate_record_account;
+/// Decodes and validates one canonical Metadata account snapshot.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_metadata_account;
+/// Decodes one Metadata Delegate Record account.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_metadata_delegate_record_account;
+/// Decodes one historical Reservation List V1 or V2 account.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_reservation_list_account;
+/// Decodes one Token Owned Escrow account.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_token_owned_escrow_account;
+/// Decodes and validates one programmable Token Record account snapshot.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_token_record_account;
+/// Decodes one Use Authority Record account.
+pub use self::account::decoder_metadata_metaplex_token_metadata_decode_use_authority_record_account;
+/// Stable identity and policy of one canonical account snapshot.
+pub use self::canonical::DcMetadataMtmCanonicalAccountIdentity;
+/// Lifecycle class of one canonical account layout.
+pub use self::canonical::DcMetadataMtmCanonicalAccountLifecycle;
+/// Provenance retained for one canonical account observation.
+pub use self::canonical::DcMetadataMtmCanonicalAccountProvenance;
+/// Execution policy separated from historical materialization.
+pub use self::canonical::DcMetadataMtmCanonicalExecutionPolicy;
+/// Materialization policy for active or historical state.
+pub use self::canonical::DcMetadataMtmCanonicalMaterializationPolicy;
+/// Canonical account envelope used by materializers and replay.
+pub use self::canonical::DcMetadataMtmCanonicalMetadataAccountSnapshot;
+/// Typed canonical Metaplex account state.
+pub use self::canonical::DcMetadataMtmCanonicalMetadataAccountState;
+/// Origin of one canonical account observation.
+pub use self::canonical::DcMetadataMtmCanonicalObservationSource;
+/// Exact Metaplex Token Metadata decoder.
+pub use self::decoder::DcMetadataMetaplexTokenMetadataDecoder;
+
+/// Approve Collection Authority discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Approve Use Authority discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_APPROVE_USE_AUTHORITY_DISCRIMINATOR;
+/// Bubblegum Set Collection Size discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Burn discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_BURN_DISCRIMINATOR;
+/// Historical Burn Edition NFT discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_BURN_EDITION_NFT_DISCRIMINATOR;
+/// Historical Burn NFT discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_BURN_NFT_DISCRIMINATOR;
+/// Close Accounts discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CLOSE_ACCOUNTS_DISCRIMINATOR;
+/// Close Escrow Account discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Collect discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_COLLECT_DISCRIMINATOR;
+/// Convert Master Edition V1 to V2 discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR;
+/// Modern Create discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CREATE_DISCRIMINATOR;
+/// Create Escrow Account discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CREATE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Master Edition discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Create Master Edition V3 discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CREATE_MASTER_EDITION_V3_DISCRIMINATOR;
+/// Historical Create Metadata Account discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Metadata Account V2 discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Create Metadata Account V3 discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR;
+/// Delegate discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_DELEGATE_DISCRIMINATOR;
+/// Deprecated Create Master Edition discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Deprecated Create Reservation List discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR;
+/// Deprecated printing-token mint-new-edition discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens Via Token discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR;
+/// Deprecated Set Reservation List discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR;
+/// Number of bytes retained in malformed-wire diagnostics.
+pub(crate) use self::constants::DC_METADATA_MTM_DIAGNOSTIC_PREFIX_BYTES;
+/// Stable event payload contract version.
+pub(crate) use self::constants::DC_METADATA_MTM_EVENT_VERSION;
+/// Freeze Delegated Account discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Current pre-release instruction inventory.
+pub(crate) use self::constants::DC_METADATA_MTM_INSTRUCTION_ENTRIES;
+/// Lock discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_LOCK_DISCRIMINATOR;
+/// Maximum encoded base64 instruction payload size.
+pub(crate) use self::constants::DC_METADATA_MTM_MAX_BASE64_BYTES;
+/// Maximum number of instruction accounts accepted by this decoder.
+pub(crate) use self::constants::DC_METADATA_MTM_MAX_INSTRUCTION_ACCOUNTS;
+/// Maximum retained instruction payload size.
+pub(crate) use self::constants::DC_METADATA_MTM_MAX_INSTRUCTION_BYTES;
+/// Migrate discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_MIGRATE_DISCRIMINATOR;
+/// Modern Mint discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_MINT_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Token discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Vault Proxy discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR;
+/// Modern Print discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_PRINT_DISCRIMINATOR;
+/// Puff Metadata discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_PUFF_METADATA_DISCRIMINATOR;
+/// Remove Creator Verification discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR;
+/// Resize discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_RESIZE_DISCRIMINATOR;
+/// Revoke Collection Authority discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Revoke discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_REVOKE_DISCRIMINATOR;
+/// Revoke Use Authority discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_REVOKE_USE_AUTHORITY_DISCRIMINATOR;
+/// Set And Verify Collection discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_SET_AND_VERIFY_COLLECTION_DISCRIMINATOR;
+/// Set And Verify Sized Collection Item discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Set Collection Size discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Set Token Standard discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_SET_TOKEN_STANDARD_DISCRIMINATOR;
+/// Sign Metadata discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_SIGN_METADATA_DISCRIMINATOR;
+/// Stable decoder surface code.
+pub(crate) use self::constants::DC_METADATA_MTM_SURFACE_CODE;
+/// Thaw Delegated Account discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_THAW_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Transfer discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_TRANSFER_DISCRIMINATOR;
+/// Transfer Out Of Escrow discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR;
+/// Unlock discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_UNLOCK_DISCRIMINATOR;
+/// Unverify Collection discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_UNVERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Unverify discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_UNVERIFY_DISCRIMINATOR;
+/// Unverify Sized Collection Item discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Modern Update discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_UPDATE_DISCRIMINATOR;
+/// Historical Update Metadata Account discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Update Metadata Account V2 discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Update Primary Sale Happened Via Token discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR;
+/// Modern Use discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_USE_DISCRIMINATOR;
+/// Utilize discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_UTILIZE_DISCRIMINATOR;
+/// Verify Collection discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_VERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Verify discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_VERIFY_DISCRIMINATOR;
+/// Verify Sized Collection Item discriminator.
+pub(crate) use self::constants::DC_METADATA_MTM_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Canonical tracing target for this crate.
+pub(crate) use self::constants::TRACING_TARGET_DECODER_METADATA_METAPLEX_TOKEN_METADATA;
+/// Crate-root access to `decode` from `instruction`.
+pub(crate) use self::instruction::decoder_metadata_metaplex_token_metadata_decode;
+/// Crate-root access to `entry_for_discriminator` from `instruction`.
+pub(crate) use self::instruction::decoder_metadata_metaplex_token_metadata_entry_for_discriminator;
+/// Crate-root access to `payload_discriminator` from `instruction`.
+pub(crate) use self::instruction::decoder_metadata_metaplex_token_metadata_payload_discriminator;

ks-lib/src/decoder/metadata/metaplex_token_metadata/canonical.rs

@@ -0,0 +1,441 @@
+// file: ks-lib/src/decoder/metadata/metaplex_token_metadata/canonical.rs
+// version: 3
+
+//! Canonical Metaplex account identities, provenance and materialization policy.
+
+/// Lifecycle class of one decoded Metaplex account layout.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum DcMetadataMtmCanonicalAccountLifecycle {
+    /// 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 DcMetadataMtmCanonicalMaterializationPolicy {
+    /// 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 DcMetadataMtmCanonicalExecutionPolicy {
+    /// 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 DcMetadataMtmCanonicalObservationSource {
+    /// 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 DcMetadataMtmCanonicalAccountProvenance {
+    /// Observation source.
+    pub source: DcMetadataMtmCanonicalObservationSource,
+    /// 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 DcMetadataMtmCanonicalAccountIdentity {
+    /// 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: DcMetadataMtmCanonicalAccountLifecycle,
+    /// Materialization policy, including historical backfill state.
+    pub materialization: DcMetadataMtmCanonicalMaterializationPolicy,
+    /// Execution policy separated from materialization.
+    pub execution: DcMetadataMtmCanonicalExecutionPolicy,
+}
+
+/// Typed state carried by one canonical Metaplex account snapshot.
+#[derive(Clone, Debug, PartialEq)]
+pub enum DcMetadataMtmCanonicalMetadataAccountState {
+    /// Metadata account state.
+    Metadata(crate::DcMetadataMtmMetadataAccountSnapshot),
+    /// Master Edition or printed Edition state.
+    Edition(crate::DcMetadataMtmEditionAccountSnapshot),
+    /// Edition Marker state.
+    EditionMarker(crate::DcMetadataMtmEditionMarkerAccountSnapshot),
+    /// Programmable Token Record state.
+    TokenRecord(crate::DcMetadataMtmTokenRecordAccountSnapshot),
+    /// Metadata or holder delegate state.
+    DelegateRecord(crate::DcMetadataMtmDelegateRecordAccountSnapshot),
+    /// Collection or use authority state.
+    AuthorityRecord(crate::DcMetadataMtmAuthorityRecordAccountSnapshot),
+    /// Token-owned escrow state.
+    TokenOwnedEscrow(crate::DcMetadataMtmTokenOwnedEscrowAccountSnapshot),
+    /// Historical Reservation List state.
+    ReservationList(crate::DcMetadataMtmReservationListAccountSnapshot),
+}
+
+/// Canonical envelope used by future materializers and stateful replay.
+#[derive(Clone, Debug, PartialEq)]
+pub struct DcMetadataMtmCanonicalMetadataAccountSnapshot {
+    /// Stable identity and lifecycle policy.
+    pub identity: DcMetadataMtmCanonicalAccountIdentity,
+    /// Observation provenance.
+    pub provenance: DcMetadataMtmCanonicalAccountProvenance,
+    /// Typed bounded state.
+    pub state: DcMetadataMtmCanonicalMetadataAccountState,
+}
+
+fn canonical_identity(
+    account: &str,
+    layout: &str,
+    discriminant: u8,
+    lifecycle: DcMetadataMtmCanonicalAccountLifecycle,
+) -> DcMetadataMtmCanonicalAccountIdentity {
+    let program_id = ks_program_ids::METADATA_METAPLEX_TOKEN_METADATA_PROGRAM_ID.to_string();
+    let materialization = match lifecycle {
+        DcMetadataMtmCanonicalAccountLifecycle::Historical => {
+            DcMetadataMtmCanonicalMaterializationPolicy::HistoricalState
+        },
+        DcMetadataMtmCanonicalAccountLifecycle::Active
+        | DcMetadataMtmCanonicalAccountLifecycle::ActiveExperimental => {
+            DcMetadataMtmCanonicalMaterializationPolicy::ActiveState
+        },
+    };
+    let execution = match lifecycle {
+        DcMetadataMtmCanonicalAccountLifecycle::Historical => {
+            DcMetadataMtmCanonicalExecutionPolicy::NeverHistorical
+        },
+        DcMetadataMtmCanonicalAccountLifecycle::Active => {
+            DcMetadataMtmCanonicalExecutionPolicy::CurrentCandidate
+        },
+        DcMetadataMtmCanonicalAccountLifecycle::ActiveExperimental => {
+            DcMetadataMtmCanonicalExecutionPolicy::ExperimentalCandidate
+        },
+    };
+    return DcMetadataMtmCanonicalAccountIdentity {
+        stable_id: format!("{program_id}:{account}"),
+        program_id,
+        account: account.to_string(),
+        layout: layout.to_string(),
+        discriminant,
+        canonical_version: 1,
+        lifecycle,
+        materialization,
+        execution,
+    };
+}
+
+impl DcMetadataMtmCanonicalMetadataAccountSnapshot {
+    /// Wraps one Metadata account snapshot with stable identity and provenance.
+    pub fn from_metadata(
+        snapshot: crate::DcMetadataMtmMetadataAccountSnapshot,
+        provenance: DcMetadataMtmCanonicalAccountProvenance,
+    ) -> Self {
+        let identity = canonical_identity(
+            &snapshot.account,
+            "MetadataV1",
+            mpl_token_metadata::types::Key::MetadataV1 as u8,
+            DcMetadataMtmCanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: DcMetadataMtmCanonicalMetadataAccountState::Metadata(snapshot),
+        };
+    }
+
+    /// Wraps one Edition or Master Edition snapshot with exact lifecycle policy.
+    pub fn from_edition(
+        snapshot: crate::DcMetadataMtmEditionAccountSnapshot,
+        provenance: DcMetadataMtmCanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant, lifecycle) = match snapshot.kind {
+            crate::DcMetadataMtmEditionAccountKind::MasterEditionV1 => (
+                "MasterEditionV1",
+                mpl_token_metadata::types::Key::MasterEditionV1 as u8,
+                DcMetadataMtmCanonicalAccountLifecycle::Historical,
+            ),
+            crate::DcMetadataMtmEditionAccountKind::MasterEditionV2 => (
+                "MasterEditionV2",
+                mpl_token_metadata::types::Key::MasterEditionV2 as u8,
+                DcMetadataMtmCanonicalAccountLifecycle::Active,
+            ),
+            crate::DcMetadataMtmEditionAccountKind::EditionV1 => (
+                "EditionV1",
+                mpl_token_metadata::types::Key::EditionV1 as u8,
+                DcMetadataMtmCanonicalAccountLifecycle::Active,
+            ),
+        };
+        let identity = canonical_identity(&snapshot.account, layout, discriminant, lifecycle);
+        return Self {
+            identity,
+            provenance,
+            state: DcMetadataMtmCanonicalMetadataAccountState::Edition(snapshot),
+        };
+    }
+
+    /// Wraps one Edition Marker snapshot with exact lifecycle policy.
+    pub fn from_edition_marker(
+        snapshot: crate::DcMetadataMtmEditionMarkerAccountSnapshot,
+        provenance: DcMetadataMtmCanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant, lifecycle) = match snapshot.kind {
+            crate::DcMetadataMtmEditionMarkerAccountKind::EditionMarkerV1 => (
+                "EditionMarker",
+                mpl_token_metadata::types::Key::EditionMarker as u8,
+                DcMetadataMtmCanonicalAccountLifecycle::Active,
+            ),
+            crate::DcMetadataMtmEditionMarkerAccountKind::EditionMarkerV2 => (
+                "EditionMarkerV2",
+                mpl_token_metadata::types::Key::EditionMarkerV2 as u8,
+                DcMetadataMtmCanonicalAccountLifecycle::ActiveExperimental,
+            ),
+        };
+        let identity = canonical_identity(&snapshot.account, layout, discriminant, lifecycle);
+        return Self {
+            identity,
+            provenance,
+            state: DcMetadataMtmCanonicalMetadataAccountState::EditionMarker(snapshot),
+        };
+    }
+
+    /// Wraps one Token Record snapshot.
+    pub fn from_token_record(
+        snapshot: crate::DcMetadataMtmTokenRecordAccountSnapshot,
+        provenance: DcMetadataMtmCanonicalAccountProvenance,
+    ) -> Self {
+        let identity = canonical_identity(
+            &snapshot.account,
+            "TokenRecord",
+            mpl_token_metadata::types::Key::TokenRecord as u8,
+            DcMetadataMtmCanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: DcMetadataMtmCanonicalMetadataAccountState::TokenRecord(snapshot),
+        };
+    }
+
+    /// Wraps one Metadata or Holder Delegate snapshot.
+    pub fn from_delegate_record(
+        snapshot: crate::DcMetadataMtmDelegateRecordAccountSnapshot,
+        provenance: DcMetadataMtmCanonicalAccountProvenance,
+    ) -> 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,
+            DcMetadataMtmCanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: DcMetadataMtmCanonicalMetadataAccountState::DelegateRecord(snapshot),
+        };
+    }
+
+    /// Wraps one Collection or Use Authority snapshot.
+    pub fn from_authority_record(
+        snapshot: crate::DcMetadataMtmAuthorityRecordAccountSnapshot,
+        provenance: DcMetadataMtmCanonicalAccountProvenance,
+    ) -> 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,
+            DcMetadataMtmCanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: DcMetadataMtmCanonicalMetadataAccountState::AuthorityRecord(snapshot),
+        };
+    }
+
+    /// Wraps one Token Owned Escrow snapshot.
+    pub fn from_token_owned_escrow(
+        snapshot: crate::DcMetadataMtmTokenOwnedEscrowAccountSnapshot,
+        provenance: DcMetadataMtmCanonicalAccountProvenance,
+    ) -> Self {
+        let identity = canonical_identity(
+            &snapshot.account,
+            "TokenOwnedEscrow",
+            mpl_token_metadata::types::Key::TokenOwnedEscrow as u8,
+            DcMetadataMtmCanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: DcMetadataMtmCanonicalMetadataAccountState::TokenOwnedEscrow(snapshot),
+        };
+    }
+
+    /// Wraps one historical Reservation List snapshot as materializable historical state.
+    pub fn from_reservation_list(
+        snapshot: crate::DcMetadataMtmReservationListAccountSnapshot,
+        provenance: DcMetadataMtmCanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant) = match snapshot.kind {
+            crate::DcMetadataMtmReservationListAccountKind::V1 => {
+                ("ReservationListV1", mpl_token_metadata::types::Key::ReservationListV1 as u8)
+            },
+            crate::DcMetadataMtmReservationListAccountKind::V2 => {
+                ("ReservationListV2", mpl_token_metadata::types::Key::ReservationListV2 as u8)
+            },
+        };
+        let identity = canonical_identity(
+            &snapshot.account,
+            layout,
+            discriminant,
+            DcMetadataMtmCanonicalAccountLifecycle::Historical,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: DcMetadataMtmCanonicalMetadataAccountState::ReservationList(snapshot),
+        };
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn historical_state_is_materializable_but_never_executable() {
+        let snapshot = crate::DcMetadataMtmReservationListAccountSnapshot {
+            account: "reservation-account".to_string(),
+            bump: 1,
+            kind: crate::DcMetadataMtmReservationListAccountKind::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::DcMetadataMtmCanonicalAccountProvenance {
+            source: super::DcMetadataMtmCanonicalObservationSource::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::DcMetadataMtmCanonicalMetadataAccountSnapshot::from_reservation_list(
+            snapshot, provenance,
+        );
+        assert_eq!(
+            canonical.identity.lifecycle,
+            super::DcMetadataMtmCanonicalAccountLifecycle::Historical
+        );
+        assert_eq!(
+            canonical.identity.materialization,
+            super::DcMetadataMtmCanonicalMaterializationPolicy::HistoricalState
+        );
+        assert_eq!(
+            canonical.identity.execution,
+            super::DcMetadataMtmCanonicalExecutionPolicy::NeverHistorical
+        );
+        assert_eq!(
+            canonical.provenance.source,
+            super::DcMetadataMtmCanonicalObservationSource::Backfill
+        );
+        assert!(canonical.identity.stable_id.ends_with(":reservation-account"));
+    }
+
+    #[test]
+    fn active_and_experimental_layouts_keep_distinct_policies() {
+        let metadata = crate::DcMetadataMtmMetadataAccountSnapshot {
+            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::DcMetadataMtmCanonicalAccountProvenance {
+            source: super::DcMetadataMtmCanonicalObservationSource::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::DcMetadataMtmCanonicalMetadataAccountSnapshot::from_metadata(
+            metadata, provenance,
+        );
+        assert_eq!(
+            canonical.identity.lifecycle,
+            super::DcMetadataMtmCanonicalAccountLifecycle::Active
+        );
+        assert_eq!(
+            canonical.identity.materialization,
+            super::DcMetadataMtmCanonicalMaterializationPolicy::ActiveState
+        );
+        assert_eq!(
+            canonical.identity.execution,
+            super::DcMetadataMtmCanonicalExecutionPolicy::CurrentCandidate
+        );
+        assert_eq!(canonical.identity.discriminant, 4);
+        assert_eq!(canonical.identity.canonical_version, 1);
+    }
+}

ks-lib/src/decoder/metadata/metaplex_token_metadata/constants.rs

@@ -0,0 +1,328 @@
+// file: ks-lib/src/decoder/metadata/metaplex_token_metadata/constants.rs
+// version: 32
+
+//! Internal constants for Metaplex Token Metadata decoding.
+
+/// Stable decoder surface code.
+pub(crate) const DC_METADATA_MTM_SURFACE_CODE: &str = "metadata.metaplex_token_metadata";
+/// Maximum retained instruction payload size.
+pub(crate) const DC_METADATA_MTM_MAX_INSTRUCTION_BYTES: usize = 16_384;
+/// Maximum encoded base64 instruction payload size.
+pub(crate) const DC_METADATA_MTM_MAX_BASE64_BYTES: usize = 21_852;
+/// Maximum number of instruction accounts accepted by this decoder.
+pub(crate) const DC_METADATA_MTM_MAX_INSTRUCTION_ACCOUNTS: usize = 64;
+/// Number of bytes retained in malformed-wire diagnostics.
+pub(crate) const DC_METADATA_MTM_DIAGNOSTIC_PREFIX_BYTES: usize = 32;
+/// Stable event payload contract version.
+pub(crate) const DC_METADATA_MTM_EVENT_VERSION: u32 = 1;
+/// Deprecated Create Master Edition discriminator.
+pub(crate) const DC_METADATA_MTM_DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR: u8 = 2;
+/// Deprecated Set Reservation List discriminator.
+pub(crate) const DC_METADATA_MTM_DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR: u8 = 5;
+/// Deprecated Create Reservation List discriminator.
+pub(crate) const DC_METADATA_MTM_DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR: u8 = 6;
+/// Deprecated Mint Printing Tokens Via Token discriminator.
+pub(crate) const DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR: u8 = 8;
+/// Deprecated Mint Printing Tokens discriminator.
+pub(crate) const DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR: u8 = 9;
+/// Historical Create Master Edition discriminator.
+pub(crate) const DC_METADATA_MTM_CREATE_MASTER_EDITION_DISCRIMINATOR: u8 = 10;
+/// Deprecated printing-token mint-new-edition discriminator.
+pub(crate) const DC_METADATA_MTM_DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR: u8 =
+    3;
+/// Historical Create Metadata Account discriminator.
+pub(crate) const DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_DISCRIMINATOR: u8 = 0;
+/// Historical Update Metadata Account discriminator.
+pub(crate) const DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_DISCRIMINATOR: u8 = 1;
+/// Historical Create Metadata Account V2 discriminator.
+pub(crate) const DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR: u8 = 16;
+/// Create Metadata Account V3 discriminator.
+pub(crate) const DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR: u8 = 33;
+/// Update Metadata Account V2 discriminator.
+pub(crate) const DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR: u8 = 15;
+/// Verify Collection discriminator.
+pub(crate) const DC_METADATA_MTM_VERIFY_COLLECTION_DISCRIMINATOR: u8 = 18;
+/// Unverify Collection discriminator.
+pub(crate) const DC_METADATA_MTM_UNVERIFY_COLLECTION_DISCRIMINATOR: u8 = 22;
+/// Set And Verify Collection discriminator.
+pub(crate) const DC_METADATA_MTM_SET_AND_VERIFY_COLLECTION_DISCRIMINATOR: u8 = 25;
+/// Approve Collection Authority discriminator.
+pub(crate) const DC_METADATA_MTM_APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR: u8 = 23;
+/// Revoke Collection Authority discriminator.
+pub(crate) const DC_METADATA_MTM_REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR: u8 = 24;
+/// Verify Sized Collection Item discriminator.
+pub(crate) const DC_METADATA_MTM_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR: u8 = 30;
+/// Unverify Sized Collection Item discriminator.
+pub(crate) const DC_METADATA_MTM_UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR: u8 = 31;
+/// Set And Verify Sized Collection Item discriminator.
+pub(crate) const DC_METADATA_MTM_SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR: u8 = 32;
+/// Sign Metadata discriminator.
+pub(crate) const DC_METADATA_MTM_SIGN_METADATA_DISCRIMINATOR: u8 = 7;
+/// Update Primary Sale Happened Via Token discriminator.
+pub(crate) const DC_METADATA_MTM_UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR: u8 = 4;
+/// Utilize discriminator.
+pub(crate) const DC_METADATA_MTM_UTILIZE_DISCRIMINATOR: u8 = 19;
+/// Approve Use Authority discriminator.
+pub(crate) const DC_METADATA_MTM_APPROVE_USE_AUTHORITY_DISCRIMINATOR: u8 = 20;
+/// Revoke Use Authority discriminator.
+pub(crate) const DC_METADATA_MTM_REVOKE_USE_AUTHORITY_DISCRIMINATOR: u8 = 21;
+/// Puff Metadata discriminator.
+pub(crate) const DC_METADATA_MTM_PUFF_METADATA_DISCRIMINATOR: u8 = 14;
+/// Freeze Delegated Account discriminator.
+pub(crate) const DC_METADATA_MTM_FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR: u8 = 26;
+/// Thaw Delegated Account discriminator.
+pub(crate) const DC_METADATA_MTM_THAW_DELEGATED_ACCOUNT_DISCRIMINATOR: u8 = 27;
+/// Remove Creator Verification discriminator.
+pub(crate) const DC_METADATA_MTM_REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR: u8 = 28;
+/// Set Token Standard discriminator.
+pub(crate) const DC_METADATA_MTM_SET_TOKEN_STANDARD_DISCRIMINATOR: u8 = 35;
+/// Mint New Edition From Master Edition Via Token discriminator.
+pub(crate) const DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR: u8 =
+    11;
+/// Mint New Edition From Master Edition Via Vault Proxy discriminator.
+pub(crate) const DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR: u8 = 13;
+/// Convert Master Edition V1 to V2 discriminator.
+pub(crate) const DC_METADATA_MTM_CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR: u8 = 12;
+/// Create Master Edition V3 discriminator.
+pub(crate) const DC_METADATA_MTM_CREATE_MASTER_EDITION_V3_DISCRIMINATOR: u8 = 17;
+/// Set Collection Size discriminator.
+pub(crate) const DC_METADATA_MTM_SET_COLLECTION_SIZE_DISCRIMINATOR: u8 = 34;
+/// Bubblegum Set Collection Size discriminator.
+pub(crate) const DC_METADATA_MTM_BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR: u8 = 36;
+/// Create Escrow Account discriminator.
+pub(crate) const DC_METADATA_MTM_CREATE_ESCROW_ACCOUNT_DISCRIMINATOR: u8 = 38;
+/// Close Escrow Account discriminator.
+pub(crate) const DC_METADATA_MTM_CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR: u8 = 39;
+/// Transfer Out Of Escrow discriminator.
+pub(crate) const DC_METADATA_MTM_TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR: u8 = 40;
+/// Collect discriminator.
+pub(crate) const DC_METADATA_MTM_COLLECT_DISCRIMINATOR: u8 = 54;
+/// Historical Burn NFT discriminator.
+pub(crate) const DC_METADATA_MTM_BURN_NFT_DISCRIMINATOR: u8 = 29;
+/// Historical Burn Edition NFT discriminator.
+pub(crate) const DC_METADATA_MTM_BURN_EDITION_NFT_DISCRIMINATOR: u8 = 37;
+/// Burn discriminator.
+pub(crate) const DC_METADATA_MTM_BURN_DISCRIMINATOR: u8 = 41;
+/// Lock discriminator.
+pub(crate) const DC_METADATA_MTM_LOCK_DISCRIMINATOR: u8 = 46;
+/// Unlock discriminator.
+pub(crate) const DC_METADATA_MTM_UNLOCK_DISCRIMINATOR: u8 = 47;
+/// Transfer discriminator.
+pub(crate) const DC_METADATA_MTM_TRANSFER_DISCRIMINATOR: u8 = 49;
+/// Close Accounts discriminator.
+pub(crate) const DC_METADATA_MTM_CLOSE_ACCOUNTS_DISCRIMINATOR: u8 = 57;
+/// Modern Create discriminator.
+pub(crate) const DC_METADATA_MTM_CREATE_DISCRIMINATOR: u8 = 42;
+/// Modern Mint discriminator.
+pub(crate) const DC_METADATA_MTM_MINT_DISCRIMINATOR: u8 = 43;
+/// Modern Print discriminator.
+pub(crate) const DC_METADATA_MTM_PRINT_DISCRIMINATOR: u8 = 55;
+/// Modern Update discriminator.
+pub(crate) const DC_METADATA_MTM_UPDATE_DISCRIMINATOR: u8 = 50;
+/// Modern Use discriminator.
+pub(crate) const DC_METADATA_MTM_USE_DISCRIMINATOR: u8 = 51;
+/// Modern Verify discriminator.
+pub(crate) const DC_METADATA_MTM_VERIFY_DISCRIMINATOR: u8 = 52;
+/// Modern Unverify discriminator.
+pub(crate) const DC_METADATA_MTM_UNVERIFY_DISCRIMINATOR: u8 = 53;
+/// Migrate discriminator.
+pub(crate) const DC_METADATA_MTM_MIGRATE_DISCRIMINATOR: u8 = 48;
+/// Resize discriminator.
+pub(crate) const DC_METADATA_MTM_RESIZE_DISCRIMINATOR: u8 = 56;
+/// Delegate discriminator.
+pub(crate) const DC_METADATA_MTM_DELEGATE_DISCRIMINATOR: u8 = 44;
+/// Revoke discriminator.
+pub(crate) const DC_METADATA_MTM_REVOKE_DISCRIMINATOR: u8 = 45;
+/// Current pre-release instruction inventory.
+pub(crate) const DC_METADATA_MTM_INSTRUCTION_ENTRIES: &[(u8, &str, bool)] = &[
+    (
+        DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_DISCRIMINATOR,
+        "create_metadata_account",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR,
+        "deprecated_create_master_edition",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR,
+        "deprecated_mint_new_edition_from_master_edition_via_printing_token",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_DISCRIMINATOR,
+        "update_metadata_account",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR,
+        "update_primary_sale_happened_via_token",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR,
+        "deprecated_set_reservation_list",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR,
+        "deprecated_create_reservation_list",
+        true,
+    ),
+    (DC_METADATA_MTM_SIGN_METADATA_DISCRIMINATOR, "sign_metadata", false),
+    (
+        DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR,
+        "deprecated_mint_printing_tokens_via_token",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR,
+        "deprecated_mint_printing_tokens",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_CREATE_MASTER_EDITION_DISCRIMINATOR,
+        "create_master_edition",
+        true,
+    ),
+    (DC_METADATA_MTM_PUFF_METADATA_DISCRIMINATOR, "puff_metadata", false),
+    (
+        DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR,
+        "mint_new_edition_from_master_edition_via_token",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR,
+        "mint_new_edition_from_master_edition_via_vault_proxy",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR,
+        "convert_master_edition_v1_to_v2",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR,
+        "update_metadata_account_v2",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR,
+        "create_metadata_account_v2",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_CREATE_MASTER_EDITION_V3_DISCRIMINATOR,
+        "create_master_edition_v3",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR,
+        "create_metadata_account_v3",
+        false,
+    ),
+    (DC_METADATA_MTM_VERIFY_COLLECTION_DISCRIMINATOR, "verify_collection", false),
+    (DC_METADATA_MTM_UNVERIFY_COLLECTION_DISCRIMINATOR, "unverify_collection", false),
+    (
+        DC_METADATA_MTM_SET_AND_VERIFY_COLLECTION_DISCRIMINATOR,
+        "set_and_verify_collection",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR,
+        "approve_collection_authority",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR,
+        "revoke_collection_authority",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR,
+        "verify_sized_collection_item",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR,
+        "unverify_sized_collection_item",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR,
+        "set_and_verify_sized_collection_item",
+        false,
+    ),
+    (DC_METADATA_MTM_UTILIZE_DISCRIMINATOR, "utilize", false),
+    (
+        DC_METADATA_MTM_APPROVE_USE_AUTHORITY_DISCRIMINATOR,
+        "approve_use_authority",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_REVOKE_USE_AUTHORITY_DISCRIMINATOR,
+        "revoke_use_authority",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR,
+        "freeze_delegated_account",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_THAW_DELEGATED_ACCOUNT_DISCRIMINATOR,
+        "thaw_delegated_account",
+        true,
+    ),
+    (
+        DC_METADATA_MTM_REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR,
+        "remove_creator_verification",
+        false,
+    ),
+    (DC_METADATA_MTM_SET_TOKEN_STANDARD_DISCRIMINATOR, "set_token_standard", false),
+    (DC_METADATA_MTM_SET_COLLECTION_SIZE_DISCRIMINATOR, "set_collection_size", false),
+    (
+        DC_METADATA_MTM_BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR,
+        "bubblegum_set_collection_size",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_CREATE_ESCROW_ACCOUNT_DISCRIMINATOR,
+        "create_escrow_account",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR,
+        "close_escrow_account",
+        false,
+    ),
+    (
+        DC_METADATA_MTM_TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR,
+        "transfer_out_of_escrow",
+        false,
+    ),
+    (DC_METADATA_MTM_BURN_NFT_DISCRIMINATOR, "burn_nft", true),
+    (DC_METADATA_MTM_BURN_EDITION_NFT_DISCRIMINATOR, "burn_edition_nft", true),
+    (DC_METADATA_MTM_BURN_DISCRIMINATOR, "burn", false),
+    (DC_METADATA_MTM_CREATE_DISCRIMINATOR, "create", false),
+    (DC_METADATA_MTM_MINT_DISCRIMINATOR, "mint", false),
+    (DC_METADATA_MTM_LOCK_DISCRIMINATOR, "lock", false),
+    (DC_METADATA_MTM_UNLOCK_DISCRIMINATOR, "unlock", false),
+    (DC_METADATA_MTM_TRANSFER_DISCRIMINATOR, "transfer", false),
+    (DC_METADATA_MTM_COLLECT_DISCRIMINATOR, "collect", false),
+    (DC_METADATA_MTM_PRINT_DISCRIMINATOR, "print", false),
+    (DC_METADATA_MTM_UPDATE_DISCRIMINATOR, "update", false),
+    (DC_METADATA_MTM_USE_DISCRIMINATOR, "use", false),
+    (DC_METADATA_MTM_VERIFY_DISCRIMINATOR, "verify", false),
+    (DC_METADATA_MTM_UNVERIFY_DISCRIMINATOR, "unverify", false),
+    (DC_METADATA_MTM_MIGRATE_DISCRIMINATOR, "migrate", false),
+    (DC_METADATA_MTM_RESIZE_DISCRIMINATOR, "resize", false),
+    (DC_METADATA_MTM_CLOSE_ACCOUNTS_DISCRIMINATOR, "close_accounts", false),
+    (DC_METADATA_MTM_DELEGATE_DISCRIMINATOR, "delegate", false),
+    (DC_METADATA_MTM_REVOKE_DISCRIMINATOR, "revoke", false),
+];
+
+/// Canonical tracing target for this decoder.
+pub(crate) const TRACING_TARGET_DECODER_METADATA_METAPLEX_TOKEN_METADATA: &str =
+    "kb-lib.decoder.metadata.metaplex_token_metadata";

ks-lib/src/decoder/metadata/solana_program_metadata.rs

@@ -0,0 +1,102 @@
+// file: ks-lib/src/decoder/metadata/solana_program_metadata.rs
+// version: 6
+
+//! Public Solana Program Metadata models and exact account and instruction decoders.
+
+mod account;
+mod constants;
+mod decoder;
+mod instruction;
+mod model;
+
+/// Error returned while decoding a Solana Program Metadata account.
+pub use self::account::DcMetadataSpmAccountDecodeError;
+/// Supported bounded Solana Program Metadata account projection.
+pub use self::account::DcMetadataSpmAccountSnapshot;
+/// Bounded projection of one Solana Program Metadata Buffer account.
+pub use self::account::DcMetadataSpmBufferAccountSnapshot;
+/// Bounded projection of one initialized Solana Program Metadata account.
+pub use self::account::DcMetadataSpmMetadataAccountSnapshot;
+/// Decodes one supported Solana Program Metadata account by its discriminator.
+pub use self::account::decoder_metadata_solana_program_metadata_decode_account;
+/// Decodes one Solana Program Metadata Buffer account.
+pub use self::account::decoder_metadata_solana_program_metadata_decode_buffer_account;
+/// Decodes one initialized Solana Program Metadata account.
+pub use self::account::decoder_metadata_solana_program_metadata_decode_metadata_account;
+/// Exact fixed byte length of one Buffer account header.
+pub use self::constants::DC_METADATA_SPM_BUFFER_HEADER_BYTES;
+/// Exact byte length of one external-account data reference.
+pub use self::constants::DC_METADATA_SPM_EXTERNAL_DATA_BYTES;
+/// Maximum Solana account-data length accepted by bounded account decoders.
+pub use self::constants::DC_METADATA_SPM_MAX_ACCOUNT_BYTES;
+/// Exact fixed byte length of one Metadata account header.
+pub use self::constants::DC_METADATA_SPM_METADATA_HEADER_BYTES;
+/// Exact byte length of one Solana Program Metadata seed.
+pub use self::constants::DC_METADATA_SPM_SEED_BYTES;
+/// Exact decoder for Solana Program Metadata instructions and account snapshots.
+pub use self::decoder::DcMetadataSolanaProgramMetadataDecoder;
+/// Solana Program Metadata account discriminator.
+pub use self::model::DcMetadataSpmAccountDiscriminator;
+/// Compression declared for metadata content.
+pub use self::model::DcMetadataSpmCompression;
+/// Typed on-chain metadata content without off-chain resolution.
+pub use self::model::DcMetadataSpmData;
+/// On-chain source used for metadata content.
+pub use self::model::DcMetadataSpmDataSource;
+/// Encoding declared for metadata content.
+pub use self::model::DcMetadataSpmEncoding;
+/// Fixed external-account data reference.
+pub use self::model::DcMetadataSpmExternalData;
+/// Format declared for metadata content.
+pub use self::model::DcMetadataSpmFormat;
+/// Bounded model conversion error.
+pub use self::model::DcMetadataSpmModelError;
+/// Official Solana Program Metadata custom error.
+pub use self::model::DcMetadataSpmProgramError;
+/// Exact fixed-size metadata seed.
+pub use self::model::DcMetadataSpmSeed;
+
+/// Account contract for `Allocate`.
+pub(crate) use self::constants::DC_METADATA_SPM_ALLOCATE_ACCOUNT_CONTRACTS;
+/// Account contract for `Close`.
+pub(crate) use self::constants::DC_METADATA_SPM_CLOSE_ACCOUNT_CONTRACTS;
+/// Surfaces handled by the Solana Program Metadata decoder.
+pub(crate) use self::constants::DC_METADATA_SPM_DECODER_SURFACES;
+/// Maximum instruction prefix retained in hexadecimal diagnostics.
+pub(crate) use self::constants::DC_METADATA_SPM_DIAGNOSTIC_PREFIX_BYTES;
+/// Stable event schema version for decoded Solana Program Metadata instructions.
+pub(crate) use self::constants::DC_METADATA_SPM_EVENT_VERSION;
+/// Account contract for `Extend`.
+pub(crate) use self::constants::DC_METADATA_SPM_EXTEND_ACCOUNT_CONTRACTS;
+/// Account contract for `Initialize`.
+pub(crate) use self::constants::DC_METADATA_SPM_INITIALIZE_ACCOUNT_CONTRACTS;
+/// Current stable instruction inventory for program releases 1.0.0 and 1.0.1.
+pub(crate) use self::constants::DC_METADATA_SPM_INSTRUCTION_ENTRIES;
+/// Maximum instruction-account count accepted by the contextual decoder.
+pub(crate) use self::constants::DC_METADATA_SPM_MAX_INSTRUCTION_ACCOUNTS;
+/// Maximum retained instruction payload accepted by the contextual decoder.
+pub(crate) use self::constants::DC_METADATA_SPM_MAX_INSTRUCTION_BYTES;
+/// Program ids handled by the Solana Program Metadata decoder.
+pub(crate) use self::constants::DC_METADATA_SPM_PROGRAM_IDS;
+/// Account contract for `SetAuthority`.
+pub(crate) use self::constants::DC_METADATA_SPM_SET_AUTHORITY_ACCOUNT_CONTRACTS;
+/// Account contract for `SetData`.
+pub(crate) use self::constants::DC_METADATA_SPM_SET_DATA_ACCOUNT_CONTRACTS;
+/// Account contract for `SetImmutable`.
+pub(crate) use self::constants::DC_METADATA_SPM_SET_IMMUTABLE_ACCOUNT_CONTRACTS;
+/// Stable Solana Program Metadata decoder surface code.
+pub(crate) use self::constants::DC_METADATA_SPM_SURFACE_CODE;
+/// Account contract for `Trim`.
+pub(crate) use self::constants::DC_METADATA_SPM_TRIM_ACCOUNT_CONTRACTS;
+/// Account contract for `Write`.
+pub(crate) use self::constants::DC_METADATA_SPM_WRITE_ACCOUNT_CONTRACTS;
+/// Expected account role and privileges for one instruction position.
+pub(crate) use self::constants::DcMetadataSpmInstructionAccountContract;
+/// Canonical tracing target for the Solana Program Metadata decoder.
+pub(crate) use self::constants::TRACING_TARGET_DECODER_METADATA_SOLANA_PROGRAM_METADATA;
+/// Decodes one bounded Solana Program Metadata instruction.
+pub(crate) use self::instruction::decoder_metadata_solana_program_metadata_decode;
+/// Returns the stable entry matching one Solana Program Metadata discriminator.
+pub(crate) use self::instruction::decoder_metadata_solana_program_metadata_entry_for_discriminator;
+/// Returns the first byte of one retained Solana Program Metadata payload.
+pub(crate) use self::instruction::decoder_metadata_solana_program_metadata_payload_discriminator;

ks-lib/src/decoder/metadata/solana_program_metadata/constants.rs

@@ -0,0 +1,341 @@
+// file: ks-lib/src/decoder/metadata/solana_program_metadata/constants.rs
+// version: 5
+
+//! Bounded Solana Program Metadata wire and decoder constants.
+
+/// Expected account role and privileges for one instruction position.
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct DcMetadataSpmInstructionAccountContract {
+    pub(crate) role: &'static str,
+    pub(crate) signer: bool,
+    pub(crate) writable: bool,
+    pub(crate) optional: bool,
+}
+
+/// Exact byte length of one Solana Program Metadata seed.
+pub const DC_METADATA_SPM_SEED_BYTES: usize = 16;
+/// Exact fixed byte length of one Buffer account header.
+pub const DC_METADATA_SPM_BUFFER_HEADER_BYTES: usize = 96;
+/// Exact fixed byte length of one Metadata account header.
+pub const DC_METADATA_SPM_METADATA_HEADER_BYTES: usize = 96;
+/// Exact byte length of one external-account data reference.
+pub const DC_METADATA_SPM_EXTERNAL_DATA_BYTES: usize = 40;
+/// Maximum Solana account-data length accepted by bounded account decoders.
+pub const DC_METADATA_SPM_MAX_ACCOUNT_BYTES: usize = 10_485_760;
+/// Maximum retained instruction payload accepted by the contextual decoder.
+pub(crate) const DC_METADATA_SPM_MAX_INSTRUCTION_BYTES: usize = 16_384;
+/// Maximum instruction-account count accepted by the contextual decoder.
+pub(crate) const DC_METADATA_SPM_MAX_INSTRUCTION_ACCOUNTS: usize = 16;
+/// Maximum instruction prefix retained in hexadecimal diagnostics.
+pub(crate) const DC_METADATA_SPM_DIAGNOSTIC_PREFIX_BYTES: usize = 64;
+/// Stable Solana Program Metadata decoder surface code.
+pub(crate) const DC_METADATA_SPM_SURFACE_CODE: &str = "metadata.solana_program_metadata";
+/// Stable event schema version for decoded Solana Program Metadata instructions.
+pub(crate) const DC_METADATA_SPM_EVENT_VERSION: u16 = 1;
+/// Current stable instruction inventory for program releases 1.0.0 and 1.0.1.
+pub(crate) const DC_METADATA_SPM_INSTRUCTION_ENTRIES: &[(u8, &str)] = &[
+    (0, "write"),
+    (1, "initialize"),
+    (2, "set_authority"),
+    (3, "set_data"),
+    (4, "set_immutable"),
+    (5, "trim"),
+    (6, "close"),
+    (7, "allocate"),
+    (8, "extend"),
+];
+/// Program ids handled by the Solana Program Metadata decoder.
+pub(crate) const DC_METADATA_SPM_PROGRAM_IDS: &[&str] =
+    &[ks_program_ids::METADATA_SOLANA_PROGRAM_METADATA_PROGRAM_ID];
+/// Surfaces handled by the Solana Program Metadata decoder.
+pub(crate) const DC_METADATA_SPM_DECODER_SURFACES: &[crate::DcApiDecoderSurface] =
+    &[crate::DcApiDecoderSurface {
+        program_id: ks_program_ids::METADATA_SOLANA_PROGRAM_METADATA_PROGRAM_ID,
+        surface_code: crate::DC_METADATA_SPM_SURFACE_CODE,
+        priority: 100,
+    }];
+/// Account contract for `Write`.
+pub(crate) const DC_METADATA_SPM_WRITE_ACCOUNT_CONTRACTS:
+    &[crate::DcMetadataSpmInstructionAccountContract] = &[
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "buffer",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "authority",
+        signer: true,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "source_buffer",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+];
+/// Account contract for `Initialize`.
+pub(crate) const DC_METADATA_SPM_INITIALIZE_ACCOUNT_CONTRACTS:
+    &[crate::DcMetadataSpmInstructionAccountContract] = &[
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "metadata",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "authority",
+        signer: true,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program",
+        signer: false,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program_data",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "system_program",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+];
+/// Account contract for `SetAuthority`.
+pub(crate) const DC_METADATA_SPM_SET_AUTHORITY_ACCOUNT_CONTRACTS:
+    &[crate::DcMetadataSpmInstructionAccountContract] = &[
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "account",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "authority",
+        signer: true,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program_data",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+];
+/// Account contract for `SetData`.
+pub(crate) const DC_METADATA_SPM_SET_DATA_ACCOUNT_CONTRACTS:
+    &[crate::DcMetadataSpmInstructionAccountContract] = &[
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "metadata",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "authority",
+        signer: true,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "buffer",
+        signer: false,
+        writable: true,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program_data",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+];
+/// Account contract for `SetImmutable`.
+pub(crate) const DC_METADATA_SPM_SET_IMMUTABLE_ACCOUNT_CONTRACTS:
+    &[crate::DcMetadataSpmInstructionAccountContract] = &[
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "metadata",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "authority",
+        signer: true,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program_data",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+];
+/// Account contract for `Trim`.
+pub(crate) const DC_METADATA_SPM_TRIM_ACCOUNT_CONTRACTS:
+    &[crate::DcMetadataSpmInstructionAccountContract] = &[
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "account",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "authority",
+        signer: true,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program_data",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "destination",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "rent_sysvar",
+        signer: false,
+        writable: false,
+        optional: false,
+    },
+];
+/// Account contract for `Close`.
+pub(crate) const DC_METADATA_SPM_CLOSE_ACCOUNT_CONTRACTS:
+    &[crate::DcMetadataSpmInstructionAccountContract] = &[
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "account",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "authority",
+        signer: true,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program_data",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "destination",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+];
+/// Account contract for `Allocate`.
+pub(crate) const DC_METADATA_SPM_ALLOCATE_ACCOUNT_CONTRACTS:
+    &[crate::DcMetadataSpmInstructionAccountContract] = &[
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "buffer",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "authority",
+        signer: true,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program_data",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "system_program",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+];
+/// Account contract for `Extend`.
+pub(crate) const DC_METADATA_SPM_EXTEND_ACCOUNT_CONTRACTS:
+    &[crate::DcMetadataSpmInstructionAccountContract] = &[
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "account",
+        signer: false,
+        writable: true,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "authority",
+        signer: true,
+        writable: false,
+        optional: false,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+    crate::DcMetadataSpmInstructionAccountContract {
+        role: "program_data",
+        signer: false,
+        writable: false,
+        optional: true,
+    },
+];
+/// Canonical tracing target for the Solana Program Metadata decoder.
+pub(crate) const TRACING_TARGET_DECODER_METADATA_SOLANA_PROGRAM_METADATA: &str =
+    "kb-lib.decoder.metadata.solana_program_metadata";

ks-lib/src/decoder/metadata/solana_program_metadata/decoder.rs

@@ -0,0 +1,134 @@
+// file: ks-lib/src/decoder/metadata/solana_program_metadata/decoder.rs
+// version: 2
+
+//! Exact contextual dispatch for Solana Program Metadata.
+
+/// Exact decoder for Solana Program Metadata instructions and account snapshots.
+#[derive(Clone, Debug, Default)]
+pub struct DcMetadataSolanaProgramMetadataDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcMetadataSolanaProgramMetadataDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.metadata.solana_program_metadata";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return crate::DC_METADATA_SPM_PROGRAM_IDS;
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        return if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            crate::DcApiDecoderSupport::Yes
+        } else {
+            crate::DcApiDecoderSupport::No
+        };
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}
+
+impl crate::DcApiInstructionDecoder for crate::DcMetadataSolanaProgramMetadataDecoder {
+    fn identity(&self) -> crate::DcApiDecoderIdentity {
+        return crate::DcApiDecoderIdentity {
+            name: crate::DC_METADATA_SPM_SURFACE_CODE.to_string(),
+            version: env!("CARGO_PKG_VERSION").to_string(),
+        };
+    }
+
+    fn surfaces(&self) -> &'static [crate::DcApiDecoderSurface] {
+        return crate::DC_METADATA_SPM_DECODER_SURFACES;
+    }
+
+    fn coverage(&self) -> std::vec::Vec<crate::DcApiDecoderCoverageDeclaration> {
+        return crate::DC_METADATA_SPM_INSTRUCTION_ENTRIES
+            .iter()
+            .map(|(tag, code)| {
+                return crate::DcApiDecoderCoverageDeclaration {
+                    program_id: ks_program_ids::METADATA_SOLANA_PROGRAM_METADATA_PROGRAM_ID
+                        .to_string(),
+                    surface_code: std::option::Option::Some(
+                        crate::DC_METADATA_SPM_SURFACE_CODE.to_string(),
+                    ),
+                    entry_kind: crate::DcApiDecoderCoverageEntryKind::Instruction,
+                    entry_code: (*code).to_string(),
+                    discriminator_hex: std::option::Option::Some(format!("{tag:02x}")),
+                    historical: false,
+                };
+            })
+            .collect();
+    }
+
+    fn recognize(
+        &self,
+        input: &crate::MdCoreInstructionReplayInput,
+    ) -> crate::DcApiDecoderRecognition {
+        if input.program_id != ks_program_ids::METADATA_SOLANA_PROGRAM_METADATA_PROGRAM_ID {
+            return crate::DcApiDecoderRecognition::incompatible();
+        }
+        let discriminator =
+            crate::decoder_metadata_solana_program_metadata_payload_discriminator(input);
+        let entry = discriminator
+            .and_then(crate::decoder_metadata_solana_program_metadata_entry_for_discriminator);
+        return crate::DcApiDecoderRecognition::compatible(
+            entry.is_some(),
+            100,
+            std::option::Option::Some(crate::DC_METADATA_SPM_SURFACE_CODE.to_string()),
+            entry.map(|(_, code)| return code.to_string()),
+            discriminator.map(|value| return format!("{value:02x}")),
+        );
+    }
+
+    fn decode(
+        &self,
+        input: &crate::MdCoreInstructionReplayInput,
+    ) -> crate::DcApiDecoderExecutionResult {
+        if input.program_id != ks_program_ids::METADATA_SOLANA_PROGRAM_METADATA_PROGRAM_ID {
+            return crate::DcApiDecoderExecutionResult::unsupported(std::option::Option::None);
+        }
+        let result = crate::decoder_metadata_solana_program_metadata_decode(input);
+        if matches!(
+            result.status,
+            crate::DcApiDecoderOutcomeStatus::Failed
+                | crate::DcApiDecoderOutcomeStatus::Unsupported
+        ) {
+            tracing::error!(
+                target: crate::TRACING_TARGET_DECODER_METADATA_SOLANA_PROGRAM_METADATA,
+                action = "decode_failure",
+                signature = %input.signature,
+                slot = input.slot,
+                instruction_path = %input.instruction_path,
+                program_id = %input.program_id,
+                processor_name = crate::DC_METADATA_SPM_SURFACE_CODE,
+                processor_version = env!("CARGO_PKG_VERSION"),
+                input_key = %input.replay_input_key,
+                transaction_failed = input.transaction_failed,
+                result_status = ?result.status,
+                diagnostics = ?result.diagnostics,
+                "Solana Program Metadata instruction was not decoded successfully"
+            );
+        }
+        tracing::debug!(
+            target: crate::TRACING_TARGET_DECODER_METADATA_SOLANA_PROGRAM_METADATA,
+            action = "decode",
+            signature = %input.signature,
+            instruction_path = %input.instruction_path,
+            transaction_failed = input.transaction_failed,
+            result_status = ?result.status,
+            observation_count = result.observations.len(),
+            "Solana Program Metadata instruction decode completed"
+        );
+        return result;
+    }
+}

ks-lib/src/decoder/metadata/solana_program_metadata/model.rs

@@ -0,0 +1,716 @@
+// file: ks-lib/src/decoder/metadata/solana_program_metadata/model.rs
+// version: 4
+
+//! Public bounded models for the Solana Program Metadata wire contract.
+
+/// Solana Program Metadata account discriminator.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[repr(u8)]
+#[serde(rename_all = "snake_case")]
+pub enum DcMetadataSpmAccountDiscriminator {
+    /// Uninitialized account data.
+    Empty = 0,
+    /// Writable staging buffer.
+    Buffer = 1,
+    /// Initialized program metadata account.
+    Metadata = 2,
+}
+
+impl DcMetadataSpmAccountDiscriminator {
+    /// Returns the exact wire discriminant.
+    pub const fn wire_value(self) -> u8 {
+        return self as u8;
+    }
+
+    /// Resolves an exact wire discriminant.
+    pub fn from_wire_value(value: u8) -> std::result::Result<Self, crate::DcMetadataSpmModelError> {
+        return match value {
+            0 => std::result::Result::Ok(Self::Empty),
+            1 => std::result::Result::Ok(Self::Buffer),
+            2 => std::result::Result::Ok(Self::Metadata),
+            _ => std::result::Result::Err(
+                crate::DcMetadataSpmModelError::UnknownAccountDiscriminator { value },
+            ),
+        };
+    }
+}
+
+/// Encoding declared for metadata content.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[repr(u8)]
+#[serde(rename_all = "snake_case")]
+pub enum DcMetadataSpmEncoding {
+    /// No content encoding is declared.
+    None = 0,
+    /// UTF-8 content encoding.
+    Utf8 = 1,
+    /// Base58 content encoding.
+    Base58 = 2,
+    /// Base64 content encoding.
+    Base64 = 3,
+}
+
+impl DcMetadataSpmEncoding {
+    /// Returns the exact wire discriminant.
+    pub const fn wire_value(self) -> u8 {
+        return self as u8;
+    }
+
+    /// Resolves an exact wire discriminant.
+    pub fn from_wire_value(value: u8) -> std::result::Result<Self, crate::DcMetadataSpmModelError> {
+        return match value {
+            0 => std::result::Result::Ok(Self::None),
+            1 => std::result::Result::Ok(Self::Utf8),
+            2 => std::result::Result::Ok(Self::Base58),
+            3 => std::result::Result::Ok(Self::Base64),
+            _ => {
+                std::result::Result::Err(crate::DcMetadataSpmModelError::UnknownEncoding { value })
+            },
+        };
+    }
+}
+
+/// Compression declared for metadata content.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[repr(u8)]
+#[serde(rename_all = "snake_case")]
+pub enum DcMetadataSpmCompression {
+    /// No content compression is declared.
+    None = 0,
+    /// Gzip content compression.
+    Gzip = 1,
+    /// Zlib content compression.
+    Zlib = 2,
+}
+
+impl DcMetadataSpmCompression {
+    /// Returns the exact wire discriminant.
+    pub const fn wire_value(self) -> u8 {
+        return self as u8;
+    }
+
+    /// Resolves an exact wire discriminant.
+    pub fn from_wire_value(value: u8) -> std::result::Result<Self, crate::DcMetadataSpmModelError> {
+        return match value {
+            0 => std::result::Result::Ok(Self::None),
+            1 => std::result::Result::Ok(Self::Gzip),
+            2 => std::result::Result::Ok(Self::Zlib),
+            _ => std::result::Result::Err(crate::DcMetadataSpmModelError::UnknownCompression {
+                value,
+            }),
+        };
+    }
+}
+
+/// Format declared for metadata content.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[repr(u8)]
+#[serde(rename_all = "snake_case")]
+pub enum DcMetadataSpmFormat {
+    /// No structured content format is declared.
+    None = 0,
+    /// JSON content format.
+    Json = 1,
+    /// YAML content format.
+    Yaml = 2,
+    /// TOML content format.
+    Toml = 3,
+}
+
+impl DcMetadataSpmFormat {
+    /// Returns the exact wire discriminant.
+    pub const fn wire_value(self) -> u8 {
+        return self as u8;
+    }
+
+    /// Resolves an exact wire discriminant.
+    pub fn from_wire_value(value: u8) -> std::result::Result<Self, crate::DcMetadataSpmModelError> {
+        return match value {
+            0 => std::result::Result::Ok(Self::None),
+            1 => std::result::Result::Ok(Self::Json),
+            2 => std::result::Result::Ok(Self::Yaml),
+            3 => std::result::Result::Ok(Self::Toml),
+            _ => std::result::Result::Err(crate::DcMetadataSpmModelError::UnknownFormat { value }),
+        };
+    }
+}
+
+/// On-chain source used for metadata content.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[repr(u8)]
+#[serde(rename_all = "snake_case")]
+pub enum DcMetadataSpmDataSource {
+    /// Content bytes are stored directly after the account header.
+    Direct = 0,
+    /// A UTF-8 URL is stored after the account header.
+    Url = 1,
+    /// A fixed external-account reference is stored after the account header.
+    External = 2,
+}
+
+impl DcMetadataSpmDataSource {
+    /// Returns the exact wire discriminant.
+    pub const fn wire_value(self) -> u8 {
+        return self as u8;
+    }
+
+    /// Resolves an exact wire discriminant.
+    pub fn from_wire_value(value: u8) -> std::result::Result<Self, crate::DcMetadataSpmModelError> {
+        return match value {
+            0 => std::result::Result::Ok(Self::Direct),
+            1 => std::result::Result::Ok(Self::Url),
+            2 => std::result::Result::Ok(Self::External),
+            _ => std::result::Result::Err(crate::DcMetadataSpmModelError::UnknownDataSource {
+                value,
+            }),
+        };
+    }
+}
+
+/// Official custom error returned by the Solana Program Metadata program.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[repr(u32)]
+#[serde(rename_all = "snake_case")]
+pub enum DcMetadataSpmProgramError {
+    /// The referenced program account is not executable.
+    NotExecutableAccount = 0,
+    /// The referenced upgradeable-program state is invalid.
+    InvalidProgramState = 1,
+    /// The referenced program-data account is invalid.
+    InvalidProgramDataAccount = 2,
+    /// The metadata account is immutable.
+    ImmutableMetadataAccount = 3,
+    /// The metadata data length is invalid for its source.
+    InvalidDataLength = 4,
+}
+
+impl DcMetadataSpmProgramError {
+    /// Returns the exact custom program error code.
+    pub const fn code(self) -> u32 {
+        return self as u32;
+    }
+
+    /// Resolves an exact custom program error code.
+    pub fn from_code(value: u32) -> std::result::Result<Self, crate::DcMetadataSpmModelError> {
+        return match value {
+            0 => std::result::Result::Ok(Self::NotExecutableAccount),
+            1 => std::result::Result::Ok(Self::InvalidProgramState),
+            2 => std::result::Result::Ok(Self::InvalidProgramDataAccount),
+            3 => std::result::Result::Ok(Self::ImmutableMetadataAccount),
+            4 => std::result::Result::Ok(Self::InvalidDataLength),
+            _ => std::result::Result::Err(crate::DcMetadataSpmModelError::UnknownProgramError {
+                value,
+            }),
+        };
+    }
+}
+
+/// Exact fixed-size seed carried by PDA derivations and account headers.
+#[derive(
+    Clone, Copy, Debug, Default, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize,
+)]
+#[serde(transparent)]
+pub struct DcMetadataSpmSeed([u8; crate::DC_METADATA_SPM_SEED_BYTES]);
+
+impl DcMetadataSpmSeed {
+    /// Creates a seed from its exact fixed-size wire representation.
+    pub const fn from_bytes(bytes: [u8; crate::DC_METADATA_SPM_SEED_BYTES]) -> Self {
+        return Self(bytes);
+    }
+
+    /// Creates a zero-padded fixed-size seed from one UTF-8 value.
+    pub fn from_utf8(value: &str) -> std::result::Result<Self, crate::DcMetadataSpmModelError> {
+        let source = value.as_bytes();
+        if source.len() > crate::DC_METADATA_SPM_SEED_BYTES {
+            return std::result::Result::Err(crate::DcMetadataSpmModelError::SeedUtf8TooLong {
+                actual_bytes: source.len(),
+                max_bytes: crate::DC_METADATA_SPM_SEED_BYTES,
+            });
+        }
+        let mut bytes = [0_u8; crate::DC_METADATA_SPM_SEED_BYTES];
+        bytes[..source.len()].copy_from_slice(source);
+        return std::result::Result::Ok(Self(bytes));
+    }
+
+    /// Parses an exact fixed-size wire slice.
+    pub fn from_wire_bytes(
+        bytes: &[u8],
+    ) -> std::result::Result<Self, crate::DcMetadataSpmModelError> {
+        if bytes.len() != crate::DC_METADATA_SPM_SEED_BYTES {
+            return std::result::Result::Err(crate::DcMetadataSpmModelError::InvalidSeedLength {
+                actual_bytes: bytes.len(),
+                expected_bytes: crate::DC_METADATA_SPM_SEED_BYTES,
+            });
+        }
+        let mut seed = [0_u8; crate::DC_METADATA_SPM_SEED_BYTES];
+        seed.copy_from_slice(bytes);
+        return std::result::Result::Ok(Self(seed));
+    }
+
+    /// Returns the exact fixed-size wire representation.
+    pub const fn as_bytes(&self) -> &[u8; crate::DC_METADATA_SPM_SEED_BYTES] {
+        return &self.0;
+    }
+
+    /// Returns the UTF-8 value after removing only terminal zero padding.
+    pub fn trimmed_utf8(&self) -> std::result::Result<&str, crate::DcMetadataSpmModelError> {
+        let mut length = self.0.len();
+        while length > 0 && self.0[length - 1] == 0 {
+            length -= 1;
+        }
+        return match std::str::from_utf8(&self.0[..length]) {
+            std::result::Result::Ok(value) => std::result::Result::Ok(value),
+            std::result::Result::Err(_) => {
+                std::result::Result::Err(crate::DcMetadataSpmModelError::InvalidSeedUtf8)
+            },
+        };
+    }
+}
+
+/// Fixed external-account data reference used by the `External` data source.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct DcMetadataSpmExternalData {
+    /// Account that stores the referenced data.
+    pub address: solana_pubkey::Pubkey,
+    /// Byte offset inside the external account.
+    pub offset: u32,
+    /// Optional non-zero byte length; `None` is encoded as zero and means the whole account.
+    pub length: std::option::Option<std::num::NonZeroU32>,
+}
+
+impl DcMetadataSpmExternalData {
+    /// Creates an exact external-account reference.
+    pub const fn new(
+        address: solana_pubkey::Pubkey,
+        offset: u32,
+        length: std::option::Option<std::num::NonZeroU32>,
+    ) -> Self {
+        return Self { address, offset, length };
+    }
+
+    /// Creates an external-account reference from a zeroable optional length.
+    pub fn from_zeroable_length(address: solana_pubkey::Pubkey, offset: u32, length: u32) -> Self {
+        return Self::new(address, offset, std::num::NonZeroU32::new(length));
+    }
+
+    /// Serializes the exact 40-byte little-endian wire representation.
+    pub fn to_wire_bytes(&self) -> [u8; crate::DC_METADATA_SPM_EXTERNAL_DATA_BYTES] {
+        let mut bytes = [0_u8; crate::DC_METADATA_SPM_EXTERNAL_DATA_BYTES];
+        bytes[..32].copy_from_slice(&self.address.to_bytes());
+        bytes[32..36].copy_from_slice(&self.offset.to_le_bytes());
+        let length = match self.length {
+            std::option::Option::Some(value) => value.get(),
+            std::option::Option::None => 0,
+        };
+        bytes[36..40].copy_from_slice(&length.to_le_bytes());
+        return bytes;
+    }
+
+    /// Parses the exact 40-byte little-endian wire representation.
+    pub fn from_wire_bytes(
+        bytes: &[u8],
+    ) -> std::result::Result<Self, crate::DcMetadataSpmModelError> {
+        if bytes.len() != crate::DC_METADATA_SPM_EXTERNAL_DATA_BYTES {
+            return std::result::Result::Err(
+                crate::DcMetadataSpmModelError::InvalidExternalDataLength {
+                    actual_bytes: bytes.len(),
+                    expected_bytes: crate::DC_METADATA_SPM_EXTERNAL_DATA_BYTES,
+                },
+            );
+        }
+        let mut address = [0_u8; 32];
+        address.copy_from_slice(&bytes[..32]);
+        let mut offset = [0_u8; 4];
+        offset.copy_from_slice(&bytes[32..36]);
+        let mut length = [0_u8; 4];
+        length.copy_from_slice(&bytes[36..40]);
+        return std::result::Result::Ok(Self::from_zeroable_length(
+            solana_pubkey::Pubkey::new_from_array(address),
+            u32::from_le_bytes(offset),
+            u32::from_le_bytes(length),
+        ));
+    }
+}
+
+/// Typed on-chain metadata content without off-chain resolution.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(tag = "source", content = "value", rename_all = "snake_case")]
+pub enum DcMetadataSpmData {
+    /// Raw content stored directly in the metadata account.
+    Direct(std::vec::Vec<u8>),
+    /// UTF-8 URL stored directly in the metadata account.
+    Url(String),
+    /// Fixed reference to data stored in another account.
+    External(crate::DcMetadataSpmExternalData),
+}
+
+impl DcMetadataSpmData {
+    /// Returns the source discriminator associated with this content.
+    pub const fn source(&self) -> crate::DcMetadataSpmDataSource {
+        return match self {
+            Self::Direct(_) => crate::DcMetadataSpmDataSource::Direct,
+            Self::Url(_) => crate::DcMetadataSpmDataSource::Url,
+            Self::External(_) => crate::DcMetadataSpmDataSource::External,
+        };
+    }
+
+    /// Validates source-specific length requirements and the `u32` header bound.
+    pub fn validate(&self) -> std::result::Result<(), crate::DcMetadataSpmModelError> {
+        let actual_bytes = self.wire_byte_len();
+        match self {
+            Self::Direct(_) | Self::Url(_) if actual_bytes == 0 => {
+                return std::result::Result::Err(crate::DcMetadataSpmModelError::EmptyData {
+                    source: self.source(),
+                });
+            },
+            Self::Direct(_) | Self::Url(_) | Self::External(_) => {},
+        }
+        if u32::try_from(actual_bytes).is_err() {
+            return std::result::Result::Err(
+                crate::DcMetadataSpmModelError::DataLengthExceedsU32 { actual_bytes },
+            );
+        }
+        return std::result::Result::Ok(());
+    }
+
+    /// Returns the exact number of bytes represented on wire.
+    pub fn wire_byte_len(&self) -> usize {
+        return match self {
+            Self::Direct(value) => value.len(),
+            Self::Url(value) => value.len(),
+            Self::External(_) => crate::DC_METADATA_SPM_EXTERNAL_DATA_BYTES,
+        };
+    }
+
+    /// Returns the exact little-endian header length after validation.
+    pub fn wire_length_u32(&self) -> std::result::Result<u32, crate::DcMetadataSpmModelError> {
+        match self.validate() {
+            std::result::Result::Ok(()) => {},
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        }
+        let actual_bytes = self.wire_byte_len();
+        return match u32::try_from(actual_bytes) {
+            std::result::Result::Ok(value) => std::result::Result::Ok(value),
+            std::result::Result::Err(_) => {
+                std::result::Result::Err(crate::DcMetadataSpmModelError::DataLengthExceedsU32 {
+                    actual_bytes,
+                })
+            },
+        };
+    }
+
+    /// Serializes the exact content bytes without fetching URL or external-account data.
+    pub fn to_wire_bytes(
+        &self,
+    ) -> std::result::Result<std::vec::Vec<u8>, crate::DcMetadataSpmModelError> {
+        match self.validate() {
+            std::result::Result::Ok(()) => {},
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        }
+        return match self {
+            Self::Direct(value) => std::result::Result::Ok(value.clone()),
+            Self::Url(value) => std::result::Result::Ok(value.as_bytes().to_vec()),
+            Self::External(value) => std::result::Result::Ok(value.to_wire_bytes().to_vec()),
+        };
+    }
+}
+
+/// Bounded error for Solana Program Metadata public model conversions.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum DcMetadataSpmModelError {
+    /// An account discriminator is outside the published closed enum.
+    UnknownAccountDiscriminator {
+        /// Rejected wire value.
+        value: u8,
+    },
+    /// An encoding discriminator is outside the published closed enum.
+    UnknownEncoding {
+        /// Rejected wire value.
+        value: u8,
+    },
+    /// A compression discriminator is outside the published closed enum.
+    UnknownCompression {
+        /// Rejected wire value.
+        value: u8,
+    },
+    /// A format discriminator is outside the published closed enum.
+    UnknownFormat {
+        /// Rejected wire value.
+        value: u8,
+    },
+    /// A data-source discriminator is outside the published closed enum.
+    UnknownDataSource {
+        /// Rejected wire value.
+        value: u8,
+    },
+    /// A custom program error code is outside the published closed enum.
+    UnknownProgramError {
+        /// Rejected custom error code.
+        value: u32,
+    },
+    /// One UTF-8 seed exceeds the exact fixed-size wire bound.
+    SeedUtf8TooLong {
+        /// Actual UTF-8 byte length.
+        actual_bytes: usize,
+        /// Maximum accepted UTF-8 byte length.
+        max_bytes: usize,
+    },
+    /// One seed slice does not have the exact fixed-size wire length.
+    InvalidSeedLength {
+        /// Actual slice length.
+        actual_bytes: usize,
+        /// Required fixed length.
+        expected_bytes: usize,
+    },
+    /// The non-padding seed bytes are not valid UTF-8.
+    InvalidSeedUtf8,
+    /// One external-data slice does not have the exact fixed-size wire length.
+    InvalidExternalDataLength {
+        /// Actual slice length.
+        actual_bytes: usize,
+        /// Required fixed length.
+        expected_bytes: usize,
+    },
+    /// Direct or URL content is empty.
+    EmptyData {
+        /// Source whose data is empty.
+        source: crate::DcMetadataSpmDataSource,
+    },
+    /// Content cannot be represented by the `u32` length stored in the account header.
+    DataLengthExceedsU32 {
+        /// Actual content byte length.
+        actual_bytes: usize,
+    },
+}
+
+impl std::fmt::Display for DcMetadataSpmModelError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return match self {
+            Self::UnknownAccountDiscriminator { value } => {
+                write!(formatter, "unknown account discriminator {value}")
+            },
+            Self::UnknownEncoding { value } => {
+                write!(formatter, "unknown encoding discriminator {value}")
+            },
+            Self::UnknownCompression { value } => {
+                write!(formatter, "unknown compression discriminator {value}")
+            },
+            Self::UnknownFormat { value } => {
+                write!(formatter, "unknown format discriminator {value}")
+            },
+            Self::UnknownDataSource { value } => {
+                write!(formatter, "unknown data-source discriminator {value}")
+            },
+            Self::UnknownProgramError { value } => {
+                write!(formatter, "unknown program metadata error code {value}")
+            },
+            Self::SeedUtf8TooLong { actual_bytes, max_bytes } => {
+                write!(formatter, "seed UTF-8 length {actual_bytes} exceeds {max_bytes} bytes",)
+            },
+            Self::InvalidSeedLength { actual_bytes, expected_bytes } => {
+                write!(
+                    formatter,
+                    "seed length {actual_bytes} does not equal {expected_bytes} bytes",
+                )
+            },
+            Self::InvalidSeedUtf8 => {
+                formatter.write_str("seed contains invalid UTF-8 before terminal padding")
+            },
+            Self::InvalidExternalDataLength { actual_bytes, expected_bytes } => {
+                write!(
+                    formatter,
+                    "external data length {actual_bytes} does not equal {expected_bytes} bytes",
+                )
+            },
+            Self::EmptyData { source } => {
+                write!(formatter, "metadata data source {source:?} cannot be empty")
+            },
+            Self::DataLengthExceedsU32 { actual_bytes } => {
+                write!(formatter, "metadata data length {actual_bytes} exceeds the u32 wire bound",)
+            },
+        };
+    }
+}
+
+impl std::error::Error for DcMetadataSpmModelError {}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn published_wire_values_are_exact_and_closed() {
+        assert_eq!(crate::DcMetadataSpmAccountDiscriminator::Empty.wire_value(), 0);
+        assert_eq!(crate::DcMetadataSpmAccountDiscriminator::Buffer.wire_value(), 1);
+        assert_eq!(crate::DcMetadataSpmAccountDiscriminator::Metadata.wire_value(), 2);
+        assert_eq!(crate::DcMetadataSpmEncoding::None.wire_value(), 0);
+        assert_eq!(crate::DcMetadataSpmEncoding::Utf8.wire_value(), 1);
+        assert_eq!(crate::DcMetadataSpmEncoding::Base58.wire_value(), 2);
+        assert_eq!(crate::DcMetadataSpmEncoding::Base64.wire_value(), 3);
+        assert_eq!(crate::DcMetadataSpmCompression::None.wire_value(), 0);
+        assert_eq!(crate::DcMetadataSpmCompression::Gzip.wire_value(), 1);
+        assert_eq!(crate::DcMetadataSpmCompression::Zlib.wire_value(), 2);
+        assert_eq!(crate::DcMetadataSpmFormat::None.wire_value(), 0);
+        assert_eq!(crate::DcMetadataSpmFormat::Json.wire_value(), 1);
+        assert_eq!(crate::DcMetadataSpmFormat::Yaml.wire_value(), 2);
+        assert_eq!(crate::DcMetadataSpmFormat::Toml.wire_value(), 3);
+        assert_eq!(crate::DcMetadataSpmDataSource::Direct.wire_value(), 0);
+        assert_eq!(crate::DcMetadataSpmDataSource::Url.wire_value(), 1);
+        assert_eq!(crate::DcMetadataSpmDataSource::External.wire_value(), 2);
+        assert_eq!(crate::DcMetadataSpmProgramError::NotExecutableAccount.code(), 0);
+        assert_eq!(crate::DcMetadataSpmProgramError::InvalidProgramState.code(), 1);
+        assert_eq!(crate::DcMetadataSpmProgramError::InvalidProgramDataAccount.code(), 2);
+        assert_eq!(crate::DcMetadataSpmProgramError::ImmutableMetadataAccount.code(), 3);
+        assert_eq!(crate::DcMetadataSpmProgramError::InvalidDataLength.code(), 4);
+        assert!(crate::DcMetadataSpmAccountDiscriminator::from_wire_value(3).is_err());
+        assert!(crate::DcMetadataSpmEncoding::from_wire_value(4).is_err());
+        assert!(crate::DcMetadataSpmCompression::from_wire_value(3).is_err());
+        assert!(crate::DcMetadataSpmFormat::from_wire_value(4).is_err());
+        assert!(crate::DcMetadataSpmDataSource::from_wire_value(3).is_err());
+        assert!(crate::DcMetadataSpmProgramError::from_code(5).is_err());
+    }
+
+    #[test]
+    fn seed_preserves_exact_bytes_and_applies_the_utf8_byte_bound() {
+        let seed_result = crate::DcMetadataSpmSeed::from_utf8("sécurité");
+        assert!(seed_result.is_ok());
+        let seed;
+        if let std::result::Result::Ok(value) = seed_result {
+            seed = value;
+        } else {
+            return;
+        }
+        assert_eq!(seed.as_bytes().len(), crate::DC_METADATA_SPM_SEED_BYTES);
+        assert_eq!(seed.trimmed_utf8(), std::result::Result::Ok("sécurité"));
+        assert!(crate::DcMetadataSpmSeed::from_utf8("éééééééé").is_ok());
+        assert_eq!(
+            crate::DcMetadataSpmSeed::from_utf8("ééééééééé"),
+            std::result::Result::Err(crate::DcMetadataSpmModelError::SeedUtf8TooLong {
+                actual_bytes: 18,
+                max_bytes: crate::DC_METADATA_SPM_SEED_BYTES,
+            }),
+        );
+        assert!(crate::DcMetadataSpmSeed::from_wire_bytes(&[0_u8; 15]).is_err());
+        let invalid = crate::DcMetadataSpmSeed::from_bytes([
+            0xff, 0_u8, 0_u8, 0_u8, 0_u8, 0_u8, 0_u8, 0_u8, 0_u8, 0_u8, 0_u8, 0_u8, 0_u8, 0_u8,
+            0_u8, 0_u8,
+        ]);
+        assert_eq!(
+            invalid.trimmed_utf8(),
+            std::result::Result::Err(crate::DcMetadataSpmModelError::InvalidSeedUtf8),
+        );
+    }
+
+    #[test]
+    fn external_data_round_trips_the_exact_zeroable_layout() {
+        let address = solana_pubkey::Pubkey::new_from_array([7_u8; 32]);
+        let length_option = std::num::NonZeroU32::new(9);
+        assert!(length_option.is_some());
+        let length;
+        if let std::option::Option::Some(value) = length_option {
+            length = value;
+        } else {
+            return;
+        }
+        let model = crate::DcMetadataSpmExternalData::new(
+            address,
+            0x1122_3344,
+            std::option::Option::Some(length),
+        );
+        let bytes = model.to_wire_bytes();
+        assert_eq!(bytes.len(), crate::DC_METADATA_SPM_EXTERNAL_DATA_BYTES);
+        assert_eq!(&bytes[..32], &[7_u8; 32]);
+        assert_eq!(&bytes[32..36], &0x1122_3344_u32.to_le_bytes());
+        assert_eq!(&bytes[36..40], &9_u32.to_le_bytes());
+        assert_eq!(
+            crate::DcMetadataSpmExternalData::from_wire_bytes(&bytes),
+            std::result::Result::Ok(model),
+        );
+        let zeroable = crate::DcMetadataSpmExternalData::from_zeroable_length(address, 3, 0);
+        assert_eq!(zeroable.length, std::option::Option::None);
+        assert_eq!(&zeroable.to_wire_bytes()[36..40], &0_u32.to_le_bytes());
+        assert!(crate::DcMetadataSpmExternalData::from_wire_bytes(&bytes[..39]).is_err());
+    }
+
+    #[test]
+    fn typed_data_keeps_url_and_external_content_on_chain_only() {
+        let direct = crate::DcMetadataSpmData::Direct(vec![1_u8, 2_u8, 3_u8]);
+        assert_eq!(direct.source(), crate::DcMetadataSpmDataSource::Direct);
+        assert_eq!(direct.wire_length_u32(), std::result::Result::Ok(3));
+        assert_eq!(direct.to_wire_bytes(), std::result::Result::Ok(vec![1_u8, 2_u8, 3_u8]));
+        let url = crate::DcMetadataSpmData::Url("https://example.invalid/idl.json".to_string());
+        assert_eq!(url.source(), crate::DcMetadataSpmDataSource::Url);
+        assert_eq!(
+            url.to_wire_bytes(),
+            std::result::Result::Ok(b"https://example.invalid/idl.json".to_vec()),
+        );
+        let external = crate::DcMetadataSpmData::External(
+            crate::DcMetadataSpmExternalData::from_zeroable_length(
+                solana_pubkey::Pubkey::new_from_array([8_u8; 32]),
+                12,
+                20,
+            ),
+        );
+        assert_eq!(external.source(), crate::DcMetadataSpmDataSource::External);
+        assert_eq!(external.wire_length_u32(), std::result::Result::Ok(40),);
+        assert_eq!(
+            external.to_wire_bytes().map(|value| return value.len()),
+            std::result::Result::Ok(crate::DC_METADATA_SPM_EXTERNAL_DATA_BYTES),
+        );
+        assert!(crate::DcMetadataSpmData::Direct(std::vec::Vec::new()).validate().is_err());
+        assert!(crate::DcMetadataSpmData::Url(String::new()).validate().is_err());
+    }
+
+    #[test]
+    fn public_json_representation_is_stable_and_typed() {
+        let encoding_result = serde_json::to_value(crate::DcMetadataSpmEncoding::Base64);
+        assert!(encoding_result.is_ok());
+        let encoding;
+        if let std::result::Result::Ok(value) = encoding_result {
+            encoding = value;
+        } else {
+            return;
+        }
+        assert_eq!(encoding, serde_json::json!("base64"));
+        let url_result = serde_json::to_value(crate::DcMetadataSpmData::Url(
+            "https://example.invalid/metadata.json".to_string(),
+        ));
+        assert!(url_result.is_ok());
+        let url;
+        if let std::result::Result::Ok(value) = url_result {
+            url = value;
+        } else {
+            return;
+        }
+        assert_eq!(
+            url,
+            serde_json::json!({
+                "source": "url",
+                "value": "https://example.invalid/metadata.json",
+            }),
+        );
+        let seed_result = crate::DcMetadataSpmSeed::from_utf8("idl");
+        assert!(seed_result.is_ok());
+        let seed;
+        if let std::result::Result::Ok(value) = seed_result {
+            seed = value;
+        } else {
+            return;
+        }
+        let json_result = serde_json::to_value(seed);
+        assert!(json_result.is_ok());
+        let json;
+        if let std::result::Result::Ok(value) = json_result {
+            json = value;
+        } else {
+            return;
+        }
+        assert_eq!(json.as_array().map(std::vec::Vec::len), std::option::Option::Some(16));
+    }
+
+    #[test]
+    fn published_fixed_sizes_match_the_audited_contract() {
+        assert_eq!(crate::DC_METADATA_SPM_SEED_BYTES, 16);
+        assert_eq!(crate::DC_METADATA_SPM_BUFFER_HEADER_BYTES, 96);
+        assert_eq!(crate::DC_METADATA_SPM_METADATA_HEADER_BYTES, 96);
+        assert_eq!(crate::DC_METADATA_SPM_EXTERNAL_DATA_BYTES, 40);
+    }
+}

ks-lib/src/decoder/metadata/spl_name_service.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/metadata/spl_name_service.rs
+// version: 5
+
+//! Reserved protocol decoder for `metadata_spl_name_service`.
+
+/// Reserved decoder for the `metadata_spl_name_service` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcMetadataSplNameServiceDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcMetadataSplNameServiceDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.metadata.spl_name_service";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::METADATA_SPL_NAME_SERVICE_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}

ks-lib/src/decoder/nft.rs

@@ -0,0 +1,12 @@
+// file: ks-lib/src/decoder/nft.rs
+// version: 6
+
+//! `nft` decoder family.
+
+mod metaplex_bubblegum;
+mod tensor_cnft;
+
+/// Reserved `kb-lib.decoder.nft.metaplex_bubblegum` decoder.
+pub use self::metaplex_bubblegum::DcNftMetaplexBubblegumDecoder;
+/// Reserved `kb-lib.decoder.nft.tensor_cnft` decoder.
+pub use self::tensor_cnft::DcNftTensorCnftDecoder;

ks-lib/src/decoder/nft/metaplex_bubblegum.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/nft/metaplex_bubblegum.rs
+// version: 5
+
+//! Reserved protocol decoder for `nft_metaplex_bubblegum`.
+
+/// Reserved decoder for the `nft_metaplex_bubblegum` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcNftMetaplexBubblegumDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcNftMetaplexBubblegumDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.nft.metaplex_bubblegum";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::NFT_METAPLEX_BUBBLEGUM_PROGRAM_ID];
+    }
+
+    fn supports_observation(
+        &self,
+        observation: &crate::MdProgramObservation,
+    ) -> crate::DcApiDecoderSupport {
+        if crate::DcApiProtocolDecoder::handles_program_id(self, &observation.program_id) {
+            return crate::DcApiDecoderSupport::Maybe;
+        }
+        return crate::DcApiDecoderSupport::No;
+    }
+
+    fn decode_observation(
+        &self,
+        _observation: &crate::MdProgramObservation,
+    ) -> ks_core::Result<std::vec::Vec<crate::MdDecodedProtocolEvent>> {
+        return std::result::Result::Ok(std::vec::Vec::new());
+    }
+}