From 64a3e5d5e9d5b38937eb9e12e8efe8a1555303df Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Wed, 2 Oct 2024 17:04:02 -0400 Subject: [PATCH] blockchain docs/types --- .../cuprated/src/rpc/request/blockchain.rs | 33 ++++--- storage/blockchain/src/service/read.rs | 13 +-- types/src/blockchain.rs | 85 ++++++++++--------- types/src/lib.rs | 3 +- types/src/types.rs | 59 +++++++++++-- 5 files changed, 126 insertions(+), 67 deletions(-) diff --git a/binaries/cuprated/src/rpc/request/blockchain.rs b/binaries/cuprated/src/rpc/request/blockchain.rs index 0e04f5f..4324fdc 100644 --- a/binaries/cuprated/src/rpc/request/blockchain.rs +++ b/binaries/cuprated/src/rpc/request/blockchain.rs @@ -12,7 +12,8 @@ use tower::{Service, ServiceExt}; use cuprate_helper::cast::{u64_to_usize, usize_to_u64}; use cuprate_types::{ blockchain::{BlockchainReadRequest, BlockchainResponse}, - Chain, ExtendedBlockHeader, OutputOnChain, + Chain, CoinbaseTxSum, ExtendedBlockHeader, MinerData, OutputHistogramEntry, + OutputHistogramInput, OutputOnChain, }; /// [`BlockchainReadRequest::BlockExtendedHeader`]. @@ -290,38 +291,46 @@ pub(super) async fn difficulty( /// [`BlockchainReadRequest::OutputHistogram`] pub(super) async fn output_histogram( mut blockchain_read: BlockchainReadHandle, -) -> Result<(), Error> { - let BlockchainResponse::OutputHistogram(_) = blockchain_read + input: OutputHistogramInput, +) -> Result, Error> { + let BlockchainResponse::OutputHistogram(histogram) = blockchain_read .ready() .await? - .call(BlockchainReadRequest::OutputHistogram) + .call(BlockchainReadRequest::OutputHistogram(input)) .await? else { unreachable!(); }; - Ok(todo!()) + Ok(histogram) } /// [`BlockchainReadRequest::CoinbaseTxSum`] pub(super) async fn coinbase_tx_sum( mut blockchain_read: BlockchainReadHandle, -) -> Result<(), Error> { - let BlockchainResponse::CoinbaseTxSum(_) = blockchain_read + height: u64, + count: u64, +) -> Result { + let BlockchainResponse::CoinbaseTxSum(sum) = blockchain_read .ready() .await? - .call(BlockchainReadRequest::CoinbaseTxSum) + .call(BlockchainReadRequest::CoinbaseTxSum { + height: u64_to_usize(height), + count, + }) .await? else { unreachable!(); }; - Ok(todo!()) + Ok(sum) } /// [`BlockchainReadRequest::MinerData`] -pub(super) async fn miner_data(mut blockchain_read: BlockchainReadHandle) -> Result<(), Error> { - let BlockchainResponse::MinerData(_) = blockchain_read +pub(super) async fn miner_data( + mut blockchain_read: BlockchainReadHandle, +) -> Result { + let BlockchainResponse::MinerData(data) = blockchain_read .ready() .await? .call(BlockchainReadRequest::MinerData) @@ -330,5 +339,5 @@ pub(super) async fn miner_data(mut blockchain_read: BlockchainReadHandle) -> Res unreachable!(); }; - Ok(todo!()) + Ok(data) } diff --git a/storage/blockchain/src/service/read.rs b/storage/blockchain/src/service/read.rs index bed2cf2..05af6ca 100644 --- a/storage/blockchain/src/service/read.rs +++ b/storage/blockchain/src/service/read.rs @@ -4,6 +4,7 @@ unreachable_code, unused_variables, clippy::unnecessary_wraps, + clippy::needless_pass_by_value, reason = "TODO: finish implementing the signatures from " )] @@ -25,7 +26,7 @@ use cuprate_database_service::{init_thread_pool, DatabaseReadService, ReaderThre use cuprate_helper::map::combine_low_high_bits_to_u128; use cuprate_types::{ blockchain::{BlockchainReadRequest, BlockchainResponse}, - Chain, ChainId, ExtendedBlockHeader, OutputOnChain, + Chain, ChainId, ExtendedBlockHeader, OutputHistogramInput, OutputOnChain, }; use crate::{ @@ -114,13 +115,13 @@ fn map_request( R::CompactChainHistory => compact_chain_history(env), R::FindFirstUnknown(block_ids) => find_first_unknown(env, &block_ids), R::AltBlocksInChain(chain_id) => alt_blocks_in_chain(env, chain_id), - R::Block(height) => block(env, height), + R::Block { height } => block(env, height), R::BlockByHash(hash) => block_by_hash(env, hash), R::TotalTxCount => total_tx_count(env), R::DatabaseSize => database_size(env), R::Difficulty(height) => difficulty(env, height), - R::OutputHistogram => output_histogram(env), - R::CoinbaseTxSum => coinbase_tx_sum(env), + R::OutputHistogram(input) => output_histogram(env, input), + R::CoinbaseTxSum { height, count } => coinbase_tx_sum(env, height, count), R::MinerData => miner_data(env), } @@ -646,12 +647,12 @@ fn difficulty(env: &ConcreteEnv, block_height: BlockHeight) -> ResponseResult { } /// [`BlockchainReadRequest::OutputHistogram`] -fn output_histogram(env: &ConcreteEnv) -> ResponseResult { +fn output_histogram(env: &ConcreteEnv, input: OutputHistogramInput) -> ResponseResult { Ok(BlockchainResponse::OutputHistogram(todo!())) } /// [`BlockchainReadRequest::CoinbaseTxSum`] -fn coinbase_tx_sum(env: &ConcreteEnv) -> ResponseResult { +fn coinbase_tx_sum(env: &ConcreteEnv, height: usize, count: u64) -> ResponseResult { Ok(BlockchainResponse::CoinbaseTxSum(todo!())) } diff --git a/types/src/blockchain.rs b/types/src/blockchain.rs index 7126c21..b72e550 100644 --- a/types/src/blockchain.rs +++ b/types/src/blockchain.rs @@ -12,7 +12,8 @@ use monero_serai::block::Block; use crate::{ types::{Chain, ExtendedBlockHeader, OutputOnChain, VerifiedBlockInformation}, - AltBlockInformation, ChainId, + AltBlockInformation, ChainId, CoinbaseTxSum, MinerData, OutputHistogramEntry, + OutputHistogramInput, }; //---------------------------------------------------------------------------------------------------- ReadRequest @@ -106,28 +107,40 @@ pub enum BlockchainReadRequest { /// A request for all alt blocks in the chain with the given [`ChainId`]. AltBlocksInChain(ChainId), - /// TODO - Block(usize), + /// Get a [`Block`] by its height. + Block { + height: usize, + }, - /// TODO + /// Get a [`Block`] by its hash. BlockByHash([u8; 32]), - /// TODO + /// Get the total amount of non-coinbase transactions in the chain. TotalTxCount, - /// TODO + /// Get the current size of the database. DatabaseSize, - // TODO + // Get the difficulty for the next block in the chain. Difficulty(usize), - /// TODO - OutputHistogram, + /// Get an output histogram. + /// + /// TODO: document fields after impl. + OutputHistogram(OutputHistogramInput), - /// TODO - CoinbaseTxSum, + /// Get the coinbase amount and the fees amount for + /// `N` last blocks starting at particular height. + /// + /// TODO: document fields after impl. + CoinbaseTxSum { + height: usize, + count: u64, + }, - /// TODO + /// Get the necessary data to create a custom block template. + /// + /// These are used by p2pool. MinerData, } @@ -242,54 +255,46 @@ pub enum BlockchainResponse { cumulative_difficulty: u128, }, - /// The response for [`BlockchainReadRequest::FindFirstUnknown`]. + /// Response to [`BlockchainReadRequest::FindFirstUnknown`]. /// /// Contains the index of the first unknown block and its expected height. /// /// This will be [`None`] if all blocks were known. FindFirstUnknown(Option<(usize, usize)>), - /// The response for [`BlockchainReadRequest::AltBlocksInChain`]. + /// Response to [`BlockchainReadRequest::AltBlocksInChain`]. /// /// Contains all the alt blocks in the alt-chain in chronological order. AltBlocksInChain(Vec), - /// The response for: + /// Response to: /// - [`BlockchainReadRequest::Block`]. /// - [`BlockchainReadRequest::BlockByHash`]. - /// - /// TODO Block(Block), - /// The response for [`BlockchainReadRequest::TotalTxCount`]. - /// - /// TODO + /// Response to [`BlockchainReadRequest::TotalTxCount`]. TotalTxCount(usize), - /// The response for [`BlockchainReadRequest::TotalTxCount`]. - /// - /// TODO - DatabaseSize { database_size: u64, free_space: u64 }, + /// Response to [`BlockchainReadRequest::DatabaseSize`]. + DatabaseSize { + /// The size of the database file in bytes. + database_size: u64, + /// The amount of free bytes there are + /// the disk where the database is located. + free_space: u64, + }, - /// The response for [`BlockchainReadRequest::TotalTxCount`]. - /// - // TODO + /// Response to [`BlockchainReadRequest::Difficulty`]. Difficulty(u128), - /// The response for [`BlockchainReadRequest::TotalTxCount`]. - /// - /// TODO - OutputHistogram(std::convert::Infallible), + /// Response to [`BlockchainReadRequest::OutputHistogram`]. + OutputHistogram(Vec), - /// The response for [`BlockchainReadRequest::TotalTxCount`]. - /// - /// TODO - CoinbaseTxSum(std::convert::Infallible), + /// Response to [`BlockchainReadRequest::CoinbaseTxSum`]. + CoinbaseTxSum(CoinbaseTxSum), - /// The response for [`BlockchainReadRequest::TotalTxCount`]. - /// - /// TODO - MinerData(std::convert::Infallible), + /// Response to [`BlockchainReadRequest::MinerData`]. + MinerData(MinerData), //------------------------------------------------------ Writes /// A generic Ok response to indicate a request was successfully handled. @@ -301,7 +306,7 @@ pub enum BlockchainResponse { /// - [`BlockchainWriteRequest::FlushAltBlocks`] Ok, - /// The response for [`BlockchainWriteRequest::PopBlocks`]. + /// Response to [`BlockchainWriteRequest::PopBlocks`]. /// /// The inner value is the alt-chain ID for the old main chain blocks. PopBlocks(ChainId), diff --git a/types/src/lib.rs b/types/src/lib.rs index 0b0dbe6..02b2f6c 100644 --- a/types/src/lib.rs +++ b/types/src/lib.rs @@ -20,7 +20,8 @@ pub use transaction_verification_data::{ CachedVerificationState, TransactionVerificationData, TxVersion, }; pub use types::{ - AltBlockInformation, Chain, ChainId, ExtendedBlockHeader, OutputOnChain, + AltBlockInformation, Chain, ChainId, CoinbaseTxSum, ExtendedBlockHeader, MinerData, + MinerDataTxBacklogEntry, OutputHistogramEntry, OutputHistogramInput, OutputOnChain, VerifiedBlockInformation, VerifiedTransactionInformation, }; diff --git a/types/src/types.rs b/types/src/types.rs index a60ce6c..e09a166 100644 --- a/types/src/types.rs +++ b/types/src/types.rs @@ -1,6 +1,5 @@ //! Various shared data types in Cuprate. -//---------------------------------------------------------------------------------------------------- Import use std::num::NonZero; use curve25519_dalek::edwards::EdwardsPoint; @@ -11,7 +10,6 @@ use monero_serai::{ use crate::HardFork; -//---------------------------------------------------------------------------------------------------- ExtendedBlockHeader /// Extended header data of a block. /// /// This contains various metadata of a block, but not the block blob itself. @@ -37,7 +35,6 @@ pub struct ExtendedBlockHeader { pub long_term_weight: usize, } -//---------------------------------------------------------------------------------------------------- VerifiedTransactionInformation /// Verified information of a transaction. /// /// This represents a valid transaction @@ -61,7 +58,6 @@ pub struct VerifiedTransactionInformation { pub tx_hash: [u8; 32], } -//---------------------------------------------------------------------------------------------------- VerifiedBlockInformation /// Verified information of a block. /// /// This represents a block that has already been verified to be correct. @@ -94,14 +90,12 @@ pub struct VerifiedBlockInformation { pub cumulative_difficulty: u128, } -//---------------------------------------------------------------------------------------------------- ChainID /// A unique ID for an alt chain. /// /// The inner value is meaningless. #[derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)] pub struct ChainId(pub NonZero); -//---------------------------------------------------------------------------------------------------- Chain /// An identifier for a chain. #[derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)] pub enum Chain { @@ -111,7 +105,6 @@ pub enum Chain { Alt(ChainId), } -//---------------------------------------------------------------------------------------------------- AltBlockInformation /// A block on an alternative chain. #[derive(Clone, Debug, PartialEq, Eq)] pub struct AltBlockInformation { @@ -141,7 +134,6 @@ pub struct AltBlockInformation { pub chain_id: ChainId, } -//---------------------------------------------------------------------------------------------------- OutputOnChain /// An already existing transaction output. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct OutputOnChain { @@ -155,6 +147,57 @@ pub struct OutputOnChain { pub commitment: EdwardsPoint, } +/// TODO +#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct OutputHistogramInput { + pub amounts: Vec, + pub min_count: u64, + pub max_count: u64, + pub unlocked: bool, + pub recent_cutoff: u64, +} + +/// TODO +#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct OutputHistogramEntry { + pub amount: u64, + pub total_instances: u64, + pub unlocked_instances: u64, + pub recent_instances: u64, +} + +/// TODO +#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct CoinbaseTxSum { + pub emission_amount: u64, + pub emission_amount_top64: u64, + pub fee_amount: u64, + pub fee_amount_top64: u64, + pub wide_emission_amount: u128, + pub wide_fee_amount: u128, +} + +/// TODO +#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct MinerData { + pub major_version: u8, + pub height: u64, + pub prev_id: [u8; 32], + pub seed_hash: [u8; 32], + pub difficulty: u128, + pub median_weight: u64, + pub already_generated_coins: u64, + pub tx_backlog: Vec, +} + +/// TODO +#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct MinerDataTxBacklogEntry { + pub id: [u8; 32], + pub weight: u64, + pub fee: u64, +} + //---------------------------------------------------------------------------------------------------- Tests #[cfg(test)] mod test {