feat: add block hash to grpc method (#7025)

Description
---
Added optional block hash to grpc method GetCompletedTransactionsRequest


Motivation and Context
---
Some clients maw want to filter completed transactions by block hash.

How Has This Been Tested?
---
System-level testing running thre grpc call.

What process can a PR reviewer use to test or verify this change?
---
Code review
System-level testing 

<!-- Checklist -->
<!-- 1. Is the title of your PR in the form that would make nice release
notes? The title, excluding the conventional commit
tag, will be included exactly as is in the CHANGELOG, so please think
about it carefully. -->


Breaking Changes
---

- [x] None
- [ ] Requires data directory on base node to be deleted
- [ ] Requires hard fork
- [ ] Other - Please specify

<!-- Does this include a breaking change? If so, include this line as a
footer -->
<!-- BREAKING CHANGE: Description what the user should do, e.g. delete a
database, resync the chain -->


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Added support for filtering completed wallet transactions by block
hash alongside payment ID.

- **Tests**
- Updated test cases and integration tests to accommodate the new block
hash filter parameter when retrieving completed transactions.

- **Chores**
- Enhanced internal request structures, gRPC service, and database
queries to support filtering by block hash.

No changes to user interface or existing transaction retrieval behavior
unless the new filter is applied.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: SW van Heerden <swvheerden@gmail.com>

Author: hansieodendaal

.license.ignore

@@ -2,6 +2,7 @@
 ./applications/minotari_node/assets/tari_logo.rs
 ./applications/minotari_node/osx-pkg/entitlements.xml
 ./base_layer/contacts/src/schema.rs
+./base_layer/core/src/blocks/gen_block/Tari.Manifesto
 ./base_layer/core/src/transactions/transaction_key_manager/schema.rs
 ./base_layer/key_manager/src/schema.rs
 ./base_layer/wallet/src/schema.rs

applications/minotari_app_grpc/proto/wallet.proto

@@ -49,6 +49,7 @@ service Wallet {
   // ```
 
   rpc GetVersion (GetVersionRequest) returns (GetVersionResponse);
+
   // Returns the current operational state of the wallet.
   //
   // This RPC provides an overview of the wallet's internal status, including:
@@ -84,6 +85,7 @@ service Wallet {
   // }
   // ```
   rpc GetState (GetStateRequest) returns (GetStateResponse);
+
   // This RPC returns a lightweight response indicating whether the wallet is connected to the network, attempting to connect, or currently offline. This is useful for UIs or clients to determine if network interactions like transactions or syncs are possible.
   //
   // Example usage (JavaScript):
@@ -99,8 +101,10 @@ service Wallet {
   // }
   // ```
   rpc CheckConnectivity(GetConnectivityRequest) returns (CheckConnectivityResponse);
+
   // Check for new updates
   rpc CheckForUpdates (Empty) returns (SoftwareUpdate);
+
   // The `Identify` RPC call returns the identity information of the wallet node.
   // This includes:
   // - **Public Key**: The wallet’s cryptographic public key.
@@ -129,6 +133,7 @@ service Wallet {
   // }
   // ```
   rpc Identify (GetIdentityRequest) returns (GetIdentityResponse);
+
   // This RPC returns two types of wallet addresses: interactive and one-sided addresses.
   // It provides these addresses in byte format as part of the response.
   // - **Interactive Address**: This is a type of address used for interaction and communication with the wallet.
@@ -153,6 +158,7 @@ service Wallet {
   // }
   // ```
   rpc GetAddress (Empty) returns (GetAddressResponse);
+
   // This RPC returns addresses generated for a specific payment ID. It provides both the interactive 
   // and one-sided addresses for the given payment ID, along with their respective representations in 
   // base58 and emoji formats.
@@ -188,6 +194,7 @@ service Wallet {
   //```
   //
   rpc GetPaymentIdAddress (GetPaymentIdAddressRequest) returns (GetCompleteAddressResponse);
+
   // This RPC call that retrieves the current wallet's interactive and one-sided addresses in multiple formats and returns them in a structured response.
   // The response includes:
   // - Raw binary
@@ -216,6 +223,7 @@ service Wallet {
   // }
   // ```
   rpc GetCompleteAddress (Empty) returns (GetCompleteAddressResponse);
+
   // This call supports standard interactive transactions (Mimblewimble),
   // one-sided transactions, and one-sided-to-stealth-address transactions.
   // Each recipient must include a valid Tari address, amount, fee, and payment type.
@@ -304,10 +312,11 @@ service Wallet {
   // }
   // ```
   rpc GetTransactionInfo (GetTransactionInfoRequest) returns (GetTransactionInfoResponse);
+
   // Streams completed transactions for a given user payment ID.
   //
   // The `GetCompletedTransactions` call retrieves all completed wallet transactions,
-  // optionally filtered by a specific `payment_id`. The response is streamed back to the client
+  // optionally filtered by a specific `payment_id` and/or block hash. The response is streamed back to the client
   // one transaction at a time, with each transaction including details such as status, direction,
   // amount, fees, and associated metadata.
   //
@@ -324,6 +333,14 @@ service Wallet {
   //     - Exactly **one format must be set**. Providing more than one or none results in an error.
   //     - If no `payment_id` is provided, all completed transactions will be returned.
   //
+  // - `block_hash` (optional):
+  //   - **Type**: `string`
+  //   - **Description**: A specific block hash to filter transactions by.
+  //   - **Accepted Formats**
+  //     - Hexadecimal string representing the block hash.
+  //   - **Restrictions**:
+  //     - If provided, the transactions will be filtered to only those included in the specified block.
+  //
   // ### Example JavaScript gRPC client usage:
   //
   // ```javascript
@@ -361,6 +378,7 @@ service Wallet {
   // }
   // ```
   rpc GetCompletedTransactions (GetCompletedTransactionsRequest) returns (stream GetCompletedTransactionsResponse);
+
   // Returns the wallet balance details.
   //
   // The `GetBalance` call retrieves the current balance status of the wallet,
@@ -406,6 +424,7 @@ service Wallet {
   // }
   // ```
   rpc GetBalance (GetBalanceRequest) returns (GetBalanceResponse);
+
   // Returns the total value of unspent outputs in the wallet.
   //
   // The `GetUnspentAmounts` call retrieves the sum of all unspent output amounts
@@ -435,6 +454,7 @@ service Wallet {
   // }
   // ```
   rpc GetUnspentAmounts (Empty) returns (GetUnspentAmountsResponse);
+
   // Creates a transaction that splits funds into multiple smaller outputs.
   //
   // The `CoinSplit` call initiates a transaction that divides wallet funds into several equal-sized outputs.
@@ -492,6 +512,7 @@ service Wallet {
   // }
   // ```
   rpc CoinSplit (CoinSplitRequest) returns (CoinSplitResponse);
+
   // Imports UTXOs into the wallet as spendable outputs.
   //
   // The `ImportUtxos` call allows you to manually insert one or more previously received UTXOs
@@ -535,6 +556,7 @@ service Wallet {
   // }
   // ```
   rpc ImportUtxos (ImportUtxosRequest) returns (ImportUtxosResponse);
+
   // Returns the wallet's current network connectivity status.
   //
   // The `GetNetworkStatus` call provides a snapshot of the wallet’s connection to the Tari network,
@@ -583,6 +605,7 @@ service Wallet {
   //   - This status means the wallet is unable to communicate with the network and cannot perform any network-related operations.
   //
   rpc GetNetworkStatus(Empty) returns (NetworkStatusResponse);
+
   // Returns a list of peers currently connected to the wallet.
   //
   // The `ListConnectedPeers` call retrieves information about peers that the wallet is currently
@@ -647,6 +670,7 @@ service Wallet {
   // }
   // ```
   rpc ListConnectedPeers(Empty) returns (ListConnectedPeersResponse);
+
   // Cancels a specific transaction by its ID.
   //
   // The `CancelTransaction` call allows a transaction to be cancelled by its unique transaction ID (TxId).
@@ -683,10 +707,13 @@ service Wallet {
   // }
   // ```
   rpc CancelTransaction (CancelTransactionRequest) returns (CancelTransactionResponse);
+
   // Will trigger a complete revalidation of all wallet outputs.
   rpc RevalidateAllTransactions (RevalidateRequest) returns (RevalidateResponse);
+
   // Will trigger a validation of all wallet outputs.
   rpc ValidateAllTransactions (ValidateRequest) returns (ValidateResponse);
+
   // Sends a XTR SHA Atomic Swap transaction.
   //
   // The `SendShaAtomicSwapTransaction` call is used to initiate an Atomic Swap 
@@ -731,6 +758,7 @@ service Wallet {
   //   "failure_message": ""
   // }
   rpc SendShaAtomicSwapTransaction(SendShaAtomicSwapRequest) returns (SendShaAtomicSwapResponse);
+
   // Creates a burn transaction for burning a specified amount of Tari currency.
   //
   // The `CreateBurnTransaction` call facilitates burning a certain amount of Tari
@@ -778,6 +806,7 @@ service Wallet {
   //   "reciprocal_claim_public_key": "0xreciprocalpublickey"
   // }
   rpc CreateBurnTransaction(CreateBurnTransactionRequest) returns (CreateBurnTransactionResponse);
+
   // Claims a SHA Atomic Swap transaction using a pre-image and output hash.
   //
   // The `ClaimShaAtomicSwapTransaction` call allows the user to unlock and claim funds from
@@ -822,6 +851,7 @@ service Wallet {
   //   }
   // }
   rpc ClaimShaAtomicSwapTransaction(ClaimShaAtomicSwapRequest) returns (ClaimShaAtomicSwapResponse);
+
   // Claims an HTLC refund transaction after the timelock period has passed.
   //
   // The `ClaimHtlcRefundTransaction` call enables the original sender of a Hash Time-Locked Contract (HTLC)
@@ -862,8 +892,10 @@ service Wallet {
   //   }
   // }
   rpc ClaimHtlcRefundTransaction(ClaimHtlcRefundRequest) returns (ClaimHtlcRefundResponse);
+
   // Creates a transaction with a template registration output
   rpc CreateTemplateRegistration(CreateTemplateRegistrationRequest) returns (CreateTemplateRegistrationResponse);
+
   // The SetBaseNode call configures the base node peer for the wallet.
   //
   // This RPC sets the public key and network address of the base node peer that the wallet should communicate with.
@@ -898,6 +930,7 @@ service Wallet {
   // {}
   // ```
   rpc SetBaseNode(SetBaseNodeRequest) returns (SetBaseNodeResponse);
+
   // Streams real-time wallet transaction events to the client.
   //
   // The `StreamTransactionEvents` RPC provides a continuous stream of transaction events as they occur within the wallet.
@@ -1141,6 +1174,11 @@ enum TransactionStatus {
 
 message GetCompletedTransactionsRequest {
   UserPaymentId payment_id = 1;
+  BlockHashHex block_hash = 2;
+}
+
+message BlockHashHex {
+  string hash = 1;
 }
 
 message GetCompletedTransactionsResponse {

applications/minotari_console_wallet/src/grpc/wallet_grpc_server.rs

@@ -930,9 +930,18 @@ impl wallet_server::Wallet for WalletGrpcServer {
         } else {
             None
         };
+        let block_hash = if let Some(hash) = message.block_hash {
+            Some(
+                BlockHash::from_hex(&hash.hash)
+                    .map_err(|_| Status::internal("Output hash is malformed".to_string()))?,
+            )
+        } else {
+            None
+        };
+
         let mut transaction_service = self.get_transaction_service();
         let transactions = transaction_service
-            .get_completed_transactions(payment_id)
+            .get_completed_transactions(payment_id, block_hash)
             .await
             .map_err(|err| Status::not_found(format!("No completed transactions found: {:?}", err)))?;
         debug!(

applications/minotari_console_wallet/src/ui/state/app_state.rs

@@ -751,7 +751,12 @@ impl AppStateInner {
             .collect::<Result<Vec<_>, _>>()?;
 
         let mut completed_transactions: Vec<CompletedTransaction> = Vec::new();
-        completed_transactions.extend(self.wallet.transaction_service.get_completed_transactions(None).await?);
+        completed_transactions.extend(
+            self.wallet
+                .transaction_service
+                .get_completed_transactions(None, None)
+                .await?,
+        );
 
         completed_transactions.extend(
             self.wallet

base_layer/wallet/src/transaction_service/handle.rs

@@ -79,7 +79,10 @@ use crate::{
 pub enum TransactionServiceRequest {
     GetPendingInboundTransactions,
     GetPendingOutboundTransactions,
-    GetCompletedTransactions(Option<Vec<u8>>),
+    GetCompletedTransactions {
+        payment_id: Option<Vec<u8>>,
+        block_hash: Option<FixedHash>,
+    },
     GetCancelledPendingInboundTransactions,
     GetCancelledPendingOutboundTransactions,
     GetCancelledCompletedTransactions,
@@ -208,7 +211,7 @@ impl fmt::Display for TransactionServiceRequest {
         match self {
             Self::GetPendingInboundTransactions => write!(f, "GetPendingInboundTransactions"),
             Self::GetPendingOutboundTransactions => write!(f, "GetPendingOutboundTransactions"),
-            Self::GetCompletedTransactions(_) => write!(f, "GetCompletedTransactions"),
+            Self::GetCompletedTransactions { .. } => write!(f, "GetCompletedTransactions"),
             Self::ImportTransaction(tx) => write!(f, "ImportTransaction: {:?}", tx),
             Self::GetCancelledPendingInboundTransactions => write!(f, "GetCancelledPendingInboundTransactions"),
             Self::GetCancelledPendingOutboundTransactions => write!(f, "GetCancelledPendingOutboundTransactions"),
@@ -963,10 +966,11 @@ impl TransactionServiceHandle {
     pub async fn get_completed_transactions(
         &mut self,
         payment_id: Option<Vec<u8>>,
+        block_hash: Option<FixedHash>,
     ) -> Result<Vec<CompletedTransaction>, TransactionServiceError> {
         match self
             .handle
-            .call(TransactionServiceRequest::GetCompletedTransactions(payment_id))
+            .call(TransactionServiceRequest::GetCompletedTransactions { payment_id, block_hash })
             .await??
         {
             TransactionServiceResponse::CompletedTransactions(c) => Ok(c),

base_layer/wallet/src/transaction_service/service.rs

@@ -891,9 +891,11 @@ where
                 TransactionServiceResponse::PendingOutboundTransactions(self.db.get_pending_outbound_transactions()?),
             ),
 
-            TransactionServiceRequest::GetCompletedTransactions(payment_id) => Ok(
-                TransactionServiceResponse::CompletedTransactions(self.db.get_completed_transactions(payment_id)?),
-            ),
+            TransactionServiceRequest::GetCompletedTransactions { payment_id, block_hash } => {
+                Ok(TransactionServiceResponse::CompletedTransactions(
+                    self.db.get_completed_transactions(payment_id, block_hash)?,
+                ))
+            },
             TransactionServiceRequest::GetCancelledPendingInboundTransactions => {
                 Ok(TransactionServiceResponse::PendingInboundTransactions(
                     self.db.get_cancelled_pending_inbound_transactions()?,

base_layer/wallet/src/transaction_service/storage/database.rs

@@ -31,7 +31,7 @@ use log::*;
 use tari_common_types::{
     tari_address::TariAddress,
     transaction::{TransactionDirection, TransactionStatus, TxId},
-    types::{BlockHash, PrivateKey},
+    types::{BlockHash, FixedHash, PrivateKey},
 };
 use tari_core::transactions::{
     tari_amount::MicroMinotari,
@@ -156,9 +156,10 @@ pub trait TransactionBackend: Send + Sync + Clone {
         height: u64,
     ) -> Result<Vec<CompletedTransaction>, TransactionStorageError>;
 
-    fn find_completed_transactions_for_payment_id(
+    fn find_completed_transactions_filter_payment_id_block_hash(
         &self,
-        payment_id: Vec<u8>,
+        payment_id: Option<Vec<u8>>,
+        block_hash: Option<FixedHash>,
     ) -> Result<Vec<CompletedTransaction>, TransactionStorageError>;
 }
 
@@ -482,11 +483,14 @@ where T: TransactionBackend + 'static
         Ok(t)
     }
 
-    pub fn get_completed_transactions_by_payment_id(
+    pub fn get_completed_transactions_filter_payment_id_block_hash(
         &self,
-        payment_id: Vec<u8>,
+        payment_id: Option<Vec<u8>>,
+        block_hash: Option<FixedHash>,
     ) -> Result<Vec<CompletedTransaction>, TransactionStorageError> {
-        let t = self.db.find_completed_transactions_for_payment_id(payment_id)?;
+        let t = self
+            .db
+            .find_completed_transactions_filter_payment_id_block_hash(payment_id, block_hash)?;
         Ok(t)
     }
 
@@ -599,12 +603,13 @@ where T: TransactionBackend + 'static
     pub fn get_completed_transactions(
         &self,
         payment_id: Option<Vec<u8>>,
+        block_hash: Option<FixedHash>,
     ) -> Result<Vec<CompletedTransaction>, TransactionStorageError> {
-        self.get_completed_transactions_by_cancelled(payment_id, false)
+        self.get_completed_transactions_by_cancelled(payment_id, false, block_hash)
     }
 
     pub fn get_cancelled_completed_transactions(&self) -> Result<Vec<CompletedTransaction>, TransactionStorageError> {
-        self.get_completed_transactions_by_cancelled(None, true)
+        self.get_completed_transactions_by_cancelled(None, true, None)
     }
 
     pub fn get_any_transaction(&self, tx_id: TxId) -> Result<Option<WalletTransaction>, TransactionStorageError> {
@@ -630,15 +635,15 @@ where T: TransactionBackend + 'static
         &self,
         payment_id: Option<Vec<u8>>,
         cancelled: bool,
+        block_hash: Option<FixedHash>,
     ) -> Result<Vec<CompletedTransaction>, TransactionStorageError> {
         let key = if cancelled {
             DbKey::CancelledCompletedTransactions
         } else {
             DbKey::CompletedTransactions
         };
-        match payment_id {
-            Some(payment_id) => self.db.find_completed_transactions_for_payment_id(payment_id),
-            None => {
+        match (payment_id.is_none(), block_hash.is_none()) {
+            (true, true) => {
                 let t = match self.db.fetch(&key) {
                     Ok(None) => log_error(
                         key,
@@ -652,6 +657,9 @@ where T: TransactionBackend + 'static
                 }?;
                 Ok(t)
             },
+            (_, _) => self
+                .db
+                .find_completed_transactions_filter_payment_id_block_hash(payment_id, block_hash),
         }
     }