Merge pull request bisq-network#5876 from ghubstan/5-api-bsqswap-simu…

…lation-n-docs-update

API BSQ swap simulation script and doc updates #5

apitest/docs/api-beta-test-guide.md

@@ -17,9 +17,9 @@ option adjustments to compensate.
 
 **Shell**:  Bash
 
-**Java SDK**:  Version 10, 11, 12 or 15
+**Java SDK**:  Version 11 - 15 (src and class generation version 11)
 
-**Bitcoin-Core**:  Version 0.19, 0.20, or 0.21
+**Bitcoin-Core**:  Version 0.19 - 22
 
 **Git Client**
 
@@ -372,6 +372,22 @@ The `trade-simulation.sh` script options that would generate the previous `creat
 $ apitest/scripts/trade-simulation.sh -d sell -c jp -m 0.5  -a 0.125
 ```
 
+The `createoffer` command can also be used to create BSQ swap offers, where trade execution is performed immediately
+after a BSQ swap offer is taken.  To swap 0.5 BTC for BSQ at a price of 0.00005 BSQ per 1 BTC:
+```
+$ ./bisq-cli --password=xyz --port=9998 createoffer \
+    --swap=true \
+    --direction=BUY \
+    --amount=0.5 \
+    --currency-code=BSQ \
+    --fixed-price=0.00005
+```
+
+The `bsqswap-simulation.sh` script options that would generate the previous `createoffer` example is:
+```
+$ apitest/scripts/bsqswap-simulation.sh -d buy -a 0.5 -f 0.00005
+```
+
 ### Browsing Your Own Offers
 
 There are different commands to browse available offers you can take, and offers you created.
@@ -530,16 +546,18 @@ A CLI user browses available offers with the getoffers command.  For example, th
 $ ./bisq-cli --password=xyz --port=9998  getoffers --direction=SELL --currency-code=EUR
 ```
 
-And takes one of the available offers with an EUR payment account ( id `fe20cdbd-22be-4b8a-a4b6-d2608ff09d6e`)
+Then 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.
+Depending on the offer type, the taken offer will be used to (1) create a trade contract, or (2) execute a BSQ swap.
+
+The next section describes how to use the Api to execute a trade.  The following <b>Completing a BSQ Swap Trade</b>
+section explains how to use the `takeoffer` command to complete a BSQ swap.
 
 ### Completing Trade Protocol
 
@@ -598,6 +616,14 @@ $ ./bisq-cli --password=xyz --port=9998 keepfunds --trade-id=<trade-id>
 $ ./bisq-cli --password=xyz --port=9999 withdrawfunds --trade-id=<trade-id> --address=<btc-address> [--memo=<"memo">]
 ```
 
+### Completing a BSQ Swap Trade
+
+The `takeoffer` command will immediately perform the BSQ swap, assuming both sides' wallets have sufficient BTC and
+BSQ to cover the trade amount, and maker or taker fee.  It takes one argument:  `--offer-id=<offer-id>`:
+```
+$ ./bisq-cli --password=xyz --port=9998 takeoffer --offer-id=Xge8b2e2-51b6-3TOOB-z748-3ebd29c2kj99
+```
+
 ## Shutting Down Test Harness
 
 The test harness should cleanly shutdown all the background apps in proper order after entering ^C.

apitest/docs/build-run.md

@@ -4,7 +4,7 @@ The Java based API runs on Linux and OSX.
 
 ## Mainnet
 
-To build from the source, clone the github repository found at `https://github.com/bisq-network/bisq`,
+To build from the source, clone the GitHub repository found at `https://github.com/bisq-network/bisq`,
 and build with gradle:
 
     $ ./gradlew clean build

apitest/scripts/bsqswap-simulation-utils.sh

@@ -0,0 +1,79 @@
+#! /bin/bash
+
+# This file must be sourced by the driver script.
+
+source "$APITEST_SCRIPTS_HOME/trade-simulation-env.sh"
+source "$APITEST_SCRIPTS_HOME/trade-simulation-utils.sh"
+
+gencreatebsqswapoffercommand() {
+    PORT="$1"
+    CMD="$CLI_BASE --port=$PORT createoffer"
+    CMD+=" --swap=true"
+    CMD+=" --direction=$DIRECTION"
+    CMD+=" --amount=$AMOUNT"
+    CMD+=" --fixed-price=$FIXED_PRICE"
+    CMD+=" --currency-code=$CURRENCY_CODE"
+    echo "$CMD"
+}
+
+createbsqswapoffer() {
+    CREATE_OFFER_CMD="$1"
+    OFFER_DESC=$($CREATE_OFFER_CMD)
+
+    # If the CLI command exited with an error, print the CLI error, and
+    # return from this function now, passing the error status code to the caller.
+    commandalert $? "Could not create offer."
+
+    OFFER_DETAIL=$(echo -e "$OFFER_DESC" | sed -n '2p')
+    NEW_OFFER_ID=$(echo -e "$OFFER_DETAIL" | awk '{print $NF}')
+    echo "$NEW_OFFER_ID"
+}
+
+executebsqswap() {
+    # Bob list available BSQ offers.  (If a v1 BSQ offer is picked this simulation will break.)
+    printdate "Bob looking at $DIRECTION $CURRENCY_CODE offers."
+    CMD="$CLI_BASE --port=$BOB_PORT getoffers --direction=$DIRECTION --currency-code=$CURRENCY_CODE"
+    printdate "BOB CLI: $CMD"
+    OFFERS=$($CMD)
+    exitoncommandalert $?
+    echo "$OFFERS"
+    printbreak
+
+    OFFER_ID=$(getfirstofferid "$BOB_PORT")
+    exitoncommandalert $?
+    printdate "First BSQ offer found: $OFFER_ID"
+
+    # Take Alice's BSQ swap offer.
+    CMD="$CLI_BASE --port=$BOB_PORT takeoffer --offer-id=$OFFER_ID"
+    printdate "BOB CLI: $CMD"
+    TRADE=$($CMD)
+    commandalert $? "Could not take BSQ swap offer."
+    # Print the takeoffer command's console output.
+    printdate "$TRADE"
+    printbreak
+
+    # Generate 1 btc block
+    printdate "Generating 1 btc block after BSQ swap execution."
+    genbtcblocks 1 2
+    printbreak
+
+    printdate "BSQ swap trade $OFFER_ID complete."
+    printbreak
+
+    printdate "Alice looking at her trade with id $OFFER_ID."
+    CMD="$CLI_BASE --port=$ALICE_PORT gettrade --trade-id=$OFFER_ID"
+    printdate "ALICE CLI: $CMD"
+    GETTRADE_CMD_OUTPUT=$(gettrade "$CMD")
+    exitoncommandalert $?
+    echo "$GETTRADE_CMD_OUTPUT"
+    printbreak
+
+    printdate "Bob looking at his trade with id $OFFER_ID."
+    CMD="$CLI_BASE --port=$BOB_PORT gettrade --trade-id=$OFFER_ID"
+    printdate "BOB CLI: $CMD"
+    GETTRADE_CMD_OUTPUT=$(gettrade "$CMD")
+    exitoncommandalert $?
+    echo "$GETTRADE_CMD_OUTPUT"
+    printbreak
+}
+

apitest/scripts/bsqswap-simulation.sh

@@ -0,0 +1,90 @@
+#! /bin/bash
+
+# Demonstrates a bsq <-> btc swap trade using the API CLI with a local regtest bitcoin node.
+#
+# Prerequisites:
+#
+#  - Linux or OSX with bash, Java 11-15 (JDK language compatibility 11), and bitcoin-core (v0.19 -  v22).
+#
+#  - Bisq must be fully built with apitest dao setup files installed.
+#    Build command:  `./gradlew clean build :apitest:installDaoSetup`
+#
+#  - All supporting nodes must be run locally, in dev/dao/regtest mode:
+#           bitcoind, seednode, arbdaemon, alicedaemon, bobdaemon
+#
+#    These should be run using the apitest harness.  From the root project dir, run:
+#    `$ ./bisq-apitest --apiPassword=xyz --supportingApps=bitcoind,seednode,arbdaemon,alicedaemon,bobdaemon --shutdownAfterTests=false`
+#
+# Usage:
+#
+#  This script must be run from the root of the project, e.g.:
+#
+#     `$ apitest/scripts/bsqswap-simulation.sh -d buy -f 0.00005 -a 0.125`
+#
+#  Script options:  -d <direction> -c <country-code> -f <fixed-price> -a <amount(btc)>
+#
+# Examples:
+#
+#    Create and take a bsq swap offer to buy 0.05 btc at a fixed-price of 0.00005 bsq (per 1 btc):
+#
+#       `$ apitest/scripts/bsqswap-simulation.sh -d buy -a 0.05 -f 0.00005`
+#
+#    Create and take a bsq swap offer to buy 1 btc at a fixed-price of 0.00005 bsq (per 1 btc):
+#
+#       `$ apitest/scripts/bsqswap-simulation.sh -d buy -a 1 -f 0.0005`
+
+export APP_BASE_NAME=$(basename "$0")
+export APP_HOME=$(pwd -P)
+export APITEST_SCRIPTS_HOME="$APP_HOME/apitest/scripts"
+
+source "$APITEST_SCRIPTS_HOME/trade-simulation-env.sh"
+source "$APITEST_SCRIPTS_HOME/trade-simulation-utils.sh"
+source "$APITEST_SCRIPTS_HOME/bsqswap-simulation-utils.sh"
+
+checksetup
+parsebsqswaporderopts "$@"
+
+printdate "Started $APP_BASE_NAME with parameters:"
+printbsqswapscriptparams
+printbreak
+
+# Alice creates a bsq swap offer.
+printdate "Alice creating BSQ swap offer: $DIRECTION $AMOUNT BTC for BSQ at fixed price of $FIXED_PRICE BTC per 1 BSQ."
+CMD=$(gencreatebsqswapoffercommand "$ALICE_PORT" "$ALICE_ACCT_ID")
+printdate "ALICE CLI: $CMD"
+OFFER_ID=$(createbsqswapoffer "$CMD")
+exitoncommandalert $?
+printdate "Alice created bsq swap offer with id: $OFFER_ID."
+printbreak
+sleeptraced 2
+
+# Show Alice's new bsq swap offer.
+printdate "Alice looking at her new $DIRECTION $CURRENCY_CODE offer."
+CMD="$CLI_BASE --port=$ALICE_PORT getmyoffer --offer-id=$OFFER_ID"
+printdate "ALICE CLI: $CMD"
+OFFER=$($CMD)
+exitoncommandalert $?
+echo "$OFFER"
+printbreak
+sleeptraced 2
+
+# Generate 1 btc block.
+printdate "Generating 1 btc block after publishing Alice's offer."
+genbtcblocks 1 1
+printbreak
+
+# Execute the BSQ swap.
+executebsqswap
+exitoncommandalert $?
+printbreak
+
+# Get balances after trade completion.
+printdate "Bob & Alice's balances after BSQ swap trade."
+printdate  "ALICE CLI:"
+printbalances "$ALICE_PORT"
+printbreak
+printdate "BOB CLI:"
+printbalances "$BOB_PORT"
+printbreak
+
+exit 0

apitest/scripts/limit-order-simulation.sh

@@ -6,7 +6,7 @@
 #
 # Prerequisites:
 #
-#  - Linux or OSX with bash, Java 10, or Java 11-12 (JDK language compatibility 10), and bitcoin-core (v0.19, v0.20, v0.21).
+#  - Linux or OSX with bash, Java 11-15 (JDK language compatibility 11), and bitcoin-core (v0.19 -  v22).
 #
 #  - Bisq must be fully built with apitest dao setup files installed.
 #    Build command:  `./gradlew clean build :apitest:installDaoSetup`

apitest/scripts/rolling-offer-simulation.sh

@@ -10,7 +10,7 @@
 #
 # Prerequisites:
 #
-#  - Linux or OSX with bash, Java 10, or Java 11-12 (JDK language compatibility 10), and bitcoin-core (v0.19, v0.20, v0.21).
+#  - Linux or OSX with bash, Java 11-15 (JDK language compatibility 11), and bitcoin-core (v0.19 -  v22).
 #
 #  - Bisq must be fully built with apitest dao setup files installed.
 #    Build command:  `./gradlew clean build :apitest:installDaoSetup`

apitest/scripts/trade-simulation-env.sh

@@ -179,6 +179,41 @@ parselimitorderopts() {
     fi
 }
 
+parsebsqswaporderopts() {
+    usage() {
+        echo "Usage: $0 [-d buy|sell] [-f <fixed-price>] [-a <amount in btc>]" 1>&2
+        exit 1;
+    }
+
+    local OPTIND o d f a
+    while getopts "d:f:a:" o; do
+        case "${o}" in
+            d) d=$(echo "${OPTARG}" | tr '[:lower:]' '[:upper:]')
+                ((d == "BUY" || d == "SELL")) || usage
+                export DIRECTION=${d}
+                ;;
+            f) f=${OPTARG}
+               export FIXED_PRICE=${f}
+               ;;
+            a) a=${OPTARG}
+               export AMOUNT=${a}
+               ;;
+            *) usage ;;
+        esac
+    done
+    shift $((OPTIND-1))
+
+    if [ -z "${d}" ] || [ -z "${a}" ]; then
+        usage
+    fi
+
+    if [ -z "${f}" ] ; then
+        usage
+    fi
+
+    export CURRENCY_CODE="BSQ"
+}
+
 checkbitcoindrunning() {
     # There may be a '+' char in the path and we have to escape it for pgrep.
     if [[ $APP_HOME == *"+"* ]]; then
@@ -310,3 +345,9 @@ printscriptparams() {
         echo "	WAIT = $WAIT"
     fi
 }
+
+printbsqswapscriptparams() {
+    echo "	DIRECTION = $DIRECTION"
+    echo "	FIXED_PRICE = $FIXED_PRICE"
+    echo "	AMOUNT = $AMOUNT"
+}

apitest/scripts/trade-simulation-utils.sh

@@ -457,11 +457,10 @@ delayconfirmpaymentreceived() {
     printbreak
 }
 
-# This is a large function that should be broken up if it ever makes sense to not treat a trade
-# execution simulation as an bsq swap operation.  But we are not testing api methods here, just
-# demonstrating how to use them to get through the trade protocol.  It should work for any trade
-# between Bob & Alice, as long as Alice is maker, Bob is taker, and the offer to be taken is the
-# first displayed in Bob's getoffers command output.
+# This is a large function that might be split into smaller functions.  But we are not testing
+# api methods here, just demonstrating how to use them to get through the V1 trade protocol with
+# the CLI.  It should work for any trade between Bob & Alice, as long as Alice is maker, Bob is
+# taker, and the offer to be taken is the first displayed in Bob's getoffers command output.
 executetrade() {
     # Bob list available offers.
     printdate "BOB $BOB_ROLE:  Looking at $DIRECTION $CURRENCY_CODE offers."
@@ -477,7 +476,7 @@ executetrade() {
     printdate "First offer found: $OFFER_ID"
 
     # Take Alice's offer.
-    CMD="$CLI_BASE --port=$BOB_PORT takeoffer --offer-id=$OFFER_ID --payment-account=$BOB_ACCT_ID --fee-currency=bsq"
+    CMD="$CLI_BASE --port=$BOB_PORT takeoffer --offer-id=$OFFER_ID --payment-account=$BOB_ACCT_ID --fee-currency=BSQ"
     printdate "BOB CLI: $CMD"
     TRADE=$($CMD)
     commandalert $? "Could not take offer."

apitest/scripts/trade-simulation.sh

@@ -1,13 +1,13 @@
 #! /bin/bash
 
-# Runs fiat <-> btc trading scenarios using the API CLI with a local regtest bitcoin node.
+# Demonstrates a fiat <-> btc trade using the API CLI with a local regtest bitcoin node.
 #
 # A country code argument is used to create a country based face to face payment account for the simulated
 # trade, and the maker's face to face payment account's currency code is used when creating the offer.
 #
 # Prerequisites:
 #
-#  - Linux or OSX with bash, Java 10, or Java 11-12 (JDK language compatibility 10), and bitcoin-core (v0.19, v0.20, or v0.21).
+#  - Linux or OSX with bash, Java 11-15 (JDK language compatibility 11), and bitcoin-core (v0.19 -  v22).
 #
 #  - Bisq must be fully built with apitest dao setup files installed.
 #    Build command:  `./gradlew clean build :apitest:installDaoSetup`
@@ -26,15 +26,16 @@
 #
 #     `$ apitest/scripts/trade-simulation.sh -d buy -c fr -m 3.00 -a 0.125`
 #
-#  Script options:  -d <direction> -c <country-code> -m <mkt-price-margin(%)> - f <fixed-price> -a <amount(btc)>
+#  Script options:  -d <direction> -c <country-code> -m <mkt-price-margin(%)> -f <fixed-price> -a <amount(btc)>
 #
 # Examples:
 #
-#    Create a buy/eur offer to buy 0.125 btc at a mkt-price-margin of 0%, using an Italy face to face payment account:
+#    Create and take a buy/eur offer to buy 0.125 btc at a mkt-price-margin of 0%, using an Italy face to face
+#    payment account:
 #
 #       `$ apitest/scripts/trade-simulation.sh -d buy -c it -m 0.00 -a 0.125`
 #
-#    Create a sell/eur offer to sell 0.125 btc at a fixed-price of 38,000 euros, using a France face to face
+#    Create and take a sell/eur offer to sell 0.125 btc at a fixed-price of 38,000 euros, using a France face to face
 #    payment account:
 #
 #       `$ apitest/scripts/trade-simulation.sh -d sell -c fr -f 38000 -a 0.125`
@@ -53,8 +54,6 @@ printdate "Started $APP_BASE_NAME with parameters:"
 printscriptparams
 printbreak
 
-registerdisputeagents
-
 # Demonstrate how to create a country based, face to face account.
 showcreatepaymentacctsteps "Alice" "$ALICE_PORT"