v0.3.1-pre.003

crates/ksp-store-api/src/model/raw_transaction.rs

@@ -0,0 +1,113 @@
+// file: crates/ksp-store-api/src/model/raw_transaction.rs
+// version: 1
+
+/// Durable backend-independent identity of one canonical RAW transaction.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct RawTransactionReference {
+    network: crate::RawNetworkId,
+    signature: crate::RawTransactionSignature,
+}
+
+impl RawTransactionReference {
+    /// Creates one durable transaction identity from network and canonical Solana signature.
+    #[must_use]
+    pub fn new(network: crate::RawNetworkId, signature: crate::RawTransactionSignature) -> Self {
+        return Self { network, signature };
+    }
+
+    /// Returns the logical Solana network/cluster identifier.
+    #[must_use]
+    pub fn network(&self) -> &crate::RawNetworkId {
+        return &self.network;
+    }
+
+    /// Returns the canonical transaction signature.
+    #[must_use]
+    pub const fn signature(&self) -> crate::RawTransactionSignature {
+        return self.signature;
+    }
+}
+
+/// Canonical source-independent N1 RAW transaction persisted by Store backends.
+///
+/// The payload must contain the complete KSP canonical transaction representation required
+/// for future STRUCTURAL replay, including transaction execution metadata and transaction
+/// log messages when the canonical format defines them. Provider/transport provenance is
+/// deliberately kept in [`crate::RawTransactionObservation`] instead.
+#[derive(Debug)]
+pub struct RawTransaction {
+    block_time: std::option::Option<crate::RawTimestamp>,
+    payload: crate::RawPayload,
+    reference: crate::RawTransactionReference,
+    slot: u64,
+}
+
+impl RawTransaction {
+    /// Creates one complete canonical RAW transaction.
+    #[must_use]
+    pub fn new(reference: crate::RawTransactionReference, slot: u64, block_time: std::option::Option<crate::RawTimestamp>, payload: crate::RawPayload) -> Self {
+        return Self { block_time, payload, reference, slot };
+    }
+
+    /// Returns the optional canonical block timestamp.
+    #[must_use]
+    pub const fn block_time(&self) -> std::option::Option<crate::RawTimestamp> {
+        return self.block_time;
+    }
+
+    /// Returns the complete KSP-owned canonical RAW payload.
+    #[must_use]
+    pub fn payload(&self) -> &crate::RawPayload {
+        return &self.payload;
+    }
+
+    /// Returns the durable backend-independent transaction identity.
+    #[must_use]
+    pub fn reference(&self) -> &crate::RawTransactionReference {
+        return &self.reference;
+    }
+
+    /// Returns the Solana slot containing the transaction.
+    #[must_use]
+    pub const fn slot(&self) -> u64 {
+        return self.slot;
+    }
+}
+
+/// Persistable acquisition observation linked to one canonical RAW transaction.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RawTransactionObservation {
+    observation_key: crate::RawObservationKey,
+    provenance: crate::RawAcquisitionProvenance,
+    transaction: crate::RawTransactionReference,
+}
+
+impl RawTransactionObservation {
+    /// Creates one successful observation of a complete canonical RAW transaction.
+    #[must_use]
+    pub fn new(observation_key: crate::RawObservationKey, transaction: crate::RawTransactionReference, provenance: crate::RawAcquisitionProvenance) -> Self {
+        return Self { observation_key, provenance, transaction };
+    }
+
+    /// Returns the deterministic producer-owned observation idempotence key.
+    #[must_use]
+    pub const fn observation_key(&self) -> crate::RawObservationKey {
+        return self.observation_key;
+    }
+
+    /// Returns safe source-independent acquisition provenance.
+    #[must_use]
+    pub fn provenance(&self) -> &crate::RawAcquisitionProvenance {
+        return &self.provenance;
+    }
+
+    /// Returns the durable transaction identity observed by this acquisition.
+    #[must_use]
+    pub fn transaction(&self) -> &crate::RawTransactionReference {
+        return &self.transaction;
+    }
+}
+
+#[cfg(test)]
+#[path = "../../unit_tests/model/raw_transaction.rs"]
+mod tests;