Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modify .proto file comments to be parsed by bisq-grpc-api-doc [#1] #6042

Merged
merged 4 commits into from
Feb 14, 2022
Merged

Modify .proto file comments to be parsed by bisq-grpc-api-doc [#1] #6042

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
459aea8
Remove banner style comments from pb.proto
ghubstan Feb 12, 2022
62e5aaf
Add license comment
ghubstan Feb 12, 2022
0fe850b
Begin commenting grpc.proto for bisq-grpc-api-doc
ghubstan Feb 12, 2022
bcfb1cb
Remove "has no parameters" comments from grpc.proto
ghubstan Feb 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 95 additions & 58 deletions proto/src/main/proto/grpc.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,22 @@

syntax = "proto3";
package io.bisq.protobuffer;

import "pb.proto";

option java_package = "bisq.proto.grpc";
option java_multiple_files = true;

///////////////////////////////////////////////////////////////////////////////////////////
// DisputeAgents
///////////////////////////////////////////////////////////////////////////////////////////

/*
* DisputeAgents service is provided for development, and can only be used when running in regtest mode.
*/
service DisputeAgents {
// Register regtest / dev mode dispute agents. Does not work if running on mainnet.
rpc RegisterDisputeAgent (RegisterDisputeAgentRequest) returns (RegisterDisputeAgentReply) {
}
}

/*
* Register a dispute agent using a registration key.
*/
message RegisterDisputeAgentRequest {
string disputeAgentType = 1;
string registrationKey = 2;
Expand All @@ -40,11 +41,12 @@ message RegisterDisputeAgentRequest {
message RegisterDisputeAgentReply {
}

///////////////////////////////////////////////////////////////////////////////////////////
// Help
///////////////////////////////////////////////////////////////////////////////////////////

/*
* CLI command help service.
*/
service Help {
// Returns CLI command help in man page format.
rpc GetMethodHelp (GetMethodHelpRequest) returns (GetMethodHelpReply) {
}
}
Expand All @@ -57,36 +59,48 @@ message GetMethodHelpReply {
string methodHelp = 1;
}

///////////////////////////////////////////////////////////////////////////////////////////
// Offers
///////////////////////////////////////////////////////////////////////////////////////////

/*
* Offers service provides rpc methods for creating, editing, listing, and cancelling Bisq offers.
*/
service Offers {
// Get offer category, one of FIAT, ALTCOIN, or BSQ_SWAP.
rpc GetOfferCategory (GetOfferCategoryRequest) returns (GetOfferCategoryReply) {
}
// Get available BSQ swap offer with offer-id.
rpc GetBsqSwapOffer (GetOfferRequest) returns (GetBsqSwapOfferReply) {
}
// Get version 1 protocol offer with offer-id.
rpc GetOffer (GetOfferRequest) returns (GetOfferReply) {
}
// Get my BSQ swap offer with offer-id.
rpc GetMyBsqSwapOffer (GetMyOfferRequest) returns (GetMyBsqSwapOfferReply) {
}
// @Deprecated since 27-Dec-2021 (v1.8.0)
// Get my open version 1 protocol offer with offer-id. Deprecated since 27-Dec-2021 (v1.8.0).
rpc GetMyOffer (GetMyOfferRequest) returns (GetMyOfferReply) {
}
// Get available BSQ swap offers with direction BUY or SELL.
rpc GetBsqSwapOffers (GetBsqSwapOffersRequest) returns (GetBsqSwapOffersReply) {
}
// Get available version 1 protocol offers with direction BUY or SELL.
rpc GetOffers (GetOffersRequest) returns (GetOffersReply) {
}
// Get my BSQ swap offers with direction BUY or SELL.
rpc GetMyBsqSwapOffers (GetBsqSwapOffersRequest) returns (GetMyBsqSwapOffersReply) {
}
// Get my open version 1 protocol offers with direction BUY or SELL.
rpc GetMyOffers (GetMyOffersRequest) returns (GetMyOffersReply) {
}
// Create a BSQ swap offer.
rpc CreateBsqSwapOffer (CreateBsqSwapOfferRequest) returns (CreateBsqSwapOfferReply) {
}
// Create a version 1 protocol offer.
rpc CreateOffer (CreateOfferRequest) returns (CreateOfferReply) {
}
// Edit an open offer.
rpc EditOffer (EditOfferRequest) returns (EditOfferReply) {
}
// Cancel (remove) an open offer.
rpc CancelOffer (CancelOfferRequest) returns (CancelOfferReply) {
}
}
Expand Down Expand Up @@ -198,9 +212,9 @@ message EditOfferRequest {
double marketPriceMargin = 4;
uint64 triggerPrice = 5;
// Send a signed int, not a bool (with default=false).
// -1 = do not change activation state
// 0 = disable
// 1 = enable
// -1 = do not change activation state
// 0 = disable
// 1 = enable
sint32 enable = 6;
// The EditType constricts what offer details can be modified and simplifies param validation.
enum EditType {
Expand Down Expand Up @@ -266,21 +280,26 @@ message AvailabilityResultWithDescription {
string description = 2;
}

///////////////////////////////////////////////////////////////////////////////////////////
// PaymentAccounts
///////////////////////////////////////////////////////////////////////////////////////////

/*
* 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.
rpc CreatePaymentAccount (CreatePaymentAccountRequest) returns (CreatePaymentAccountReply) {
}
// Get list of all saved fiat payment accounts.
rpc GetPaymentAccounts (GetPaymentAccountsRequest) returns (GetPaymentAccountsReply) {
}
// Get list of all supported Bisq payment methods.
rpc GetPaymentMethods (GetPaymentMethodsRequest) returns (GetPaymentMethodsReply) {
}
// Get a json template file for a supported Bisq payment method.
rpc GetPaymentAccountForm (GetPaymentAccountFormRequest) returns (GetPaymentAccountFormReply) {
}
// Create a crypto currency (altcoin) payment account.
rpc CreateCryptoCurrencyPaymentAccount (CreateCryptoCurrencyPaymentAccountRequest) returns (CreateCryptoCurrencyPaymentAccountReply) {
}
// Get list of all supported Bisq crypto currency (altcoin) payment methods.
rpc GetCryptoCurrencyPaymentMethods (GetCryptoCurrencyPaymentMethodsRequest) returns (GetCryptoCurrencyPaymentMethodsReply) {
}
}
Expand Down Expand Up @@ -333,11 +352,11 @@ message GetCryptoCurrencyPaymentMethodsReply {
repeated PaymentMethod paymentMethods = 1;
}

///////////////////////////////////////////////////////////////////////////////////////////
// Price
///////////////////////////////////////////////////////////////////////////////////////////

/*
* Price service comment.
*/
service Price {
// Get current market price for a crypto currency.
rpc GetMarketPrice (MarketPriceRequest) returns (MarketPriceReply) {
}
}
Expand All @@ -350,11 +369,11 @@ message MarketPriceReply {
double price = 1;
}

///////////////////////////////////////////////////////////////////////////////////////////
// GetTradeStatistics
///////////////////////////////////////////////////////////////////////////////////////////

/*
* GetTradeStatistics service is not implemented. It's stub will be remove from the gRPC daemon.
*/
service GetTradeStatistics {
// Not implemented.
rpc GetTradeStatistics (GetTradeStatisticsRequest) returns (GetTradeStatisticsReply) {
}
}
Expand All @@ -366,11 +385,11 @@ message GetTradeStatisticsReply {
repeated TradeStatistics3 TradeStatistics = 1;
}

///////////////////////////////////////////////////////////////////////////////////////////
// Shutdown
///////////////////////////////////////////////////////////////////////////////////////////

/*
* ShutdownServer service comment.
*/
service ShutdownServer {
// Shut down a local Bisq daemon.
rpc Stop (StopRequest) returns (StopReply) {
}
}
Expand All @@ -381,27 +400,35 @@ message StopRequest {
message StopReply {
}

///////////////////////////////////////////////////////////////////////////////////////////
// Trades
///////////////////////////////////////////////////////////////////////////////////////////

/*
* Trades service provides rpc methods for taking, executing, and listing trades.
*/
service Trades {
// Get an open trade with a trade-id.
rpc GetTrade (GetTradeRequest) returns (GetTradeReply) {
}
// Get all open or historical trades.
rpc GetTrades (GetTradesRequest) returns (GetTradesReply) {
}
// Take an open offer.
rpc TakeOffer (TakeOfferRequest) returns (TakeOfferReply) {
}
// Send a 'payment started' message to a trading peer (seller).
rpc ConfirmPaymentStarted (ConfirmPaymentStartedRequest) returns (ConfirmPaymentStartedReply) {
}
// Send a 'payment received' message to a trading peer (buyer).
rpc ConfirmPaymentReceived (ConfirmPaymentReceivedRequest) returns (ConfirmPaymentReceivedReply) {
}
// Close a completed trade (moves it to trade history).
rpc CloseTrade (CloseTradeRequest) returns (CloseTradeReply) {
}
// Fail an open trade.
rpc FailTrade (FailTradeRequest) returns (FailTradeReply) {
}
// Unfail a failed trade.
rpc UnFailTrade (UnFailTradeRequest) returns (UnFailTradeReply) {
}
// Withdraw trade proceeds to an external bitcoin wallet address.
rpc WithdrawFunds (WithdrawFundsRequest) returns (WithdrawFundsReply) {
}
}
Expand Down Expand Up @@ -483,7 +510,6 @@ message WithdrawFundsReply {
}

message TradeInfo {
// Bisq v1 trade protocol fields.
OfferInfo offer = 1;
string tradeId = 2;
string shortId = 3;
Expand All @@ -510,14 +536,9 @@ message TradeInfo {
string contractAsJson = 24;
ContractInfo contract = 25;
uint64 tradeVolume = 26;

// Optional Bisq v2+ trade protocol fields.
BsqSwapTradeInfo bsqSwapTradeInfo = 28;

// Needed by open/closed/failed trade list items.
string closingStatus = 29;

// TODO? Field for displaying correct precision per coin type, e.g., int32 coinPrecision = 32;
}

message ContractInfo {
Expand All @@ -535,8 +556,10 @@ message ContractInfo {
uint64 lockTime = 12;
}

/*
* BSQ Swap protocol specific fields not common to Bisq v1 trade protocol fields.
*/
message BsqSwapTradeInfo {
// BSQ Swap protocol specific fields not common to Bisq v1 trade protocol fields.
string txId = 1;
uint64 bsqTradeAmount = 2;
uint64 btcTradeAmount = 3;
Expand All @@ -559,10 +582,6 @@ message PaymentAccountPayloadInfo {
string address = 3;
}

///////////////////////////////////////////////////////////////////////////////////////////
// Transactions
///////////////////////////////////////////////////////////////////////////////////////////

message TxFeeRateInfo {
bool useCustomTxFeeRate = 1;
uint64 customTxFeeRate = 2;
Expand All @@ -581,39 +600,56 @@ message TxInfo {
string memo = 7;
}

///////////////////////////////////////////////////////////////////////////////////////////
// Wallets
///////////////////////////////////////////////////////////////////////////////////////////

/*
* Wallets service provides rpc methods for basic wallet operations such as checking balances,
* sending BTC or BSQ to external wallets, checking transaction fee rates, setting or unsetting
* an encryption password on a a wallet, and unlocking / locking an encrypted wallet.
*/
service Wallets {
// Get current BSQ and BTC balances.
rpc GetBalances (GetBalancesRequest) returns (GetBalancesReply) {
}
// Get BTC balance for a wallet address.
rpc GetAddressBalance (GetAddressBalanceRequest) returns (GetAddressBalanceReply) {
}
// Get an unused BSQ wallet address.
rpc GetUnusedBsqAddress (GetUnusedBsqAddressRequest) returns (GetUnusedBsqAddressReply) {
}
// Send BSQ to an address.
rpc SendBsq (SendBsqRequest) returns (SendBsqReply) {
}
// Send BSQ to an address.
rpc SendBtc (SendBtcRequest) returns (SendBtcReply) {
}
// Verify a specific amount of BSQ was received by a BSQ wallet address. (TODO change method name?)
rpc VerifyBsqSentToAddress (VerifyBsqSentToAddressRequest) returns (VerifyBsqSentToAddressReply) {
}
// Get most recently available BTC network tx fee, or custom fee rate if set.
rpc GetTxFeeRate (GetTxFeeRateRequest) returns (GetTxFeeRateReply) {
}
// Set custom tx fee rate.
rpc SetTxFeeRatePreference (SetTxFeeRatePreferenceRequest) returns (SetTxFeeRatePreferenceReply) {
}
// Remove custom tx fee rate, revert to using BTC network tx fee rate.
rpc UnsetTxFeeRatePreference (UnsetTxFeeRatePreferenceRequest) returns (UnsetTxFeeRatePreferenceReply) {
}
// Get a BTC tx with a transaction-id.
rpc GetTransaction (GetTransactionRequest) returns (GetTransactionReply) {
}
// Get all BTC receiving address in the wallet.
rpc GetFundingAddresses (GetFundingAddressesRequest) returns (GetFundingAddressesReply) {
}
// Set wallet encryption password.
rpc SetWalletPassword (SetWalletPasswordRequest) returns (SetWalletPasswordReply) {
}
// Remove wallet encryption password.
rpc RemoveWalletPassword (RemoveWalletPasswordRequest) returns (RemoveWalletPasswordReply) {
}
// Lock unlocked, encrypted wallet.
rpc LockWallet (LockWalletRequest) returns (LockWalletReply) {
}
// Unlock encrypted wallet before executing wallet sensitive methods:
// createoffer, takeoffer, getbalances, etc.
rpc UnlockWallet (UnlockWalletRequest) returns (UnlockWalletReply) {
}
}
Expand Down Expand Up @@ -737,10 +773,11 @@ message UnlockWalletRequest {
message UnlockWalletReply {
}

/* Field names are shortened for readability's sake, i.e.,
* balancesInfo.getBtc().getAvailableBalance() is cleaner than
* balancesInfo.getBtcBalanceInfo().getAvailableBalance().
*/
message BalancesInfo {
// Field names are shortened for readability's sake, i.e.,
// balancesInfo.getBtc().getAvailableBalance() is cleaner than
// balancesInfo.getBtcBalanceInfo().getAvailableBalance().
BsqBalanceInfo bsq = 1;
BtcBalanceInfo btc = 2;
}
Expand Down Expand Up @@ -768,11 +805,11 @@ message AddressBalanceInfo {
bool isAddressUnused = 4;
}

///////////////////////////////////////////////////////////////////////////////////////////
// Version
///////////////////////////////////////////////////////////////////////////////////////////

/*
* GetVersion service provides the local Bisq daemon's version.
*/
service GetVersion {
// Get current Bisq version number.
rpc GetVersion (GetVersionRequest) returns (GetVersionReply) {
}
}
Expand Down
Loading