feat: full PayRef implementation

applications/minotari_app_grpc/Cargo.toml

@@ -10,7 +10,7 @@ license.workspace = true
 [dependencies]
 tari_common_types = { workspace = true }
 tari_comms = { workspace = true }
-tari_core = { workspace = true }
+tari_core = { workspace = true, features = ["base_node"] }
 tari_crypto = { workspace = true }
 tari_script = { workspace = true }
 tari_max_size = { workspace = true }

applications/minotari_app_grpc/proto/base_node.proto

@@ -100,6 +100,8 @@ service BaseNode {
     rpc GetTemplateRegistrations(GetTemplateRegistrationsRequest) returns (stream GetTemplateRegistrationResponse);
     rpc GetSideChainUtxos(GetSideChainUtxosRequest) returns (stream GetSideChainUtxosResponse);
     rpc GetNetworkState(GetNetworkStateRequest) returns (GetNetworkStateResponse);
+    // PayRef (Payment Reference) lookup for block explorers and external services
+    rpc SearchPaymentReferences(SearchPaymentReferencesRequest) returns (stream PaymentReferenceResponse);
 }
 
 message GetAssetMetadataRequest {
@@ -559,3 +561,35 @@ message LivenessResult{
     uint64 ping_latency = 3;
 }
 
+// PayRef (Payment Reference) search and lookup messages
+
+// Request to search for outputs by payment reference
+message SearchPaymentReferencesRequest {
+    // Payment reference as hex string (64 characters)
+    repeated string payment_reference_hex = 1;
+    // Optional: include spent outputs in results
+    bool include_spent = 2;
+}
+
+// Response containing payment reference match
+message PaymentReferenceResponse {
+    // The payment reference that was found
+    string payment_reference_hex = 1;
+    // Block height where the output was mined
+    uint64 block_height = 2;
+    // Block hash where the output was mined
+    bytes block_hash = 3;
+    // Timestamp when the output was mined
+    uint64 mined_timestamp = 4;
+    // Output commitment (32 bytes)
+    bytes commitment = 5;
+    // Whether this output has been spent
+    bool is_spent = 6;
+    // Height where output was spent (if spent)
+    uint64 spent_height = 7;
+    // Block hash where output was spent (if spent)
+    bytes spent_block_hash = 8;
+    // Transaction output amount will be 0 for non set a
+    uint64 min_value_promise = 9;
+}
+

applications/minotari_app_grpc/proto/transaction.proto

@@ -115,6 +115,10 @@ message TransactionOutput {
     bytes encrypted_data = 10;
     // The minimum value of the commitment that is proven by the range proof (in MicroMinotari)
     uint64 minimum_value_promise = 11;
+    // Payment reference (PayRef) - 32-byte Blake2b hash of (block_hash || output_hash)
+    // This provides a unique, deterministic reference for the output that can be used
+    // for payment verification without revealing wallet ownership
+    bytes payment_reference = 12;
 }
 
 // Options for UTXOs

applications/minotari_app_grpc/proto/wallet.proto

@@ -434,6 +434,44 @@ service Wallet {
   // ```
   rpc GetBlockHeightTransactions (GetBlockHeightTransactionsRequest) returns (GetBlockHeightTransactionsResponse);
 
+  // Returns all PayRefs (payment references) for a specific transaction.
+  //
+  // The `GetTransactionPayRefs` call retrieves all PayRefs associated with the specified
+  // transaction ID. PayRefs are cryptographic references generated from output hashes
+  // that allow recipients to verify payments without revealing sensitive transaction details.
+  //
+  // ### Request Parameters:
+  //
+  // - `transaction_id` (required):
+  //   - **Type**: `uint64`
+  //   - **Description**: The transaction ID to retrieve PayRefs for.
+  //   - **Restrictions**:
+  //     - Must be a valid transaction ID that exists in the wallet.
+  //     - If the transaction ID is invalid or not found, an error will be returned.
+  //
+  // ### Example JavaScript gRPC client usage:
+  //
+  // ```javascript
+  // const request = {
+  //   transaction_id: 12345
+  // };
+  // const response = await client.getTransactionPayRefs(request);
+  // console.log("PayRefs:", response.payment_references.map(ref => Buffer.from(ref).toString('hex')));
+  // ```
+  //
+  // ### Sample JSON Response:
+  //
+  // ```json
+  // {
+  //   "payment_references": [
+  //     "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+  //     "0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321"
+  //   ]
+  // }
+  // ```
+  rpc GetTransactionPayRefs (GetTransactionPayRefsRequest) returns (GetTransactionPayRefsResponse);
+
+
   // Returns the wallet balance details.
   //
   // The `GetBalance` call retrieves the current balance status of the wallet,
@@ -1050,6 +1088,52 @@ service Wallet {
 
   // Get all completed transactions including cancelled ones, sorted by timestamp and paginated
   rpc GetAllCompletedTransactions(GetAllCompletedTransactionsRequest) returns (GetAllCompletedTransactionsResponse);
+
+  // Gets transaction information by payment reference (PayRef)
+  //
+  // The `GetPaymentByReference` call retrieves transaction information using a 32-byte payment reference hash.
+  // PayRefs are generated as Blake2b_256(block_hash || output_hash) and provide a stable way to look up
+  // transactions even after outputs are spent.
+  //
+  // ### Request Parameters:
+  //
+  // - `payment_reference` (required):
+  //   - **Type**: `bytes` (32 bytes)
+  //   - **Description**: The payment reference hash to look up
+  //   - **Restrictions**: Must be exactly 32 bytes representing a valid PayRef
+  //
+  // ### Example JavaScript gRPC client usage:
+  //
+  // ```javascript
+  // const payref = Buffer.from('a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890', 'hex');
+  // const request = { payment_reference: payref };
+  // client.getPaymentByReference(request, (err, response) => {
+  //   if (err) console.error(err);
+  //   else console.log('Transaction found:', response.transaction);
+  // });
+  // ```
+  //
+  // ### Sample JSON Response:
+  //
+  // ```json
+  // {
+  //   "transaction": {
+  //     "tx_id": 12345,
+  //     "source_address": "0x1234abcd...",
+  //     "dest_address": "0x5678efgh...",
+  //     "status": "TRANSACTION_STATUS_MINED_CONFIRMED",
+  //     "direction": "TRANSACTION_DIRECTION_INBOUND",
+  //     "amount": 1000000,
+  //     "fee": 20,
+  //     "is_cancelled": false,
+  //     "excess_sig": "0xabcdef...",
+  //     "timestamp": 1681234567,
+  //     "payment_id": "0xdeadbeef...",
+  //     "mined_in_block_height": 150000
+  //   }
+  // }
+  // ```
+  rpc GetPaymentByReference(GetPaymentByReferenceRequest) returns (GetPaymentByReferenceResponse);
 }
 
 
@@ -1197,6 +1281,9 @@ message TransactionInfo {
   bytes user_payment_id = 14;
   repeated bytes input_commitments = 15;
   repeated bytes output_commitments = 16;
+  repeated bytes payment_references_sent = 17;
+  repeated bytes payment_references_received = 18;
+  repeated bytes payment_references_change = 19;
 }
 
 enum TransactionDirection {
@@ -1252,6 +1339,7 @@ message GetCompletedTransactionsResponse {
   TransactionInfo transaction = 1;
 }
 
+
 // Request message for GetBalance RPC.
 message GetBalanceRequest {
   // Optional: A user-defined payment ID to filter balance data.
@@ -1443,3 +1531,52 @@ message GetBlockHeightTransactionsResponse {
   // List of transactions mined at the specified block height
   repeated TransactionInfo transactions = 1;
 }
+
+// PayRef (Payment Reference) related messages and enums
+
+// Request message for GetTransactionPayRefs RPC.
+message GetTransactionPayRefsRequest {
+  // The transaction ID to retrieve PayRefs for.
+  uint64 transaction_id = 1;
+}
+
+// Response message for GetTransactionPayRefs RPC.
+message GetTransactionPayRefsResponse {
+  // List of PayRefs (32-byte payment references) for the transaction.
+  repeated bytes payment_references = 1;
+}
+
+
+// Response message for GetTransactionsWithPayRefs RPC.
+message GetTransactionsWithPayRefsResponse {
+  // The transaction information.
+  TransactionInfo transaction = 1;
+  // List of PayRefs associated with this transaction.
+  repeated bytes payment_references = 2;
+  // Number of unique recipients for this transaction.
+  uint64 recipient_count = 3;
+}
+
+// Request message for getting payment details by payment reference
+message GetPaymentByReferenceRequest {
+  // The 32-byte payment reference hash to look up
+  bytes payment_reference = 1;
+}
+
+// Response message containing transaction information for a payment reference
+message GetPaymentByReferenceResponse {
+  // The transaction information if PayRef is found (optional).
+  // Returns full transaction details
+  TransactionInfo transaction = 1;
+}
+
+
+// Enum for payment direction
+enum PaymentDirection {
+  // Unknown or unspecified direction
+  PAYMENT_DIRECTION_UNKNOWN = 0;
+  // Payment received by this wallet
+  PAYMENT_DIRECTION_INBOUND = 1;
+  // Payment sent from this wallet
+  PAYMENT_DIRECTION_OUTBOUND = 2;
+}

applications/minotari_app_grpc/src/conversions/transaction_output.rs

@@ -111,6 +111,9 @@ impl TryFrom<TransactionOutput> for grpc::TransactionOutput {
             version: output.version as u32,
             encrypted_data: output.encrypted_data.to_byte_vec(),
             minimum_value_promise: output.minimum_value_promise.into(),
+            // Payment reference will be populated when the output is included in a block
+            // and the block hash is available
+            payment_reference: vec![],
         })
     }
 }

applications/minotari_console_wallet/src/automation/commands.rs

@@ -2711,6 +2711,132 @@ pub async fn command_runner(
                 println!("removing temp wallet in: {:?}", temp_path);
                 fs::remove_dir_all(temp_path)?;
             },
+            ShowPayRef(args) => {
+                // Show transaction details first
+                match transaction_service
+                    .get_any_transaction(args.transaction_id.into())
+                    .await
+                {
+                    Ok(Some(tx)) => {
+                        println!("Transaction ID: {}", args.transaction_id);
+                        let _status = match &tx {
+                            WalletTransaction::Completed(completed_tx) => {
+                                println!("Transaction status: Completed");
+                                println!("Amount: {}", completed_tx.amount);
+                                println!("Fee: {}", completed_tx.fee);
+                                println!("Direction: {:?}", completed_tx.direction);
+                                if let Some(height) = completed_tx.mined_height {
+                                    println!("Mined at height: {}", height);
+                                }
+                                if let Some(timestamp) = completed_tx.mined_timestamp {
+                                    println!("Mined timestamp: {}", timestamp);
+                                }
+                                if completed_tx.mined_in_block.is_some() {
+                                    println!("\nReceived PayRefs for this transaction:");
+                                    for (i, pay_ref) in completed_tx.calculate_received_payment_references().iter().enumerate() {
+                                        println!("{}. PayRef: {}", i + 1, pay_ref);
+                                    }
+                                    println!("\nSent PayRefs for this transaction:");
+                                    for (i, pay_ref) in completed_tx.calculate_sent_payment_references().iter().enumerate() {
+                                        println!("{}. PayRef: {}", i + 1, pay_ref);
+                                    }
+                                    println!("\nChange PayRefs for this transaction:");
+                                    for (i, pay_ref) in completed_tx.calculate_change_payment_references().iter().enumerate() {
+                                        println!("{}. PayRef: {}", i + 1, pay_ref);
+                                    }
+                                } else {
+                                    println!("Payrefs: Transaction not mined yet.");
+                                }
+                                "Completed"
+                            },
+                            minotari_wallet::transaction_service::storage::models::WalletTransaction::PendingInbound(_) => {
+                                println!("Transaction status: PendingInbound");
+                                "PendingInbound"
+                            },
+                            minotari_wallet::transaction_service::storage::models::WalletTransaction::PendingOutbound(_) => {
+                                println!("Transaction status: PendingOutbound");
+                                "PendingOutbound"
+                            },
+                        };
+                    },
+                    Ok(None) => {
+                        println!("Transaction ID {} not found", args.transaction_id);
+                    },
+                    Err(e) => eprintln!("ShowPayRef error! {}", e),
+                }
+            },
+            FindPayRef(args) => match FixedHash::from_hex(&args.payment_reference_hex) {
+                Ok(payref) => match transaction_service.get_payment_by_reference(payref).await {
+                    Ok(Some(payment_details)) => {
+                        println!("Found PayRef: {}", args.payment_reference_hex);
+                        println!("Transaction ID: {}", payment_details.tx_id);
+                        println!("Amount: {}", payment_details.amount);
+                        println!("Direction: {:?}", payment_details.direction);
+                        println!("Block height: {}", payment_details.block_height);
+                        println!("Confirmations: {}", payment_details.confirmations);
+                        if let Some(timestamp) = payment_details.timestamp {
+                            println!("Timestamp: {}", timestamp);
+                        }
+                        if let Some(payment_id) = &payment_details.payment_id {
+                            println!("Payment ID: {}", String::from_utf8_lossy(payment_id));
+                        }
+                    },
+                    Ok(None) => {
+                        println!("No payment found for PayRef: {}", args.payment_reference_hex);
+                    },
+                    Err(e) => eprintln!("FindPayRef error! {}", e),
+                },
+                Err(e) => {
+                    eprintln!("FindPayRef error! Invalid PayRef format: {}", e);
+                },
+            },
+            ListTx => {
+                debug!(target: LOG_TARGET, "payref_debug: List all transactions command starting execution");
+
+                match transaction_service.get_completed_transactions(None, None, None).await {
+                    Ok(txs) => {
+                        debug!(target: LOG_TARGET, "ListTxs command got {} transactions", txs.len());
+
+                        if txs.is_empty() {
+                            println!("No transactions.");
+                            continue;
+                        }
+                        println!("Found {} transaction(s)", txs.len());
+                        println!("{}", "=".repeat(80));
+
+                        for (i, tx) in txs.iter().enumerate() {
+                            println!("{}. Transaction ID: {}", i + 1, tx.tx_id);
+                            println!("   Amount: {}", tx.amount);
+                            println!("   Direction: {:?}", tx.direction);
+                            println!("   Status: {:?}", tx.status);
+                            if let Some(height) = tx.mined_height {
+                                println!("   Mined at height: {}", height);
+                            }
+                            if let Some(timestamp) = tx.mined_timestamp {
+                                println!("   Mined timestamp: {}", timestamp);
+                            }
+                            if tx.mined_in_block.is_some() {
+                                println!("\nReceived PayRefs for this transaction:");
+                                for (i, pay_ref) in tx.calculate_received_payment_references().iter().enumerate() {
+                                    println!("{}. PayRef: {}", i + 1, pay_ref);
+                                }
+                                println!("\nSent PayRefs for this transaction:");
+                                for (i, pay_ref) in tx.calculate_sent_payment_references().iter().enumerate() {
+                                    println!("{}. PayRef: {}", i + 1, pay_ref);
+                                }
+                                println!("\nChange PayRefs for this transaction:");
+                                for (i, pay_ref) in tx.calculate_change_payment_references().iter().enumerate() {
+                                    println!("{}. PayRef: {}", i + 1, pay_ref);
+                                }
+                            } else {
+                                println!("Payrefs: Transaction not mined yet.");
+                            }
+                            println!();
+                        }
+                    },
+                    Err(e) => eprintln!("ListTxs error! {}", e),
+                }
+            },
         }
     }
     if unban_peer_manager_peers {