cuprate_blockchain/ops/

tx.rs

//! Transaction functions.
use std::collections::HashMap;

use cuprate_helper::{cast::usize_to_u64, crypto::compute_zero_commitment};
use cuprate_pruning::CRYPTONOTE_PRUNING_LOG_STRIPES;

use fjall::Readable;
use monero_oxide::transaction::{Input, Pruned, Timelock, Transaction};
use tapes::{TapesAppend, TapesRead};

use crate::{
    error::{BlockchainError, DbResult},
    ops::output::{add_output, remove_output},
    types::{Amount, BlockHeight, Output, RctOutput, TxHash, TxId, TxInfo},
    BlockchainDatabase,
};

const EMPTY_PRUNABLE_BLOB_HASH: [u8; 32] = [
    0xc5, 0xd2, 0x46, 0x01, 0x86, 0xf7, 0x23, 0x3c, 0x92, 0x7e, 0x7d, 0xb2, 0xdc, 0xc7, 0x03, 0xc0,
    0xe5, 0x00, 0xb6, 0x53, 0xca, 0x82, 0x27, 0x3b, 0x7b, 0xfa, 0xd8, 0x04, 0x5d, 0x85, 0xa4, 0x70,
];

/// Adds the tx info and related data to the tapes, this does not add the tx blob to the tapes.
#[expect(clippy::too_many_arguments)]
pub fn add_tx_info_to_tapes(
    tx: &Transaction<Pruned>,
    pruned_blob_idx: u64,
    prunable_blob_idx: u64,
    pruned_size: usize,
    prunable_size: usize,
    height: &BlockHeight,
    numb_rct_outputs: &mut u64,
    append_tx: &mut tapes::TapesAppendTransaction,
    db: &BlockchainDatabase,
) -> DbResult<TxId> {
    let tx_id = append_tx
        .fixed_sized_tape_len(&db.tx_infos)
        .expect("Required tape was not open.");

    append_tx.append_entries(
        &db.tx_infos,
        &[TxInfo {
            height: *height,
            pruned_blob_idx,
            prunable_blob_idx,
            pruned_size,
            prunable_size,
            rct_output_start_idx: if tx.version() == 1 {
                u64::MAX
            } else {
                *numb_rct_outputs
            },
            numb_rct_outputs: tx.prefix().outputs.len(),
        }],
    )?;

    let timelock = match tx.prefix().additional_timelock {
        Timelock::None => 0,
        Timelock::Block(height) => usize_to_u64(height),
        Timelock::Time(time) => time,
    };

    //------------------------------------------------------ Key Images
    // Is this a miner transaction?
    // Which table we add the output data to depends on this.
    // <https://github.com/monero-project/monero/blob/eac1b86bb2818ac552457380c9dd421fb8935e5b/src/blockchain_db/blockchain_db.cpp#L212-L216>
    let miner_tx = matches!(tx.prefix().inputs.as_slice(), &[Input::Gen(_)]);

    if let Transaction::V2 { prefix, proofs } = &tx {
        for (i, output) in prefix.outputs.iter().enumerate() {
            // Create commitment.
            let commitment = if miner_tx {
                compute_zero_commitment(output.amount.unwrap_or(0))
            } else {
                proofs
                    .as_ref()
                    .expect("A V2 transaction with no RCT proofs is a miner tx")
                    .base
                    .commitments[i]
            };

            append_tx.append_entries(
                &db.rct_outputs,
                &[RctOutput {
                    key: output.key.to_bytes(),
                    height: *height,
                    timelock,
                    tx_idx: tx_id,
                    commitment: commitment.to_bytes(),
                }],
            )?;

            *numb_rct_outputs += 1;
        }
    }

    Ok(tx_id)
}

/// Adds the tx info and related data to the dynamic tables.
pub fn add_tx_info_to_dynamic_tables(
    db: &BlockchainDatabase,
    tx: &Transaction<Pruned>,
    tx_id: TxId,
    tx_hash: &TxHash,
    height: &BlockHeight,
    w: &mut fjall::OwnedWriteBatch,
    pre_rct_numb_outputs_cache: &mut HashMap<Amount, u64>,
) -> DbResult<()> {
    w.insert(&db.tx_ids, tx_hash, tx_id.to_le_bytes());

    //------------------------------------------------------ Timelocks
    // Height/time is not differentiated via type, but rather:
    // "height is any value less than 500_000_000 and timestamp is any value above"
    // so the `u64/usize` is stored without any tag.
    //
    // <https://github.com/Cuprate/cuprate/pull/102#discussion_r1558504285>
    let timelock = match tx.prefix().additional_timelock {
        Timelock::None => 0,
        Timelock::Block(height) => usize_to_u64(height),
        Timelock::Time(time) => time,
    };

    for inputs in &tx.prefix().inputs {
        match inputs {
            // Key images.
            Input::ToKey { key_image, .. } => {
                w.insert(&db.key_images, key_image.to_bytes(), []);
            }
            // This is a miner transaction.
            Input::Gen(_) => (),
        }
    }

    match &tx {
        Transaction::V1 { prefix, .. } => {
            let amount_indices = prefix
                .outputs
                .iter()
                .map(|output| {
                    // Pre-RingCT outputs.
                    Ok(add_output(
                        db,
                        output.amount.unwrap_or(0),
                        &Output {
                            key: output.key.to_bytes(),
                            height: *height,
                            timelock,
                            tx_idx: tx_id,
                        },
                        w,
                        pre_rct_numb_outputs_cache,
                    )?
                    .amount_index)
                })
                .collect::<DbResult<Vec<_>>>()?;

            w.insert(
                &db.v1_tx_outputs,
                tx_id.to_le_bytes(),
                bytemuck::cast_slice::<_, u8>(&amount_indices),
            );
        }
        Transaction::V2 { .. } => return Ok(()),
    }

    Ok(())
}

/// Removes a transaction from the dynamic tables.
#[inline]
pub fn remove_tx_from_dynamic_tables(
    db: &BlockchainDatabase,
    tx_hash: &TxHash,
    tx_rw: &mut fjall::OwnedWriteBatch,
    tapes: &tapes::TapesTruncateTransaction,
) -> DbResult<(TxId, Transaction)> {
    let tx_id = u64::from_le_bytes(
        db.tx_ids
            .get(tx_hash)?
            .ok_or(BlockchainError::NotFound)?
            .as_ref()
            .try_into()
            .unwrap(),
    );

    tx_rw.remove(&db.tx_ids, tx_hash);

    let tx = get_tx_from_id(&tx_id, tapes, db)?;

    for inputs in &tx.prefix().inputs {
        match inputs {
            Input::ToKey { key_image, .. } => {
                tx_rw.remove(&db.key_images, key_image.to_bytes());
            }
            Input::Gen(_) => (),
        }
    }

    if tx.version() != 1 {
        return Ok((tx_id, tx));
    }

    // Remove each v1 output in the transaction.

    for output in &tx.prefix().outputs {
        // Outputs with clear amounts.
        if let Some(amount) = output.amount {
            remove_output(db, amount, tx_rw)?;
        }
    }

    tx_rw.remove(&db.v1_tx_outputs, tx_id.to_le_bytes());

    Ok((tx_id, tx))
}

//---------------------------------------------------------------------------------------------------- `get_tx_*`
/// Retrieve a [`Transaction`] from the database with its [`TxHash`].
#[inline]
pub fn get_tx(
    db: &BlockchainDatabase,
    tx_hash: &TxHash,
    tx_ro: &fjall::Snapshot,
    tapes: &impl TapesRead,
) -> DbResult<Transaction> {
    let tx_id = tx_ro
        .get(&db.tx_ids, tx_hash)?
        .ok_or(BlockchainError::NotFound)?;

    get_tx_from_id(
        &u64::from_le_bytes(tx_id.as_ref().try_into().unwrap()),
        tapes,
        db,
    )
}

/// Retrieve a [`Transaction`] from the database with its [`TxId`].
#[inline]
pub fn get_tx_from_id(
    tx_id: &TxId,
    tapes: &impl TapesRead,
    db: &BlockchainDatabase,
) -> DbResult<Transaction> {
    let blob = get_tx_blob_from_id(tx_id, tapes, db)?;
    let tx = Transaction::read(&mut blob.as_slice())?;

    Ok(tx)
}

/// Returns the prunable hash for a miner transaction.
const fn miner_tx_prunable_hash(tx_info: &TxInfo) -> [u8; 32] {
    if tx_info.is_v1_tx() {
        [0; 32]
    } else {
        EMPTY_PRUNABLE_BLOB_HASH
    }
}

/// Returns a transaction's split blobs and prunable hash from its [`TxInfo`].
pub(crate) fn get_split_tx_blobs(
    tx_info: &TxInfo,
    is_miner_tx: bool,
    tapes: &impl TapesRead,
    db: &BlockchainDatabase,
) -> DbResult<(Vec<u8>, Vec<u8>, [u8; 32])> {
    let pruned_len = if is_miner_tx {
        tx_info.pruned_size
    } else {
        tx_info.pruned_size + 32
    };
    let mut pruned_blob = vec![0; pruned_len];
    tapes.read_bytes(&db.pruned_blobs, tx_info.pruned_blob_idx, &mut pruned_blob)?;

    let prunable_hash = if is_miner_tx {
        miner_tx_prunable_hash(tx_info)
    } else {
        pruned_blob[tx_info.pruned_size..].try_into().unwrap()
    };
    pruned_blob.truncate(tx_info.pruned_size);

    let mut prunable_blob = vec![0; tx_info.prunable_size];
    if !prunable_blob.is_empty() {
        let prunable_tape = if tx_info.is_v1_tx() {
            &db.v1_prunable_blobs
        } else {
            let stripe = cuprate_pruning::get_block_pruning_stripe(
                tx_info.height,
                usize::MAX,
                CRYPTONOTE_PRUNING_LOG_STRIPES,
            )
            .unwrap();

            &db.prunable_blobs
                [usize::try_from(stripe).expect("stripe will not exceed usize::MAX") - 1]
        };

        tapes.read_bytes(prunable_tape, tx_info.prunable_blob_idx, &mut prunable_blob)?;
    }

    Ok((pruned_blob, prunable_blob, prunable_hash))
}

/// Returns the tx-blob from a tx id.
pub fn get_tx_blob_from_id(
    tx_id: &TxId,
    tapes: &impl TapesRead,
    db: &BlockchainDatabase,
) -> DbResult<Vec<u8>> {
    let tx_info = tapes
        .read_entry(&db.tx_infos, *tx_id)?
        .ok_or(BlockchainError::NotFound)?;

    let mut blob = vec![0; tx_info.pruned_size + tx_info.prunable_size];

    tapes.read_bytes(
        &db.pruned_blobs,
        tx_info.pruned_blob_idx,
        &mut blob[..tx_info.pruned_size],
    )?;

    let prunable_tape = if tx_info.is_v1_tx() {
        &db.v1_prunable_blobs
    } else {
        let stripe = cuprate_pruning::get_block_pruning_stripe(
            tx_info.height,
            usize::MAX,
            CRYPTONOTE_PRUNING_LOG_STRIPES,
        )
        .unwrap();
        &db.prunable_blobs[usize::try_from(stripe).expect("stripe will not exceed usize::MAX") - 1]
    };

    tapes.read_bytes(
        prunable_tape,
        tx_info.prunable_blob_idx,
        &mut blob[tx_info.pruned_size..],
    )?;

    Ok(blob)
}

//----------------------------------------------------------------------------------------------------
/// How many [`Transaction`]s are there?
///
/// This returns the amount of transactions currently stored.
///
/// For example:
/// - 0 transactions exist => returns 0
/// - 1 transactions exist => returns 1
/// - 5 transactions exist => returns 5
/// - etc
#[inline]
pub fn get_num_tx(db: &BlockchainDatabase, tx_ro: &fjall::Snapshot) -> DbResult<u64> {
    Ok(usize_to_u64(tx_ro.len(&db.tx_ids)?))
}

//----------------------------------------------------------------------------------------------------
/// Check if a transaction exists in the database.
///
/// Returns `true` if it does, else `false`.
#[inline]
pub fn tx_exists(
    db: &BlockchainDatabase,
    tx_hash: &TxHash,
    tx_ro: &fjall::Snapshot,
) -> DbResult<bool> {
    Ok(tx_ro.contains_key(&db.tx_ids, tx_hash)?)
}

#[cfg(test)]
mod tests {
    use super::EMPTY_PRUNABLE_BLOB_HASH;

    #[test]
    fn empty_prunable_blob_hash_correct() {
        assert_eq!(
            EMPTY_PRUNABLE_BLOB_HASH,
            monero_oxide::primitives::keccak256([])
        );
    }
}