ledger-prototype/utxo/src/ledger.rs

use crate::{
    amount::AmountCents, storage::Storage, transaction::Type, AccountId, Amount, AssetManager,
    Error, Payment, PaymentId, Status, Transaction, TransactionId,
};
use std::{cmp::Ordering, collections::HashMap};

/// The Verax ledger
#[derive(Clone, Debug)]
pub struct Ledger<S>
where
    S: Storage + Sync + Send,
{
    storage: S,
    asset_manager: AssetManager,
}

impl<S> Ledger<S>
where
    S: Storage + Sync + Send,
{
    /// Creates a new ledger instance
    pub fn new(storage: S, asset_manager: AssetManager) -> Self {
        Self {
            storage,
            asset_manager,
        }
    }

    /// Parses a human amount (float amounts serialized as string to avoid precision loss)
    pub fn parse_amount(&self, asset: &str, amount: &str) -> Result<Amount, Error> {
        self.asset_manager.human_amount_by_name(asset, amount)
    }

    /// Returns a reference to the asset manager
    pub fn asset_manager(&self) -> &AssetManager {
        &self.asset_manager
    }

    /// The internal usage is to select unspent payments for each account to
    /// create new transactions. The external API however does not expose that
    /// level of usage, instead it exposes a simple API to move funds using
    /// accounts to debit from and accounts to credit to. A single transaction
    /// can use multiple accounts to debit and credit, instead of a single
    /// account.
    ///
    /// This function selects the unspent payments to be used in a transaction,
    /// in a descending order (making sure to include any negative deposit).
    ///
    /// This function returns a vector of payments to be used as inputs and
    /// optionally a dependent transaction to be executed first. This
    /// transaction is an internal transaction and it settles immediately. It is
    /// used to split an existing payment into two payments, one to be used as
    /// input and the other to be used as change. This is done to avoid locking
    /// any change amount until the main transaction settles.
    async fn select_payments_from_accounts(
        &self,
        payments: Vec<(AccountId, Amount)>,
    ) -> Result<(Option<Transaction>, Vec<Payment>), Error> {
        let mut to_spend = HashMap::<_, AmountCents>::new();

        for (account_id, amount) in payments.into_iter() {
            let id = (account_id, amount.asset().clone());
            if let Some(value) = to_spend.get_mut(&id) {
                (*value)
                    .checked_add(amount.cents())
                    .ok_or(Error::Overflow)?;
            } else {
                to_spend.insert(id, amount.cents());
            }
        }

        let mut change_input = vec![];
        let mut change_output = vec![];
        let mut payments: Vec<Payment> = vec![];

        for ((account, asset), mut to_spend_cents) in to_spend.into_iter() {
            let iterator = self
                .storage
                .get_unspent_payments(&account, asset.id, to_spend_cents)
                .await?;
            for payment in iterator.into_iter() {
                let cents = payment.amount.cents();
                to_spend_cents = to_spend_cents.checked_sub(cents).ok_or(Error::Underflow)?;
                payments.push(payment);
                match to_spend_cents.cmp(&0) {
                    Ordering::Equal => {
                        // No change amount, we are done with this input
                        break;
                    }
                    Ordering::Less => {
                        // The last input a greater amount than needed, therefore the last payment
                        // must be split into two payments.
                        //
                        // This function ensures the exact amounts are used, to archieve that an
                        // internal transaction is executed to split this unspent payment into two
                        // unspent payments. This internal transaction settles immediately.
                        //
                        // The alternative would be to use this whole unspent payment but the it
                        // will mean the exchange amount will not be spendable until the current
                        // transaction finalizes.
                        let required_amount = to_spend_cents.abs();
                        let input = payments
                            .pop()
                            .ok_or(Error::InsufficientBalance(account.clone(), asset.id))?;

                        let change_back =
                            cents.checked_sub(required_amount).ok_or(Error::Underflow)?;

                        change_input.push(input);
                        change_output.push((account.clone(), asset.new_amount(change_back)));
                        change_output.push((account.clone(), asset.new_amount(required_amount)));

                        // Go to the next payment
                        break;
                    }
                    _ => {
                        // We need more funds, continue to the selecting the
                        // available payment if any
                    }
                }
            }

            if to_spend_cents > 0 {
                // We don't have enough payment to cover the to_spend_cents
                // Return an insufficient balance error
                return Err(Error::InsufficientBalance(account, asset.id));
            }
        }

        let exchange_tx = if change_input.is_empty() {
            None
        } else {
            let total = change_input.len();
            let split_input = Transaction::new(
                "Exchange transaction".to_owned(),
                // Set the change transaction as settled. This is an
                // internal transaction to split existing payments
                // into exact new payments, so the main transaction has no
                // change.
                Status::Settled,
                Type::Exchange,
                change_input,
                change_output,
            )
            .await?;

            for i in 0..total {
                #[allow(clippy::arithmetic_side_effects)]
                // Spend the new payment
                payments.push(split_input.creates()[i * 2].clone());
            }
            Some(split_input)
        };

        Ok((exchange_tx, payments))
    }

    /// Creates a new transaction and returns it.
    ///
    /// The input is pretty simple, take this amounts from these given accounts
    /// and send them to these accounts (and amounts). The job of this function
    /// is to figure it out how to do it. This function will make sure that each
    /// account has enough balance, selecting the unspent payments from each
    /// account that will be spent. It will also return a list of transactions
    /// that will be used to return the change to the accounts, these accounts
    /// can be settled immediately so no other funds required to perform the
    /// transaction are locked.
    ///
    /// This functions performs read only operations on top of the storage layer
    /// and it will guarantee execution (meaning that it will not lock any
    /// funds, so these transactions may fail if any selected payment is spent
    /// between the time the transaction is created and executed).
    ///
    /// A NewTransaction struct is returned, the change_transactions should be
    /// executed and set as settled before the transaction is executed,
    /// otherwise it will fail. A failure in any execution will render the
    /// entire operation as failed but no funds will be locked.
    pub async fn new_transaction(
        &self,
        reference: String,
        status: Status,
        from: Vec<(AccountId, Amount)>,
        to: Vec<(AccountId, Amount)>,
    ) -> Result<Transaction, Error> {
        let (change_transaction, payments) = self.select_payments_from_accounts(from).await?;
        if let Some(mut change_tx) = change_transaction {
            change_tx.persist(&self.storage).await?;
        }
        let mut transaction =
            Transaction::new(reference, status, Type::Transaction, payments, to).await?;
        transaction.persist(&self.storage).await?;
        Ok(transaction)
    }

    /// Return the balances from a given account
    ///
    /// The balance is a vector of Amounts, one for each asset. The balance will
    /// return only spendable amounts, meaning that any amount that is locked in
    /// a transaction will not be returned.
    ///
    /// TODO: Return locked funds as well.
    pub async fn get_balance(&self, account: &AccountId) -> Result<Vec<Amount>, Error> {
        Ok(self.storage.get_balance(account).await?)
    }

    /// Creates an external deposit
    ///
    /// Although a deposit can have multiple output payments, to different
    /// accounts and amounts, to keep the upstream API simple, this function
    /// only accepts a single account and amount to credit
    pub async fn deposit(
        &self,
        account: &AccountId,
        amount: Amount,
        status: Status,
        reference: String,
    ) -> Result<Transaction, Error> {
        let mut transaction =
            Transaction::new_external_deposit(reference, status, vec![(account.clone(), amount)])?;
        transaction.persist(&self.storage).await?;
        Ok(transaction)
    }

    /// Creates a new withdrawal transaction and returns it.
    ///
    /// Although a transaction supports multiple inputs to be burned, from
    /// different accounts, to keep things simple, this function only supports a
    /// single input (single account and single amount). This is because the
    /// natural behaviour is to have withdrawals from a single account.
    pub async fn withdrawal(
        &self,
        account: &AccountId,
        amount: Amount,
        status: Status,
        reference: String,
    ) -> Result<Transaction, Error> {
        let (change_transactions, payments) = self
            .select_payments_from_accounts(vec![(account.clone(), amount)])
            .await?;
        for mut change_tx in change_transactions.into_iter() {
            change_tx.persist(&self.storage).await?;
        }
        let mut transaction = Transaction::new_external_withdrawal(reference, status, payments)?;
        transaction.persist(&self.storage).await?;
        Ok(transaction)
    }

    /// Returns the payment object by a given payment id
    pub async fn get_payment_info(&self, payment_id: &PaymentId) -> Result<Payment, Error> {
        Ok(self.storage.get_payment(payment_id).await?)
    }

    /// Returns the transaction object by a given transaction id
    pub async fn get_transaction(
        &self,
        transaction_id: &TransactionId,
    ) -> Result<Transaction, Error> {
        Ok(self
            .storage
            .get_transaction(transaction_id)
            .await?
            .try_into()?)
    }

    /// Returns all transactions from a given account. It can be optionally be
    /// sorted by transaction type. The transactions are sorted from newest to
    /// oldest.
    pub async fn get_transactions(
        &self,
        account_id: &AccountId,
        types: Vec<Type>,
    ) -> Result<Vec<Transaction>, Error> {
        let types = if types.is_empty() {
            vec![Type::Transaction, Type::Deposit, Type::Withdrawal]
        } else {
            types
        };
        let r = self
            .storage
            .get_transactions(account_id, &types, &[])
            .await?
            .into_iter()
            .map(|x| x.try_into())
            .collect::<Result<Vec<Transaction>, _>>()?;

        Ok(r)
    }

    /// Attempts to change the status of a given transaction id. On success the
    /// new transaction object is returned, otherwise an error is returned.
    pub async fn change_status(
        &self,
        transaction_id: &TransactionId,
        new_status: Status,
        reason: String,
    ) -> Result<Transaction, Error> {
        let mut tx: Transaction = self
            .storage
            .get_transaction(transaction_id)
            .await?
            .try_into()?;
        tx.change_status(new_status, reason)?;
        tx.persist(&self.storage).await?;
        Ok(tx)
    }
}