2024-08-05 20:47:30 +00:00
|
|
|
//! Database [`BlockchainReadRequest`]s, [`BlockchainWriteRequest`]s, and [`BlockchainResponse`]s.
|
2024-05-05 14:21:28 +00:00
|
|
|
//!
|
|
|
|
//! Tests that assert particular requests lead to particular
|
2024-06-04 17:19:35 +00:00
|
|
|
//! responses are also tested in Cuprate's blockchain database crate.
|
2024-03-27 00:46:32 +00:00
|
|
|
|
|
|
|
//---------------------------------------------------------------------------------------------------- Import
|
|
|
|
use std::{
|
|
|
|
collections::{HashMap, HashSet},
|
|
|
|
ops::Range,
|
|
|
|
};
|
|
|
|
|
2024-07-29 00:13:08 +00:00
|
|
|
use crate::types::{Chain, ExtendedBlockHeader, OutputOnChain, VerifiedBlockInformation};
|
2024-03-27 00:46:32 +00:00
|
|
|
|
|
|
|
//---------------------------------------------------------------------------------------------------- ReadRequest
|
2024-06-04 17:19:35 +00:00
|
|
|
/// A read request to the blockchain database.
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
2024-08-05 20:47:30 +00:00
|
|
|
/// This pairs with [`BlockchainResponse`], where each variant here
|
|
|
|
/// matches in name with a [`BlockchainResponse`] variant. For example,
|
|
|
|
/// the proper response for a [`BlockchainReadRequest::BlockHash`]
|
|
|
|
/// would be a [`BlockchainResponse::BlockHash`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// See `Response` for the expected responses per `Request`.
|
2024-03-27 00:46:32 +00:00
|
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
2024-08-05 20:47:30 +00:00
|
|
|
pub enum BlockchainReadRequest {
|
2024-05-05 14:21:28 +00:00
|
|
|
/// Request a block's extended header.
|
|
|
|
///
|
|
|
|
/// The input is the block's height.
|
2024-03-27 00:46:32 +00:00
|
|
|
BlockExtendedHeader(u64),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
|
|
|
/// Request a block's hash.
|
|
|
|
///
|
2024-07-29 00:13:08 +00:00
|
|
|
/// The input is the block's height and the chain it is on.
|
|
|
|
BlockHash(u64, Chain),
|
|
|
|
|
|
|
|
/// Request to check if we have a block and which [`Chain`] it is on.
|
|
|
|
///
|
|
|
|
/// The input is the block's hash.
|
|
|
|
FindBlock([u8; 32]),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-06-04 17:19:35 +00:00
|
|
|
/// Removes the block hashes that are not in the _main_ chain.
|
|
|
|
///
|
|
|
|
/// This should filter (remove) hashes in alt-blocks as well.
|
|
|
|
FilterUnknownHashes(HashSet<[u8; 32]>),
|
|
|
|
|
2024-05-05 14:21:28 +00:00
|
|
|
/// Request a range of block extended headers.
|
|
|
|
///
|
|
|
|
/// The input is a range of block heights.
|
2024-07-29 00:13:08 +00:00
|
|
|
BlockExtendedHeaderInRange(Range<u64>, Chain),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
|
|
|
/// Request the current chain height.
|
|
|
|
///
|
|
|
|
/// Note that this is not the top-block height.
|
2024-03-27 00:46:32 +00:00
|
|
|
ChainHeight,
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-07-29 00:13:08 +00:00
|
|
|
/// Request the total amount of generated coins (atomic units) at this height.
|
|
|
|
GeneratedCoins(u64),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
|
|
|
/// Request data for multiple outputs.
|
|
|
|
///
|
|
|
|
/// The input is a `HashMap` where:
|
|
|
|
/// - Key = output amount
|
|
|
|
/// - Value = set of amount indices
|
|
|
|
///
|
|
|
|
/// For pre-RCT outputs, the amount is non-zero,
|
|
|
|
/// and the amount indices represent the wanted
|
|
|
|
/// indices of duplicate amount outputs, i.e.:
|
|
|
|
///
|
|
|
|
/// ```ignore
|
|
|
|
/// // list of outputs with amount 10
|
|
|
|
/// [0, 1, 2, 3, 4, 5]
|
|
|
|
/// // ^ ^
|
|
|
|
/// // we only want these two, so we would provide
|
|
|
|
/// // `amount: 10, amount_index: {1, 3}`
|
|
|
|
/// ```
|
|
|
|
///
|
|
|
|
/// For RCT outputs, the amounts would be `0` and
|
|
|
|
/// the amount indices would represent the global
|
|
|
|
/// RCT output indices.
|
2024-03-27 00:46:32 +00:00
|
|
|
Outputs(HashMap<u64, HashSet<u64>>),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
|
|
|
/// Request the amount of outputs with a certain amount.
|
|
|
|
///
|
|
|
|
/// The input is a list of output amounts.
|
2024-03-27 00:46:32 +00:00
|
|
|
NumberOutputsWithAmount(Vec<u64>),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-07-02 22:08:19 +00:00
|
|
|
/// Check that all key images within a set are not spent.
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// Input is a set of key images.
|
2024-06-04 17:19:35 +00:00
|
|
|
KeyImagesSpent(HashSet<[u8; 32]>),
|
2024-07-02 22:08:19 +00:00
|
|
|
|
|
|
|
/// A request for the compact chain history.
|
|
|
|
CompactChainHistory,
|
|
|
|
|
|
|
|
/// A request to find the first unknown block ID in a list of block IDs.
|
|
|
|
////
|
|
|
|
/// # Invariant
|
|
|
|
/// The [`Vec`] containing the block IDs must be sorted in chronological block
|
|
|
|
/// order, or else the returned response is unspecified and meaningless,
|
|
|
|
/// as this request performs a binary search.
|
|
|
|
FindFirstUnknown(Vec<[u8; 32]>),
|
2024-03-27 00:46:32 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
//---------------------------------------------------------------------------------------------------- WriteRequest
|
2024-06-04 17:19:35 +00:00
|
|
|
/// A write request to the blockchain database.
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// There is currently only 1 write request to the database,
|
2024-08-05 20:47:30 +00:00
|
|
|
/// as such, the only valid [`BlockchainResponse`] to this request is
|
|
|
|
/// the proper response for a [`BlockchainResponse::WriteBlockOk`].
|
2024-03-27 00:46:32 +00:00
|
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
2024-08-05 20:47:30 +00:00
|
|
|
pub enum BlockchainWriteRequest {
|
2024-05-05 14:21:28 +00:00
|
|
|
/// Request that a block be written to the database.
|
|
|
|
///
|
|
|
|
/// Input is an already verified block.
|
2024-03-27 00:46:32 +00:00
|
|
|
WriteBlock(VerifiedBlockInformation),
|
|
|
|
}
|
|
|
|
|
|
|
|
//---------------------------------------------------------------------------------------------------- Response
|
|
|
|
/// A response from the database.
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// These are the data types returned when using sending a `Request`.
|
|
|
|
///
|
2024-08-05 20:47:30 +00:00
|
|
|
/// This pairs with [`BlockchainReadRequest`] and [`BlockchainWriteRequest`],
|
2024-05-05 14:21:28 +00:00
|
|
|
/// see those two for more info.
|
2024-03-27 00:46:32 +00:00
|
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
2024-08-05 20:47:30 +00:00
|
|
|
pub enum BlockchainResponse {
|
2024-03-27 00:46:32 +00:00
|
|
|
//------------------------------------------------------ Reads
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::BlockExtendedHeader`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// Inner value is the extended headed of the requested block.
|
2024-03-27 00:46:32 +00:00
|
|
|
BlockExtendedHeader(ExtendedBlockHeader),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::BlockHash`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// Inner value is the hash of the requested block.
|
2024-03-27 00:46:32 +00:00
|
|
|
BlockHash([u8; 32]),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::FindBlock`].
|
2024-07-29 00:13:08 +00:00
|
|
|
///
|
|
|
|
/// Inner value is the chain and height of the block if found.
|
|
|
|
FindBlock(Option<(Chain, u64)>),
|
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::FilterUnknownHashes`].
|
2024-06-04 17:19:35 +00:00
|
|
|
///
|
|
|
|
/// Inner value is the list of hashes that were in the main chain.
|
|
|
|
FilterUnknownHashes(HashSet<[u8; 32]>),
|
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::BlockExtendedHeaderInRange`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// Inner value is the list of extended header(s) of the requested block(s).
|
2024-03-27 00:46:32 +00:00
|
|
|
BlockExtendedHeaderInRange(Vec<ExtendedBlockHeader>),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::ChainHeight`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// Inner value is the chain height, and the top block's hash.
|
2024-03-27 00:46:32 +00:00
|
|
|
ChainHeight(u64, [u8; 32]),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::GeneratedCoins`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
2024-07-29 00:13:08 +00:00
|
|
|
/// Inner value is the total amount of generated coins up to and including the chosen height, in atomic units.
|
2024-03-27 00:46:32 +00:00
|
|
|
GeneratedCoins(u64),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::Outputs`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// Inner value is all the outputs requested,
|
|
|
|
/// associated with their amount and amount index.
|
2024-03-27 00:46:32 +00:00
|
|
|
Outputs(HashMap<u64, HashMap<u64, OutputOnChain>>),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::NumberOutputsWithAmount`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// Inner value is a `HashMap` of all the outputs requested where:
|
|
|
|
/// - Key = output amount
|
|
|
|
/// - Value = count of outputs with the same amount
|
2024-03-27 00:46:32 +00:00
|
|
|
NumberOutputsWithAmount(HashMap<u64, usize>),
|
2024-05-05 14:21:28 +00:00
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::KeyImagesSpent`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// The inner value is `true` if _any_ of the key images
|
2024-06-04 17:19:35 +00:00
|
|
|
/// were spent (existed in the database already).
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// The inner value is `false` if _none_ of the key images were spent.
|
2024-06-04 17:19:35 +00:00
|
|
|
KeyImagesSpent(bool),
|
2024-03-27 00:46:32 +00:00
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainReadRequest::CompactChainHistory`].
|
2024-07-02 22:08:19 +00:00
|
|
|
CompactChainHistory {
|
|
|
|
/// A list of blocks IDs in our chain, starting with the most recent block, all the way to the genesis block.
|
|
|
|
///
|
|
|
|
/// These blocks should be in reverse chronological order, not every block is needed.
|
|
|
|
block_ids: Vec<[u8; 32]>,
|
|
|
|
/// The current cumulative difficulty of the chain.
|
|
|
|
cumulative_difficulty: u128,
|
|
|
|
},
|
|
|
|
|
2024-08-05 20:47:30 +00:00
|
|
|
/// The response for [`BlockchainReadRequest::FindFirstUnknown`].
|
2024-07-02 22:08:19 +00:00
|
|
|
///
|
|
|
|
/// Contains the index of the first unknown block and its expected height.
|
|
|
|
///
|
|
|
|
/// This will be [`None`] if all blocks were known.
|
|
|
|
FindFirstUnknown(Option<(usize, u64)>),
|
|
|
|
|
2024-03-27 00:46:32 +00:00
|
|
|
//------------------------------------------------------ Writes
|
2024-08-05 20:47:30 +00:00
|
|
|
/// Response to [`BlockchainWriteRequest::WriteBlock`].
|
2024-05-05 14:21:28 +00:00
|
|
|
///
|
|
|
|
/// This response indicates that the requested block has
|
|
|
|
/// successfully been written to the database without error.
|
2024-03-27 00:46:32 +00:00
|
|
|
WriteBlockOk,
|
|
|
|
}
|
|
|
|
|
|
|
|
//---------------------------------------------------------------------------------------------------- Tests
|
|
|
|
#[cfg(test)]
|
|
|
|
mod test {
|
|
|
|
// use super::*;
|
|
|
|
}
|