ledger-prototype/utxo/src/transaction/mod.rs

use crate::{
    config::Config, payment::PaymentTo, storage::Storage, AccountId, Amount, FilterableValue,
    MaxLengthString, PaymentFrom, RevId, Status, TxId,
};
use chrono::{DateTime, TimeZone, Utc};
use serde::{Deserialize, Serialize};
use std::ops::Deref;

mod base_tx;
mod error;
mod revision;
mod typ;

pub use self::{base_tx::BaseTx, error::Error, revision::Revision, typ::Type};

/// Tag definition
pub type Tag = MaxLengthString<64>;

pub(crate) fn to_ts_microseconds<W: std::io::Write>(
    dt: &DateTime<Utc>,
    writer: &mut W,
) -> std::io::Result<()> {
    borsh::BorshSerialize::serialize(&dt.timestamp_millis(), writer)?;
    Ok(())
}

pub(crate) fn from_ts_microseconds<R: borsh::io::Read>(
    reader: &mut R,
) -> ::core::result::Result<DateTime<Utc>, borsh::io::Error> {
    match Utc.timestamp_millis_opt(borsh::BorshDeserialize::deserialize_reader(reader)?) {
        chrono::LocalResult::Single(dt) => Ok(dt.with_timezone(&Utc)),
        _ => Err(borsh::io::Error::new(
            borsh::io::ErrorKind::InvalidData,
            "invalid timestamp".to_owned(),
        )),
    }
}

#[derive(Debug, Clone, Deserialize, Serialize)]
/// A transaction with a revision
///
/// This is the public representation of a transaction, with the revision. Since transactions are
/// immutable, the revision is the only way to update them.
///
/// A Revision is an ammenment to a transaction, but it can only ammend a few fields of the
/// transaction, mainly their status and certain unrelated fields to the transactions, such as tags.
///
/// Revisions are only updatable until the transaction is finalized, by which point they are also
/// immutable.
///
/// Having a revision also makes concurrency easier, since only the latest revision can may be
/// upgraded, any other attempt to ammend a stale revision will be rejected.
pub struct Transaction {
    /// Transaction ID
    #[serde(rename = "_id")]
    pub id: TxId,

    /// List of all revisions
    #[serde(rename = "_all_revs")]
    pub revisions: Vec<RevId>,

    /// Revision ID
    #[serde(rename = "_rev")]
    pub revision_id: RevId,

    /// The revision struct.
    #[serde(flatten)]
    pub revision: Revision,

    #[serde(flatten)]
    /// The transaction struct
    pub transaction: BaseTx,
}

impl Deref for Transaction {
    type Target = BaseTx;

    fn deref(&self) -> &Self::Target {
        &self.transaction
    }
}

impl TryFrom<(Vec<RevId>, BaseTx, Revision)> for Transaction {
    type Error = Error;

    fn try_from(value: (Vec<RevId>, BaseTx, Revision)) -> Result<Self, Self::Error> {
        Ok(Self {
            id: value.1.id()?,
            revisions: value.0,
            revision_id: value.2.rev_id()?,
            transaction: value.1,
            revision: value.2,
        })
    }
}

impl Transaction {
    /// Creates a new transaction
    pub async fn new(
        reference: String,
        status: Status,
        typ: Type,
        spends: Vec<PaymentFrom>,
        creates: Vec<(AccountId, Amount)>,
    ) -> Result<Self, Error> {
        let creates = creates
            .into_iter()
            .map(|(to, amount)| PaymentTo { to, amount })
            .collect();

        let (transaction, revision) = BaseTx::new(spends, creates, reference, typ, status)?;
        let revision_id = revision.rev_id()?;

        Ok(Self {
            id: transaction.id()?,
            revisions: vec![revision_id.clone()],
            revision_id,
            revision,
            transaction,
        })
    }

    /// Returns the filterable fields
    pub fn get_filterable_fields(&self) -> Vec<FilterableValue> {
        let mut filters = vec![
            FilterableValue::Anything,
            FilterableValue::Type(self.transaction.typ.clone()),
            FilterableValue::TxId(self.id.clone()),
            FilterableValue::Status(self.revision.status.clone()),
            FilterableValue::Revision(self.revision_id.clone()),
            FilterableValue::Type(self.typ),
        ];

        for account in self.accounts() {
            filters.push(FilterableValue::Account(account));
        }

        for tag in &self.revision.tags {
            filters.push(FilterableValue::Tag(tag.clone()));
        }

        filters
    }

    /// Creates a new external deposit transaction
    ///
    /// All transactions must be balanced, same amounts that are spent should be
    /// created. There are two exceptions, external deposits and withdrawals.
    /// The idea is to mimic external operations, where new assets enter the system.
    pub fn new_external_deposit(
        reference: String,
        status: Status,
        tags: Vec<Tag>,
        creates: Vec<(AccountId, Amount)>,
    ) -> Result<Self, Error> {
        let creates = creates
            .into_iter()
            .map(|(to, amount)| PaymentTo { to, amount })
            .collect();
        let (transaction, mut revision) =
            BaseTx::new(Vec::new(), creates, reference, Type::Deposit, status)?;
        revision.tags = tags;
        let revision_id = revision.rev_id()?;

        Ok(Self {
            id: transaction.id()?,
            revisions: vec![revision_id.clone()],
            revision_id,
            revision,
            transaction,
        })
    }

    /// Creates a new external withdrawal transaction
    ///
    /// Burns assets to reflect external withdrawals
    pub fn new_external_withdrawal(
        reference: String,
        status: Status,
        spends: Vec<PaymentFrom>,
    ) -> Result<Self, Error> {
        let (transaction, revision) =
            BaseTx::new(spends, Vec::new(), reference, Type::Withdrawal, status)?;
        let revision_id = revision.rev_id()?;

        Ok(Self {
            id: transaction.id()?,
            revisions: vec![revision_id.clone()],
            revision_id,
            transaction,
            revision,
        })
    }

    /// Updates the transaction tags
    pub fn set_tags(self, new_tags: Vec<Tag>, reason: String) -> Result<Self, Error> {
        let new_revision = Revision {
            transaction_id: self.revision.transaction_id,
            changelog: reason,
            previous: Some(self.revision_id),
            tags: new_tags,
            status: self.revision.status,
            created_at: Utc::now(),
        };
        let revision_id = new_revision.rev_id()?;
        let mut revisions = self.revisions;
        revisions.push(revision_id.clone());

        Ok(Transaction {
            id: self.id,
            revisions,
            revision_id,
            transaction: self.transaction,
            revision: new_revision,
        })
    }

    /// Prepares a new revision to change the transaction status
    ///
    /// If the status transaction is not allowed, it will return an error.
    ///
    /// The new transaction with revision is returned, which should be persisted. When it is
    /// persisted, the previous struct is consumed and the latest revision is preserved for
    /// historical purposes but it is no longer the latest revision
    #[inline]
    pub fn change_status<S>(
        self,
        config: &Config<S>,
        new_status: Status,
        reason: String,
    ) -> Result<Self, Error>
    where
        S: Storage + Sync + Send,
    {
        config
            .status
            .is_valid_transition(&self.revision.status, &new_status)?;
        let new_revision = Revision {
            transaction_id: self.revision.transaction_id,
            changelog: reason,
            previous: Some(self.revision_id),
            tags: self.revision.tags,
            status: new_status,
            created_at: Utc::now(),
        };
        let revision_id = new_revision.rev_id()?;
        let mut revisions = self.revisions;
        revisions.push(revision_id.clone());

        Ok(Transaction {
            id: self.id,
            revisions,
            revision_id,
            transaction: self.transaction,
            revision: new_revision,
        })
    }

    /// Validates the transaction and its revisions
    pub fn validate(&self) -> Result<(), Error> {
        let rev_id = self.revision.rev_id()?;
        let tx_id = self.transaction.id()?;
        if self.revision_id != rev_id {
            return Err(Error::InvalidRevId(self.revision_id.clone(), rev_id));
        }
        if tx_id != self.revision.transaction_id || tx_id != self.id {
            return Err(Error::InvalidTxId(
                tx_id,
                self.revision.transaction_id.clone(),
            ));
        }
        self.transaction.validate()?;
        Ok(())
    }
}