From bf07f2c84c196e46849c921fc0302692f751e8f6 Mon Sep 17 00:00:00 2001
From: "hinto.janai" <hinto.janai@protonmail.com>
Date: Wed, 16 Oct 2024 20:46:24 -0400
Subject: [PATCH] `BlockchainManagerRequest` docs

---
 binaries/cuprated/src/rpc/handler.rs          | 46 +++++++++++++------
 binaries/cuprated/src/rpc/json.rs             |  6 ++-
 .../src/rpc/request/blockchain_manager.rs     |  4 +-
 3 files changed, 38 insertions(+), 18 deletions(-)

diff --git a/binaries/cuprated/src/rpc/handler.rs b/binaries/cuprated/src/rpc/handler.rs
index bfa6a82..13e8924 100644
--- a/binaries/cuprated/src/rpc/handler.rs
+++ b/binaries/cuprated/src/rpc/handler.rs
@@ -69,30 +69,48 @@ pub enum BlockchainManagerRequest {
         seed_hash: [u8; 32],
     },
 
-    /// TODO
+    /// Add auxirilly proof-of-work to a block.
+    ///
+    /// From the RPC `add_aux_pow` usecase's documentation:
+    /// ````
+    /// This enables merge mining with Monero without requiring
+    /// software that manually alters the extra field in the coinbase
+    /// tx to include the merkle root of the aux blocks.
+    /// ````
     AddAuxPow {
-        /// TODO
-        blocktemplate_blob: Vec<u8>,
-        /// TODO
+        /// The block template to add to.
+        block_template: Block,
+        /// The auxirilly proof-of-work to add.
         aux_pow: Vec<AuxPow>,
     },
 
-    /// TODO
+    /// Generate new blocks.
+    ///
+    /// This request is only for regtest, see RPC's `generateblocks`.
     GenerateBlocks {
-        /// TODO
+        /// Number of the blocks to be generated.
         amount_of_blocks: u64,
-        /// TODO
+        /// The previous block's hash.
         prev_block: [u8; 32],
-        /// TODO
+        /// The starting value for the nonce.
         starting_nonce: u32,
-        /// TODO
+        /// The address that will receive the coinbase reward.
         wallet_address: String,
     },
 
-    /// TODO
+    /// Get a visual [`String`] overview of blockchain progress.
     ///
-    /// <https://github.com/monero-project/monero/blob/master/src/cryptonote_protocol/block_queue.cpp#L178>
-    Overview { height: usize },
+    /// This is a highly implementation specific format used by
+    /// `monerod` in the `sync_info` RPC call's `overview` field;
+    /// it is essentially an ASCII visual of blocks.
+    ///
+    /// See also:
+    /// - <https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#sync_info>
+    /// - <https://github.com/monero-project/monero/blob/master/src/cryptonote_protocol/block_queue.cpp#L178>
+    Overview {
+        /// TODO: the current blockchain height? do we need to pass this?
+        height: usize,
+    },
 }
 
 /// TODO: use real type when public.
@@ -134,9 +152,9 @@ pub enum BlockchainManagerResponse {
 
     /// Response to [`BlockchainManagerRequest::GenerateBlocks`]
     GenerateBlocks {
-        /// TODO
+        /// Hashes of the blocks generated.
         blocks: Vec<[u8; 32]>,
-        /// TODO
+        /// The new top height. (TODO: is this correct?)
         height: usize,
     },
 
diff --git a/binaries/cuprated/src/rpc/json.rs b/binaries/cuprated/src/rpc/json.rs
index 204b36f..a8ee552 100644
--- a/binaries/cuprated/src/rpc/json.rs
+++ b/binaries/cuprated/src/rpc/json.rs
@@ -910,7 +910,9 @@ async fn add_aux_pow(
     mut state: CupratedRpcHandler,
     request: AddAuxPowRequest,
 ) -> Result<AddAuxPowResponse, Error> {
-    let blocktemplate_blob = hex::decode(request.blocktemplate_blob)?;
+    let hex = hex::decode(request.blocktemplate_blob)?;
+    let block_template = Block::read(&mut hex.as_slice())?;
+
     let aux_pow = request
         .aux_pow
         .into_iter()
@@ -922,7 +924,7 @@ async fn add_aux_pow(
         .collect::<Result<Vec<_>, Error>>()?;
 
     let resp =
-        blockchain_manager::add_aux_pow(&mut state.blockchain_manager, blocktemplate_blob, aux_pow)
+        blockchain_manager::add_aux_pow(&mut state.blockchain_manager, block_template, aux_pow)
             .await?;
 
     let blocktemplate_blob = hex::encode(resp.blocktemplate_blob);
diff --git a/binaries/cuprated/src/rpc/request/blockchain_manager.rs b/binaries/cuprated/src/rpc/request/blockchain_manager.rs
index 1ee702d..62eecda 100644
--- a/binaries/cuprated/src/rpc/request/blockchain_manager.rs
+++ b/binaries/cuprated/src/rpc/request/blockchain_manager.rs
@@ -172,14 +172,14 @@ pub(crate) async fn calculate_pow(
 /// [`BlockchainManagerRequest::AddAuxPow`]
 pub(crate) async fn add_aux_pow(
     blockchain_manager: &mut BlockchainManagerHandle,
-    blocktemplate_blob: Vec<u8>,
+    block_template: Block,
     aux_pow: Vec<AuxPow>,
 ) -> Result<AddAuxPow, Error> {
     let BlockchainManagerResponse::AddAuxPow(response) = blockchain_manager
         .ready()
         .await?
         .call(BlockchainManagerRequest::AddAuxPow {
-            blocktemplate_blob,
+            block_template,
             aux_pow,
         })
         .await?