From 459aea803f6f13e4cf69a81566c22096331dd656 Mon Sep 17 00:00:00 2001 From: ghubstan <36207203+ghubstan@users.noreply.github.com> Date: Sat, 12 Feb 2022 16:57:11 -0300 Subject: [PATCH 1/4] Remove banner style comments from pb.proto The bisq-grpc-api-doc generator needs comments spefic to protobuf message definitions, not groups of message defs. This kind of information can be included in the message specific comments. Also changed some existing comments, and added others to suggest a commenting style for .proto message and field defs. --- proto/src/main/proto/pb.proto | 213 ++++++++++------------------------ 1 file changed, 61 insertions(+), 152 deletions(-) diff --git a/proto/src/main/proto/pb.proto b/proto/src/main/proto/pb.proto index f092d9d61c1..0dc10ca5b8c 100644 --- a/proto/src/main/proto/pb.proto +++ b/proto/src/main/proto/pb.proto @@ -1,18 +1,8 @@ syntax = "proto3"; package io.bisq.protobuffer; - -// -// Protobuffer v3 definitions of network messages and persisted objects. -// - - option java_package = "protobuf"; option java_multiple_files = true; -/////////////////////////////////////////////////////////////////////////////////////////// -// Network messages -/////////////////////////////////////////////////////////////////////////////////////////// -// Those are messages sent over wire message NetworkEnvelope { int32 message_version = 1; oneof message { @@ -94,16 +84,10 @@ message NetworkEnvelope { } } -/////////////////////////////////////////////////////////////////////////////////////////// -// Implementations of NetworkEnvelope -/////////////////////////////////////////////////////////////////////////////////////////// - message BundleOfEnvelopes { repeated NetworkEnvelope envelopes = 1; } -// get data - message PreliminaryGetDataRequest { int32 nonce = 21; // This was set to 21 instead of 1 in some old commit so we cannot change it. repeated bytes excluded_keys = 2; @@ -135,8 +119,6 @@ message FileTransferPart { bytes message_data = 6; } -// peers - message GetPeersRequest { NodeAddress sender_node_address = 1; int32 nonce = 2; @@ -159,8 +141,6 @@ message Pong { int32 request_nonce = 1; } -// Inventory - message GetInventoryRequest { string version = 1; } @@ -169,8 +149,6 @@ message GetInventoryResponse { map inventory = 1; } -// offer - message OfferAvailabilityRequest { string offer_id = 1; PubKeyRing pub_key_ring = 2; @@ -197,8 +175,6 @@ message RefreshOfferMessage { int32 sequence_number = 4; } -// storage - message AddDataMessage { StorageEntryWrapper entry = 1; } @@ -215,8 +191,6 @@ message AddPersistableNetworkPayloadMessage { PersistableNetworkPayload payload = 1; } -// misc - message CloseConnectionMessage { string reason = 1; } @@ -239,8 +213,6 @@ message PrefixedSealedAndSignedMessage { string uid = 4; } -// trade - message InputsForDepositTxRequest { string trade_id = 1; NodeAddress sender_node_address = 2; @@ -255,7 +227,8 @@ message InputsForDepositTxRequest { bytes taker_multi_sig_pub_key = 11; string taker_payout_address_string = 12; PubKeyRing taker_pub_key_ring = 13; - PaymentAccountPayload taker_payment_account_payload = 14; // Not used anymore from 1.7.0 but kept for backward compatibility + // Not used anymore from 1.7.0 but kept for backward compatibility. + PaymentAccountPayload taker_payment_account_payload = 14; string taker_account_id = 15; string taker_fee_tx_id = 16; repeated NodeAddress accepted_arbitrator_node_addresses = 17; @@ -273,7 +246,8 @@ message InputsForDepositTxRequest { message InputsForDepositTxResponse { string trade_id = 1; - PaymentAccountPayload maker_payment_account_payload = 2; // Not used anymore from 1.7.0 but kept for backward compatibility + // Not used anymore from 1.7.0 but kept for backward compatibility. + PaymentAccountPayload maker_payment_account_payload = 2; string maker_account_id = 3; string maker_contract_as_json = 4; string maker_contract_signature = 5; @@ -375,14 +349,14 @@ message MediatedPayoutTxSignatureMessage { NodeAddress sender_node_address = 4; } -// Deprecated since 1.4.0 +/* Deprecated since 1.4.0. */ message RefreshTradeStateRequest { string uid = 1 [deprecated = true]; string trade_id = 2 [deprecated = true]; NodeAddress sender_node_address = 3 [deprecated = true]; } -// Deprecated since 1.4.0 +/* Deprecated since 1.4.0. */ message TraderSignedWitnessMessage { string uid = 1 [deprecated = true]; string trade_id = 2 [deprecated = true]; @@ -390,7 +364,6 @@ message TraderSignedWitnessMessage { SignedWitness signed_witness = 4 [deprecated = true]; } -// BsqSwap message SellersBsqSwapRequest { string uid = 1; string trade_id = 2; @@ -447,8 +420,7 @@ message BsqSwapFinalizedTxMessage { bytes tx = 4; } -// dispute - +/* Dispute support types. */ enum SupportType { ARBITRATION = 0; MEDIATION = 1; @@ -510,8 +482,7 @@ message PrivateNotificationMessage { PrivateNotificationPayload private_notification_payload = 3; } -// DAO - +/* DAO blocks request. */ message GetBlocksRequest { int32 from_block_height = 1; int32 nonce = 2; @@ -519,14 +490,15 @@ message GetBlocksRequest { repeated int32 supported_capabilities = 4; } +/* DAO blocks response. */ message GetBlocksResponse { - // Because of the way how PB implements inheritance we need to use the super class as type + // Because of the way how PB implements inheritance we need to use the super class as type. repeated BaseBlock raw_blocks = 1; int32 request_nonce = 2; } message NewBlockBroadcastMessage { - // Because of the way how PB implements inheritance we need to use the super class as type + // Because of the way how PB implements inheritance we need to use the super class as type. BaseBlock raw_block = 1; } @@ -575,12 +547,6 @@ message GetBlindVoteStateHashesResponse { int32 request_nonce = 2; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Payload -/////////////////////////////////////////////////////////////////////////////////////////// - -// core - message NodeAddress { string host_name = 1; int32 port = 2; @@ -595,7 +561,7 @@ message Peer { message PubKeyRing { bytes signature_pub_key_bytes = 1; bytes encryption_pub_key_bytes = 2; - reserved 3; // WAS: string pgp_pub_key_as_pem = 3; + reserved 3; // Formerly: string pgp_pub_key_as_pem = 3; } message SealedAndSigned { @@ -605,8 +571,6 @@ message SealedAndSigned { bytes sig_public_key_bytes = 4; } -// storage - message StoragePayload { oneof message { Alert alert = 1; @@ -643,8 +607,6 @@ message ProtectedStorageEntry { int64 creation_time_stamp = 5; } -// mailbox - message StorageEntryWrapper { oneof message { ProtectedStorageEntry protected_storage_entry = 1; @@ -684,8 +646,6 @@ message DecryptedMessageWithPubKey { bytes signature_pub_key_bytes = 2; } -// misc - message PrivateNotificationPayload { string message = 1; string signature_as_base64 = 2; @@ -698,10 +658,6 @@ message PaymentAccountFilter { string value = 3; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Storage payload -/////////////////////////////////////////////////////////////////////////////////////////// - message Alert { string message = 1; string version = 2; @@ -788,7 +744,7 @@ message Filter { repeated int32 enabled_pow_versions = 35; } -// Deprecated +/* Deprecated */ message TradeStatistics2 { string base_currency = 1 [deprecated = true]; string counter_currency = 2 [deprecated = true]; @@ -840,8 +796,10 @@ message OfferPayload { int64 min_amount = 10; string base_currency_code = 11; string counter_currency_code = 12; - repeated NodeAddress arbitrator_node_addresses = 13 [deprecated = true]; // not used anymore but still required as old clients check for nonNull - repeated NodeAddress mediator_node_addresses = 14 [deprecated = true]; // not used anymore but still required as old clients check for nonNull + // Not used anymore but still required as old clients check for nonNull. + repeated NodeAddress arbitrator_node_addresses = 13 [deprecated = true]; + // Not used anymore but still required as old clients check for nonNull. + repeated NodeAddress mediator_node_addresses = 14 [deprecated = true]; string payment_method_id = 15; string maker_payment_account_id = 16; string offer_fee_payment_tx_id = 17; @@ -920,11 +878,6 @@ message SignedWitness { int64 trade_amount = 7; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Dispute payload -/////////////////////////////////////////////////////////////////////////////////////////// - - message Dispute { enum State { NEEDS_UPGRADE = 0; @@ -1022,10 +975,6 @@ message DisputeResult { PayoutSuggestion payout_suggestion = 17; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Trade payload -/////////////////////////////////////////////////////////////////////////////////////////// - message Contract { OfferPayload offer_payload = 1; int64 trade_amount = 2; @@ -1035,8 +984,10 @@ message Contract { bool is_buyer_maker_and_seller_taker = 6; string maker_account_id = 7; string taker_account_id = 8; - PaymentAccountPayload maker_payment_account_payload = 9; // Not used anymore from 1.7.0 but kept for backward compatibility - PaymentAccountPayload taker_payment_account_payload = 10; // Not used anymore from 1.7.0 but kept for backward compatibility + // Not used anymore from 1.7.0 but kept for backward compatibility. + PaymentAccountPayload maker_payment_account_payload = 9; + // Not used anymore from 1.7.0 but kept for backward compatibility. + PaymentAccountPayload taker_payment_account_payload = 10; PubKeyRing maker_pub_key_ring = 11; PubKeyRing taker_pub_key_ring = 12; NodeAddress buyer_node_address = 13; @@ -1078,15 +1029,11 @@ enum AvailabilityResult { PRICE_CHECK_FAILED = 13; } -/////////////////////////////////////////////////////////////////////////////////////////// -// PaymentAccount payload -/////////////////////////////////////////////////////////////////////////////////////////// - - message PaymentAccountPayload { string id = 1; string payment_method_id = 2; - int64 max_trade_period = 3 [deprecated = true]; // not used anymore but we need to keep it in PB for backward compatibility + // Not used anymore but we need to keep it in PB for backward compatibility. + int64 max_trade_period = 3 [deprecated = true]; oneof message { AliPayAccountPayload ali_pay_account_payload = 4; ChaseQuickPayAccountPayload chase_quick_pay_account_payload = 5; @@ -1295,7 +1242,7 @@ message InteracETransferAccountPayload { string answer = 4; } -// Deprecated, not used anymore +/* Deprecated, not used. */ message OKPayAccountPayload { string account_nr = 1; } @@ -1305,7 +1252,7 @@ message UpholdAccountPayload { string account_owner = 2; } -// Deprecated, not used anymore +/* Deprecated, not used. */ message CashAppAccountPayload { string cash_tag = 1; } @@ -1314,7 +1261,7 @@ message MoneyBeamAccountPayload { string account_id = 1; } -// Deprecated, not used anymore +/* Deprecated, not used. */ message VenmoAccountPayload { string venmo_user_name = 1; string holder_name = 2; @@ -1473,11 +1420,6 @@ message SwiftAccountPayload { string intermediary_address = 16; } -/////////////////////////////////////////////////////////////////////////////////////////// -// PersistableEnvelope -/////////////////////////////////////////////////////////////////////////////////////////// - -// Those are persisted to disc message PersistableEnvelope { oneof message { SequenceNumberMap sequence_number_map = 1; @@ -1487,20 +1429,24 @@ message PersistableEnvelope { NavigationPath navigation_path = 5; TradableList tradable_list = 6; - // TradeStatisticsList trade_statistics_list = 7; // Was used in pre v0.6.0 version. Not used anymore. + + // TradeStatisticsList trade_statistics_list = 7; Deprecated, Was used in pre v0.6.0 version. Not used anymore. + ArbitrationDisputeList arbitration_dispute_list = 8; PreferencesPayload preferences_payload = 9; UserPayload user_payload = 10; PaymentAccountList payment_account_list = 11; - // deprecated - // BsqState bsq_state = 12; // not used but as other non-dao data have a higher index number we leave it to make clear that we cannot change following indexes + // Deprecated. + // Not used but as other non-dao data have a higher index number we leave it to make clear that we + // cannot change following indexes. + // BsqState bsq_state = 12; AccountAgeWitnessStore account_age_witness_store = 13; TradeStatistics2Store trade_statistics2_store = 14 [deprecated = true]; - // PersistableNetworkPayloadList persistable_network_payload_list = 15; // long deprecated & migration away from it is already done + // PersistableNetworkPayloadList persistable_network_payload_list = 15; // long deprecated & migration away from it is already done. ProposalStore proposal_store = 16; TempProposalStore temp_proposal_store = 17; @@ -1509,7 +1455,9 @@ message PersistableEnvelope { BallotList ballot_list = 20; MyVoteList my_vote_list = 21; MyBlindVoteList my_blind_vote_list = 22; - // MeritList merit_list = 23; // was not used here, but its class used to implement PersistableEnvelope via its super + + // MeritList merit_list = 23; // was not used here, but its class used to implement PersistableEnvelope via its super. + DaoStateStore dao_state_store = 24; MyReputationList my_reputation_list = 25; MyProofOfBurnList my_proof_of_burn_list = 26; @@ -1525,10 +1473,6 @@ message PersistableEnvelope { } } -/////////////////////////////////////////////////////////////////////////////////////////// -// Collections -/////////////////////////////////////////////////////////////////////////////////////////// - message SequenceNumberMap { repeated SequenceNumberEntry sequence_number_entries = 1; } @@ -1547,12 +1491,12 @@ message MapValue { int64 time_stamp = 2; } -// deprecated. Not used anymore. +/* Deprecated. Not used anymore. */ message PersistedEntryMap { map persisted_entry_map = 1; } -// We use a list not a hash map to save disc space. The hash can be calculated from the payload anyway +/* We use a list not a hash map to save disc space. The hash can be calculated from the payload anyway. */ message AccountAgeWitnessStore { repeated AccountAgeWitness items = 1; } @@ -1561,8 +1505,9 @@ message SignedWitnessStore { repeated SignedWitness items = 1; } -// We use a list not a hash map to save disc space. The hash can be calculated from the payload anyway -// Deprecated +/* Deprecated. Not used anymore. +* We use a list not a hash map to save disc space. The hash can be calculated from the payload anyway. +*/ message TradeStatistics2Store { repeated TradeStatistics2 items = 1 [deprecated = true]; } @@ -1606,10 +1551,6 @@ message PaymentAccountList { repeated PaymentAccount payment_account = 1; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Offer/Trade -/////////////////////////////////////////////////////////////////////////////////////////// - message TradableList { repeated Tradable tradable = 1; } @@ -1713,9 +1654,12 @@ message Trade { enum DisputeState { PB_ERROR_DISPUTE_STATE = 0; NO_DISPUTE = 1; - DISPUTE_REQUESTED = 2; // arbitration We use the enum name for resolving enums so it cannot be renamed - DISPUTE_STARTED_BY_PEER = 3; // arbitration We use the enum name for resolving enums so it cannot be renamed - DISPUTE_CLOSED = 4; // arbitration We use the enum name for resolving enums so it cannot be renamed + // Arbitration requested. We use the enum name for resolving enums so it cannot be renamed. + DISPUTE_REQUESTED = 2; + // Arbitration requested. We use the enum name for resolving enums so it cannot be renamed. + DISPUTE_STARTED_BY_PEER = 3; + // Arbitration requested. We use the enum name for resolving enums so it cannot be renamed + DISPUTE_CLOSED = 4; MEDIATION_REQUESTED = 5; MEDIATION_STARTED_BY_PEER = 6; MEDIATION_CLOSED = 7; @@ -1833,8 +1777,8 @@ message ProcessModel { PubKeyRing pub_key_ring = 4; string take_offer_fee_tx_id = 5; bytes payout_tx_signature = 6; - reserved 7; // Not used anymore - reserved 8; // Not used anymore + reserved 7; // Not used anymore. + reserved 8; // Not used anymore. bytes prepared_deposit_tx = 9; repeated RawTransactionInput raw_transaction_inputs = 10; int64 change_output_value = 11; @@ -1890,11 +1834,6 @@ message BsqSwapTradePeer { bytes tx = 7; } - -/////////////////////////////////////////////////////////////////////////////////////////// -// Dispute -/////////////////////////////////////////////////////////////////////////////////////////// - message ArbitrationDisputeList { repeated Dispute dispute = 1; } @@ -1926,16 +1865,11 @@ enum MediationResultState { PAYOUT_TX_SEEN_IN_NETWORK = 15; } -//todo enum RefundResultState { PB_ERROR_REFUND_RESULT = 0; UNDEFINED_REFUND_RESULT = 1; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Preferences -/////////////////////////////////////////////////////////////////////////////////////////// - message PreferencesPayload { string user_language = 1; Country user_country = 2; @@ -1966,7 +1900,8 @@ message PreferencesPayload { string bitcoin_nodes = 27; repeated string ignore_traders_list = 28; string directory_chooser_path = 29; - int64 buyer_security_deposit_as_long = 30 [deprecated = true]; // Superseded by buyerSecurityDepositAsPercent + // Superseded by buyerSecurityDepositAsPercent. + int64 buyer_security_deposit_as_long = 30 [deprecated = true]; bool use_animations = 31; PaymentAccount selectedPayment_account_for_createOffer = 32; bool pay_fee_in_Btc = 33; @@ -2010,10 +1945,6 @@ message AutoConfirmSettings { string currency_code = 5; } -/////////////////////////////////////////////////////////////////////////////////////////// -// UserPayload -/////////////////////////////////////////////////////////////////////////////////////////// - message UserPayload { string account_id = 1; repeated PaymentAccount payment_accounts = 2; @@ -2033,12 +1964,6 @@ message UserPayload { map cookie = 16; } -/////////////////////////////////////////////////////////////////////////////////////////// -// DAO -/////////////////////////////////////////////////////////////////////////////////////////// - -// blockchain - message BaseBlock { int32 height = 1; int64 time = 2; @@ -2055,12 +1980,12 @@ message BsqBlockStore { } message RawBlock { - // Because of the way how PB implements inheritance we need to use the super class as type + // Because of the way how PB implements inheritance we need to use the super class as type. repeated BaseTx raw_txs = 1; } message Block { - // Because of the way how PB implements inheritance we need to use the super class as type + // Because of the way how PB implements inheritance we need to use the super class as type. repeated BaseTx txs = 1; } @@ -2078,12 +2003,12 @@ message BaseTx { } message RawTx { - // Because of the way how PB implements inheritance we need to use the super class as type + // Because of the way how PB implements inheritance we need to use the super class as type. repeated BaseTxOutput raw_tx_outputs = 1; } message Tx { - // Because of the way how PB implements inheritance we need to use the super class as type + // Because of the way how PB implements inheritance we need to use the super class as type. repeated BaseTxOutput tx_outputs = 1; TxType txType = 2; int64 burnt_bsq = 3; @@ -2195,8 +2120,6 @@ message PubKeyScript { string hex = 5; } -// dao data - message DaoPhase { int32 phase_ordinal = 1; int32 duration = 2; @@ -2209,10 +2132,10 @@ message Cycle { message DaoState { int32 chain_height = 1; - // Because of the way how PB implements inheritance we need to use the super class as type + // Because of the way how PB implements inheritance we need to use the super class as type. repeated BaseBlock blocks = 2; repeated Cycle cycles = 3; - // Because of the way how PB implements inheritance we need to use the super class as type + // Because of the way how PB implements inheritance we need to use the super class as type. map unspent_tx_output_map = 4; map issuance_map = 5; repeated string confiscated_lockup_tx_list = 6; @@ -2245,7 +2168,7 @@ message Proposal { GenericProposal generic_proposal = 11; RemoveAssetProposal remove_asset_proposal = 12; } - // We leave some index space here in case we add more subclasses + // We leave some index space here in case we add more subclasses. map extra_data = 20; } @@ -2260,7 +2183,7 @@ message ReimbursementProposal { } message ChangeParamProposal { - string param = 1; // name of enum + string param = 1; // Name of enum. string param_value = 2; } @@ -2285,7 +2208,7 @@ message Role { string uid = 1; string name = 2; string link = 3; - string bonded_role_type = 4; // name of BondedRoleType enum + string bonded_role_type = 4; // Name of BondedRoleType enum. } message MyReputation { @@ -2458,10 +2381,6 @@ message BlindVoteStateHash { int32 num_blind_votes = 4; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Misc -/////////////////////////////////////////////////////////////////////////////////////////// - message BlockChainExplorer { string name = 1; string tx_url = 2; @@ -2484,8 +2403,6 @@ message PaymentMethod { int64 max_trade_limit = 3; } -// Currency - message Currency { string currency_code = 1; } @@ -2518,10 +2435,6 @@ message Region { string name = 2; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Notifications -/////////////////////////////////////////////////////////////////////////////////////////// - message PriceAlertFilter { string currencyCode = 1; int64 high = 2; @@ -2535,10 +2448,6 @@ message MarketAlertFilter { repeated string alert_ids = 4; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Mock -/////////////////////////////////////////////////////////////////////////////////////////// - message MockMailboxPayload { string message = 1; NodeAddress sender_node_address = 2; From 62e5aaf4f88c6cd30de9c1ace2d070d1be14227d Mon Sep 17 00:00:00 2001 From: ghubstan <36207203+ghubstan@users.noreply.github.com> Date: Sat, 12 Feb 2022 17:03:35 -0300 Subject: [PATCH 2/4] Add license comment --- proto/src/main/proto/pb.proto | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/proto/src/main/proto/pb.proto b/proto/src/main/proto/pb.proto index 0dc10ca5b8c..8a63d6a1c10 100644 --- a/proto/src/main/proto/pb.proto +++ b/proto/src/main/proto/pb.proto @@ -1,3 +1,20 @@ +/* + * This file is part of Bisq. + * + * Bisq is free software: you can redistribute it and/or modify it + * under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or (at + * your option) any later version. + * + * Bisq is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public + * License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with Bisq. If not, see . + */ + syntax = "proto3"; package io.bisq.protobuffer; option java_package = "protobuf"; From 0fe850bf0ec9bacac5272e36edf557a67cad3e45 Mon Sep 17 00:00:00 2001 From: ghubstan <36207203+ghubstan@users.noreply.github.com> Date: Sat, 12 Feb 2022 17:52:03 -0300 Subject: [PATCH 3/4] Begin commenting grpc.proto for bisq-grpc-api-doc Banner comments were replace by simple service description comments. Rpc methods were commented, some field level comments were moved to to bisq-grpc-api-doc comment conventions. --- proto/src/main/proto/grpc.proto | 165 +++++++++++++++++++++----------- 1 file changed, 107 insertions(+), 58 deletions(-) diff --git a/proto/src/main/proto/grpc.proto b/proto/src/main/proto/grpc.proto index 0a0c4921f33..9a5e74ea98b 100644 --- a/proto/src/main/proto/grpc.proto +++ b/proto/src/main/proto/grpc.proto @@ -17,34 +17,39 @@ 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; } +/* +* This response has no parameters. (TODO automate generation of "This response has no parameters" comment.) +*/ message RegisterDisputeAgentReply { } -/////////////////////////////////////////////////////////////////////////////////////////// -// Help -/////////////////////////////////////////////////////////////////////////////////////////// +/* +* CLI command help service. +*/ service Help { + // Returns CLI command help in man page format. rpc GetMethodHelp (GetMethodHelpRequest) returns (GetMethodHelpReply) { } } @@ -53,40 +58,55 @@ message GetMethodHelpRequest { string methodName = 1; } +/* +* This response has no parameters. (TODO automate generation of "This response has no parameters" comment.) +*/ 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) { } } @@ -198,9 +218,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 { @@ -266,21 +286,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) { } } @@ -333,11 +358,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) { } } @@ -350,11 +375,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) { } } @@ -366,42 +391,53 @@ message GetTradeStatisticsReply { repeated TradeStatistics3 TradeStatistics = 1; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Shutdown -/////////////////////////////////////////////////////////////////////////////////////////// - +/* +* ShutdownServer service comment. +*/ service ShutdownServer { + // Shut down a local Bisq daemon. rpc Stop (StopRequest) returns (StopReply) { } } +/* +* This request has no parameters. (TODO automate generation of "This response has no parameters" comment.) +*/ 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) { } } @@ -483,7 +519,6 @@ message WithdrawFundsReply { } message TradeInfo { - // Bisq v1 trade protocol fields. OfferInfo offer = 1; string tradeId = 2; string shortId = 3; @@ -510,14 +545,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 { @@ -535,8 +565,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; @@ -559,10 +591,6 @@ message PaymentAccountPayloadInfo { string address = 3; } -/////////////////////////////////////////////////////////////////////////////////////////// -// Transactions -/////////////////////////////////////////////////////////////////////////////////////////// - message TxFeeRateInfo { bool useCustomTxFeeRate = 1; uint64 customTxFeeRate = 2; @@ -581,39 +609,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) { } } @@ -671,6 +716,9 @@ message VerifyBsqSentToAddressReply { bool isAmountReceived = 1; } +/* +* This request has no parameters. (TODO automate generation of "This response has no parameters" comment.) +*/ message GetTxFeeRateRequest { } @@ -737,10 +785,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; } @@ -768,11 +817,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) { } } From bcfb1cbf87349e5849364923147e2b28942d3989 Mon Sep 17 00:00:00 2001 From: ghubstan <36207203+ghubstan@users.noreply.github.com> Date: Sun, 13 Feb 2022 17:57:53 -0300 Subject: [PATCH 4/4] Remove "has no parameters" comments from grpc.proto --- proto/src/main/proto/grpc.proto | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/proto/src/main/proto/grpc.proto b/proto/src/main/proto/grpc.proto index 9a5e74ea98b..b5530a890a2 100644 --- a/proto/src/main/proto/grpc.proto +++ b/proto/src/main/proto/grpc.proto @@ -38,9 +38,6 @@ message RegisterDisputeAgentRequest { string registrationKey = 2; } -/* -* This response has no parameters. (TODO automate generation of "This response has no parameters" comment.) -*/ message RegisterDisputeAgentReply { } @@ -58,9 +55,6 @@ message GetMethodHelpRequest { string methodName = 1; } -/* -* This response has no parameters. (TODO automate generation of "This response has no parameters" comment.) -*/ message GetMethodHelpReply { string methodHelp = 1; } @@ -400,9 +394,6 @@ service ShutdownServer { } } -/* -* This request has no parameters. (TODO automate generation of "This response has no parameters" comment.) -*/ message StopRequest { } @@ -716,9 +707,6 @@ message VerifyBsqSentToAddressReply { bool isAmountReceived = 1; } -/* -* This request has no parameters. (TODO automate generation of "This response has no parameters" comment.) -*/ message GetTxFeeRateRequest { }