// 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;