This protobuf definition and service stub has been in place since
the start of work on the API, but was never fully implmented, nor
intended to be included in the API beta & v1 releases.
Its presence added a useless section to the gRPC API Reference doc.
https://ghubstan.github.io/slate
Based on branch `7-more-grpcproto-comments`,
PR https://github.com/bisq-network/bisq/pull/6068.
We will consider each problematic number field one at a time.
Note: changing field types in following commits will break
the API's backward compatibility, but devs agree it's OK since
it is still in beta.
This commit adds comments to grpc.proto to be pulled into a new API
reference doc. Some of the comments highlight issues to be resolved
in following PRs.
The main focus is on documenting gRPC Offers service definitions in
grpc.proto:
- Comment each field in the Offers service's messages.
- Add TODO comments about fixing field defs with usability &
consistency problems.
Other API reference doc related changes to grpc.proto:
- Comment each gRPC service's rpc method definitions, however briefly.
- Improve some existing rpc method comments.
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.
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.
Prerequisite for next PR: Add API method 'gettrades'
The `gettrades` method will show 'open', 'closed', and 'failed' trades.
Users already needed to be able to fail and unfail trades for the
same reasons they do in the UI. API test cases will need to be able to
fail and unfail trades to check correct behavior of 'gettrades' method.
Based on branch `rename-keepfunds2closetrade`.
Trade proceeds and deposits have already been transfered to Bisq wallets
before the `keepfunds` command is (was) executed; `keepfunds` merely moves
open trades to closed trades lists and persistence files. Renaming `keepfunds`
as `closetrade` makes its purpose clear to API users.
The commit modifies only method names and comments in api server+cli classes,
apitest cases, and api trade simulation scripts.
Based on `master`
The method 'getoffer' should support looking up a user's open-offers, and other users' available offers.
- Adjust api-beta-test-guide.md to use only 'getoffer'.
- Adjust trade simulation scripts to use only 'getoffer'.
- Adjust api testcases to use 'getoffer' in place of 'getmyoffer'.
- Mark appropriate methods and protobuf msgs as deprecated.
Avoid repurposing the 'ProofOfWork.payload' field for Equihash puzzle
solutions, as that may be of later use in interactive PoW schemes such
as P2P network DoS protection (where the challenge may be a random nonce
instead of derived from the offer ID). Instead, make the payload the
UTF-8 bytes of the offer ID, just as with Hashcash.
Also, make the puzzle seed the SHA-256 hash of the payload concatenated
with the challenge, instead of just the 256-bit challenge on its own, so
that the PoW is tied to a particular payload and cannot be reused for
other payloads in the case of future randomly chosen challenges.
1. Reorder the PoW fields in the 'Filter' proto by field index, instead
of contextually.
2. Deduplicate expression for 'pow' & replace if-block with boolean op
to simplify 'FilterManager::isProofOfWorkValid'.
3. Avoid slightly confusing use of null char as a separator to prevent
hashing collisions in 'EquihashProofOfWorkService::getChallenge'. Use
comma separator and escape the 'itemId' & 'ownerId' arguments instead.
(based on PR #5858 review comments)
There are some use cases where the CLI needs to know what kind of offer
is being acted on before the request is made, For example:
There are differences between a BsqSwap 'takeoffer'request, and a v1
'takeoffer' request.
A BsqSwap offer cannot be edited by an 'editoffer' request, and an
attempt should be blocked by the CLI.
- Append isMyOffer GetOfferCategoryRequest rpc msg def.
- Adjust daemon.grpc services for new boolean GetOfferCategoryRequest param.
- Adjust core.api for new boolean GetOfferCategoryRequest param.
- Add validation check in core.api EditOfferValidator to block attempt to
edit a BsqSwap offer.
- Refactor CoreOffersService get*offer(id) methods to optionally throw
excpetions.
Change the type of the 'difficulty' field in the Filter & ProofOfWork
proto objects from int32/bytes to double and make it use a linear scale,
in place of the original logarithmic scale which counts the (effective)
number of required zeros.
This allows fine-grained difficulty control for Equihash, though for
Hashcash it simply rounds up to the nearest power of 2 internally.
NOTE: This is a breaking change to PoW & filter serialisation (unlike
the earlier PR commits), as the proto field version nums aren't updated.
Add a numeric version field to the 'ProofOfWork' protobuf object, along
with a list of allowed version numbers, 'enabled_pow_versions', to the
filter. The versions are taken to be in order of preference from most to
least preferred when creating a PoW, with an empty list signifying use
of the default algorithm only (that is, version 0: Hashcash).
An explicit list is used instead of an upper & lower version bound, in
case a new PoW algorithm (or changed algorithm params) turns out to
provide worse resistance than an earlier version.
(The fields are unused for now, to be enabled in a later commit.)
- Made several adjustments to CLI's 'gettrade' output related code
so it can show single trade details for either Bisq v1 trades, or
BSQ swap trades.
- Did minor refactoring of API's core to retrieve # tx confirmations
for an addresses and transactions.
- Show # of tx confirmations in bsq swap trade detail.
This commit refactors the first cut of the BsqSwapTradeInfo and
TradeInfo gRPC proto defs and wrappers. The change avoids duplication
of fields between BsqSwapTradeInfo and TradeInfo, and adds a
bsqSwapTradeInfo field to the old TradeInfo proto & wrapper.
The immediate goal is moving towards getting the API's 'gettrade'
method to work for both Bisq v1 trades and BSQ swap trades: the TradeInfo
proto sent to the CLI should represent either a Bisq v1 trade or a BSQ
swap trade. A mid-term term goal is to also make a new 'gettrades' method
return a List<TradeInfo> to the CLI, where items in the List<TradeInfo>
can be either v1 trades or bsq-swap trades.
- Adjust GetBsqSwapOffer(s) rpc services to remove currency param.
- Adjust OfferInfo and remove BsqSwapOfferInfo.
- Add GetOfferCategory service so CLI can determine what kind of takeoffer service is to be used.
- Add comment about adding sub-message BsqSwapTradeInfo field to TradeInfo.
