<p></p>
<p><b>@m52go</b> commented on this pull request.</p>
<p>Great overall -- most suggestions I made are minor items that I think would help clarity.</p>
<p>Just one minor point of confusion about where the payment account ID comes from, which I noted in a comment.</p><hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574760949">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +```
+
+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.
</pre>
⬇️ Suggested change
<pre style="color: #555">-In this example, a beta tester uses the `apitest.properties` below, instead of ./bisq-cli options.
+In this example, a beta tester uses the `apitest.properties` below, instead of `./bisq-cli` options.
</pre>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574761179">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +## 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.
</pre>
⬇️ Suggested change
<pre style="color: #555">-accounts for Bob and Alice, create an offer, take the offer, and complete a trade protocol.
+accounts for Bob and Alice, create an offer, take the offer, and complete a trade.
</pre>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574761348">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +
+### 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.
</pre>
⬇️ Suggested change
<pre style="color: #555">--m=<margin-from-price> The offer’s margin (%) from market price.
+-m=<margin-from-price> The offer’s margin (%) below the current market price.
</pre>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574761539">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +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.
</pre>
⬇️ Suggested change
<pre style="color: #555">-the trade protocol, checking their trade status along the way, and their BSQ / BTC balances when the trade is closed.
+the trade, checking their trade status along the way, and their BSQ / BTC balances when the trade is closed.
</pre>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574761649">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +_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:
</pre>
⬇️ Suggested change
<pre style="color: #555">-You can check block explorers for the status of a transaction, and check your Bisq BTC wallet address directly:
+You can check a block explorer for the status of a transaction, or you can check your Bisq BTC wallet address directly:
</pre>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574761708">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +$ ./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:
</pre>
⬇️ Suggested change
<pre style="color: #555">-but you can check your BSQ wallet’s balance to see when the new funds arrive:
+but you can check your BSQ wallet’s balance to determine if the new funds have arrived:
</pre>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574761945">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +#### 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.
</pre>
<p>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?</p>
<p>"Please note that sending BSQ to non-Bisq wallets is not supported and highly discouraged."</p>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574762321">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +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
</pre>
⬇️ Suggested change
<pre style="color: #555">-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
+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
</pre>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574762527">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> + 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,
</pre>
⬇️ Suggested change
<pre style="color: #555">-In one of the examples, Alice created a BUY/ EUR offer to buy 0.125 BTC at a fixed price of 30,800 EUR,
+In a previous example, Alice created a BUY/ EUR offer to buy 0.125 BTC at a fixed price of 30,800 EUR,
</pre>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574762773">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> + _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:
</pre>
<p>How does one know this payment account ID? Does <code>createpaymentacct</code> return it upon successful account creation?</p>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574763859">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +
+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:
</pre>
⬇️ Suggested change
<pre style="color: #555">-the taken offer. After the Bisq servers prepare the trade, its status can be viewed with the `gettrade` command:
+the taken offer. After the Bisq nodes prepare the trade, its status can be viewed with the `gettrade` command:
</pre>
<p>I see how 'server' might make sense in this context but 'node' is more commonly-used throughout docs.</p>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574763927">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +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.
</pre>
⬇️ Suggested change
<pre style="color: #555">-Fiat Received YES if the sell has sent a “payment received” message to buyer.
+Fiat Received YES if the seller has sent a “payment received” message to buyer.
</pre>
<hr>
<p>In <a href="https://github.com/bisq-network/bisq/pull/5159#discussion_r574764045">apitest/docs/api-beta-test-guide.md</a>:</p>
<pre style='color:#555'>> +_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
</pre>
⬇️ Suggested change
<pre style="color: #555">-because they inform the server that a trade’s state can be set to `CLOSED`. Please close out your trades with one or
+because they inform the Bisq node that a trade’s state can be set to `CLOSED`. Please close out your trades with one or
</pre>
<p style="font-size:small;-webkit-text-size-adjust:none;color:#666;">—<br />You are receiving this because you are subscribed to this thread.<br />Reply to this email directly, <a href="https://github.com/bisq-network/bisq/pull/5159#pullrequestreview-588900434">view it on GitHub</a>, or <a href="https://github.com/notifications/unsubscribe-auth/AJFFTNTNMZ2ZVCH2736YE5TS6QVABANCNFSM4XGSLVDQ">unsubscribe</a>.<img src="https://github.com/notifications/beacon/AJFFTNVC4C66PI66R6UDOGDS6QVABA5CNFSM4XGSLVD2YY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOEMM6QUQ.gif" height="1" width="1" alt="" /></p>
<script type="application/ld+json">[
{
"@context": "http://schema.org",
"@type": "EmailMessage",
"potentialAction": {
"@type": "ViewAction",
"target": "https://github.com/bisq-network/bisq/pull/5159#pullrequestreview-588900434",
"url": "https://github.com/bisq-network/bisq/pull/5159#pullrequestreview-588900434",
"name": "View Pull Request"
},
"description": "View this Pull Request on GitHub",
"publisher": {
"@type": "Organization",
"name": "GitHub",
"url": "https://github.com"
}
}
]</script>