diff --git a/proto/src/main/proto/grpc.proto b/proto/src/main/proto/grpc.proto index 6267201930..ea4b2a99ee 100644 --- a/proto/src/main/proto/grpc.proto +++ b/proto/src/main/proto/grpc.proto @@ -47,11 +47,11 @@ service Help { } message GetMethodHelpRequest { - string methodName = 1; // CLI command name. + string methodName = 1; // The CLI command name. } message GetMethodHelpReply { - string methodHelp = 1; // Man page for CLI command. + string methodHelp = 1; // The man page for the CLI command. } /* @@ -96,7 +96,7 @@ service Offers { // Edit an open offer. rpc EditOffer (EditOfferRequest) returns (EditOfferReply) { } - // Cancel (remove) an open offer. + // Cancel an open offer; remove it from the offer book. rpc CancelOffer (CancelOfferRequest) returns (CancelOfferReply) { } } @@ -108,10 +108,10 @@ message GetOfferCategoryRequest { message GetOfferCategoryReply { enum OfferCategory { - UNKNOWN = 0; - FIAT = 1; - ALTCOIN = 2; - BSQ_SWAP = 3; + UNKNOWN = 0; // An invalid offer category probably indicates a software bug. + FIAT = 1; // Indicates offer is to BUY or SELL BTC with a fiat currency. + ALTCOIN = 2; // Indicates offer is to BUY or SELL BTC with an altcoin. + BSQ_SWAP = 3; // Indicates offer is to swap BTC for BSQ. } OfferCategory offerCategory = 1; } @@ -361,7 +361,7 @@ message AvailabilityResultWithDescription { * The PaymentAccounts service provides rpc methods for creating fiat and crypto currency payment accounts. */ service PaymentAccounts { - // Create a fiat payment account, providing details in a json form. + // Create a fiat payment account, providing details in a json form generated by rpc method GetPaymentAccountForm. rpc CreatePaymentAccount (CreatePaymentAccountRequest) returns (CreatePaymentAccountReply) { } // Get list of all saved fiat payment accounts. @@ -370,7 +370,7 @@ service PaymentAccounts { // Get list of all supported Bisq payment methods. rpc GetPaymentMethods (GetPaymentMethodsRequest) returns (GetPaymentMethodsReply) { } - // Get a json template file for a supported Bisq payment method. + // Get a json template file for a supported Bisq payment method. Fill in the form and call rpc method CreatePaymentAccount. rpc GetPaymentAccountForm (GetPaymentAccountFormRequest) returns (GetPaymentAccountFormReply) { } // Create a crypto currency (altcoin) payment account. @@ -382,51 +382,52 @@ service PaymentAccounts { } message CreatePaymentAccountRequest { - string paymentAccountForm = 1; + string paymentAccountForm = 1; // File path of filled json payment account form. } message CreatePaymentAccountReply { - PaymentAccount paymentAccount = 1; + PaymentAccount paymentAccount = 1; // The new payment account. } message GetPaymentAccountsRequest { } message GetPaymentAccountsReply { - repeated PaymentAccount paymentAccounts = 1; + repeated PaymentAccount paymentAccounts = 1; // All user's saved payment accounts. } message GetPaymentMethodsRequest { } message GetPaymentMethodsReply { - repeated PaymentMethod paymentMethods = 1; + repeated PaymentMethod paymentMethods = 1; // Ids of all supported Bisq fiat payment methods. } message GetPaymentAccountFormRequest { - string paymentMethodId = 1; + string paymentMethodId = 1; // Payment method id determining content of the requested payment account form. } message GetPaymentAccountFormReply { + // An empty payment account json form to be filled out and passed to rpc method CreatePaymentAccount. string paymentAccountFormJson = 1; } message CreateCryptoCurrencyPaymentAccountRequest { - string accountName = 1; - string currencyCode = 2; - string address = 3; - bool tradeInstant = 4; + string accountName = 1; // The name of the altcoin payment account. Uniqueness is not enforced. + string currencyCode = 2; // The altcoin currency code. + string address = 3; // The altcoin receiving address. + bool tradeInstant = 4; // Whether the altcoin payment account is an instant account or not. } message CreateCryptoCurrencyPaymentAccountReply { - PaymentAccount paymentAccount = 1; + PaymentAccount paymentAccount = 1; // The new altcoin payment account. } message GetCryptoCurrencyPaymentMethodsRequest { } message GetCryptoCurrencyPaymentMethodsReply { - repeated PaymentMethod paymentMethods = 1; + repeated PaymentMethod paymentMethods = 1; // Ids of all supported Bisq altcoin payment methods. } service Price { @@ -436,11 +437,11 @@ service Price { } message MarketPriceRequest { - string currencyCode = 1; + string currencyCode = 1; // The three letter currency code. } message MarketPriceReply { - double price = 1; + double price = 1; // The most recently available market price. } /* @@ -476,22 +477,22 @@ message StopReply { * The Trades service provides rpc methods for taking, executing, and listing trades. */ service Trades { - // Get an open trade with a trade-id. + // Get a currently open trade. rpc GetTrade (GetTradeRequest) returns (GetTradeReply) { } - // Get all open or historical trades. + // Get currently open, or historical trades (closed or failed). rpc GetTrades (GetTradesRequest) returns (GetTradesReply) { } // Take an open offer. rpc TakeOffer (TakeOfferRequest) returns (TakeOfferReply) { } - // Send a 'payment started' message to a trading peer (seller). + // Send a 'payment started' message to a trading peer (the BTC seller). rpc ConfirmPaymentStarted (ConfirmPaymentStartedRequest) returns (ConfirmPaymentStartedReply) { } - // Send a 'payment received' message to a trading peer (buyer). + // Send a 'payment received' message to a trading peer (the BTC buyer). rpc ConfirmPaymentReceived (ConfirmPaymentReceivedRequest) returns (ConfirmPaymentReceivedReply) { } - // Close a completed trade (moves it to trade history). + // Close a completed trade; move it to trade history. rpc CloseTrade (CloseTradeRequest) returns (CloseTradeReply) { } // Fail an open trade. @@ -506,173 +507,204 @@ service Trades { } message TakeOfferRequest { - string offerId = 1; - string paymentAccountId = 2; - string takerFeeCurrencyCode = 3; + string offerId = 1; // The unique identifier of the offer being taken. + string paymentAccountId = 2; // The unique identifier of the payment account used to take offer.. + string takerFeeCurrencyCode = 3; // The code of the currency (BSQ or BTC) used to pay the taker's Bisq trade fee. } message TakeOfferReply { - TradeInfo trade = 1; - AvailabilityResultWithDescription failureReason = 2; + TradeInfo trade = 1; // The new trade. + AvailabilityResultWithDescription failureReason = 2; // The reason the offer could not be taken. } message ConfirmPaymentStartedRequest { - string tradeId = 1; + string tradeId = 1; // The unique identifier of the open trade. } message ConfirmPaymentStartedReply { } message ConfirmPaymentReceivedRequest { - string tradeId = 1; + string tradeId = 1; // The unique identifier of the open trade. } message ConfirmPaymentReceivedReply { } message GetTradeRequest { - string tradeId = 1; + string tradeId = 1; // The unique identifier of the trade. } message GetTradeReply { - TradeInfo trade = 1; + TradeInfo trade = 1; // The unique identifier of the trade. } message GetTradesRequest { + // Rpc method GetTrades parameter determining what category of trade list is is being requested. enum Category { - OPEN = 0; - CLOSED = 1; - FAILED = 2; + OPEN = 0; // Get all currently open trades. + CLOSED = 1; // Get all completed trades. + FAILED = 2; // Get all failed trades. } Category category = 1; } message GetTradesReply { - repeated TradeInfo trades = 1; + repeated TradeInfo trades = 1; // All trades for GetTradesRequest.Category. } message CloseTradeRequest { - string tradeId = 1; + string tradeId = 1; // The unique identifier of the trade. } message CloseTradeReply { } message FailTradeRequest { - string tradeId = 1; + string tradeId = 1; // The unique identifier of the trade. } message FailTradeReply { } message UnFailTradeRequest { - string tradeId = 1; + string tradeId = 1; // The unique identifier of the trade. } message UnFailTradeReply { } message WithdrawFundsRequest { - string tradeId = 1; - string address = 2; - string memo = 3; + string tradeId = 1; // The unique identifier of the trade. + string address = 2; // The receiver's bitcoin wallet address. + string memo = 3; // An optional memo saved with the sent btc transaction. } message WithdrawFundsReply { } message TradeInfo { + // The original offer. OfferInfo offer = 1; + // The unique identifier of the trade. string tradeId = 2; + // An abbreviation of unique identifier of the trade. It cannot be used as parameter to rpc methods GetTrade, + // ConfirmPaymentStarted, CloseTrade, etc., but it may be useful while interacting with support or trading peers. string shortId = 3; + // The creation date of the trade as a long: the number of milliseconds that have elapsed since January 1, 1970. uint64 date = 4; + // A brief description of the user's role in the trade, i.e., an offer maker or taker, a BTC buyer or seller. string role = 5; + // Whether the offer taker's Bisq trade fee was paid in BTC or not (BSQ). bool isCurrencyForTakerFeeBtc = 6; + // The bitcoin miner transaction fee in satoshis. uint64 txFeeAsLong = 7; + // The offer taker's Bisq trade fee in satoshis. uint64 takerFeeAsLong = 8; + // The bitcoin transaction id for offer taker's Bisq trade fee. string takerFeeTxId = 9; + // The bitcoin transaction id for the offer taker's security deposit. string depositTxId = 10; + // The bitcoin transaction id for trade payout. string payoutTxId = 11; + // The trade payout amount in satoshis. uint64 tradeAmountAsLong = 12; // For fiat trades: the fiat price for 1 BTC to 4 decimal places, e.g., 41000.50 EUR is "41000.5000". // For altcoin trades: the altcoin price for 1 BTC to 8 decimal places, e.g., 0.5 BTC is "0.50000000". string tradePrice = 13; + // The trading peer's node address. string tradingPeerNodeAddress = 14; + // The internal state of the trade. (TODO Needs more explanation.) string state = 15; + // The internal phase of the trade. (TODO Needs more explanation.) string phase = 16; + // How much of the trade protocol's time limit has elapsed. (TODO Needs more explanation.) string tradePeriodState = 17; + // Whether the trade's security deposit bitcoin transaction has been broadcast, or not. bool isDepositPublished = 18; + // Whether the trade's security deposit bitcoin transaction has been confirmed at least once, or not. bool isDepositConfirmed = 19; + // Whether the trade's 'start payment' message has been sent by the BTC buyer, or not. + // (TODO Rename field to isPaymentSent because payment could be made in altcoin.) bool isFiatSent = 20; + // Whether the trade's 'payment received' message has been sent by the BTC seller, or not. + // (TODO Rename field to isPaymentReceived because payment could be made in altcoin.) bool isFiatReceived = 21; + // Whether the trade's payout bitcoin transaction has been confirmed at least once, or not. bool isPayoutPublished = 22; + // Whether the trade's payout has been completed and the trade is now closed, or not. + // (TODO Rename field to isClosed, or isCompleted because payment could be made in altcoin.) bool isWithdrawn = 23; + // The entire trade contract as a json string. string contractAsJson = 24; + // The summary of the trade contract. ContractInfo contract = 25; // The volume of currency traded for BTC. string tradeVolume = 26; + // The details specific to the BSQ swap trade. If the trade is not a BSQ swap, this field should be ignored. BsqSwapTradeInfo bsqSwapTradeInfo = 28; // Needed by open/closed/failed trade list items. string closingStatus = 29; } message ContractInfo { - string buyerNodeAddress = 1; - string sellerNodeAddress = 2; - string mediatorNodeAddress = 3; - string refundAgentNodeAddress = 4; - bool isBuyerMakerAndSellerTaker = 5; - string makerAccountId = 6; - string takerAccountId = 7; - PaymentAccountPayloadInfo makerPaymentAccountPayload = 8; - PaymentAccountPayloadInfo takerPaymentAccountPayload = 9; - string makerPayoutAddressString = 10; - string takerPayoutAddressString = 11; - uint64 lockTime = 12; + string buyerNodeAddress = 1; // The BTC buyer peer's node address. + string sellerNodeAddress = 2; // The BTC seller peer's node address. + string mediatorNodeAddress = 3; // If the trade was disputed, the Bisq mediator's node address. + string refundAgentNodeAddress = 4; // If a trade refund was requested, the Bisq refund agent's node address. + bool isBuyerMakerAndSellerTaker = 5; // Whether the BTC buyer created the original offer, or not. + string makerAccountId = 6; // The offer maker's payment account id. + string takerAccountId = 7; // The offer taker's payment account id. + PaymentAccountPayloadInfo makerPaymentAccountPayload = 8; // A summary of the offer maker's payment account. + PaymentAccountPayloadInfo takerPaymentAccountPayload = 9; // A summary of the offer taker's payment account. + string makerPayoutAddressString = 10; // The offer maker's BTC payout address. + string takerPayoutAddressString = 11; // The offer taker's BTC payout address. + uint64 lockTime = 12; // TODO } /* * BSQ Swap protocol specific fields not common to Bisq v1 trade protocol fields. */ message BsqSwapTradeInfo { - string txId = 1; - uint64 bsqTradeAmount = 2; - uint64 btcTradeAmount = 3; - uint64 bsqMakerTradeFee = 4; - uint64 bsqTakerTradeFee = 5; - uint64 txFeePerVbyte = 6; - string makerBsqAddress = 7; - string makerBtcAddress = 8; - string takerBsqAddress = 9; - string takerBtcAddress = 10; - uint64 numConfirmations = 11; - string errorMessage = 12; - uint64 payout = 13; - uint64 swapPeerPayout = 14; + string txId = 1; // The BSQ swap's bitcoin transaction id. + uint64 bsqTradeAmount = 2; // The amount of BSQ swapped in satoshis. + uint64 btcTradeAmount = 3; // The amount of BTC swapped in satoshis. + uint64 bsqMakerTradeFee = 4; // The swap offer maker's BSQ trade fee. + uint64 bsqTakerTradeFee = 5; // The swap offer taker's BSQ trade fee. + uint64 txFeePerVbyte = 6; // The swap transaction's bitcoin transaction id. + string makerBsqAddress = 7; // The swap offer maker's BSQ wallet address. + string makerBtcAddress = 8; // The swap offer maker's BTC wallet address. + string takerBsqAddress = 9; // The swap offer taker's BSQ wallet address. + string takerBtcAddress = 10; // The swap offer taker's BTC wallet address. + uint64 numConfirmations = 11; // The confirmations count for the completed swap's bitcoin transaction. + string errorMessage = 12; // An explanation for a failure to complete the swap. + uint64 payout = 13; // The amount of the user's payout in satoshis. (TODO explanation about miner fee vs trade fee) + uint64 swapPeerPayout = 14; // The amount of the peer's payout in satoshis. (TODO explanation about miner fee vs trade fee) } message PaymentAccountPayloadInfo { - string id = 1; - string paymentMethodId = 2; - string address = 3; + string id = 1; // The unique identifier of the payment account. + string paymentMethodId = 2; // The unique identifier of the payment method. + string address = 3; // The optional altcoin wallet address associated with the (altcoin) payment account. } message TxFeeRateInfo { - bool useCustomTxFeeRate = 1; - uint64 customTxFeeRate = 2; - uint64 feeServiceRate = 3; + bool useCustomTxFeeRate = 1; // Whether the daemon's custom btc transaction fee rate preference is set, or not. + uint64 customTxFeeRate = 2; // The daemon's custom btc transaction fee rate preference, in sats/byte. + uint64 feeServiceRate = 3; // The Bisq network's most recently available btc transaction fee rate, in sats/byte. + // The date of the most recent Bisq network fee rate request as a long: the number of milliseconds that have elapsed since January 1, 1970. uint64 lastFeeServiceRequestTs = 4; - uint64 minFeeServiceRate = 5; + uint64 minFeeServiceRate = 5; // The Bisq network's minimum btc transaction fee rate, in sats/byte. } message TxInfo { - string txId = 1; - uint64 inputSum = 2; - uint64 outputSum = 3; - uint64 fee = 4; - int32 size = 5; - bool isPending = 6; - string memo = 7; + string txId = 1; // The bitcoin transaction id. + uint64 inputSum = 2; // The sum of the bitcoin transactions input values in satoshis. + uint64 outputSum = 3; // The sum of the bitcoin transactions output values in satoshis. + uint64 fee = 4; // The bitcoin transaction's miner fee in satoshis. + int32 size = 5; // The bitcoin transaction's size in bytes. + bool isPending = 6; // Whether the bitcoin transaction has been confirmed at least one time, or not. + string memo = 7; // An optional memo associated with the bitcoin transaction. } /*