v0.3.5-pre.003

crates/ksp-interface-lib/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-interface-lib/src/lib.rs
-// version: 4
+// version: 5
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -16,6 +16,7 @@ mod error;
 mod program_account_meta;
 mod program_instruction;
 mod slot_lifecycle;
+mod transaction_execution;
 
 /// Error code used when an Interface-owned Program instruction admission limit is exceeded.
 pub use self::error::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED;
@@ -31,5 +32,11 @@ pub use self::program_instruction::ProgramInstruction;
 pub use self::slot_lifecycle::SlotLifecycleEvent;
 /// Provider-neutral stage in the lifecycle of an observed Solana slot.
 pub use self::slot_lifecycle::SlotLifecycleStage;
+/// Passive provider-neutral observation of one transaction execution result.
+pub use self::transaction_execution::TransactionExecutionEvent;
+/// Provider-neutral outcome of one observed transaction execution.
+pub use self::transaction_execution::TransactionExecutionOutcome;
+/// Canonical 64-byte Solana transaction signature used by passive Interface events.
+pub use self::transaction_execution::TransactionSignature;
 /// Canonical Solana account address primitive owned by `ksp-core-lib`.
 pub use ksp_core_lib::Pubkey;

crates/ksp-interface-lib/src/transaction_execution.rs

@@ -0,0 +1,85 @@
+// file: crates/ksp-interface-lib/src/transaction_execution.rs
+// version: 1
+
+/// Canonical 64-byte Solana transaction signature used by passive Interface events.
+#[derive(Clone, Copy, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub struct TransactionSignature([u8; 64]);
+
+impl TransactionSignature {
+    /// Creates one transaction signature from already-decoded canonical bytes.
+    #[must_use]
+    pub const fn new(bytes: [u8; 64]) -> Self {
+        return Self(bytes);
+    }
+
+    /// Returns the exact canonical signature bytes.
+    #[must_use]
+    pub const fn as_bytes(&self) -> &[u8; 64] {
+        return &self.0;
+    }
+}
+
+impl std::fmt::Debug for TransactionSignature {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter.write_str("TransactionSignature(..)");
+    }
+}
+
+/// Provider-neutral outcome of one observed transaction execution.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub enum TransactionExecutionOutcome {
+    /// The observed transaction execution completed without a transaction error.
+    Succeeded,
+    /// The observed transaction execution completed with a transaction error.
+    Failed,
+}
+
+/// Passive provider-neutral observation of one transaction execution result.
+#[derive(Clone, Copy, Eq, PartialEq)]
+pub struct TransactionExecutionEvent {
+    slot: u64,
+    signature: TransactionSignature,
+    outcome: TransactionExecutionOutcome,
+}
+
+impl TransactionExecutionEvent {
+    /// Creates one transaction execution event from its common provider-neutral fields.
+    #[must_use]
+    pub const fn new(slot: u64, signature: TransactionSignature, outcome: TransactionExecutionOutcome) -> Self {
+        return Self { slot, signature, outcome };
+    }
+
+    /// Returns the containing slot exactly as observed by the producer.
+    #[must_use]
+    pub const fn slot(&self) -> u64 {
+        return self.slot;
+    }
+
+    /// Returns the canonical transaction signature.
+    #[must_use]
+    pub const fn signature(&self) -> TransactionSignature {
+        return self.signature;
+    }
+
+    /// Returns the normalized execution outcome.
+    #[must_use]
+    pub const fn outcome(&self) -> TransactionExecutionOutcome {
+        return self.outcome;
+    }
+}
+
+impl std::fmt::Debug for TransactionExecutionEvent {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter
+            .debug_struct("TransactionExecutionEvent")
+            .field("slot", &self.slot)
+            .field("signature", &"<omitted>")
+            .field("outcome", &self.outcome)
+            .finish();
+    }
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/transaction_execution.rs"]
+mod tests;