0.5.1-pre.002

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());
+    }
+}

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

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/nft/tensor_cnft.rs
+// version: 2
+
+//! Reserved protocol decoder for `nft_tensor_cnft`.
+
+/// Reserved decoder for the `nft_tensor_cnft` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcNftTensorCnftDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcNftTensorCnftDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.nft.tensor_cnft";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::NFT_TENSOR_CNFT_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/orderbook.rs

@@ -0,0 +1,15 @@
+// file: ks-lib/src/decoder/orderbook.rs
+// version: 5
+
+//! `orderbook` decoder family.
+
+mod jupiter_limit_order;
+mod jupiter_limit_order_v2;
+mod openbook_v2;
+
+/// Reserved `kb-lib.decoder.orderbook.jupiter_limit_order` decoder.
+pub use self::jupiter_limit_order::DcOrderbookJupiterLimitOrderDecoder;
+/// Reserved `kb-lib.decoder.orderbook.jupiter_limit_order_v2` decoder.
+pub use self::jupiter_limit_order_v2::DcOrderbookJupiterLimitOrderV2Decoder;
+/// Reserved `kb-lib.decoder.orderbook.openbook_v2` decoder.
+pub use self::openbook_v2::DcOrderbookOpenbookV2Decoder;

ks-lib/src/decoder/orderbook/jupiter_limit_order.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/orderbook/jupiter_limit_order.rs
+// version: 5
+
+//! Reserved protocol decoder for `orderbook_jupiter_limit_order`.
+
+/// Reserved decoder for the `orderbook_jupiter_limit_order` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcOrderbookJupiterLimitOrderDecoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcOrderbookJupiterLimitOrderDecoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.orderbook.jupiter_limit_order";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::ORDERBOOK_JUPITER_LIMIT_ORDER_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/orderbook/jupiter_limit_order_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/orderbook/jupiter_limit_order_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `orderbook_jupiter_limit_order_v2`.
+
+/// Reserved decoder for the `orderbook_jupiter_limit_order_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcOrderbookJupiterLimitOrderV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcOrderbookJupiterLimitOrderV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.orderbook.jupiter_limit_order_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::ORDERBOOK_JUPITER_LIMIT_ORDER_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/orderbook/openbook_v2.rs

@@ -0,0 +1,39 @@
+// file: ks-lib/src/decoder/orderbook/openbook_v2.rs
+// version: 5
+
+//! Reserved protocol decoder for `orderbook_openbook_v2`.
+
+/// Reserved decoder for the `orderbook_openbook_v2` program surface.
+#[derive(Clone, Debug, Default)]
+pub struct DcOrderbookOpenbookV2Decoder;
+
+impl crate::DcApiProtocolDecoder for crate::DcOrderbookOpenbookV2Decoder {
+    fn decoder_name(&self) -> &'static str {
+        return "kb-lib.decoder.orderbook.openbook_v2";
+    }
+
+    fn decoder_version(&self) -> &'static str {
+        return env!("CARGO_PKG_VERSION");
+    }
+
+    fn program_ids(&self) -> &'static [&'static str] {
+        return &[ks_program_ids::ORDERBOOK_OPENBOOK_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/perpetuals.rs

@@ -0,0 +1,18 @@
+// file: ks-lib/src/decoder/perpetuals.rs
+// version: 6
+
+//! `perpetuals` decoder family.
+
+mod drift_v2;
+mod jupiter;
+mod phoenix_eternal;
+mod zeta;
+
+/// Reserved `kb-lib.decoder.perpetuals.drift_v2` decoder.
+pub use self::drift_v2::DcPerpetualsDriftV2Decoder;
+/// Reserved `kb-lib.decoder.perpetuals.jupiter` decoder.
+pub use self::jupiter::DcPerpetualsJupiterDecoder;
+/// Reserved `kb-lib.decoder.perpetuals.phoenix_eternal` decoder.
+pub use self::phoenix_eternal::DcPerpetualsPhoenixEternalDecoder;
+/// Reserved `kb-lib.decoder.perpetuals.zeta` decoder.
+pub use self::zeta::DcPerpetualsZetaDecoder;