0.1.0

kb-lib/src/model/replay.rs

@@ -0,0 +1,126 @@
+// file: kb-lib/src/model/replay.rs
+// version: 2
+
+//! Source-neutral instruction replay input shared by decoders and stores.
+
+/// Version of the normalized core replay contract.
+pub const CORE_REPLAY_INPUT_CONTRACT_VERSION: u32 = 2;
+
+/// Decoder replay input containing one instruction plus extracted transaction context.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct CoreInstructionReplayInput {
+    /// Version of the normalized core replay contract.
+    pub core_contract_version: u32,
+    /// Stable deduplication key for this replay input.
+    pub replay_input_key: std::string::String,
+    /// Transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Transaction slot in Solana unsigned representation.
+    pub slot: u64,
+    /// Stable instruction path, for example `0` or `2/1`.
+    pub instruction_path: std::string::String,
+    /// Program id as non-empty base58 text.
+    pub program_id: std::string::String,
+    /// Optional surface hint supplied by an operator or upstream classifier.
+    pub surface_code_hint: std::option::Option<std::string::String>,
+    /// Whether the parent transaction failed on-chain.
+    pub transaction_failed: bool,
+    /// Optional transaction error JSON.
+    pub transaction_err_json: std::option::Option<serde_json::Value>,
+    /// Resolved account keys for the whole transaction.
+    pub account_keys_json: serde_json::Value,
+    /// Instruction accounts for the target instruction.
+    pub instruction_accounts_json: serde_json::Value,
+    /// Optional instruction payload retained by the store.
+    pub instruction_payload_json: std::option::Option<serde_json::Value>,
+    /// Optional deterministic hash of the retained instruction payload.
+    pub instruction_payload_hash: std::option::Option<std::string::String>,
+    /// Ordered outer instructions for the transaction.
+    pub outer_instructions_json: serde_json::Value,
+    /// Inner instruction tree or subtree relevant to the target instruction.
+    pub inner_instructions_json: serde_json::Value,
+    /// Ordered logs relevant to the transaction or target instruction.
+    pub logs_json: serde_json::Value,
+    /// Balance changes relevant to the transaction or target instruction.
+    pub balance_changes_json: serde_json::Value,
+}
+
+impl CoreInstructionReplayInput {
+    /// Builds a decoder replay input after validating its stable identity and array context.
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        replay_input_key: impl std::convert::Into<std::string::String>,
+        signature: impl std::convert::Into<std::string::String>,
+        slot: u64,
+        instruction_path: impl std::convert::Into<std::string::String>,
+        program_id: impl std::convert::Into<std::string::String>,
+        transaction_failed: bool,
+        transaction_err_json: std::option::Option<serde_json::Value>,
+        account_keys_json: serde_json::Value,
+        instruction_accounts_json: serde_json::Value,
+        instruction_payload_json: std::option::Option<serde_json::Value>,
+        instruction_payload_hash: std::option::Option<std::string::String>,
+        outer_instructions_json: serde_json::Value,
+        inner_instructions_json: serde_json::Value,
+        logs_json: serde_json::Value,
+        balance_changes_json: serde_json::Value,
+    ) -> kb_core::Result<Self> {
+        if !outer_instructions_json.is_array() {
+            return std::result::Result::Err(kb_core::Error::invalid_state(
+                "core replay input outer instructions must be a JSON array",
+            ));
+        }
+        let value = Self {
+            core_contract_version: crate::CORE_REPLAY_INPUT_CONTRACT_VERSION,
+            replay_input_key: replay_input_key.into(),
+            signature: signature.into(),
+            slot,
+            instruction_path: instruction_path.into(),
+            program_id: program_id.into(),
+            surface_code_hint: std::option::Option::None,
+            transaction_failed,
+            transaction_err_json,
+            account_keys_json,
+            instruction_accounts_json,
+            instruction_payload_json,
+            instruction_payload_hash,
+            outer_instructions_json,
+            inner_instructions_json,
+            logs_json,
+            balance_changes_json,
+        };
+        let validation_result = value.validate();
+        if let std::result::Result::Err(error) = validation_result {
+            return std::result::Result::Err(error);
+        }
+        return std::result::Result::Ok(value);
+    }
+
+    /// Validates the stable replay identity and contract version.
+    pub fn validate(&self) -> kb_core::Result<()> {
+        if self.core_contract_version != crate::CORE_REPLAY_INPUT_CONTRACT_VERSION {
+            return std::result::Result::Err(kb_core::Error::invalid_state(
+                "unsupported core replay input contract version",
+            ));
+        }
+        if self.replay_input_key.trim().is_empty()
+            || self.signature.trim().is_empty()
+            || self.instruction_path.trim().is_empty()
+            || self.program_id.trim().is_empty()
+        {
+            return std::result::Result::Err(kb_core::Error::invalid_state(
+                "core replay identity fields must not be empty",
+            ));
+        }
+        if self
+            .instruction_payload_hash
+            .as_deref()
+            .is_some_and(|value| return value.trim().is_empty())
+        {
+            return std::result::Result::Err(kb_core::Error::invalid_state(
+                "core replay payload hash must not be empty when present",
+            ));
+        }
+        return std::result::Result::Ok(());
+    }
+}