Merge bitcoin#10655: Properly document target_confirmations in listsi…

…nceblock

9f8a46f Properly document target_confirmations in listsinceblock (Ryan Havar)

Pull request description:

  There seems to be some misunderstandings about this, but it's a heavily used function so I'd like to make sure the docs are clear about how it works.

  For a later issue:
  * Change the default of target_confirmations to 6  (1 is a pretty silly default)
  * Change the name of target_confirmations (it's really a horrible name)

Tree-SHA512: a2fba2fab30019cea9db56cd7e31de95ba31090617ab336bdf130f9591bfcf3fc5fbd9e7e1e40b6c7bd2f74b9b4658afb1fdc7fc44e1f79520d1319758982a1c

src/wallet/rpcwallet.cpp

@@ -1746,7 +1746,7 @@ UniValue listsinceblock(const JSONRPCRequest& request)
             "Additionally, if include_removed is set, transactions affecting the wallet which were removed are returned in the \"removed\" array.\n"
             "\nArguments:\n"
             "1. \"blockhash\"            (string, optional) The block hash to list transactions since\n"
-            "2. target_confirmations:    (numeric, optional, default=1) The confirmations required, must be 1 or more\n"
+            "2. target_confirmations:    (numeric, optional, default=1) Return the nth block hash from the main chain. e.g. 1 would mean the best block hash. Note: this is not used as a filter, but only affects [lastblock] in the return value\n"
             "3. include_watchonly:       (bool, optional, default=false) Include transactions to watch-only addresses (see 'importaddress')\n"
             "4. include_removed:         (bool, optional, default=true) Show transactions that were removed due to a reorg in the \"removed\" array\n"
             "                                                           (not guaranteed to work on pruned nodes)\n"
@@ -1780,7 +1780,7 @@ UniValue listsinceblock(const JSONRPCRequest& request)
             "    <structure is the same as \"transactions\" above, only present if include_removed=true>\n"
             "    Note: transactions that were readded in the active chain will appear as-is in this array, and may thus have a positive confirmation count.\n"
             "  ],\n"
-            "  \"lastblock\": \"lastblockhash\"  (string) The hash of the last block\n"
+            "  \"lastblock\": \"lastblockhash\"  (string) The hash of the block (target_confirmations-1) from the best block on the main chain. This is typically used to feed back into listsinceblock the next time you call it. So you would generally use a target_confirmations of say 6, so you will be continually re-notified of transactions until they've reached 6 confirmations plus any new ones\n"
             "}\n"
             "\nExamples:\n"
             + HelpExampleCli("listsinceblock", "")