mobilecoind_api.proto

// Copyright (c) 2018-2020 MobileCoin Inc.

// 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";

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) {}

    // Utilities
    rpc GenerateEntropy (google.protobuf.Empty) returns (GenerateEntropyResponse) {}
    rpc GetAccountKey (GetAccountKeyRequest) returns (GetAccountKeyResponse) {}
    rpc GetPublicAddress (GetPublicAddressRequest) returns (GetPublicAddressResponse) {}

    // b58 Codes
    rpc ReadRequestCode (ReadRequestCodeRequest) returns (ReadRequestCodeResponse) {}
    rpc GetRequestCode (GetRequestCodeRequest) returns (GetRequestCodeResponse) {}
    rpc ReadTransferCode (ReadTransferCodeRequest) returns (ReadTransferCodeResponse) {}
    rpc GetTransferCode (GetTransferCodeRequest) returns (GetTransferCodeResponse) {}
    rpc ReadAddressCode (ReadAddressCodeRequest) returns (ReadAddressCodeResponse) {}
    rpc GetAddressCode (GetAddressCodeRequest) returns (GetAddressCodeResponse) {}

    // Txs
    rpc GenerateTx (GenerateTxRequest) returns (GenerateTxResponse) {}
    rpc GenerateOptimizationTx (GenerateOptimizationTxRequest) returns (GenerateOptimizationTxResponse) {}
    rpc GenerateTransferCodeTx (GenerateTransferCodeTxRequest) returns (GenerateTransferCodeTxResponse) {}
    rpc SubmitTx (SubmitTxRequest) returns (SubmitTxResponse) {}

    // Databases
    rpc GetLedgerInfo (google.protobuf.Empty) returns (GetLedgerInfoResponse) {}
    rpc GetBlockInfo (GetBlockInfoRequest) returns (GetBlockInfoResponse) {}
    rpc GetBlock (GetBlockRequest) returns (GetBlockResponse) {}
    rpc GetTxStatusAsSender (GetTxStatusAsSenderRequest) returns (GetTxStatusAsSenderResponse) {}
    rpc GetTxStatusAsReceiver (GetTxStatusAsReceiverRequest) returns (GetTxStatusAsReceiverResponse) {}
    rpc GetProcessedBlock (GetProcessedBlockRequest) returns (GetProcessedBlockResponse) {}

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

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

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


// Possible transaction status values. Senders check with key images. 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;
}

// Structure used in specifying the list of outputs when generating a transaction.
message Outlay {
    uint64 value = 1;
    external.PublicAddress receiver = 2;
}

// 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 monitor id this UnspentTxOut belongs to.
    // Note that this field is not included in the Rust `utxo_store::UnspentTxOut` struct.
    bytes monitor_id = 10;
}

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

// 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 tx outs received in a given processed block.
message ProcessedTxOut {
    // The monitor id that received the transaction.
    bytes monitor_id = 1;

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

    // The public key of the received 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 this ProcessedTxOut was received at this block or spent at this block.
    ProcessedTxOutDirection direction = 6;
}

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

// 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.
message GetUnspentTxOutListRequest {
    bytes monitor_id = 1;
    uint64 subaddress_index = 2;
}
message GetUnspentTxOutListResponse {
    repeated UnspentTxOut output_list = 1;
}

//
// Utilities
//

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

// Generate an AccountKey from a 32 byte root entropy value.
message GetAccountKeyRequest {
    bytes entropy = 1;
}
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;
}

//
// b58 Codes
//

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

// Encode receiver's public address, value, and memo into a base-58 "MobileCoin Request Code".
message GetRequestCodeRequest {
    external.PublicAddress receiver = 1;
    uint64 value = 2;
    string memo = 3;
}
message GetRequestCodeResponse {
    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 ReadTransferCodeRequest {
    string b58_code = 1;
}
message ReadTransferCodeResponse {
    bytes entropy = 1;
    external.CompressedRistretto tx_public_key = 2;
    string memo = 3;
    UnspentTxOut utxo = 4;
}

// Encode entropy/tx_public_key/memo into a base-58 "MobileCoin Transfer Code".
message GetTransferCodeRequest {
    bytes entropy = 1;
    external.CompressedRistretto tx_public_key = 2;
    string memo = 3;
}
message GetTransferCodeResponse {
    string b58_code = 1;
}

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

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

//
// Transactions
//

// 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 hardcoded.
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 in 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;
}
message GenerateTxResponse {
    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;
}
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;
}
message GenerateTransferCodeTxResponse {
    // The tx proposal to submit to the network.
    TxProposal tx_proposal = 1;

    // The entropy for constructing the AccountKey that can access the funds.
    bytes 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;
}

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

// Get the status of a submitted transaction as the Sender (using the key image).
message GetTxStatusAsSenderRequest {
    SenderTxReceipt receipt = 1;
}
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;
}

//
// Convenience calls
///

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

    // Subaddress to query balance for.
    uint64 subaddress_index = 2;
}
message GetBalanceResponse {
    // Sum of all utxos associated with the requested monitor_id/subaddress_index.
    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 in 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 = 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;
}
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;
}

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