Update RPC docs to Bitcoin Core 0.21

bitcoin-dot-org · Feb 27, 2021 · 8c6bab6 · 8c6bab6
1 parent abe1c25
commit 8c6bab6
Show file tree

Hide file tree

Showing 140 changed files with 2,680 additions and 1,290 deletions.
diff --git a/helpers/rpc/TODO.md b/helpers/rpc/TODO.md
@@ -1,10 +1,12 @@
 # RPC helper To do
 
-* Add RST
-  * Add basic renderer
-  * Try rendered result
-  * Add unit tests
-  * Refactor (share between backends, abstract rst page)
+* Add command to add deprecation notice and deprecate getbalance, getunconfirmedbalance in 0.19
+
+* Remove markdown support
+  * Remove renderer
+  * Remove helper subcommands which rely on markdown files
+
+* Add command to add "see also" and add references, e.g. in importaddress, importmulti, importprivkey, importpubkey, importwallet, rescanblockchain, walletprocesspsbt
 
 * Fix description
   * gettxoutproof (first line cut off before "txids")

diff --git a/helpers/rpc/annotations-bitcoin-0.21.json b/helpers/rpc/annotations-bitcoin-0.21.json
@@ -186,6 +186,9 @@
     "deprecated": "0.18.0",
     "removed": "0.19"
   },
+  "generateblock": {
+    "added": "0.21"
+  },
   "generatetoaddress": {
     "added": "0.13.0",
     "see_also": {
@@ -586,6 +589,9 @@
       ]
     }
   },
+  "importdescriptors": {
+    "added": "0.21"
+  },
   "importmulti": {
     "added": "0.14.0",
     "see_also": {
@@ -743,6 +749,9 @@
       ]
     }
   },
+  "psbtbumpfee": {
+    "added": "0.21"
+  },
   "removeprunedfunds": {
     "added": "0.13.0",
     "see_also": {

diff --git a/reference/rpc/abandontransaction.rst b/reference/rpc/abandontransaction.rst
@@ -21,6 +21,13 @@ Argument #1 - txid
 
 The transaction id
 
+Result
+~~~~~~
+
+::
+
+  null    (json null)
+
 Examples
 ~~~~~~~~
 
@@ -33,5 +40,5 @@ Examples
 
 ::
 
-  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "abandontransaction", "params": ["1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d"] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "abandontransaction", "params": ["1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
 
diff --git a/reference/rpc/abortrescan.rst b/reference/rpc/abortrescan.rst
@@ -8,6 +8,21 @@ abortrescan
 
 Stops current wallet rescan triggered by an RPC call, e.g. by an importprivkey call.
 
+Note: Use "getwalletinfo" to query the scanning progress.
+
+Result
+~~~~~~
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Type
+     - Description
+   * - true|false
+     - boolean
+     - Whether the abort was successful
+
 Examples
 ~~~~~~~~
 
@@ -24,5 +39,5 @@ Abort the running wallet rescan::
 
 As a JSON-RPC call::
 
-  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "abortrescan", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "abortrescan", "params": []}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
 
diff --git a/reference/rpc/addmultisigaddress.rst b/reference/rpc/addmultisigaddress.rst
@@ -6,7 +6,7 @@ addmultisigaddress
 
 ``addmultisigaddress nrequired ["key",...] ( "label" "address_type" )``
 
-Add a nrequired-to-sign multisignature address to the wallet. Requires a new wallet backup.
+Add an nrequired-to-sign multisignature address to the wallet. Requires a new wallet backup.
 
 Each key is a Bitcoin address or hex-encoded public key.
 
@@ -28,7 +28,7 @@ Argument #2 - keys
 
 **Type:** json array, required
 
-A json array of bitcoin addresses or hex-encoded public keys
+The bitcoin addresses or hex-encoded public keys
 
 ::
 
@@ -56,9 +56,10 @@ Result
 
 ::
 
-  {
-    "address":"multisigaddress",    (string) The value of the new multisig address.
-    "redeemScript":"script"         (string) The string value of the hex-encoded redemption script.
+  {                            (json object)
+    "address" : "str",         (string) The value of the new multisig address
+    "redeemScript" : "hex",    (string) The string value of the hex-encoded redemption script
+    "descriptor" : "str"       (string) The descriptor for this multisig
   }
 
 Examples
@@ -69,9 +70,9 @@ Examples
 
 Add a multisig address from 2 addresses::
 
-  bitcoin-cli addmultisigaddress 2 "[\"16sSauSf5pF2UkUwvKGq4qjNRzBZYqgEL5\",\"171sgjn4YtPu27adkKGrdDwzRTxnRkBfKV\"]"
+  bitcoin-cli addmultisigaddress 2 "[\"bc1q09vm5lfy0j5reeulh4x5752q25uqqvz34hufdl\",\"bc1q02ad21edsxd23d32dfgqqsz4vv4nmtfzuklhy3\"]"
 
 As a JSON-RPC call::
 
-  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "addmultisigaddress", "params": [2, "[\"16sSauSf5pF2UkUwvKGq4qjNRzBZYqgEL5\",\"171sgjn4YtPu27adkKGrdDwzRTxnRkBfKV\"]"] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "addmultisigaddress", "params": [2, "[\"bc1q09vm5lfy0j5reeulh4x5752q25uqqvz34hufdl\",\"bc1q02ad21edsxd23d32dfgqqsz4vv4nmtfzuklhy3\"]"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
 
diff --git a/reference/rpc/addnode.rst b/reference/rpc/addnode.rst
@@ -27,6 +27,13 @@ Argument #2 - command
 
 'add' to add a node to the list, 'remove' to remove a node from the list, 'onetry' to try a connection to the node once
 
+Result
+~~~~~~
+
+::
+
+  null    (json null)
+
 Examples
 ~~~~~~~~
 
@@ -39,5 +46,5 @@ Examples
 
 ::
 
-  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "addnode", "params": ["192.168.0.6:8333", "onetry"] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "addnode", "params": ["192.168.0.6:8333", "onetry"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
 
diff --git a/reference/rpc/analyzepsbt.rst b/reference/rpc/analyzepsbt.rst
@@ -20,29 +20,32 @@ Result
 
 ::
 
-  {
-    "inputs" : [                      (array of json objects)
-      {
-        "has_utxo" : true|false     (boolean) Whether a UTXO is provided
-        "is_final" : true|false     (boolean) Whether the input is finalized
-        "missing" : {               (json object, optional) Things that are missing that are required to complete this input
-          "pubkeys" : [             (array, optional)
-            "keyid"                 (string) Public key ID, hash160 of the public key, of a public key whose BIP 32 derivation path is missing
-          ]
-          "signatures" : [          (array, optional)
-            "keyid"                 (string) Public key ID, hash160 of the public key, of a public key whose signature is missing
-          ]
-          "redeemscript" : "hash"   (string, optional) Hash160 of the redeemScript that is missing
-          "witnessscript" : "hash"  (string, optional) SHA256 of the witnessScript that is missing
-        }
-        "next" : "role"             (string, optional) Role of the next person that this input needs to go to
-      }
-      ,...
-    ]
-    "estimated_vsize" : vsize       (numeric, optional) Estimated vsize of the final signed transaction
-    "estimated_feerate" : feerate   (numeric, optional) Estimated feerate of the final signed transaction in BTC/kB. Shown only if all UTXO slots in the PSBT have been filled.
-    "fee" : fee                     (numeric, optional) The transaction fee paid. Shown only if all UTXO slots in the PSBT have been filled.
-    "next" : "role"                 (string) Role of the next person that this psbt needs to go to
+  {                                   (json object)
+    "inputs" : [                      (json array)
+      {                               (json object)
+        "has_utxo" : true|false,      (boolean) Whether a UTXO is provided
+        "is_final" : true|false,      (boolean) Whether the input is finalized
+        "missing" : {                 (json object, optional) Things that are missing that are required to complete this input
+          "pubkeys" : [               (json array, optional)
+            "hex",                    (string) Public key ID, hash160 of the public key, of a public key whose BIP 32 derivation path is missing
+            ...
+          ],
+          "signatures" : [            (json array, optional)
+            "hex",                    (string) Public key ID, hash160 of the public key, of a public key whose signature is missing
+            ...
+          ],
+          "redeemscript" : "hex",     (string, optional) Hash160 of the redeemScript that is missing
+          "witnessscript" : "hex"     (string, optional) SHA256 of the witnessScript that is missing
+        },
+        "next" : "str"                (string, optional) Role of the next person that this input needs to go to
+      },
+      ...
+    ],
+    "estimated_vsize" : n,            (numeric, optional) Estimated vsize of the final signed transaction
+    "estimated_feerate" : n,          (numeric, optional) Estimated feerate of the final signed transaction in BTC/kB. Shown only if all UTXO slots in the PSBT have been filled
+    "fee" : n,                        (numeric, optional) The transaction fee paid. Shown only if all UTXO slots in the PSBT have been filled
+    "next" : "str",                   (string) Role of the next person that this psbt needs to go to
+    "error" : "str"                   (string, optional) Error message (if there is one)
   }
 
 Examples

diff --git a/reference/rpc/backupwallet.rst b/reference/rpc/backupwallet.rst
@@ -15,6 +15,13 @@ Argument #1 - destination
 
 The destination directory or file
 
+Result
+~~~~~~
+
+::
+
+  null    (json null)
+
 Examples
 ~~~~~~~~
 
@@ -27,5 +34,5 @@ Examples
 
 ::
 
-  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "backupwallet", "params": ["backup.dat"] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "backupwallet", "params": ["backup.dat"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
 
diff --git a/reference/rpc/bumpfee.rst b/reference/rpc/bumpfee.rst
@@ -10,21 +10,25 @@ Bumps the fee of an opt-in-RBF transaction T, replacing it with a new transactio
 
 An opt-in RBF transaction with the given txid must be in the wallet.
 
-The command will pay the additional fee by decreasing (or perhaps removing) its change output.
+The command will pay the additional fee by reducing change outputs or adding inputs when necessary.
+
+It may add a new change output if one does not already exist.
+
+All inputs in the original transaction will be included in the replacement transaction.
 
-If the change output is not big enough to cover the increased fee, the command will currently fail
-instead of adding new inputs to compensate. (A future implementation could improve this.)
 The command will fail if the wallet or mempool contains a transaction that spends one of T's outputs.
 
-By default, the new fee will be calculated automatically using estimatesmartfee.
+By default, the new fee will be calculated automatically using the estimatesmartfee RPC.
 
 The user can specify a confirmation target for estimatesmartfee.
 
-Alternatively, the user can specify totalFee, or use RPC settxfee to set a higher fee rate.
+Alternatively, the user can specify a fee rate in sat/vB for the new transaction.
 
 At a minimum, the new fee rate must be high enough to pay an additional new relay fee (incrementalfee
 returned by getnetworkinfo) to enter the node's mempool.
 
+\* WARNING: before version 0.21, fee_rate was in BTC/kvB. As of 0.21, fee_rate is in sat/vB. \*
+
 Argument #1 - txid
 ~~~~~~~~~~~~~~~~~~
 
@@ -40,34 +44,41 @@ Argument #2 - options
 ::
 
      {
-       "confTarget": n,           (numeric, optional, default=fallback to wallet's default) Confirmation target (in blocks)
-       "totalFee": n,             (numeric, optional, default=fallback to 'confTarget') Total fee (NOT feerate) to pay, in satoshis.
-                                  In rare cases, the actual fee paid might be slightly higher than the specified
-                                  totalFee if the tx change output has to be removed because it is too close to
-                                  the dust threshold.
+       "conf_target": n,          (numeric, optional, default=wallet -txconfirmtarget) Confirmation target in blocks
+                                  
+       "fee_rate": amount,        (numeric or string, optional, default=not set, fall back to wallet fee estimation) 
+                                  Specify a fee rate in sat/vB instead of relying on the built-in fee estimator.
+                                  Must be at least 1.000 sat/vB higher than the current transaction fee rate.
+                                  WARNING: before version 0.21, fee_rate was in BTC/kvB. As of 0.21, fee_rate is in sat/vB.
+                                  
        "replaceable": bool,       (boolean, optional, default=true) Whether the new transaction should still be
                                   marked bip-125 replaceable. If true, the sequence numbers in the transaction will
                                   be left unchanged from the original. If false, any input sequence numbers in the
                                   original transaction that were less than 0xfffffffe will be increased to 0xfffffffe
                                   so the new transaction will not be explicitly bip-125 replaceable (though it may
                                   still be replaceable in practice, for example if it has unconfirmed ancestors which
                                   are replaceable).
-       "estimate_mode": "str",    (string, optional, default=UNSET) The fee estimate mode, must be one of:
-                                  "UNSET"
-                                  "ECONOMICAL"
-                                  "CONSERVATIVE"
+                                  
+       "estimate_mode": "str",    (string, optional, default=unset) The fee estimate mode, must be one of (case insensitive):
+                                  "unset"
+                                  "economical"
+                                  "conservative"
      }
 
 Result
 ~~~~~~
 
 ::
 
-  {
-    "txid":    "value",   (string)  The id of the new transaction
-    "origfee":  n,         (numeric) Fee of the replaced transaction
-    "fee":      n,         (numeric) Fee of the new transaction
-    "errors":  [ str... ] (json array of strings) Errors encountered during processing (may be empty)
+  {                    (json object)
+    "psbt" : "str",    (string) The base64-encoded unsigned PSBT of the new transaction. Only returned when wallet private keys are disabled. (DEPRECATED)
+    "txid" : "hex",    (string) The id of the new transaction. Only returned when wallet private keys are enabled.
+    "origfee" : n,     (numeric) The fee of the replaced transaction.
+    "fee" : n,         (numeric) The fee of the new transaction.
+    "errors" : [       (json array) Errors encountered during processing (may be empty).
+      "str",           (string)
+      ...
+    ]
   }
 
 Examples
@@ -76,7 +87,7 @@ Examples
 
 .. highlight:: shell
 
-Bump the fee, get the new transaction's txid::
+Bump the fee, get the new transaction'stxid::
 
   bitcoin-cli bumpfee <txid>
 
diff --git a/reference/rpc/clearbanned.rst b/reference/rpc/clearbanned.rst
@@ -8,6 +8,13 @@ clearbanned
 
 Clear all banned IPs.
 
+Result
+~~~~~~
+
+::
+
+  null    (json null)
+
 Examples
 ~~~~~~~~
 
@@ -20,5 +27,5 @@ Examples
 
 ::
 
-  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "clearbanned", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+  curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "clearbanned", "params": []}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
 
diff --git a/reference/rpc/combinepsbt.rst b/reference/rpc/combinepsbt.rst
@@ -15,7 +15,7 @@ Argument #1 - txs
 
 **Type:** json array, required
 
-A json array of base64 strings of partially signed transactions
+The base64 strings of partially signed transactions
 
 ::
 
@@ -24,6 +24,19 @@ A json array of base64 strings of partially signed transactions
        ...
      ]
 
+Result
+~~~~~~
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Type
+     - Description
+   * - str
+     - string
+     - The base64-encoded partially signed transaction
+
 Examples
 ~~~~~~~~
 
@@ -32,5 +45,5 @@ Examples
 
 ::
 
-  bitcoin-cli combinepsbt ["mybase64_1", "mybase64_2", "mybase64_3"]
+  bitcoin-cli combinepsbt '["mybase64_1", "mybase64_2", "mybase64_3"]'