Merge pull request #5951 from ghubstan/rename-keepfunds2closetrade

Rename API method keepfunds -> closetrade (#1)

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

@@ -637,19 +637,19 @@ protocol completed.  There are three CLI commands that must be performed in coor
 ```
 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.
+closetrade                  Set trade state to CLOSED, and keep trade proceeds in user's Bisq wallet.
     OR
-withdrawfunds               Send trade proceeds to an external wallet.
+withdrawfunds               Set trade state to CLOSED, and 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 Bisq node that a trade’s state can be set to `CLOSED`.  Please close out your trades with one
+The last two mutually exclusive commands (`closetrade` or `withdrawfunds`) may seem unnecessary, but they are critical
+because they tell the Bisq node to set a completed trade’s state `CLOSED`.  Please close out your trades with one
 or the other command.
 
 Each of the CLI commands above takes one argument:  `--trade-id=<trade-id>`:
 ```
 $ ./bisq-cli --password=xyz --port=9998 confirmpaymentstarted --trade-id=<trade-id>
 $ ./bisq-cli --password=xyz --port=9999 confirmpaymentreceived --trade-id=<trade-id>
-$ ./bisq-cli --password=xyz --port=9998 keepfunds --trade-id=<trade-id>
+$ ./bisq-cli --password=xyz --port=9998 closetrade --trade-id=<trade-id>
 $ ./bisq-cli --password=xyz --port=9999 withdrawfunds --trade-id=<trade-id> --address=<btc-address> [--memo=<"memo">]
 ```
 

apitest/scripts/trade-simulation-utils.sh

@@ -536,22 +536,22 @@ executetrade() {
     printbreak
 
     # Complete the trade on both sides
-    printdate "BOB $BOB_ROLE:  Closing trade by keeping funds in Bisq wallet."
-    CMD="$CLI_BASE --port=$BOB_PORT keepfunds --trade-id=$OFFER_ID"
+    printdate "BOB $BOB_ROLE:  Closing trade and keeping funds in Bisq wallet."
+    CMD="$CLI_BASE --port=$BOB_PORT closetrade --trade-id=$OFFER_ID"
     printdate "BOB CLI: $CMD"
     KEEP_FUNDS_MSG=$($CMD)
-    commandalert $? "Could close trade with keepfunds command."
-    # Print the keepfunds command's console output.
+    commandalert $? "Closed trade with closetrade command."
+    # Print the closetrade command's console output.
     printdate "$KEEP_FUNDS_MSG"
     sleeptraced 3
     printbreak
 
-    printdate "ALICE (taker):  Closing trade by keeping funds in Bisq wallet."
-    CMD="$CLI_BASE --port=$ALICE_PORT keepfunds --trade-id=$OFFER_ID"
+    printdate "ALICE (taker):  Closing trade and keeping funds in Bisq wallet."
+    CMD="$CLI_BASE --port=$ALICE_PORT closetrade --trade-id=$OFFER_ID"
     printdate "ALICE CLI: $CMD"
     KEEP_FUNDS_MSG=$($CMD)
-    commandalert $? "Could close trade with keepfunds command."
-    # Print the keepfunds command's console output.
+    commandalert $? "Closed trade with closetrade command."
+    # Print the closetrade command's console output.
     printdate "$KEEP_FUNDS_MSG"
     sleeptraced 3
     printbreak

apitest/src/test/java/bisq/apitest/method/trade/TakeBuyBSQOfferTest.java

@@ -162,10 +162,10 @@ public void testKeepFunds(final TestInfo testInfo) {
             genBtcBlocksThenWait(1, 1_000);
 
             var trade = bobClient.getTrade(tradeId);
-            logTrade(log, testInfo, "Alice's view before keeping funds", trade);
+            logTrade(log, testInfo, "Alice's view before closing trade", trade);
 
-            aliceClient.keepFunds(tradeId);
-            bobClient.keepFunds(tradeId);
+            aliceClient.closeTrade(tradeId);
+            bobClient.closeTrade(tradeId);
             genBtcBlocksThenWait(1, 1_000);
 
             trade = bobClient.getTrade(tradeId);

apitest/src/test/java/bisq/apitest/method/trade/TakeBuyBTCOfferTest.java

@@ -137,9 +137,9 @@ public void testKeepFunds(final TestInfo testInfo) {
         try {
             genBtcBlocksThenWait(1, 1_000);
             var trade = aliceClient.getTrade(tradeId);
-            logTrade(log, testInfo, "Alice's view before keeping funds", trade);
-            aliceClient.keepFunds(tradeId);
-            bobClient.keepFunds(tradeId);
+            logTrade(log, testInfo, "Alice's view before closing trade and keeping funds", trade);
+            aliceClient.closeTrade(tradeId);
+            bobClient.closeTrade(tradeId);
             genBtcBlocksThenWait(1, 1_000);
             trade = aliceClient.getTrade(tradeId);
             EXPECTED_PROTOCOL_STATUS.setState(BUYER_RECEIVED_PAYOUT_TX_PUBLISHED_MSG).setPhase(PAYOUT_PUBLISHED);

apitest/src/test/java/bisq/apitest/method/trade/TakeBuyBTCOfferWithNationalBankAcctTest.java

@@ -213,9 +213,9 @@ public void testKeepFunds(final TestInfo testInfo) {
             genBtcBlocksThenWait(1, 1_000);
 
             var trade = aliceClient.getTrade(tradeId);
-            logTrade(log, testInfo, "Alice's view before keeping funds", trade);
-            aliceClient.keepFunds(tradeId);
-            bobClient.keepFunds(tradeId);
+            logTrade(log, testInfo, "Alice's view before closing trade and keeping funds", trade);
+            aliceClient.closeTrade(tradeId);
+            bobClient.closeTrade(tradeId);
             genBtcBlocksThenWait(1, 1_000);
             trade = aliceClient.getTrade(tradeId);
             EXPECTED_PROTOCOL_STATUS.setState(BUYER_RECEIVED_PAYOUT_TX_PUBLISHED_MSG)

apitest/src/test/java/bisq/apitest/method/trade/TakeBuyXMROfferTest.java

@@ -156,9 +156,9 @@ public void testKeepFunds(final TestInfo testInfo) {
         try {
             genBtcBlocksThenWait(1, 1_000);
             var trade = bobClient.getTrade(tradeId);
-            logTrade(log, testInfo, "Alice's view before keeping funds", trade);
-            aliceClient.keepFunds(tradeId);
-            bobClient.keepFunds(tradeId);
+            logTrade(log, testInfo, "Alice's view before closing trade and keeping funds", trade);
+            aliceClient.closeTrade(tradeId);
+            bobClient.closeTrade(tradeId);
             genBtcBlocksThenWait(1, 1_000);
 
             trade = bobClient.getTrade(tradeId);

apitest/src/test/java/bisq/apitest/method/trade/TakeSellBSQOfferTest.java

@@ -155,11 +155,14 @@ public void testAlicesBtcWithdrawalToExternalAddress(final TestInfo testInfo) {
             genBtcBlocksThenWait(1, 1_000);
 
             var trade = aliceClient.getTrade(tradeId);
-            logTrade(log, testInfo, "Alice's view before withdrawing BTC funds to external wallet", trade);
+            logTrade(log,
+                    testInfo,
+                    "Alice's view before closing trade and withdrawing BTC funds to external wallet",
+                    trade);
             String toAddress = bitcoinCli.getNewBtcAddress();
             aliceClient.withdrawFunds(tradeId, toAddress, WITHDRAWAL_TX_MEMO);
-            // Bob keeps funds.
-            bobClient.keepFunds(tradeId);
+            // Bob closes trade and keeps funds.
+            bobClient.closeTrade(tradeId);
             genBtcBlocksThenWait(1, 1_000);
             trade = aliceClient.getTrade(tradeId);
             EXPECTED_PROTOCOL_STATUS.setState(WITHDRAW_COMPLETED)

apitest/src/test/java/bisq/apitest/method/trade/TakeSellBTCOfferTest.java

@@ -144,7 +144,7 @@ public void testBobsBtcWithdrawalToExternalAddress(final TestInfo testInfo) {
             logTrade(log, testInfo, "Bob's view before withdrawing funds to external wallet", trade);
             String toAddress = bitcoinCli.getNewBtcAddress();
             bobClient.withdrawFunds(tradeId, toAddress, WITHDRAWAL_TX_MEMO);
-            aliceClient.keepFunds(tradeId);
+            aliceClient.closeTrade(tradeId);
             genBtcBlocksThenWait(1, 1_000);
             trade = bobClient.getTrade(tradeId);
             EXPECTED_PROTOCOL_STATUS.setState(WITHDRAW_COMPLETED)

apitest/src/test/java/bisq/apitest/method/trade/TakeSellXMROfferTest.java

@@ -165,7 +165,7 @@ public void testAlicesBtcWithdrawalToExternalAddress(final TestInfo testInfo) {
 
             String toAddress = bitcoinCli.getNewBtcAddress();
             aliceClient.withdrawFunds(tradeId, toAddress, WITHDRAWAL_TX_MEMO);
-            bobClient.keepFunds(tradeId);
+            bobClient.closeTrade(tradeId);
             genBtcBlocksThenWait(1, 1_000);
 
             trade = aliceClient.getTrade(tradeId);

apitest/src/test/java/bisq/apitest/scenario/bot/BotClient.java

@@ -282,12 +282,12 @@ public void sendConfirmPaymentReceivedMessage(String tradeId) {
     }
 
     /**
-     * Sends a 'keep funds in wallet message' for a trade with the given tradeId,
+     * Sends a 'closetrade' for a trade with the given tradeId,
      * or throws an exception.
      * @param tradeId
      */
-    public void sendKeepFundsMessage(String tradeId) {
-        grpcClient.keepFunds(tradeId);
+    public void sendCloseTradeMessage(String tradeId) {
+        grpcClient.closeTrade(tradeId);
     }
 
     /**

apitest/src/test/java/bisq/apitest/scenario/bot/protocol/BotProtocol.java

@@ -219,8 +219,8 @@ protected void printBotProtocolStep() {
         }
     };
 
-    protected final Function<TradeInfo, TradeInfo> keepFundsFromTrade = (trade) -> {
-        initProtocolStep.accept(KEEP_FUNDS);
+    protected final Function<TradeInfo, TradeInfo> closeTrade = (trade) -> {
+        initProtocolStep.accept(CLOSE_TRADE);
         var isBuy = trade.getOffer().getDirection().equalsIgnoreCase(BUY);
         var isSell = trade.getOffer().getDirection().equalsIgnoreCase(SELL);
         var cliUserIsSeller = (this instanceof MakerBotProtocol && isBuy) || (this instanceof TakerBotProtocol && isSell);
@@ -229,8 +229,8 @@ protected void printBotProtocolStep() {
         } else {
             createGetBalanceScript();
         }
-        checkIfShutdownCalled("Interrupted before closing trade with 'keep funds' command.");
-        this.getBotClient().sendKeepFundsMessage(trade.getTradeId());
+        checkIfShutdownCalled("Interrupted before closing trade with 'closetrade' command.");
+        this.getBotClient().sendCloseTradeMessage(trade.getTradeId());
         return trade;
     };
 

apitest/src/test/java/bisq/apitest/scenario/bot/protocol/MakerBotProtocol.java

@@ -56,7 +56,7 @@ public void run() {
                 : waitForPaymentStartedMessage.andThen(sendPaymentReceivedMessage);
         completeFiatTransaction.apply(trade);
 
-        Function<TradeInfo, TradeInfo> closeTrade = waitForPayoutTx.andThen(keepFundsFromTrade);
+        Function<TradeInfo, TradeInfo> closeTrade = waitForPayoutTx.andThen(this.closeTrade);
         closeTrade.apply(trade);
 
         currentProtocolStep = DONE;

apitest/src/test/java/bisq/apitest/scenario/bot/protocol/ProtocolStep.java

@@ -12,6 +12,6 @@ public enum ProtocolStep {
     SEND_PAYMENT_RECEIVED_CONFIRMATION_MESSAGE,
     WAIT_FOR_PAYMENT_RECEIVED_CONFIRMATION_MESSAGE,
     WAIT_FOR_PAYOUT_TX,
-    KEEP_FUNDS,
+    CLOSE_TRADE,
     DONE
 }

apitest/src/test/java/bisq/apitest/scenario/bot/protocol/TakerBotProtocol.java

@@ -55,7 +55,7 @@ public void run() {
                 : sendPaymentStartedMessage.andThen(waitForPaymentReceivedConfirmation);
         completeFiatTransaction.apply(trade);
 
-        Function<TradeInfo, TradeInfo> closeTrade = waitForPayoutTx.andThen(keepFundsFromTrade);
+        Function<TradeInfo, TradeInfo> closeTrade = waitForPayoutTx.andThen(this.closeTrade);
         closeTrade.apply(trade);
 
         currentProtocolStep = DONE;

apitest/src/test/java/bisq/apitest/scenario/bot/script/BashScriptGenerator.java

@@ -167,10 +167,10 @@ public File createPaymentReceivedScript(TradeInfo trade) {
     }
 
     public File createKeepFundsScript(TradeInfo trade) {
-        String paymentStartedCmd = format("%s keepfunds --trade-id=%s", cliBase, trade.getTradeId());
+        String paymentStartedCmd = format("%s closetrade --trade-id=%s", cliBase, trade.getTradeId());
         String getTradeCmd = format("%s gettrade --trade-id=%s", cliBase, trade.getTradeId());
         String getBalanceCmd = format("%s getbalance", cliBase);
-        return createCliScript("keepfunds.sh",
+        return createCliScript("closetrade.sh",
                 paymentStartedCmd,
                 "sleep 2",
                 getTradeCmd,

cli/src/main/java/bisq/cli/CliMain.java

@@ -525,15 +525,15 @@ public static void run(String[] args) {
                     out.printf("trade %s payment received message sent%n", tradeId);
                     return;
                 }
-                case keepfunds: {
+                case closetrade: {
                     var opts = new GetTradeOptionParser(args).parse();
                     if (opts.isForHelp()) {
                         out.println(client.getMethodHelp(method));
                         return;
                     }
                     var tradeId = opts.getTradeId();
-                    client.keepFunds(tradeId);
-                    out.printf("funds from trade %s saved in bisq wallet%n", tradeId);
+                    client.closeTrade(tradeId);
+                    out.printf("trade %s is closed%n", tradeId);
                     return;
                 }
                 case withdrawfunds: {
@@ -864,10 +864,10 @@ private static void printHelp(OptionParser parser, @SuppressWarnings("SameParame
             stream.println();
             stream.format(rowFormat, confirmpaymentreceived.name(), "--trade-id=<trade-id>", "Confirm payment received");
             stream.println();
-            stream.format(rowFormat, keepfunds.name(), "--trade-id=<trade-id>", "Keep received funds in Bisq wallet");
+            stream.format(rowFormat, closetrade.name(), "--trade-id=<trade-id>", "Close completed trade");
             stream.println();
             stream.format(rowFormat, withdrawfunds.name(), "--trade-id=<trade-id> --address=<btc-address> \\",
-                    "Withdraw received funds to external wallet address");
+                    "Withdraw received trade funds to external wallet address");
             stream.format(rowFormat, "", "[--memo=<\"memo\">]", "");
             stream.println();
             stream.format(rowFormat, getpaymentmethods.name(), "", "Get list of supported payment account method ids");

cli/src/main/java/bisq/cli/GrpcClient.java

@@ -372,8 +372,8 @@ public void confirmPaymentReceived(String tradeId) {
         tradesServiceRequest.confirmPaymentReceived(tradeId);
     }
 
-    public void keepFunds(String tradeId) {
-        tradesServiceRequest.keepFunds(tradeId);
+    public void closeTrade(String tradeId) {
+        tradesServiceRequest.closeTrade(tradeId);
     }
 
     public void withdrawFunds(String tradeId, String address, String memo) {

cli/src/main/java/bisq/cli/Method.java

@@ -22,6 +22,7 @@
  */
 public enum Method {
     canceloffer,
+    closetrade,
     confirmpaymentreceived,
     confirmpaymentstarted,
     createoffer,
@@ -45,7 +46,6 @@ public enum Method {
     gettxfeerate,
     getunusedbsqaddress,
     getversion,
-    keepfunds,
     lockwallet,
     registerdisputeagent,
     removewalletpassword,

cli/src/main/java/bisq/cli/request/TradesServiceRequest.java

@@ -17,10 +17,10 @@
 
 package bisq.cli.request;
 
+import bisq.proto.grpc.CloseTradeRequest;
 import bisq.proto.grpc.ConfirmPaymentReceivedRequest;
 import bisq.proto.grpc.ConfirmPaymentStartedRequest;
 import bisq.proto.grpc.GetTradeRequest;
-import bisq.proto.grpc.KeepFundsRequest;
 import bisq.proto.grpc.TakeOfferReply;
 import bisq.proto.grpc.TakeOfferRequest;
 import bisq.proto.grpc.TradeInfo;
@@ -86,12 +86,12 @@ public void confirmPaymentReceived(String tradeId) {
         grpcStubs.tradesService.confirmPaymentReceived(request);
     }
 
-    public void keepFunds(String tradeId) {
-        var request = KeepFundsRequest.newBuilder()
+    public void closeTrade(String tradeId) {
+        var request = CloseTradeRequest.newBuilder()
                 .setTradeId(tradeId)
                 .build();
         //noinspection ResultOfMethodCallIgnored
-        grpcStubs.tradesService.keepFunds(request);
+        grpcStubs.tradesService.closeTrade(request);
     }
 
     public void withdrawFunds(String tradeId, String address, String memo) {

core/src/main/java/bisq/core/api/CoreApi.java

@@ -315,8 +315,8 @@ public void confirmPaymentReceived(String tradeId) {
         coreTradesService.confirmPaymentReceived(tradeId);
     }
 
-    public void keepFunds(String tradeId) {
-        coreTradesService.keepFunds(tradeId);
+    public void closeTrade(String tradeId) {
+        coreTradesService.closeTrade(tradeId);
     }
 
     public void withdrawFunds(String tradeId, String address, String memo) {

core/src/main/java/bisq/core/api/CoreTradesService.java

@@ -180,14 +180,14 @@ void confirmPaymentReceived(String tradeId) {
         }
     }
 
-    void keepFunds(String tradeId) {
+    void closeTrade(String tradeId) {
         coreWalletsService.verifyWalletsAreAvailable();
         coreWalletsService.verifyEncryptedWalletIsUnlocked();
 
         verifyTradeIsNotClosed(tradeId);
         var trade = getOpenTrade(tradeId).orElseThrow(() ->
                 new IllegalArgumentException(format("trade with id '%s' not found", tradeId)));
-        log.info("Keeping funds received from trade {}", tradeId);
+        log.info("Closing trade {}", tradeId);
         tradeManager.onTradeCompleted(trade);
     }
 

core/src/main/resources/help/closetrade-help.txt

@@ -0,0 +1,29 @@
+closetrade
+
+NAME
+----
+closetrade - close open trade
+
+SYNOPSIS
+--------
+closetrade
+		--trade-id=<trade-id>
+
+DESCRIPTION
+-----------
+This final step in the trade protocol moves a completed trade from the open trades list
+to the closed trade list, where it becomes part of the user's trade history.
+The step is necessary for correct transition of a trade's state to CLOSED.
+
+The alternative way to close a trade is to send the received BTC to an external
+BTC wallet, using the withdrawfunds command.
+
+OPTIONS
+-------
+--trade-id
+		The ID of the completed trade (the full offer-id).
+
+EXAMPLES
+--------
+The BTC buyer or seller closes out trade 83e8b2e2-51b6-4f39-a748-3ebd29c22aea:
+$ ./bisq-cli --password=xyz --port=9998 closetrade --trade-id=83e8b2e2-51b6-4f39-a748-3ebd29c22aea