// Copyright 2020. The Tari Project
//
// Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
// following conditions are met:
//
// 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
// disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
// following disclaimer in the documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
// products derived from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
// USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
syntax = "proto3";

package tari.rpc;

import "google/protobuf/timestamp.proto";
import "types.proto";
import "transaction.proto";
import "sidechain_types.proto";
import "network.proto";

// The gRPC interface for interacting with the wallet.
service Wallet {
  // Returns the current version of the running wallet service.
  //
  // This method retrieves the semantic version of the wallet software as defined in the Cargo.toml file (e.g., "1.2.3"). Useful for diagnostics and compatibility checks.
  //
  // Example usage (JavaScript gRPC client):
  // ```javascript
  // const response = await client.getVersion({});
  // console.log(response.version); // e.g., "1.2.3"
  // ```
  //
  // Example response:
  // ```json
  // {
  //   "version": "1.2.3"
  // }
  // ```

  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:
  // - The latest blockchain height scanned by the wallet
  // - The current balance (available, pending incoming/outgoing)
  // - Network connectivity status with the base node
  //
  // This is commonly used by UI clients or backend systems to confirm the wallet is healthy,
  // synchronized, and connected to the Tari network.
  //
  // Example usage (JavaScript):
  // ```javascript
  // const response = await client.getState({});
  // console.log(response.scanned_height); // e.g., 1523493
  // console.log(response.balance.available_balance); // e.g., 1234567890
  // console.log(response.network.status); // e.g., "Online"
  // ```
  //
  // Example response:
  // ```json
  // {
  //   "scanned_height": 1523493,
  //   "balance": {
  //     "available_balance": 1234567890,
  //     "pending_incoming_balance": 100000000,
  //     "pending_outgoing_balance": 0
  //   },
  //   "network": {
  //     "status": "Online",
  //     "avg_latency_ms": 28,
  //     "num_node_connections": 8
  //   }
  // }
  // ```
  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):
  // ```javascript
  // const response = await client.checkConnectivity({});
  // console.log(response.status); // e.g., 1 (Online)
  // ```
  //
  // Example response:
  // ```json
  // {
  //   "status": "Online"
  // }
  // ```
  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.
  // - **Public Address**: The wallet's public address used to receive funds.
  // - **Node ID**: The unique identifier of the wallet node in the network.
  //
  // Example usage (JavaScript):
  // ```javascript
 // // Call the Identify RPC method
  // client.Identify({}, (error, response) => {
  //   if (error) {
  //     console.error('Error:', error);
  //   } else {
  //     console.log('Identity Response:', response);
  //   }
  // });
  // ```
  //
  // **Sample JSON Response:**
  //
  // ```json
  // {
  //   "public_key": "0x04b2c5f3fe65bb1c3cde019e34f3eab1234598c820dca43bbf4d5686a980ddc69e0d4b180d85990d0a5e4aee46e0a6ad9283f0a41783992a70c548e53e47321fa",
  //   "public_address": "14HVCEeZC2RGE4SDn3yGwqzXepJ2LDqXva7kb4fherYMQR9dF7341T3TjMZobB1a6xouGvS5SXwEvXKwK3zLz2rgReh",
  //   "node_id": "0x1234abcd5678efgh9012ijkl3456mnop"
  // }
  // ```
  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.
  // - **One-Sided Address**: This is another address type, typically used in scenarios where a one-way interaction or transaction is needed.
  //
  // Example usage (JavaScript):
  // // Call the GetAddress RPC method
  // client.GetAddress({}, (error, response) => {
  //   if (error) {
  //     console.error('Error:', error);
  //   } else {
  //     console.log('Address Response:', response);
  //   }
  // });
  // ```
  //
  // **Sample JSON Response:**
  //  // ```json
  // {
  //   "interactive_address": "0x14b27bde3f7d9c9d7455f16b056a3c439c663af93356f56e16d2b2c79e6995c44c9c6c7c",
  //   "one_sided_address": "0x12b35ddcb2270a72d7b327abc7cd4f607a492c6e13e72e65c34742069e48bd3bc462df63"
  // }
  // ```
  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.
  //
  // Example usage (JavaScript):
  //
  // ```javascript
  // // Prepare the payment ID for the request
  // const paymentId = Buffer.from('your_payment_id_here', 'hex');
  // const request = { payment_id: paymentId };
  //
  // // Call the GetPaymentIdAddress RPC method
  // client.GetPaymentIdAddress(request, (error, response) => {
  //   if (error) {
  //     console.error('Error:', error);
  //   } else {
  //     console.log('Payment ID Address Response:', response);
  //   }
  // });
  // ```
  //
  // **Sample JSON Response:**
  //
  // ```json
  //{
  //  "interactive_address": "0411aabbccddeeff00112233445566778899aabbccddeeff0011223344556677",
  //  "one_sided_address": "02ff8899aabbccddeeff00112233445566778899aabbccddeeff001122334455",
  //  "interactive_address_base58": "14HVCEeZC2RGE4SDn3yG.....6xouGvS5SXwEvXKwK3zLz2rgReh",
  //  "one_sided_address_base58": "12HVCEeZC2RGE4SDn3yGwqz.....obB1a6xouGvS5SXwEvXKwK3zLz2rgReL",
  //  "interactive_address_emoji": "🐢🌊💤🔌🚑🐛🏦⚽🍓🐭🚁🎢🔪🥐👛🍞.....🍐🍟💵🎉🍯🎁🎾🎼💻💄🍳🍐🤔🥝🍫👅🚀🐬🎭",
  //  "one_sided_address_emoji": "🐢📟💤🔌🚑🐛🏦⚽🍓🐭🚁🎢🔪🥐👛🍞📜.....🍐🍟💵🎉🍯🎁🎾🎼💻💄🍳🍐🤔🥝🍫👅🚀🐬🎭"
  //}
  //```
  //
  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
  // - Base58-encoded (human-readable)
  // - Emoji-encoded (for fun and friendliness)
  //
  // Example usage (JavaScript with gRPC):
  //
  // ```js
  // const client = new WalletClient('localhost:50051', grpc.credentials.createInsecure());
  // client.getCompleteAddress({}, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log(response);
  // });
  // ```
  //
  // Sample response:
  // ```json
  // {
  //  "interactive_address": "0411aabbccddeeff00112233445566778899aabbccddeeff0011223344556677",
  //  "one_sided_address": "02ff8899aabbccddeeff00112233445566778899aabbccddeeff001122334455",
  //  "interactive_address_base58": "14HVCEeZC2RGE4SDn3yG.....6xouGvS5SXwEvXKwK3zLz2rgReh",
  //  "one_sided_address_base58": "12HVCEeZC2RGE4SDn3yGwqz.....obB1a6xouGvS5SXwEvXKwK3zLz2rgReL",
  //  "interactive_address_emoji": "🐢🌊💤🔌🚑🐛🏦⚽🍓🐭🚁🎢🔪🥐👛🍞.....🍐🍟💵🎉🍯🎁🎾🎼💻💄🍳🍐🤔🥝🍫👅🚀🐬🎭",
  //  "one_sided_address_emoji": "🐢📟💤🔌🚑🐛🏦⚽🍓🐭🚁🎢🔪🥐👛🍞📜.....🍐🍟💵🎉🍯🎁🎾🎼💻💄🍳🍐🤔🥝🍫👅🚀🐬🎭"
  // }
  // ```
  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.
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // const recipient = new PaymentRecipient();
  // recipient.setAddress("14HVCEeZ...");
  // recipient.setAmount(1000000); // 1 T
  // recipient.setFeePerGram(25);
  // recipient.setPaymentType(PaymentType.ONE_SIDED);
  // recipient.setPaymentId(Buffer.from("abc123", "utf-8"));
  //
  // const request = new TransferRequest();
  // request.setRecipientsList([recipient]);
  //
  // client.transfer(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log(response.toObject());
  // });
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "results": [
  //     {
  //       "address": "14HVCEeZ...",
  //       "transaction_id": 12345,
  //       "is_success": true,
  //       "failure_message": ""
  //     }
  //   ]
  // }
  rpc Transfer (TransferRequest)  returns (TransferResponse);

  // Returns the transaction details for the given transaction IDs.
  //
  // The GetTransactionInfo RPC retrieves detailed information about specific transactions based on their IDs.
  // The response includes details such as transaction status, direction, amount, fee, and more.
  //
  // ### Request Parameters:
  //
  // - `transaction_ids` (required):
  //   - **Type**: `repeated uint64`
  //   - **Description**: A list of transaction IDs to query.
  //   - **Restrictions**:
  //     - Must contain at least one ID.
  //     - All IDs must be valid unsigned 64-bit integers.
  //     - Duplicates will be ignored; only the first occurrence is processed.
  //     - If a transaction ID is not found, it will be returned with a `status` of `NOT_FOUND`.
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // const request = { transaction_ids: [12345, 67890] };
  // client.getTransactionInfo(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log(response.transactions);
  // });
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "transactions": [
  //     {
  //       "tx_id": 12345,
  //       "source_address": "0x1234abcd...",
  //       "dest_address": "0x5678efgh...",
  //       "status": "TRANSACTION_STATUS_MINED_CONFIRMED",
  //       "direction": "TRANSACTION_DIRECTION_OUTBOUND",
  //       "amount": 1000000,
  //       "fee": 25,
  //       "is_cancelled": false,
  //       "excess_sig": "0xabcdef...",
  //       "timestamp": 1681234567,
  //       "payment_id": "0xdeadbeef...",
  //       "mined_in_block_height": 1523493
  //     }
  //   ]
  // }
  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` 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.
  //
  // ### Request Parameters:
  //
  // - `payment_id` (optional):
  //   - **Type**: `UserPaymentId` (a flexible ID object)
  //   - **Description**: Allows filtering the completed transactions by a specific payment ID.
  //   - **Accepted Formats** (must provide **only one**):
  //     - `u256`: a 32-byte hexadecimal string.
  //     - `utf8_string`: a UTF-8 string.
  //     - `user_bytes`: raw bytes.
  //   - **Restrictions**:
  //     - 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.
  //
  // - `block_height` (optional):
  //   - **Type**: `uint64`
  //   - **Description**: A specific block height to filter transactions by.
  //   - **Restrictions**:
  //     - If provided, the transactions will be filtered to only those included in the specified height.

  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // const request = {
  //   payment_id: {
  //     utf8_string: "invoice-001"
  //   }
  // };
  // const call = client.getCompletedTransactions(request);
  // call.on('data', (response) => {
  //   console.log(response.transaction);
  // });
  // call.on('error', console.error);
  // call.on('end', () => console.log("Stream ended"));
  // ```
  //
  // ### Sample Streamed JSON Response:
  //
  // ```json
  // {
  //   "transaction": {
  //     "tx_id": 12345,
  //     "source_address": "0x1234abcd...",
  //     "dest_address": "0x5678efgh...",
  //     "status": "TRANSACTION_STATUS_MINED_CONFIRMED",
  //     "direction": "TRANSACTION_DIRECTION_INBOUND",
  //     "amount": 500000,
  //     "fee": 20,
  //     "is_cancelled": false,
  //     "excess_sig": "0xabcdef...",
  //     "timestamp": 1681234567,
  //     "payment_id": "0xdeadbeef...",
  //     "mined_in_block_height": 1523493
  //   }
  // }
  // ```
  rpc GetCompletedTransactions (GetCompletedTransactionsRequest) returns (stream GetCompletedTransactionsResponse);

  // Returns all transactions that were mined at a specific block height.
  //
  // The `GetBlockHeightTransactions` call retrieves all wallet transactions that were mined
  // at the specified block height. The response includes all transactions in a single response,
  // with each transaction including details such as status, direction, amount,
  // fees, and associated metadata.
  //
  // ### Request Parameters:
  //
  // - `block_height` (required):
  //   - **Type**: `uint64`
  //   - **Description**: The specific block height to fetch transactions for.
  //   - **Restrictions**:
  //     - Must be a valid block height (greater than 0).
  //     - If the block height is beyond the current chain height, no transactions will be returned.
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // const request = {
  //   block_height: 1523493
  // };
  // const response = await client.getBlockHeightTransactions(request);
  // console.log(response.transactions);
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "transactions": [
  //     {
  //       "tx_id": 12345,
  //       "source_address": "0x1234abcd...",
  //       "dest_address": "0x5678efgh...",
  //       "status": "TRANSACTION_STATUS_MINED_CONFIRMED",
  //       "direction": "TRANSACTION_DIRECTION_INBOUND",
  //       "amount": 500000,
  //       "fee": 20,
  //       "is_cancelled": false,
  //       "excess_sig": "0xabcdef...",
  //       "timestamp": 1681234567,
  //       "payment_id": "0xdeadbeef...",
  //       "mined_in_block_height": 1523493
  //     }
  //   ]
  // }
  // ```
  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,
  // optionally filtered by a specific `payment_id`. The response includes detailed
  // breakdowns of available, pending incoming/outgoing, and timelocked balances.
  //
  // ### Request Parameters:
  //
  // - `payment_id` (optional):
  //   - **Type**: `UserPaymentId` (one of several formats).
  //   - **Description**: An optional filter to retrieve the balance associated with a specific payment ID.
  //   - **Accepted Formats** (must provide **only one**):
  //     - `u256`: a 32-byte hexadecimal identifier.
  //     - `utf8_string`: a human-readable string ID.
  //     - `user_bytes`: raw binary bytes.
  //   - **Restrictions**:
  //     - Only one format must be provided at a time.
  //     - If multiple or no formats are provided within `payment_id`, the request will return an error.
  //     - If `payment_id` is omitted, the total wallet balance is returned.
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // const request = {
  //   payment_id: {
  //     utf8_string: "invoice-002"
  //   }
  // };
  // client.getBalance(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log("Balance:", response);
  // });
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "available_balance": 950000,
  //   "pending_incoming_balance": 200000,
  //   "pending_outgoing_balance": 50000,
  //   "timelocked_balance": 100000
  // }
  // ```
  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
  // currently held by the wallet. These are outputs that have not yet been spent or time-locked,
  // and are available for future transactions.
  //
  // ### Request Parameters:
  //
  // - *(none)*
  //   - This method uses an empty request body (`google.protobuf.Empty`).
  //   - No filters or arguments are required.
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // client.getUnspentAmounts({}, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log("Total unspent amount:", response.amount);
  // });
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "amount": 1250000
  // }
  // ```
  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.
  // This is useful for preparing a wallet for many small transactions (e.g., for micropayments or batching).
  // The resulting transaction is broadcast and can be tracked via its transaction ID.
  //
  // ### Request Parameters:
  //
  // - `amount_per_split` (required):
  //   - **Type**: `uint64`
  //   - **Description**: The value of each individual output in the split.
  //   - **Restrictions**: Must be greater than zero.
  //
  // - `split_count` (required):
  //   - **Type**: `uint64`
  //   - **Description**: The number of outputs to create.
  //   - **Restrictions**: Must be greater than zero and within practical system limits.
  //
  // - `fee_per_gram` (required):
  //   - **Type**: `uint64`
  //   - **Description**: The transaction fee rate (per gram of weight).
  //   - **Restrictions**: Should be set high enough to ensure confirmation.
  //
  // - `lock_height` (optional):
  //   - **Type**: `uint64`
  //   - **Description**: The earliest block height at which the transaction becomes valid.
  //   - **Restrictions**: Defaults to 0 if not specified.
  //
  // - `payment_id` (optional):
  //   - **Type**: `bytes`
  //   - **Description**: A user-defined identifier for tracking or referencing the transaction.
  //   - **Restrictions**: Optional; can be left empty.
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // const request = {
  //   amount_per_split: 100000,
  //   split_count: 5,
  //   fee_per_gram: 25,
  //   lock_height: 0,
  //   payment_id: new Uint8Array([])
  // };
  // client.coinSplit(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log("Created CoinSplit Tx ID:", response.tx_id);
  // });
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "tx_id": 987654321
  // }
  // ```
  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
  // into the wallet, marking them as spendable without needing rewindable metadata.
  // Each UTXO is associated with a transaction ID in the response.
  //
  // ### Request Parameters:
  //
  // - `outputs` (required):
  //   - **Type**: `repeated UnblindedOutput`
  //   - **Description**: A list of unblinded outputs to import into the wallet.
  //   - **Restrictions**:
  //     - Each output must be valid and convertible to an internal UTXO format.
  //     - The list must contain at least one item.
  //
  // - `payment_id` (optional):
  //   - **Type**: `bytes`
  //   - **Description**: An optional user-defined identifier to associate with the imported outputs.
  //   - **Restrictions**:
  //     - Can be left empty if not needed.
  //     - Must be a valid byte string if provided.
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // const request = {
  //   outputs: [/* array of unblinded outputs */],
  //   payment_id: new Uint8Array([])
  // };
  // client.importUtxos(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log("Imported Tx IDs:", response.tx_ids);
  // });
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "tx_ids": [101, 102, 103]
  // }
  // ```
  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,
  // including whether it is online, the number of active peer connections, and the average latency
  // to the configured base node.
  //
  // ### Request Parameters:
  //
  // - *(none)*
  //   - This method uses an empty request body (`google.protobuf.Empty`).
  //   - No filters or arguments are required.
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // client.getNetworkStatus({}, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log("Network Status:", response);
  // });
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "status": "ONLINE",
  //   "avg_latency_ms": 142,
  //   "num_node_connections": 8
  // }
  // ```
  //
  // ### Status Field Values:
  //
  // The `status` field indicates the current network connectivity of the wallet. Possible values are:
  //
  // - `ONLINE`:
  //   - The wallet is fully connected to the network and functioning normally.
  //   - The node has enough active peer connections to operate efficiently.
  //
  // - `DEGRADED`:
  //   - The wallet is connected to some peers but not enough to maintain full functionality.
  //   - This could indicate issues with network connectivity, such as intermittent disconnections or insufficient peers, leading to reduced performance or reliability.
  //
  // - `OFFLINE`:
  //   - The wallet is not connected to any peers.
  //   - 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
  // connected to. This includes details such as peer addresses, connection status, supported protocols,
  // and other metadata relevant to the connection.
  //
  // ### Request Parameters:
  //
  // - *(none)*
  //   - This method uses an empty request body (`google.protobuf.Empty`).
  //   - No filters or arguments are required.
  //
  // ### Response Fields:
  //
  // - **connected_peers**: List of peers currently connected to the wallet.
  //   - **public_key**: The peer's public key (bytes).
  //   - **node_id**: The unique node ID of the peer (bytes).
  //   - **addresses**: List of the peer's addresses (repeated Address).
  //   - **last_connection**: The timestamp of the last connection attempt (uint64).
  //   - **flags**: Flags associated with the peer (uint32).
  //   - **banned_until**: The timestamp until which the peer is banned (uint64, 0 if not banned).
  //   - **banned_reason**: The reason for banning the peer (string, empty if not banned).
  //   - **offline_at**: The timestamp indicating when the peer went offline (uint64, 0 if online).
  //   - **features**: The features supported by the peer (uint32).
  //   - **supported_protocols**: List of supported protocols by the peer (repeated bytes).
  //   - **user_agent**: The user agent advertised by the peer (string).
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // client.listConnectedPeers({}, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log("Connected Peers:", response);
  // });
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "connected_peers": [
  //     {
  //       "public_key": "0x1234abcd...",
  //       "node_id": "0x5678efgh...",
  //       "addresses": [
  //         "127.0.0.1:18080",
  //         "192.168.1.2:18080"
  //       ],
  //       "last_connection": 1625493123,
  //       "flags": 1,
  //       "banned_until": 0,
  //       "banned_reason": "",
  //       "offline_at": 0,
  //       "features": 10,
  //       "supported_protocols": [
  //         "protocol_v1",
  //         "protocol_v2"
  //       ],
  //       "user_agent": "TariBaseNode/1.0.0"
  //     }
  //   ]
  // }
  // ```
  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).
  // If the cancellation is successful, the response will indicate success. Otherwise, the response will
  // contain a failure message with the reason for the failure.
  //
  // ### Request Parameters:
  //
  // - **tx_id**: The unique identifier for the transaction to be cancelled (uint64).
  //
  // ### Response Fields:
  //
  // - **is_success**: A boolean indicating whether the cancellation was successful (bool).
  //   - `true` if the cancellation was successful, `false` if not.
  // - **failure_message**: A string that provides the reason for the failure, if applicable (string).
  //   - This field will be empty if the cancellation was successful.
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // const request = { tx_id: 12345 };
  // client.cancelTransaction(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log(response);
  // });
  // ```
  //
  // ### Sample JSON Response:
  //
  // ```json
  // {
  //   "is_success": true,
  //   "failure_message": ""
  // }
  // ```
  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
  // transaction using SHA. It allows the sender to send a payment to the recipient
  // in exchange for an atomic swap, with SHA used as the secret for the swap.
  // The method accepts the recipient's information and initiates the transaction.
  //
  // ### Request Parameters:
  // - **recipient** (required): A PaymentRecipient object containing the recipient's address,
  //   the amount to be swapped, the fee per gram, and the payment ID to identify the transaction.
  //
  // ### Response Fields:
  // - **transaction_id**: The ID of the transaction.
  // - **pre_image**: The SHA pre-image of the atomic swap.
  // - **output_hash**: The hash of the output associated with the transaction.
  // - **is_success**: Indicates whether the transaction was successful (true) or failed (false).
  // - **failure_message**: Provides an error message if the transaction failed.
  //
  // ### Example JavaScript gRPC client usage:
  // ```javascript
  // const request = {
  //   recipient: {
  //     address: "t1abc12345",
  //     amount: 1000000,
  //     fee_per_gram: 10,
  //     payment_id: "0xdeadbeef"
  //   }
  // };
  // client.sendShaAtomicSwapTransaction(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log(response);
  // });
  // ```
  //
  // ### Sample JSON Response:
  // ```json
  // {
  //   "transaction_id": 123456789,
  //   "pre_image": "0xabcdef1234567890",
  //   "output_hash": "0x123456abcdef7890",
  //   "is_success": true,
  //   "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
  // by initiating a burn transaction. It allows the user to specify the amount to burn,
  // along with a fee per gram and optionally a payment ID and claim public key.
  //
  // ### Request Parameters:
  // - **amount** (required): The amount of Tari to be burned.
  // - **fee_per_gram** (required): The fee per gram for the transaction.
  // - **claim_public_key** (optional): The public key to claim ownership of the burned coins.
  // - **payment_id** (optional): A unique identifier for the payment associated with the burn transaction.
  //
  // ### Response Fields:
  // - **transaction_id**: The ID of the burn transaction.
  // - **is_success**: Indicates whether the burn transaction was successfully created.
  // - **failure_message**: Provides an error message if the transaction creation failed.
  // - **commitment**: The commitment associated with the burn transaction.
  // - **ownership_proof**: A proof of ownership for the burned coins.
  // - **range_proof**: The range proof associated with the burned coins.
  // - **reciprocal_claim_public_key**: The public key of the reciprocal claim for the burn.
  //
  // ### Example JavaScript gRPC client usage:
  // ```javascript
  // const request = {
  //   amount: 1000000,
  //   fee_per_gram: 10,
  //   claim_public_key: "0xabcdef1234567890",
  //   payment_id: "0xdeadbeef"
  // };
  // client.createBurnTransaction(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log(response);
  // });
  // ```
  //
  // ### Sample JSON Response:
  // ```json
  // {
  //   "transaction_id": 123456789,
  //   "is_success": true,
  //   "failure_message": "",
  //   "commitment": "0xcommitmenthash",
  //   "ownership_proof": "0xownershipproof",
  //   "range_proof": "0xrangeproof",
  //   "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
  // a hash-time-locked contract (HTLC) by supplying the correct pre-image that matches a
  // previously committed SHA-256 hash. This pre-image proves the user's knowledge of the
  // secret required to spend the output.
  //
  // ### Request Parameters:
  // - **output** (required): The hex-encoded output hash (SHA-256 digest) that was locked in the atomic swap.
  // - **pre_image** (required): The hex-encoded original pre-image (raw bytes, *not* hashed) which, when hashed with SHA-256, must match the `output` hash.
  // - **fee_per_gram** (required): The transaction fee per gram, specified as an unsigned integer.
  //
  // ### Input Validation:
  // - `output` must be a valid hex-encoded SHA-256 hash (64 hex characters).
  // - `pre_image` must be a valid hex string representing the original secret (any byte length, commonly 32 bytes).
  // - `fee_per_gram` must be a non-zero `uint64`; a fee of `0` may be rejected or deprioritized by the network.
  //
  // ### Response Fields:
  // - **results**: A `TransferResult` object containing transaction ID, success status, and an error message if applicable.
  //
  // ### Example JavaScript gRPC client usage:
  // ```javascript
  // const request = {
  //   output: "3e1f89af...e923", // SHA-256 hash of the expected pre-image
  //   pre_image: "6a1b2c...eaf1", // raw pre-image (not hashed)
  //   fee_per_gram: 10
  // };
  // client.claimShaAtomicSwapTransaction(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log(response.results);
  // });
  // ```
  //
  // ### Sample JSON Response:
  // ```json
  // {
  //   "results": {
  //     "address": "",
  //     "transaction_id": 789654,
  //     "is_success": true,
  //     "failure_message": ""
  //   }
  // }
  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)
  // to reclaim the locked funds if the recipient has not claimed them in time using the correct pre-image.
  // This is possible only after the output's timelock has expired.
  //
  // ### Request Parameters:
  // - **output_hash** (required): Hex-encoded SHA-256 hash of the HTLC output being refunded.
  // - **fee_per_gram** (required): Transaction fee per gram, specified as a `uint64`.
  //
  // ### Input Validation:
  // - `output_hash` must be a valid 64-character hex string representing the hash of the HTLC output.
  // - `fee_per_gram` must be a non-zero `uint64` value.
  //
  // ### Response Fields:
  // - **results**: A `TransferResult` object including transaction ID, success status, and failure reason if any.
  //
  // ### Example JavaScript gRPC client usage:
  // ```javascript
  // const request = {
  //   output_hash: "aabbccddeeff0011...99",
  //   fee_per_gram: 20
  // };
  // client.claimHtlcRefundTransaction(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log(response.results);
  // });
  // ```
  //
  // ### Sample JSON Response:
  // ```json
  // {
  //   "results": {
  //     "address": "",
  //     "transaction_id": 889977,
  //     "is_success": true,
  //     "failure_message": ""
  //   }
  // }
  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.
  //
  // ### Request Fields:
  // - `public_key_hex` (string): The public key of the base node, provided as a hex string.
  // - `net_address` (string): The multiaddress of the base node (e.g., `/ip4/127.0.0.1/tcp/18141`).
  //
  // ### Example JavaScript gRPC client usage:
  //
  // ```javascript
  // const request = {
  //   public_key_hex: "0281bdfc...",
  //   net_address: "/ip4/127.0.0.1/tcp/18141"
  // };
  // client.setBaseNode(request, (err, response) => {
  //   if (err) console.error(err);
  //   else console.log("Base node set successfully");
  // });
  // ```
  //
  // ### Sample JSON Request:
  // ```json
  // {
  //   "public_key_hex": "0281bdfc...",
  //   "net_address": "/ip4/127.0.0.1/tcp/18141"
  // }
  // ```
  //
  // ### Sample JSON Response:
  // ```json
  // {}
  // ```
  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.
  // This allows clients to react to changes in transaction status such as received, sent, mined, or cancelled transactions,
  // making it ideal for real-time UI updates or external monitoring.
  //
  // ### Request Parameters:
  // - _(none)_ – This RPC does not take any parameters.
  //
  // ### Response Stream:
  // - Each message in the response stream is a `TransactionEventResponse` containing:
  //   - **transaction**: A `TransactionEvent` object representing the latest event related to a wallet transaction.
  //
  // ### `TransactionEvent` Fields:
  // - **event** (string): Human-readable event type. Examples include: `"Received"`, `"Mined"`, `"Cancelled"`, `"Sent"`.
  // - **tx_id** (string): Transaction identifier.
  // - **source_address** (bytes): Sender address, if applicable.
  // - **dest_address** (bytes): Recipient address, if applicable.
  // - **status** (string): Current status of the transaction. E.g., `"Completed"`, `"Pending"`, `"Cancelled"`.
  // - **direction** (string): `"Inbound"` or `"Outbound"`.
  // - **amount** (uint64): Transaction amount in microTari.
  // - **payment_id** (bytes): Payment ID associated with the transaction.
  //

  // ### Example JavaScript gRPC client usage:
  // ```javascript
  // const call = client.streamTransactionEvents({});
  //
  // call.on("data", (response) => {
  //   console.log("Transaction Event:", response.transaction);
  // });
  //
  // call.on("end", () => {
  //   console.log("Stream ended.");
  // });
  //
  // call.on("error", (err) => {
  //   console.error("Stream error:", err);
  // });
  // ```
  //
  // ### Sample JSON Streamed Response:
  // ```json
  // {
  //   "transaction": {
  //     "event": "Mined",
  //     "tx_id": "103248",
  //     "source_address": "0xabc123...",
  //     "dest_address": "0xdef456...",
  //     "status": "Completed",
  //     "direction": "Outbound",
  //     "amount": 100000000,
  //     "payment_id": "0xdeadbeef..."
  //   }
  // }
  // ```
  rpc StreamTransactionEvents(TransactionEventRequest) returns (stream TransactionEventResponse);

  rpc RegisterValidatorNode(RegisterValidatorNodeRequest) returns (RegisterValidatorNodeResponse);

  rpc ImportTransactions(ImportTransactionsRequest) returns (ImportTransactionsResponse);

  // 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);
}


message GetVersionRequest {}


message GetVersionResponse {
  string version = 1;
}

message GetAddressResponse {
  bytes interactive_address = 1;
  bytes one_sided_address = 2;
}

message GetPaymentIdAddressRequest {
  bytes payment_id = 1;
}
// Response message containing all formats of wallet addresses.
message GetCompleteAddressResponse {
  // Binary form of the interactive address.
  bytes interactive_address = 1;
  // Binary form of the one-sided address.
  bytes one_sided_address = 2;
  // Base58-encoded version of the interactive address.
  string interactive_address_base58 = 3;
  // Base58-encoded version of the one-sided address.
  string one_sided_address_base58 = 4;
  // Emoji-encoded version of the interactive address.
  string interactive_address_emoji = 5;
  // Emoji-encoded version of the one-sided address.
  string one_sided_address_emoji = 6;
}

// A request to send funds to one or more recipients.
message TransferRequest {
  repeated PaymentRecipient recipients = 1;
}

message SendShaAtomicSwapRequest {
  PaymentRecipient recipient = 1;
}

message CreateBurnTransactionRequest{
  uint64 amount = 1;
  uint64 fee_per_gram = 2;
  bytes claim_public_key = 4;
  bytes payment_id = 5;
}

// A recipient for a transfer, including address, amount, fee, and optional payment ID.
message PaymentRecipient {
  // Base58 Tari address of the recipient.
  string address = 1;
  // Amount to send in microTari (1 T = 1_000_000 µT).
  uint64 amount = 2;
   // Fee rate per gram.
  uint64 fee_per_gram = 3;
  enum PaymentType {
    // Default Mimblewimble-style transaction.
    STANDARD_MIMBLEWIMBLE = 0 [deprecated = true] ;
    // One-sided transaction (receiver not required to participate).
    ONE_SIDED = 1 [deprecated = true] ;
    // One-sided stealth address (adds privacy by hiding destination).
    ONE_SIDED_TO_STEALTH_ADDRESS = 2;
  }
  // The type of payment to perform.
  PaymentType payment_type = 5;
  // raw payment id
  bytes raw_payment_id = 6;
  // Optional user encrypted payment ID for reference (max 256 bytes).
  UserPaymentId user_payment_id = 7;
}

message TransferResponse {
  repeated TransferResult results = 1;
}

message SendShaAtomicSwapResponse {
  uint64 transaction_id = 1;
  string pre_image = 2;
  string output_hash = 3;
  bool is_success = 4;
  string failure_message = 5;
}

message CreateBurnTransactionResponse{
  uint64 transaction_id = 1;
  bool is_success = 2;
  string failure_message = 3;
  bytes commitment = 4;
  CommitmentSignature ownership_proof = 5;
  bytes range_proof = 6;
  bytes reciprocal_claim_public_key = 7;
}

message TransferResult {
  string address = 1;
  uint64 transaction_id = 2;
  bool is_success = 3;
  string failure_message = 4;
  TransactionInfo transaction_info = 5;
}

message ClaimShaAtomicSwapRequest{
  string output = 1;
  string pre_image = 2;
  uint64 fee_per_gram = 3;
}

message ClaimShaAtomicSwapResponse {
  TransferResult results = 1;
}

message ClaimHtlcRefundRequest{
  string output_hash = 1;
  uint64 fee_per_gram = 2;
}

message ClaimHtlcRefundResponse {
  TransferResult results = 1;
}

message GetTransactionInfoRequest {
  repeated uint64 transaction_ids = 1;
}

message GetTransactionInfoResponse {
  repeated TransactionInfo transactions = 1;
}

message TransactionInfo {
  uint64 tx_id = 1;
  bytes source_address = 2;
  bytes dest_address = 3;
  TransactionStatus status = 4;
  TransactionDirection direction = 5;
  uint64 amount = 6;
  uint64 fee = 7;
  bool is_cancelled = 8;
  bytes excess_sig = 9;
  uint64 timestamp = 10;
  bytes raw_payment_id = 12;
  uint64 mined_in_block_height = 13;
  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 {
  TRANSACTION_DIRECTION_UNKNOWN = 0;
  TRANSACTION_DIRECTION_INBOUND = 1;
  TRANSACTION_DIRECTION_OUTBOUND = 2;
}

enum TransactionStatus {
  // This transaction has been completed between the parties but has not been broadcast to the base layer network.
  TRANSACTION_STATUS_COMPLETED = 0;
  // This transaction has been broadcast to the base layer network and is currently in one or more base node mempools.
  TRANSACTION_STATUS_BROADCAST = 1;
  // This transaction has been mined and included in a block.
  TRANSACTION_STATUS_MINED_UNCONFIRMED = 2;
  // This transaction was generated as part of importing a spendable UTXO
  TRANSACTION_STATUS_IMPORTED = 3;
  // This transaction is still being negotiated by the parties
  TRANSACTION_STATUS_PENDING = 4;
  // This is a created Coinbase Transaction
  TRANSACTION_STATUS_COINBASE = 5;
  // This transaction is mined and confirmed at the current base node's height
  TRANSACTION_STATUS_MINED_CONFIRMED = 6;
  // The transaction was rejected by the mempool
  TRANSACTION_STATUS_REJECTED = 7;
  // This is faux transaction mainly for one-sided transaction outputs or wallet recovery outputs have been found
  TRANSACTION_STATUS_ONE_SIDED_UNCONFIRMED = 8;
  // All Imported and FauxUnconfirmed transactions will end up with this status when the outputs have been confirmed
  TRANSACTION_STATUS_ONE_SIDED_CONFIRMED = 9;
  // This transaction is still being queued for sending
  TRANSACTION_STATUS_QUEUED = 10;
  // The transaction was not found by the wallet its in transaction database
  TRANSACTION_STATUS_NOT_FOUND = 11;
  // This is Coinbase transaction that is detected from chain
  TRANSACTION_STATUS_COINBASE_UNCONFIRMED = 12;
  // This is Coinbase transaction that is detected from chain
  TRANSACTION_STATUS_COINBASE_CONFIRMED = 13;
  // This is Coinbase transaction that is not currently detected as mined
  TRANSACTION_STATUS_COINBASE_NOT_IN_BLOCK_CHAIN = 14;
}

message GetCompletedTransactionsRequest {
  UserPaymentId payment_id = 1;
  BlockHashHex block_hash = 2;
  BlockHeight block_height = 3;
}

message BlockHashHex {
  string hash = 1;
}

message GetCompletedTransactionsResponse {
  TransactionInfo transaction = 1;
}


// Request message for GetBalance RPC.
message GetBalanceRequest {
  // Optional: A user-defined payment ID to filter balance data.
  // Must provide only one of the following fields: u256, utf8_string, or user_bytes.
  UserPaymentId payment_id = 1;
}

message UserPaymentId {
  bytes u256 = 1;
  string utf8_string = 2;
  bytes user_bytes = 3;
}

message GetStateRequest {}

message GetBalanceResponse {
  uint64 available_balance = 1;
  uint64 pending_incoming_balance = 2;
  uint64 pending_outgoing_balance = 3;
  uint64 timelocked_balance = 4;
}

// Response message for GetState
message GetStateResponse {
  // The blockchain height (in blocks) that the wallet has scanned up to
  uint64 scanned_height = 1;
  // Current wallet balance information (available, pending), based on the GetBalanceResponse
  GetBalanceResponse balance = 2;
  // Status of the wallet's connection to the base node, based on the NetworkStatusResponse
  NetworkStatusResponse network = 3;
}

// Response message for GetUnspentAmounts RPC.
message GetUnspentAmountsResponse {
  // Total value of all unspent outputs, in the smallest unit (e.g., microTari).
  repeated uint64 amount = 1;
}

// Request message for the CoinSplit RPC.
message CoinSplitRequest {
  // The value of each output to create.
  uint64 amount_per_split = 1;
  // The number of outputs to create in total.
  uint64 split_count = 2;
  // Fee rate per weight unit (gram).
  uint64 fee_per_gram = 3;
  // Block height when the transaction becomes valid.
  uint64 lock_height = 5;
  // Optional identifier for referencing the transaction.
  bytes payment_id = 6;
}

// Response message containing the transaction ID of the coin split.
message CoinSplitResponse {
  // The unique ID of the transaction created.
  uint64 tx_id = 1;
}

// Request message for importing UTXOs into the wallet.
message ImportUtxosRequest {
  // List of unblinded outputs to be imported as UTXOs.
  repeated UnblindedOutput outputs = 1;

  // Optional payment ID to tag the imported outputs.
  bytes payment_id = 2;
}

// Response message containing transaction IDs for the imported outputs.
message ImportUtxosResponse {
  // Transaction IDs corresponding to the imported UTXOs.
  repeated uint64 tx_ids = 1;
}

message CreateTemplateRegistrationRequest {
  TemplateRegistration template_registration = 1;
  uint64 fee_per_gram = 2;
}

message CreateTemplateRegistrationResponse {
  uint64 tx_id = 1;
  bytes template_address = 2;
}

// Request message for the CancelTransaction RPC.
message CancelTransactionRequest {
  // The transaction ID to be cancelled.
  uint64 tx_id = 1;
}

// Response message for the CancelTransaction RPC.
message CancelTransactionResponse {
  // Indicates whether the cancellation was successful.
  bool is_success = 1;

  // The failure message if the cancellation was not successful.
  string failure_message = 2;
}

message RevalidateRequest{}

message RevalidateResponse{}

message ValidateRequest{}

message ValidateResponse{}

message SetBaseNodeRequest {
  string public_key_hex = 1;
  string net_address = 2;
}

message SetBaseNodeResponse{}

// Empty request for CheckConnectivity
message GetConnectivityRequest{}

// Response indicating the wallet's connectivity status
message CheckConnectivityResponse{
  // Describes the wallet's network connection state
  enum OnlineStatus {
    // The wallet is attempting to connect to peers
    Connecting = 0;
    // The wallet is successfully connected to peers
    Online = 1;
    // The wallet is not connected to any peers
    Offline = 2;
  }
  // The current connectivity state of the wallet
  OnlineStatus status = 1;
}

message TransactionEventRequest{

}

message TransactionEvent {
  string event = 1;
  string tx_id = 2;
  bytes source_address = 3;
  bytes dest_address = 4;
  string status = 5;
  string direction = 6;
  uint64 amount = 7;
  bytes payment_id = 9;
}

message TransactionEventResponse {
  TransactionEvent transaction = 1;
}

message RegisterValidatorNodeRequest {
  bytes validator_node_public_key = 1;
  Signature validator_node_signature = 2;
  uint64 fee_per_gram = 3;
  bytes payment_id = 5;
}

message RegisterValidatorNodeResponse {
  uint64 transaction_id = 1;
  bool is_success = 2;
  string failure_message = 3;
}

message ImportTransactionsRequest {
  string txs = 1;
}

message ImportTransactionsResponse {
    repeated uint64 tx_ids = 1;
}

message GetAllCompletedTransactionsRequest {
  uint64 offset = 1;
  uint64 limit = 2;
  uint64 status_bitflag = 3;
}

message GetAllCompletedTransactionsResponse {
  repeated TransactionInfo transactions = 1;
}

// Request message for getting transactions at a specific block height
message GetBlockHeightTransactionsRequest {
  // The block height to fetch transactions for
  uint64 block_height = 1;
}

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;
}