mobilecoind_api.proto

// Copyright (c) 2018-2022 The MobileCoin Foundation

// MUST BE KEPT IN SYNC WITH RUST CODE!

// mobilecoind client data types and service descriptors.

syntax = "proto3";
import "google/protobuf/empty.proto";
import "external.proto";
import "blockchain.proto";
import "watcher.proto";
import "ledger.proto";

package mobilecoind_api;

option java_package = "com.mobilecoin.mobilecoind";
option java_outer_classname = "MobileCoinDAPI";

service MobilecoindAPI {
    // Monitors
    rpc AddMonitor (AddMonitorRequest) returns (AddMonitorResponse) {}
    rpc RemoveMonitor (RemoveMonitorRequest) returns (google.protobuf.Empty) {}
    rpc GetMonitorList (google.protobuf.Empty) returns (GetMonitorListResponse) {}
    rpc GetMonitorStatus (GetMonitorStatusRequest) returns (GetMonitorStatusResponse) {}
    rpc GetUnspentTxOutList (GetUnspentTxOutListRequest) returns (GetUnspentTxOutListResponse) {}
    rpc GetAllUnspentTxOut (GetAllUnspentTxOutRequest) returns (GetAllUnspentTxOutResponse) {}

    // Utilities
    rpc GenerateRootEntropy (google.protobuf.Empty) returns (GenerateRootEntropyResponse) {}
    rpc GenerateMnemonic (google.protobuf.Empty) returns (GenerateMnemonicResponse) {}
    rpc GetAccountKeyFromRootEntropy (GetAccountKeyFromRootEntropyRequest) returns (GetAccountKeyResponse) {}
    rpc GetAccountKeyFromMnemonic (GetAccountKeyFromMnemonicRequest) returns (GetAccountKeyResponse) {}
    rpc GetPublicAddress (GetPublicAddressRequest) returns (GetPublicAddressResponse) {}
    rpc GetShortAddressHash (GetShortAddressHashRequest) returns (GetShortAddressHashResponse) {}
    rpc ValidateAuthenticatedSenderMemo (ValidateAuthenticatedSenderMemoRequest) returns (ValidateAuthenticatedSenderMemoResponse) {}
    rpc TxOutViewKeyMatch (TxOutViewKeyMatchRequest) returns (TxOutViewKeyMatchResponse) {}

    // b58 Codes
    rpc ParseRequestCode (ParseRequestCodeRequest) returns (ParseRequestCodeResponse) {}
    rpc CreateRequestCode (CreateRequestCodeRequest) returns (CreateRequestCodeResponse) {}
    rpc ParseTransferCode (ParseTransferCodeRequest) returns (ParseTransferCodeResponse) {}
    rpc CreateTransferCode (CreateTransferCodeRequest) returns (CreateTransferCodeResponse) {}
    rpc ParseAddressCode (ParseAddressCodeRequest) returns (ParseAddressCodeResponse) {}
    rpc CreateAddressCode (CreateAddressCodeRequest) returns (CreateAddressCodeResponse) {}

    // Txs
    rpc GetMixins (GetMixinsRequest) returns (GetMixinsResponse) {}
    rpc GetMembershipProofs (GetMembershipProofsRequest) returns (GetMembershipProofsResponse) {}
    rpc GenerateTx (GenerateTxRequest) returns (GenerateTxResponse) {}
    rpc GenerateOptimizationTx (GenerateOptimizationTxRequest) returns (GenerateOptimizationTxResponse) {}
    rpc GenerateTransferCodeTx (GenerateTransferCodeTxRequest) returns (GenerateTransferCodeTxResponse) {}
    rpc GenerateTxFromTxOutList (GenerateTxFromTxOutListRequest) returns (GenerateTxFromTxOutListResponse) {}
    rpc GenerateBurnRedemptionTx (GenerateBurnRedemptionTxRequest) returns (GenerateBurnRedemptionTxResponse) {}
    rpc SubmitTx (SubmitTxRequest) returns (SubmitTxResponse) {}

    // Swaps
    rpc GenerateSwap (GenerateSwapRequest) returns (GenerateSwapResponse) {}
    rpc GenerateMixedTx (GenerateMixedTxRequest) returns (GenerateMixedTxResponse) {}

    // Databases
    rpc GetLedgerInfo (google.protobuf.Empty) returns (GetLedgerInfoResponse) {}
    rpc GetBlockInfo (GetBlockInfoRequest) returns (GetBlockInfoResponse) {}
    rpc GetBlock (GetBlockRequest) returns (GetBlockResponse) {}
    rpc GetLatestBlock (google.protobuf.Empty) returns (GetBlockResponse) {}
    rpc GetBlocksData (GetBlocksDataRequest) returns (GetBlocksDataResponse) {}
    rpc GetTxStatusAsSender (SubmitTxResponse) returns (GetTxStatusAsSenderResponse) {}
    rpc GetTxStatusAsReceiver (GetTxStatusAsReceiverRequest) returns (GetTxStatusAsReceiverResponse) {}
    rpc GetProcessedBlock (GetProcessedBlockRequest) returns (GetProcessedBlockResponse) {}
    rpc GetBlockIndexByTxPubKey (GetBlockIndexByTxPubKeyRequest) returns (GetBlockIndexByTxPubKeyResponse) {}
    rpc GetTxOutResultsByPubKey (GetTxOutResultsByPubKeyRequest) returns (GetTxOutResultsByPubKeyResponse) {}

    // Convenience calls
    rpc GetBalance (GetBalanceRequest) returns (GetBalanceResponse) {}
    rpc SendPayment (SendPaymentRequest) returns (SendPaymentResponse) {}
    rpc PayAddressCode (PayAddressCodeRequest) returns (SendPaymentResponse) {}

    // Network status
    rpc GetNetworkStatus (google.protobuf.Empty) returns (GetNetworkStatusResponse) {}

    // Database encryption
    rpc SetDbPassword (SetDbPasswordRequest) returns (google.protobuf.Empty) {}
    rpc UnlockDb (UnlockDbRequest) returns (google.protobuf.Empty) {}

    // Versioning
    rpc GetVersion(google.protobuf.Empty) returns (MobilecoindVersionResponse) {}
}

//*********************************
//*
//*  Structures
//*
//*********************************


// Possible transaction status values. Senders check with key images and tx public keys. Receivers check with tx public keys.
enum TxStatus {
    // The transaction is not in the public ledger.
    Unknown = 0;

    // The transaction is in the public ledger.
    Verified = 1;

    // Error: The transaction is not in the public ledger, and the tombstone block has been exceeded.
    TombstoneBlockExceeded = 2;

    // The transaction was found in the ledger but the confirmation number is incorrect.
    InvalidConfirmationNumber = 3;

    // The tx public keys are in different blocks. This indicates the receipt is possibly malformed.
    PublicKeysInDifferentBlocks = 4;

    // Not all key_images in the same block as the tx_public_keys, indicating the transaction for this receipt failed.
    TransactionFailureKeyImageBlockMismatch = 5;

    // Some key_images are spent elsewhere in the ledger, despite the tx_public_keys not appearing in the ledger.
    TransactionFailureKeyImageAlreadySpent = 6;
}

// Structure used in specifying the list of outputs when generating a transaction.
// Here the token id is implied from context, and matches the fee token id.
message Outlay {
    uint64 value = 1;
    external.PublicAddress receiver = 2;
    // Optional tx private key to use for this tx out. This can be chosen explicitly as a mechanism for idempotence.
    // Must be 32 pseudorandom bytes or none. Will be reduced to curve25519 scalar mod order.
    bytes tx_private_key = 3;
}

// Structure used in specifying the list of outputs in a transaction.
// Here the token id is explicit.
message OutlayV2 {
    uint64 value = 1;
    external.PublicAddress receiver = 2;
    uint64 token_id = 3;
    // Optional tx private key to use for this tx out. This can be chosen explicitly as a mechanism for idempotence.
    // Must be 32 pseudorandom bytes or none. Will be reduced to curve25519 scalar mod order.
    bytes tx_private_key = 4;
}

// Structure used to refer to a TxOut in the ledger that is presumed to be spendable.
// The structure is annotated with extra information needed to spend the TxOut in a payment, calculated using the private keys that control the TxOut.
message UnspentTxOut {
    // The actual TxOut object found in the ledger.
    external.TxOut tx_out = 1;

    // The subaddress the TxOut was sent to.
    uint64 subaddress_index = 2;

    // The key image of the TxOut.
    external.KeyImage key_image = 3;

    // The value of the TxOut.
    uint64 value = 4;

    // The block height at which this UnspentTxOut was last attempted to be spent.
    uint64 attempted_spend_height = 5;

    // The tombstone block used when we attempted to spend the UTXO.
    uint64 attempted_spend_tombstone = 6;

    // The token id of the TxOut
    uint64 token_id = 7;

    // The (decrypted) MemoPayload of this TxOut
    bytes memo_payload = 8;

    // The monitor id this UnspentTxOut belongs to.
    // Note that this field is not included in the Rust `utxo_store::UnspentTxOut` struct.
    bytes monitor_id = 10;

    // The decoded memo info, if any
    DecodedMemo decoded_memo = 11;
}

message DecodedMemo {
    // Details of the decoded memo payload.
    // Omitted if the empty memo was found.
    oneof decoded_memo {
      UnknownMemo unknown_memo = 1;
      AuthenticatedSenderMemo authenticated_sender_memo = 2;
    }
}

// Structure used to represent the decoded MCIP #4 Authenticated sender memo and its variants.
// Note that the sender can write whatever they want in a memo, and to rely on the data.
// You must validate the memo by checking the hmac, see the ValidateAuthenticatedSenderMemo rpc call.
message AuthenticatedSenderMemo {
    /// The standard short address hash (MCIP #4)
    bytes sender_hash = 1;
    // Payment request ID if present
    optional uint64 payment_request_id = 2;
    // Payment intent ID if present
    optional uint64 payment_intent_id = 3;
}

// Details returned when this version of mobilecoind couldn't interpret a memo payload.
message UnknownMemo {
    // The type bytes of this memo, which couldn't be interpreted by mobilecoind.
    bytes type_bytes = 1;
}

// Structure used to refer to an SCI that we want to add to a transaction.
// The structure has additional information -- if it's a partial fill SCI, we need to know the partial fill amount.
message SciForTx {
    /// The signed input we want to add
    external.SignedContingentInput sci = 1;

    /// If it's a partial fill SCI, the value we wish to fill it for
    /// This is the amount that, we, the counter-party, take from the SCI originator,
    /// in exchange for a corresponding fraction of the partial fill outputs in the SCI.
    ///
    /// This is a u64 value corresponding to an amount less or equal to the partial_fill_change amount
    /// in the SCI.
    ///
    /// In case of a non partial fill SCI (without partial_fill_change output),
    /// this must be zero.
    uint64 partial_fill_value = 2;
}

// Structure used to refer to a prepared transaction
message TxProposal {
    // List of inputs being spent.
    repeated UnspentTxOut input_list = 1;

    // List of outputs being created.
    // This excludes the fee output.
    repeated OutlayV2 outlay_list = 2;

    // The actual transaction object.
    // Together with the private view/spend keys, this structure contains all information in existence about the transaction.
    external.Tx tx = 3;

    // The transaction fee. This is equal to `tx.prefix.fee`.
    // Note that changing this fee will have no effect on the transaction. Changing the fee
    // inside `tx` will invalidate the ring signature.
    uint64 fee = 4;

    /// A map of outlay index -> TxOut index in the Tx object.
    /// This is needed to map recipients to their respective TxOuts.
    map<uint64, uint64> outlay_index_to_tx_out_index = 5;

    /// A list of the confirmation numbers, in the same order
    /// as the outlays.
    repeated bytes outlay_confirmation_numbers = 6;

    /// A list of the scis that were incorporated into this transaction, if any
    repeated SciForTx scis = 7;
}

// Structure used to check transaction status as a Sender.
message SenderTxReceipt {
    // Key images that are going to be added to the ledger once the transaction goes through.
    repeated external.KeyImage key_image_list = 1;

    // Tombstone block set in the transaction.
    uint64 tombstone = 2;
}

// Structure used to check transaction status as a recipient.
// There exists one receipt per output, so a transaction having multiple outputs would have
// multiple ReceiverTxReceipts.
message ReceiverTxReceipt {
    // The recipient this receipt refers to
    external.PublicAddress recipient = 1;

    // The public key of the TxOut sent to this recipient.
    external.CompressedRistretto tx_public_key = 2;

    // The hash of the TxOut sent to this recipient.
    bytes tx_out_hash = 3;

    // Tombstone block set in the transaction.
    uint64 tombstone = 4;

    // Confirmation number for this TxOut
    bytes confirmation_number = 5;
}

// Structure used to report monitor status
message MonitorStatus {
    // The account key the monitor is monitoring.
    external.AccountKey account_key = 1;

    // The first subaddress being monitored.
    uint64 first_subaddress = 2;

    // The number of subaddresses being monitored, starting at first_subaddress.
    uint64 num_subaddresses = 3;

    // Block index we started scanning from.
    uint64 first_block = 4;

    // Next block we are waiting to sync.
    uint64 next_block = 5;

    // Optional monitor name.
    string name = 6;
}

// Enum used to indicate whether a ProcessedTxOut is a sent one or a received one.
enum ProcessedTxOutDirection {
    // This should never happen, but is available here as an option to catch uninitialized data.
    // The name "Unknown" cannot be used because, quoting the protobuf compiler:
    // Note that enum values use C++ scoping rules, meaning that enum values are siblings of their type, not children of it.  Therefore, "Unknown" must be unique within "mobilecoind_api", not just within "ProcessedTxOutDirection".
    Invalid = 0;

    // The ProcessedTxOut has been received at the block queried for.
    Received = 1;

    // The ProcessedTxOut has been spent at the block queried for.
    Spent = 2;
}


// Structure used to report processed information for TxOuts discovered in a given processed block.
message ProcessedTxOut {
    // The monitor id that owns the TxOut.
    bytes monitor_id = 1;

    // The subaddress that owns the TxOut.
    uint64 subaddress_index = 2;

    // The public key of the TxOut.
    external.CompressedRistretto public_key = 3;

    // The key image of the TxOut.
    external.KeyImage key_image = 4;

    // The value of the TxOut.
    uint64 value = 5;

    // Whether the TxOut was received (deposit to subaddress) or spent (withdrawal from subaddress).
    ProcessedTxOutDirection direction = 6;

    // The b58-encoded Address Code for the subaddress that owns the TxOut.
    string address_code = 7;

    // The token id of the TxOut.
    uint64 token_id = 8;
}


// Recoverable Transaction History memo with an optional u64 specifying the
// subaddress index to generate the sender memo credential from.
// Defaults to the default subaddress of the monitor.
// Allows optinally speciying a payment intent id or payment request id.
message TransactionMemo_RTH {
    optional uint64 subaddress_index = 1;
    oneof payment_id {
        uint64 payment_intent_id = 2;
        uint64 payment_request_id = 3;
    }
}

// Empty transaction memo.
message TransactionMemo_Empty {
}

// Burn redemption memo
message TransactionMemo_BurnRedemption {
    // The burn redemption memo data (64 bytes).
    bytes memo_data = 1;
}

// Memo type to use when building a transaction.
// We will default to RTH from the default subaddress if nothing else is explicitly specified.
message TransactionMemo {
    oneof transaction_memo {
        TransactionMemo_RTH rth = 1;
        TransactionMemo_Empty empty = 2;
        TransactionMemo_BurnRedemption burn_redemption = 3;
    }
}

//*********************************
//*
//*  Requests and Responses for API
//*
//*********************************

//
// Monitors
//

// Add a new monitor.
message AddMonitorRequest {
    // Account key to monitor.
    external.AccountKey account_key = 1;

    // The first subaddress being monitored.
    uint64 first_subaddress = 2;

    // The number of subaddresses being monitored, starting at first_subaddress.
    uint64 num_subaddresses = 3;

    // Block index to start monitoring from.
    uint64 first_block = 4;

    // Optional name.
    string name = 5;
}
message AddMonitorResponse {
    bytes monitor_id = 1;
    bool is_new = 2;
}

// Remove a monitor and all associated data.
message RemoveMonitorRequest {
    bytes monitor_id = 1;
}
// - empty response

// List all known monitor ids.
// - empty request
message GetMonitorListResponse {
    repeated bytes monitor_id_list = 1;
}

// Get the status of a specific monitor.
message GetMonitorStatusRequest {
    bytes monitor_id = 1;
}
message GetMonitorStatusResponse {
    MonitorStatus status = 1;
}

// Get a list of UnspentTxOuts for a given monitor and subadddress index,
// filtered to a specific token id.
message GetUnspentTxOutListRequest {
    bytes monitor_id = 1;
    uint64 subaddress_index = 2;
    uint64 token_id = 3;
}
message GetUnspentTxOutListResponse {
    repeated UnspentTxOut output_list = 1;
}

// Get a list of all UnspentTxOuts for a given monitor, without any filtering
message GetAllUnspentTxOutRequest {
    bytes monitor_id = 1;
}
message GetAllUnspentTxOutResponse {
    repeated UnspentTxOut output_list = 1;
}

//
// Utilities
//

// Generate a new random root entropy value.
// - empty request
message GenerateRootEntropyResponse {
    // 32 bytes generated using a cryptographically secure RNG.
    bytes root_entropy = 1;
}

// Generate a new random mnemomic.
// - empty request
message GenerateMnemonicResponse {
    // mnemonic generated using a cryptographically secure RNG.
    string mnemonic = 1;

    // The mnemonic represented as 32 bytes entropy.
    bytes bip39_entropy = 2;
}

// Generate an AccountKey from a 32 byte root entropy value.
message GetAccountKeyFromRootEntropyRequest {
    bytes root_entropy = 1;
}

// Generate an AccountKey from a mnemonic.
message GetAccountKeyFromMnemonicRequest {
    string mnemonic = 1;
    uint32 account_index = 2;
}
message GetAccountKeyResponse {
    external.AccountKey account_key = 1;
}

// Get the public address for a given monitor and subadddress index.
message GetPublicAddressRequest {
    bytes monitor_id = 1;
    uint64 subaddress_index = 2;
}
message GetPublicAddressResponse {
    external.PublicAddress public_address = 1;
    string b58_code = 2;
}

//
// Memos
//

message GetShortAddressHashRequest {
    external.PublicAddress public_address = 1;
}

message GetShortAddressHashResponse {
    bytes hash = 1;
}

message ValidateAuthenticatedSenderMemoRequest {
    bytes monitor_id = 1;
    UnspentTxOut utxo = 2;
    external.PublicAddress sender = 3;
}

message ValidateAuthenticatedSenderMemoResponse {
    bool success = 1;
}

message TxOutViewKeyMatchRequest {
    external.TxOut txo = 1;
    external.RistrettoPrivate view_private_key = 2;
}

message TxOutViewKeyMatchResponse {
    // Whether the tx out belongs to the provided view private key.
    bool matched = 1;

    // The value of the tx out, only valid if matched is true.
    uint64 value = 2;

    // The token_id of the tx out, only valid if matched is true.
    uint64 token_id = 3;

    // The tx out shared secret, only valid if matched is true.
    external.CompressedRistretto shared_secret = 4;
}

//
// b58 Codes
//

// Decode a base-58 encoded "MobileCoin Request Code" into receiver's public address, value, and memo.
message ParseRequestCodeRequest {
    string b58_code = 1;
}
message ParseRequestCodeResponse {
    external.PublicAddress receiver = 1;
    uint64 value = 2;
    string memo = 3;
    uint64 token_id = 4;
}

// Encode receiver's public address, value, and memo into a base-58 "MobileCoin Request Code".
message CreateRequestCodeRequest {
    external.PublicAddress receiver = 1;
    uint64 value = 2;
    string memo = 3;
    uint64 token_id = 4;
}
message CreateRequestCodeResponse {
    string b58_code = 1;
}

// Decode a base-58 encoded "MobileCoin Transfer Code" into entropy/tx_public_key/memo.
// This code provides a mobile client with everything required to construct a self-payment, allowing funds to be withdrawn from a gift card.
message ParseTransferCodeRequest {
    string b58_code = 1;
}
message ParseTransferCodeResponse {
    bytes root_entropy = 1 [deprecated=true];
    external.CompressedRistretto tx_public_key = 2;
    string memo = 3;
    UnspentTxOut utxo = 4;
    bytes bip39_entropy = 5;
}

// Encode entropy/tx_public_key/memo into a base-58 "MobileCoin Transfer Code".
message CreateTransferCodeRequest {
    bytes root_entropy = 1 [deprecated=true];
    external.CompressedRistretto tx_public_key = 2;
    string memo = 3;
    bytes bip39_entropy = 4;
}
message CreateTransferCodeResponse {
    string b58_code = 1;
}

// Decode a base-58 encoded "MobileCoin Address Code" into the receiver's public address.
message ParseAddressCodeRequest {
    string b58_code = 1;
}
message ParseAddressCodeResponse {
    external.PublicAddress receiver = 1;
}

// Encode receiver's public address into a base-58 "MobileCoin Address Code".
message CreateAddressCodeRequest {
    external.PublicAddress receiver = 1;
}
message CreateAddressCodeResponse {
    string b58_code = 1;
}

//
// Transactions
//

message TxOutWithProof {
    external.TxOut output = 1;
    external.TxOutMembershipProof proof = 2;
}

message GetMixinsRequest {
    uint64 num_mixins = 1;
    repeated external.TxOut excluded = 2;
}

message GetMixinsResponse {
    repeated TxOutWithProof mixins = 1;
}

// Get membership proofs either by TxOuts or by TxOut indices.
message GetMembershipProofsRequest {
    repeated external.TxOut outputs = 1;
    repeated uint64 indices = 2;
}

message GetMembershipProofsResponse {
    repeated TxOutWithProof output_list = 1;
}

// Generate a transaction proposal object.
// Notes:
// - Sum of inputs needs to be greater than sum of outlays and fee.
// - The set of inputs to use would be chosen automatically by mobilecoind.
// - The fee field could be set to zero, in which case mobilecoind would choose a fee.
// Right now that fee is the network-reported minimum fee for the given token id.
message GenerateTxRequest {
    // Monitor id sending the funds.
    bytes sender_monitor_id = 1;

    // Subaddress to return change to.
    uint64 change_subaddress = 2;

    // List of UnspentTxOuts to be spent by the transaction.
    // All UnspentTxOuts must belong to the same sender_monitor_id.
    // mobilecoind would choose a subset of these inputs to construct the transaction.
    // Total input amount must be >= sum of outlays + fees.
    repeated UnspentTxOut input_list = 3;

    // Outputs to be generated by the transaction. This excludes change and fee.
    repeated Outlay outlay_list = 4;

    // Fee value, in smallest representable units (u64).
    // (For MOB this is picoMOB.)
    // Setting to 0 causes mobilecoind to choose a value.
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.fee
    uint64 fee = 5;

    // Tombstone block (setting to 0 causes mobilecoind to choose a value).
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.tombstone_block
    uint64 tombstone = 6;

    // Token id to use for the transaction.
    uint64 token_id = 7;

    // List of SCIs to be added to the transaction
    repeated SciForTx scis = 8;

    // TxOut memo to use for the transaction.
    // This defaults to RTH authenticated sender from the default subaddress of the sender monitor.
    TransactionMemo memo = 9;
}

message GenerateTxResponse {
    TxProposal tx_proposal = 1;
}

// Generate a transaction proposal object with mixed token types.
// Notes:
// - Sum of inputs needs to be greater than or equal to the sum of outlays and fee.
// - The set of inputs to use would be chosen automatically by mobilecoind.
// - The fee field could be set to zero, in which case mobilecoind would choose a fee.
// Right now that fee is the network-reported minimum fee for the fee token id.
message GenerateMixedTxRequest {
    // Monitor id sending the funds.
    bytes sender_monitor_id = 1;

    // Subaddress to return change to.
    uint64 change_subaddress = 2;

    // List of UnspentTxOuts to be spent by the transaction.
    // All UnspentTxOuts must belong to the same sender_monitor_id.
    // mobilecoind would choose a subset of these inputs to construct the transaction.
    // Total input amount must be >= sum of outlays + fees, for each token id involved.
    repeated UnspentTxOut input_list = 3;

    // List of SCIs to be added to the transaction
    repeated SciForTx scis = 4;

    // Outputs to be generated by the transaction. This excludes change and fee.
    repeated OutlayV2 outlay_list = 5;

    // Fee value, in smallest representable units (u64).
    // (For MOB this is picoMOB.)
    // Setting to 0 causes mobilecoind to choose a value.
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.fee
    uint64 fee = 6;

    // Token id to use for the transaction fee.
    uint64 fee_token_id = 7;

    // Tombstone block (setting to 0 causes mobilecoind to choose a value).
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.tombstone_block
    uint64 tombstone = 8;
}

message GenerateMixedTxResponse {
    TxProposal tx_proposal = 1;
}

// Generate a transaction that merges a few UnspentTxOuts into one, in order to reduce wallet fragmentation.
message GenerateOptimizationTxRequest {
    // Monitor Id to operate on.
    bytes monitor_id = 1;

    // Subaddress to operate on.
    uint64 subaddress = 2;

    // Add an optional fee
    uint64 fee = 3;

    // Token id to use for the transaction.
    uint64 token_id = 4;
}
message GenerateOptimizationTxResponse {
    TxProposal tx_proposal = 1;
}

// Generate a transaction that can be used for a "MobileCoin Transfer Code"
message GenerateTransferCodeTxRequest {
    bytes sender_monitor_id = 1;
    uint64 change_subaddress = 2;
    repeated UnspentTxOut input_list = 3;
    uint64 value = 4;
    uint64 fee = 5;
    uint64 tombstone = 6;
    string memo = 7;
    uint64 token_id = 8;
}
message GenerateTransferCodeTxResponse {
    // The tx proposal to submit to the network.
    TxProposal tx_proposal = 1;

    // Deprecated - left here as an explanation to why we skip tag 2: bytes root_entropy = 2;

    // The TxOut public key that has the funds.
    external.CompressedRistretto tx_public_key = 3;

    // The memo (simply copied from the request).
    string memo = 4;

    // The b58-encoded Transfer Code
    string b58_code = 5;

    // The entropy for constructing the AccountKey that can access the funds.
    bytes bip39_entropy = 6;
}

// Generate a transaction without a monitor, requires an account key and
// a list of UnspentTxOuts. All coins (minus the fee) are transferred to
// a single recipient. Used for temporary accounts like gift codes.
// All inputs must be of the same token id.
message GenerateTxFromTxOutListRequest {
    // Account key that owns the transactions
    external.AccountKey account_key = 1;

    // List of TxOuts to spend
    repeated UnspentTxOut input_list = 2;

    // Address to transfer coins to
    external.PublicAddress receiver = 3;

    // Fee
    uint64 fee = 4;

    // Token id
    uint64 token_id = 5;
}

message GenerateTxFromTxOutListResponse {
    TxProposal tx_proposal = 1;
}

// Generate a burn redemption transaction proposal object.
// Notes:
// - Sum of inputs needs to be greater than or equal to the burn amount and fee.
// - The set of inputs to use would be chosen automatically by mobilecoind.
// - The fee field could be set to zero, in which case mobilecoind would try and choose a fee.
message GenerateBurnRedemptionTxRequest {
    // Monitor id sending the funds.
    bytes sender_monitor_id = 1;

    // Subaddress to return change to.
    uint64 change_subaddress = 2;

    // List of UnspentTxOuts to be spent by the transaction.
    // All UnspentTxOuts must belong to the same sender_monitor_id.
    // mobilecoind would choose a subset of these inputs to construct the transaction.
    // Total input amount must be >= burn amount + fee.
    repeated UnspentTxOut input_list = 3;

    // Amount to be burnt. This excludes change and fee.
    uint64 burn_amount = 4;

    // Fee (setting to 0 causes mobilecoind to choose a value).
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.fee
    uint64 fee = 5;

    // Tombstone block (setting to 0 causes mobilecoind to choose a value).
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.tombstone_block
    uint64 tombstone = 6;

    // Token id to use for the transaction.
    uint64 token_id = 7;

    // Optional 64 bytes of data to include in the burn redemption memo that is attached to the burn TxOut.
    // If not provided zeros will be used.
    bytes redemption_memo = 8;

    // Enable RTH destination memo.
    bool enable_destination_memo = 9;
}
message GenerateBurnRedemptionTxResponse {
    TxProposal tx_proposal = 1;
}

// Generate a simple swap proposal. The result is a signed contingent input
// which trades one currency for another and is suitable for use with the deqs.
// (This API is restrictive and doesn't let you build more complex SCIs.)
message GenerateSwapRequest {
    // Monitor id sending the funds.
    bytes sender_monitor_id = 1;

    // Subaddress to return change to.
    uint64 change_subaddress = 2;

    // A specific input, whose value will be offered in full by the swap.
    //
    // This becomes the "base token" amount from the point of view of a quoting service.
    //
    // You may need to conduct a self-spend first to make an input of exactly
    // the correct value before using this API if none of your inputs match
    // the volume of the quote you want to make.
    UnspentTxOut input = 3;

    // The u64 value we are asking for in exchange for our input
    //
    // This becomes the "counter token" value from the point of view of a quoting service.
    uint64 counter_value = 4;

    // The token_id we are asking for in exchange for our input
    //
    // This becomes the "counter token" token id from the point of view of a quoting service.
    uint64 counter_token_id = 5;

    // If set to false, the offer is "all or nothing", the entire counter token value must be supplied,
    // in exchange for the entire value of the input we are signing over.
    // Otherwise, it is a "partial-fill" SCI, and can be filled at less than the maximum volume for
    // proportionally more of the input value.
    bool allow_partial_fill = 6;

    // The smallest u64 value that we will accept to conduct the swap.
    // This can be set to avoid receiving "dust" amounts when allow_partial_fill is true.
    // This is ignored if allow_partial_fill is false.
    uint64 minimum_fill_value = 7;

    // Tombstone block (setting to 0 means this offer does not expire).
    uint64 tombstone = 8;
}

message GenerateSwapResponse {
    external.SignedContingentInput sci = 1;
}

// Submits a transaction to the network.
message SubmitTxRequest {
    TxProposal tx_proposal = 1;
}
message SubmitTxResponse {
    SenderTxReceipt sender_tx_receipt = 1;
    repeated ReceiverTxReceipt receiver_tx_receipt_list = 2;
}

//
// Databases
//

// Get information about the downloaded ledger.
// - empty request
message GetLedgerInfoResponse {
    // Total number of blocks in the ledger.
    uint64 block_count = 1;

    // Total number of TxOuts in the ledger.
    uint64 txo_count = 2;
}

// Get information about a downloaded block.
message GetBlockInfoRequest {
    uint64 block = 1;
}
message GetBlockInfoResponse {
    // Number of key images in the block.
    uint64 key_image_count = 1;

    // Number of TxOuts in the block.
    uint64 txo_count = 2;
}

message ArchiveBlockSignatureData {
    // The origin of the Archive Block.
    string src_url = 1;

    // The archive filename.
    string filename = 2;

    // The block signature.
    blockchain.BlockSignature signature = 3;
}

// Get more detailed information about a downloaded block
message GetBlockRequest {
    uint64 block = 1;
}
message GetBlockResponse {
    // The block
    blockchain.Block block = 1;

    // Signatures for this block
    repeated ArchiveBlockSignatureData signatures = 2;

    // Key images in the block
    repeated external.KeyImage key_images = 3;

    // TxOuts in the block.
    repeated external.TxOut txos = 4;

    // Timestamp result code
    watcher.TimestampResultCode timestamp_result_code = 5;

    // Timestamp (only valid if timestamp_result_code is TimestampFound)
    uint64 timestamp = 6;
}

// Get multiple block datas coupled with timestamps
message GetBlocksDataRequest {
    // List of block numbers to query
    repeated uint64 blocks = 1;
}

message BlockDataWithTimestamp {
    /// The block index that was requested.
    uint64 block_index = 1;

    /// Whether we found a block for the provided index.
    bool found = 2;

    /// The block data
    blockchain.ArchiveBlock block_data = 3;

    // Timestamp result code
    watcher.TimestampResultCode timestamp_result_code = 4;

    // Timestamp (only valid if timestamp_result_code is TimestampFound)
    uint64 timestamp = 5;
}

message GetBlocksDataResponse {
    /// Result (one for each index in the request)
    repeated BlockDataWithTimestamp results = 1;

    /// Latest block in the ledger.
    blockchain.Block latest_block = 2;
}

// Get the status of a submitted transaction as the Sender.
message GetTxStatusAsSenderResponse {
    TxStatus status = 1;
}

// Get the status of a submitted transaction as the Recipient (using the tx public key).
message GetTxStatusAsReceiverRequest {
    ReceiverTxReceipt receipt = 1;

    // Optionally pass in a monitor ID to validate confirmation number
    bytes monitor_id = 2;
}
message GetTxStatusAsReceiverResponse {
    TxStatus status = 1;
}

// Get the contents of a processed block.
message GetProcessedBlockRequest {
    // Monitor id to query data for.
    bytes monitor_id = 1;

    // Block number to query.
    uint64 block = 2;
}
message GetProcessedBlockResponse {
    // Processed tx output information that belongs to the requested monitor_id/block.
    repeated ProcessedTxOut tx_outs = 1;
}

// Get the block index containing a given TxOut public key.
message GetBlockIndexByTxPubKeyRequest {
    // The TxOut public key to look for.
    external.CompressedRistretto tx_public_key = 1;
}
message GetBlockIndexByTxPubKeyResponse {
    // The block index.
    uint64 block = 1;
}

// Get TxOutResults for a list of TxOut public keys.
message GetTxOutResultsByPubKeyRequest {
    repeated external.CompressedRistretto tx_out_public_keys = 1;
}

message GetTxOutResultsByPubKeyResponse {
    repeated fog_ledger.TxOutResult results = 1;
    blockchain.Block latest_block = 2;
}

//
// Convenience calls
///

// Get the balance for a given monitor, subadddress index and a specific token id.
message GetBalanceRequest {
    // Monitor id to query balance for.
    bytes monitor_id = 1;

    // Subaddress to query balance for.
    uint64 subaddress_index = 2;

    // Token id to filter for.
    uint64 token_id = 3;
}
message GetBalanceResponse {
    // Sum of all utxos associated with the requested monitor_id/subaddress_index/token_id.
    uint64 balance = 1;
}

// Build and submit a simple payment and return any change to the Sender's subaddress.
message SendPaymentRequest {
    // Monitor id sending the funds.
    bytes sender_monitor_id = 1;

    // Subaddress the funds are coming from.
    uint64 sender_subaddress = 2;

    // Outputs to be generated by the transaction. This excludes change and fee.
    repeated Outlay outlay_list = 3;

    // Fee (setting to 0 causes mobilecoind to choose a value).
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.fee
    uint64 fee = 4;

    // Tombstone block (setting to 0 causes mobilecoind to choose a value).
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.tombstone_block
    uint64 tombstone = 5;

    // Optional: When selecting input UTXOs for the transaction, limit selection only to UTXOs whose
    // value is lower or equal to to this.
    uint64 max_input_utxo_value = 6;

    // Optional: Return change to a different subaddress than the sender
    bool override_change_subaddress = 7;
    uint64 change_subaddress = 8;

    // Token id to transact in.
    uint64 token_id = 9;

    // TxOut memo to use for the transaction.
    // This defaults to RTH authenticated sender from the first subaddress index of the sender monitor.
    TransactionMemo memo = 10;
}

message SendPaymentResponse {
    // Information the sender can use to check if the transaction landed in the ledger.
    SenderTxReceipt sender_tx_receipt = 1;

    // Information receivers can use to check if the transaction landed in the ledger.
    repeated ReceiverTxReceipt receiver_tx_receipt_list = 2;

    // The TxProposal that was submitted to the network. The fee that was paid can be checked at
    // tx_proposal.tx.prefix.fee
    TxProposal tx_proposal = 3;
}

// Build and submit a simple payment to an address provided by a b58 address code
message PayAddressCodeRequest {
    // Monitor id sending the funds.
    bytes sender_monitor_id = 1;

    // Subaddress the funds are coming from.
    uint64 sender_subaddress = 2;

    // Base-58 encoded "MobileCoin Address Code"
    string receiver_b58_code = 3;

    // Amount to pay
    uint64 amount = 4;

    // Fee (setting to 0 causes mobilecoind to choose a value).
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.fee
    uint64 fee = 5;

    // Tombstone block (setting to 0 causes mobilecoind to choose a value).
    // The value used can be checked (but not changed) in tx_proposal.tx.prefix.tombstone_block
    uint64 tombstone = 6;

    // Optional: When selecting input UTXOs for the transaction, limit selection only to UTXOs whose
    // value is lower or equal to to this.
    uint64 max_input_utxo_value = 7;

    // Optional: Return change to a different subaddress than the sender
    bool override_change_subaddress = 8;
    uint64 change_subaddress = 9;

    // Token id to transact in.
    uint64 token_id = 10;
}

//
// Network status
//

// Get information about the network.
// - empty request
message GetNetworkStatusResponse {
    // Total highest block number the network agrees on.
    // (This is the block number we will try to sync to).
    uint64 network_highest_block_index = 1;

    // A map of node responder id to the block index reported by it.
    map<string, uint64> peer_block_index_map = 2;

    // The local ledger block index.
    uint64 local_block_index = 3;

    // Whether we are behind.
    bool is_behind = 4;

    // The latest block info data reported by a consensus node
    LastBlockInfo last_block_info = 5;

    // The chain id of the network we are connected to
    string chain_id = 6;
}

// Data about the network state and last block processed by the consensus network
message LastBlockInfo {
    // Block index
    uint64 index = 1;

    // Current MOB minimum fee (kept for backwards compatibility)
    uint64 mob_minimum_fee = 2 [deprecated = true];

    // A map of token id -> minimum fee
    map<uint64, uint64> minimum_fees = 3;

    // Current network_block version, appropriate for new transactions.
    //
    // Note that if the server was just reconfigured, this may be HIGHER than
    // the highest block version in the ledger, so for clients this is a better
    // source of truth than the local ledger, if the client might possibly be
    // creating the first transaction after a reconfigure / redeploy.
    uint32 network_block_version = 4;
}


//
// Database encryption
//

// Set the current database encryption password.
message SetDbPasswordRequest {
    bytes password = 2;
}

// Unlock a currently password-protected database.
message UnlockDbRequest {
    bytes password = 1;
}

// Get the mobilecoind version
// empty request
message MobilecoindVersionResponse {
    string version = 1;
}