[bisq-network/bisq] Api v1 Beta Test Guide (#5159)
m52go
notifications at github.com
Thu Feb 11 20:22:40 CET 2021
@m52go commented on this pull request.
Great overall -- most suggestions I made are minor items that I think would help clarity.
Just one minor point of confusion about where the payment account ID comes from, which I noted in a comment.
> +```
+
+If your bitcoin-core binaries are not statically linked to your BerkleyDB library, you can specify the path to it
+with the `–-berkeleyDbLibPath=<path>` option:
+```
+$ ./bisq-apitest --apiPassword=xyz
+ --supportingApps=bitcoind,seednode,arbdaemon,alicedaemon,bobdaemon
+ --shutdownAfterTests=false
+ --bitcoinPath=<bitcoin-core-home>/bin
+ --berkeleyDbLibPath=<lib-berkleydb-path>
+```
+
+Alternatively, you can specify any or all of these bisq-apitest options in a properties file located in
+`apitest/src/main/resources/apitest.properties`.
+
+In this example, a beta tester uses the `apitest.properties` below, instead of ./bisq-cli options.
```suggestion
In this example, a beta tester uses the `apitest.properties` below, instead of `./bisq-cli` options.
```
> +## Running Trade Simulation Script
+
+_Warning: again, it is assumed the beta tester has a reasonably fast machine, or the scripted wait times -- for
+the other side to perform his step in the protocol, and for btc block generation and asynchronous processing
+of new btc blocks by test daemons -- may not be long enough._
+
+### System Requirements
+
+Same as described at the top of this document, but your bitcoin-core’s `bitcoin-cli` binary must be in the system
+`PATH`. (The script generates regtest blocks with it.)
+
+### Description
+
+The regtest trade simulation script `apitest/scripts/trade-simulation.sh` is a useful introduction to the Bisq Api.
+The bash script’s output is intended to serve as a tutorial, showing how the CLI can be used to create payment
+accounts for Bob and Alice, create an offer, take the offer, and complete a trade protocol.
```suggestion
accounts for Bob and Alice, create an offer, take the offer, and complete a trade.
```
> +
+### Description
+
+The regtest trade simulation script `apitest/scripts/trade-simulation.sh` is a useful introduction to the Bisq Api.
+The bash script’s output is intended to serve as a tutorial, showing how the CLI can be used to create payment
+accounts for Bob and Alice, create an offer, take the offer, and complete a trade protocol.
+(The bash script itself is not intended to be as useful as the output.) The output is generated too quickly to
+follow in real time, so let the script complete before studying the output from start to finish.
+
+The script takes four options:
+```
+-d=<direction> The trade direciton, BUY or SELL.
+-c=<country> The two letter country code, US, FR, AT, RU, etc.
+-f=<fixed-price> The offer’s fixed price.
+ OR (-f and -m options mutually exclusive, use one or the other)
+-m=<margin-from-price> The offer’s margin (%) from market price.
```suggestion
-m=<margin-from-price> The offer’s margin (%) below the current market price.
```
> +The script takes four options:
+```
+-d=<direction> The trade direciton, BUY or SELL.
+-c=<country> The two letter country code, US, FR, AT, RU, etc.
+-f=<fixed-price> The offer’s fixed price.
+ OR (-f and -m options mutually exclusive, use one or the other)
+-m=<margin-from-price> The offer’s margin (%) from market price.
+-a=<btc-amount> The amount of btc to buy or sell.
+```
+
+### Examples
+
+This simulation creates US / USD face-to-face payment accounts for Bob and Alice. Alice (always the trade maker)
+creates a SELL / USD offer for the amount of 0.1 BTC, at a price 2% below the current market price.
+Bob (always the taker), will use his face-to-face account to take the offer, then the two sides will complete
+the trade protocol, checking their trade status along the way, and their BSQ / BTC balances when the trade is closed.
```suggestion
the trade, checking their trade status along the way, and their BSQ / BTC balances when the trade is closed.
```
> +_Note: The example above is asking for Bob’s balance (using port `9999`), not Alice’s balance._
+
+Show Bob’s full BTC wallet balance information:
+```
+$ ./bisq-cli --password=xyz --port=9999 getbalance --currency-code=btc
+```
+
+### Funding a Bisq Wallet
+
+#### Receiving BTC
+
+To receive BTC from an external wallet, find an unused BTC address (with a zero balance) to receive the BTC.
+```
+$ ./bisq-cli --password=xyz --port=9998 getfundingaddresses
+```
+You can check block explorers for the status of a transaction, and check your Bisq BTC wallet address directly:
```suggestion
You can check a block explorer for the status of a transaction, or you can check your Bisq BTC wallet address directly:
```
> +$ ./bisq-cli --password=xyz --port=9998 getfundingaddresses
+```
+You can check block explorers for the status of a transaction, and check your Bisq BTC wallet address directly:
+```
+$ ./bisq-cli --password=xyz --port=9998 getaddressbalance --address=<btc-address>
+```
+
+#### Receiving BSQ
+To receive BSQ from an external wallet, find an unused BSQ address:
+```
+$ ./bisq-cli --password=xyz --port=9998 getunusedbsqaddress
+```
+
+Give the public address to the sender. After the BSQ is sent, you can check block explorers for the status of
+the transaction. There is no support (yet) to check the balance of an individual BSQ address in your wallet,
+but you can check your BSQ wallet’s balance to see when the new funds arrive:
```suggestion
but you can check your BSQ wallet’s balance to determine if the new funds have arrived:
```
> +#### Receiving BSQ
+To receive BSQ from an external wallet, find an unused BSQ address:
+```
+$ ./bisq-cli --password=xyz --port=9998 getunusedbsqaddress
+```
+
+Give the public address to the sender. After the BSQ is sent, you can check block explorers for the status of
+the transaction. There is no support (yet) to check the balance of an individual BSQ address in your wallet,
+but you can check your BSQ wallet’s balance to see when the new funds arrive:
+```
+$ ./bisq-cli --password=xyz --port=9999 getbalance --currency-code=bsq
+```
+
+### Sending BSQ and BTC to External Wallets
+
+Below are commands for sending BSQ and BTC to external wallets.
Sending BSQ to a non-Bisq wallet is not supported and is likely to cause problems and/or losses...maybe a warning like the following could be worth adding here?
"Please note that sending BSQ to non-Bisq wallets is not supported and highly discouraged."
> +If you have traded using the Bisq UI, you are probably aware of the default network bitcoin withdrawal transaction
+fee, and the custom withdrawal transaction fee user preference in the UI’s setting view. The Api uses these same
```suggestion
If you have traded using the Bisq UI, you are probably aware of the default withdrawal transaction
fee and custom withdrawal transaction fee user preference in the UI’s setting view. The Api uses these same
```
> + The server will create and save the new payment account from details defined in the json file.
+
+ _Note: You can rename the file before passing it to the `createpaymentacct` command._
+
+### Creating Offers
+
+The createoffer command is the Api's most complex command (so far), but CLI posix-style options are self-explanatory,
+and CLI `createoffer` command help gives you specific information about each option.
+```
+$ ./bisq-cli --password=xyz --port=9998 createoffer --help
+```
+
+#### Examples
+
+The `trade-simulation.sh` script described above is an easy way to figure out how to use this command.
+In one of the examples, Alice created a BUY/ EUR offer to buy 0.125 BTC at a fixed price of 30,800 EUR,
```suggestion
In a previous example, Alice created a BUY/ EUR offer to buy 0.125 BTC at a fixed price of 30,800 EUR,
```
> + _Note: You can rename the file before passing it to the `createpaymentacct` command._
+
+### Creating Offers
+
+The createoffer command is the Api's most complex command (so far), but CLI posix-style options are self-explanatory,
+and CLI `createoffer` command help gives you specific information about each option.
+```
+$ ./bisq-cli --password=xyz --port=9998 createoffer --help
+```
+
+#### Examples
+
+The `trade-simulation.sh` script described above is an easy way to figure out how to use this command.
+In one of the examples, Alice created a BUY/ EUR offer to buy 0.125 BTC at a fixed price of 30,800 EUR,
+and pay the Bisq maker fee in BSQ. Alice had already created an EUR face-to-face payment account with id
+`f3c1ec8b-9761-458d-b13d-9039c6892413`, and used this `createoffer` command:
How does one know this payment account ID? Does `createpaymentacct` return it upon successful account creation?
> +
+And takes one of the available offers with an EUR payment account ( id `fe20cdbd-22be-4b8a-a4b6-d2608ff09d6e`)
+with the `takeoffer` command:
+```
+$ ./bisq-cli --password=xyz --port=9998 takeoffer
+ --offer-id=83e8b2e2-51b6-4f39-a748-3ebd29c22aea
+ --payment-account=fe20cdbd-22be-4b8a-a4b6-d2608ff09d6e
+ --fee-currency=btc
+```
+The taken offer will be used to create a trade contract. The next section describes how to use the Api to execute
+the trade.
+
+### Completing Trade Protocol
+
+The first step in the Bisq trade protocol is completed when a `takeoffer` command successfully creates a new trade from
+the taken offer. After the Bisq servers prepare the trade, its status can be viewed with the `gettrade` command:
```suggestion
the taken offer. After the Bisq nodes prepare the trade, its status can be viewed with the `gettrade` command:
```
I see how 'server' might make sense in this context but 'node' is more commonly-used throughout docs.
> +Bisq UI.
+
+You can also view the entire trade contract in `json` format by using the `gettrade` command's `--show-contract=true`
+option:
+```
+$ ./bisq-cli --password=xyz --port=9998 gettrade --trade-id=<trade-id> --show-contract=true
+```
+
+
+The `gettrade` command’s output shows the state of the trade from initial preparation through completion and closure.
+Output columns include:
+```
+Deposit Published YES if the taker fee tx deposit has been broadcast to the network.
+Deposit Confirmed YES if the taker fee tx deposit has been confirmed by the network.
+Fiat Sent YES if the buyer has sent a “payment started” message to seller.
+Fiat Received YES if the sell has sent a “payment received” message to buyer.
```suggestion
Fiat Received YES if the seller has sent a “payment received” message to buyer.
```
> +_Note: There is some delay after a new trade is created due to the time it takes for a taker’s trade deposit fee
+transaction to be published and confirmed on the bitcoin network. Both sides of the trade can check the `gettrade`
+output's `Deposit Published` and `Deposit Confirmed` columns to find out when this early phase of the trade protocol is
+complete._
+
+Once the taker fee transaction has been confirmed, payment can be sent, payment receipt confirmed, and the trade
+protocol completed. There are three CLI commands that must be performed in coordinated order by each side of the trade:
+```
+confirmpaymentstarted Buyer sends seller a message confirming payment has been sent.
+confirmpaymentreceived Seller sends buyer a message confirming payment has been received.
+keepfunds Keep trade proceeds in their Bisq wallets.
+ OR
+withdrawfunds Send trade proceeds to an external wallet.
+```
+The last two mutually exclusive commands (`keepfunds` or `withdrawfunds`) may seem unnecessary, but they are critical
+because they inform the server that a trade’s state can be set to `CLOSED`. Please close out your trades with one or
```suggestion
because they inform the Bisq node that a trade’s state can be set to `CLOSED`. Please close out your trades with one or
```
--
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/bisq-network/bisq/pull/5159#pullrequestreview-588900434
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bisq.network/pipermail/bisq-github/attachments/20210211/2820ad4d/attachment-0001.htm>
More information about the bisq-github
mailing list