rpc: Fix documentation assertion for `getrawtransaction`

laanwj commented at 3:10 pm on March 30, 2022: member

When getrawtransaction is successfully used on a coinbase transaction, there is an assertion error. This is very unlikely but happens in the interface_usdt_utxocache.py test in #24358.

This does the following:

Add missing “coinbase” documentation.
Synchronize documentation between getrawtransaction and decoderawtransaction, the two users of TxToUniv that have detailed documentation. decodepsbt and getblock also uses it but fortunately elides this block.
Change “vout[].amount” to STR_AMOUNT for consistency.
Add maintainer comment to keep the two places synchronized. It might be possible to get smarter with deduplication, but there are some extra fields that prevent the obvious way.

When `getrawtransaction` is successfully used on a coinbase transaction,
there is an assertion error. This is very unlikely but happens in the
test in #24358.

This does the following:

- Add missing "coinbase" documentation.

- Synchronize documentation between `getrawtransaction` and
  `decoderawtransaction`, the two users of `TxToUniv` that have detailed
  documentation. `decodepsbt` also uses it but fortunately elides this block.

- Change "vout[].amount" to `STR_AMOUNT` for consistency.

- Add maintainer comment to keep the two places synchronized. It might
  be possible to get smarter with deduplication, but there are some
  extra fields that prevent the obvious way.

71038a151e

laanwj added the label Docs on Mar 30, 2022

laanwj added the label RPC/REST/ZMQ on Mar 30, 2022

fanquake requested review from MarcoFalke on Mar 30, 2022

jonatack approved

jonatack commented at 9:29 pm on March 30, 2022: member

ACK 71038a151e3136c22449e1a5cb1f386e8474c32d

DrahtBot commented at 3:47 am on March 31, 2022: member

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#24718 (rpc: getblock/getrawtransaction/decode*/gettxout fixups by jonatack)
#23319 (rpc: Return fee and prevout (utxos) to getrawtransaction by dougEfresh)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

MarcoFalke commented at 9:05 am on March 31, 2022: member

Rendered diff:

  0diff --git a/decoderawtransaction b/decoderawtransaction
  1index 276cb46..6acb235 100644
  2--- a/decoderawtransaction
  3+++ b/decoderawtransaction
  4@@ -1,58 +1,58 @@
  5 decoderawtransaction "hexstring" ( iswitness )
  6 
  7 Return a JSON object representing the serialized, hex-encoded transaction.
  8 
  9 Arguments:
 10 1. hexstring    (string, required) The transaction hex string
 11 2. iswitness    (boolean, optional, default=depends on heuristic tests) Whether the transaction hex is a serialized witness transaction.
 12                 If iswitness is not present, heuristic tests will be used in decoding.
 13                 If true, only witness deserialization will be tried.
 14                 If false, only non-witness deserialization will be tried.
 15                 This boolean should reflect whether the transaction has inputs
 16                 (e.g. fully valid, or on-chain transactions), if known by the caller.
 17 
 18 Result:
 19 {                             (json object)
 20   "txid" : "hex",             (string) The transaction id
 21   "hash" : "hex",             (string) The transaction hash (differs from txid for witness transactions)
 22-  "size" : n,                 (numeric) The transaction size
 23+  "size" : n,                 (numeric) The serialized transaction size
 24   "vsize" : n,                (numeric) The virtual transaction size (differs from size for witness transactions)
 25-  "weight" : n,               (numeric) The transaction's weight (between vsize*4 - 3 and vsize*4)
 26+  "weight" : n,               (numeric) The transaction's weight (between vsize*4-3 and vsize*4)
 27   "version" : n,              (numeric) The version
 28   "locktime" : xxx,           (numeric) The lock time
 29   "vin" : [                   (json array)
 30     {                         (json object)
 31-      "coinbase" : "hex",     (string, optional)
 32-      "txid" : "hex",         (string, optional) The transaction id
 33-      "vout" : n,             (numeric, optional) The output number
 34-      "scriptSig" : {         (json object, optional) The script
 35+      "coinbase" : "hex",     (string, optional) The coinbase value (only if coinbase transaction)
 36+      "txid" : "hex",         (string, optional) The transaction id (if not coinbase transaction)
 37+      "vout" : n,             (numeric, optional) The output number (if not coinbase transaction)
 38+      "scriptSig" : {         (json object, optional) The script (if not coinbase transaction)
 39         "asm" : "str",        (string) asm
 40         "hex" : "hex"         (string) hex
 41       },
 42       "txinwitness" : [       (json array, optional)
 43         "hex",                (string) hex-encoded witness data (if any)
 44         ...
 45       ],
 46       "sequence" : n          (numeric) The script sequence number
 47     },
 48     ...
 49   ],
 50   "vout" : [                  (json array)
 51     {                         (json object)
 52       "value" : n,            (numeric) The value in BTC
 53       "n" : n,                (numeric) index
 54       "scriptPubKey" : {      (json object)
 55         "asm" : "str",        (string) the asm
 56         "desc" : "str",       (string) Inferred descriptor for the output
 57         "hex" : "hex",        (string) the hex
 58         "type" : "str",       (string) The type, eg 'pubkeyhash'
 59         "address" : "str"     (string, optional) The Bitcoin address (only if a well-defined address exists)
 60       }
 61     },
 62     ...
 63   ]
 64 }
 65 
 66 Examples:
 67 > bitcoin-cli decoderawtransaction "hexstring"
 68 > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "decoderawtransaction", "params": ["hexstring"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
 69diff --git a/getrawtransaction b/getrawtransaction
 70index fbbe77c..e1a266d 100644
 71--- a/getrawtransaction
 72+++ b/getrawtransaction
 73@@ -1,75 +1,76 @@
 74 getrawtransaction "txid" ( verbose "blockhash" )
 75 
 76 Return the raw transaction data.
 77 
 78 By default, this call only returns a transaction if it is in the mempool. If -txindex is enabled
 79 and no blockhash argument is passed, it will return the transaction if it is in the mempool or any block.
 80 If a blockhash argument is passed, it will return the transaction if
 81 the specified block is available and the transaction is in that block.
 82 
 83 Hint: Use gettransaction for wallet transactions.
 84 
 85 If verbose is 'true', returns an Object with information about 'txid'.
 86 If verbose is 'false' or omitted, returns a string that is serialized, hex-encoded data for 'txid'.
 87 
 88 Arguments:
 89 1. txid         (string, required) The transaction id
 90 2. verbose      (boolean, optional, default=false) If false, return a string, otherwise return a json object
 91 3. blockhash    (string, optional) The block in which to look for the transaction
 92 
 93 Result (if verbose is not set or set to false):
 94 "str"    (string) The serialized, hex-encoded data for 'txid'
 95 
 96 Result (if verbose is set to true):
 97 {                                    (json object)
 98   "in_active_chain" : true|false,    (boolean, optional) Whether specified block is in the active chain or not (only present with explicit "blockhash" argument)
 99   "hex" : "hex",                     (string) The serialized, hex-encoded data for 'txid'
100   "txid" : "hex",                    (string) The transaction id (same as provided)
101   "hash" : "hex",                    (string) The transaction hash (differs from txid for witness transactions)
102   "size" : n,                        (numeric) The serialized transaction size
103   "vsize" : n,                       (numeric) The virtual transaction size (differs from size for witness transactions)
104   "weight" : n,                      (numeric) The transaction's weight (between vsize*4-3 and vsize*4)
105   "version" : n,                     (numeric) The version
106   "locktime" : xxx,                  (numeric) The lock time
107   "vin" : [                          (json array)
108     {                                (json object)
109-      "txid" : "hex",                (string) The transaction id
110-      "vout" : n,                    (numeric) The output number
111-      "scriptSig" : {                (json object) The script
112+      "coinbase" : "hex",            (string, optional) The coinbase value (only if coinbase transaction)
113+      "txid" : "hex",                (string, optional) The transaction id (if not coinbase transaction)
114+      "vout" : n,                    (numeric, optional) The output number (if not coinbase transaction)
115+      "scriptSig" : {                (json object, optional) The script (if not coinbase transaction)
116         "asm" : "str",               (string) asm
117         "hex" : "hex"                (string) hex
118       },
119-      "sequence" : n,                (numeric) The script sequence number
120       "txinwitness" : [              (json array, optional)
121         "hex",                       (string) hex-encoded witness data (if any)
122         ...
123-      ]
124+      ],
125+      "sequence" : n                 (numeric) The script sequence number
126     },
127     ...
128   ],
129   "vout" : [                         (json array)
130     {                                (json object)
131       "value" : n,                   (numeric) The value in BTC
132       "n" : n,                       (numeric) index
133       "scriptPubKey" : {             (json object)
134         "asm" : "str",               (string) the asm
135         "desc" : "str",              (string) Inferred descriptor for the output
136-        "hex" : "str",               (string) the hex
137+        "hex" : "hex",               (string) the hex
138         "type" : "str",              (string) The type, eg 'pubkeyhash'
139         "address" : "str"            (string, optional) The Bitcoin address (only if a well-defined address exists)
140       }
141     },
142     ...
143   ],
144   "blockhash" : "hex",               (string, optional) the block hash
145   "confirmations" : n,               (numeric, optional) The confirmations
146   "blocktime" : xxx,                 (numeric, optional) The block time expressed in UNIX epoch time
147   "time" : n                         (numeric, optional) Same as "blocktime"
148 }
149 
150 Examples:
151 > bitcoin-cli getrawtransaction "mytxid"
152 > bitcoin-cli getrawtransaction "mytxid" true
153 > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getrawtransaction", "params": ["mytxid", true]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
154 > bitcoin-cli getrawtransaction "mytxid" false "myblockhash"
155 > bitcoin-cli getrawtransaction "mytxid" true "myblockhash"

MarcoFalke merged this on Mar 31, 2022

MarcoFalke closed this on Mar 31, 2022

MarcoFalke commented at 9:46 am on March 31, 2022: member

Follow up in https://github.com/bitcoin/bitcoin/pull/24721

sidhujag referenced this in commit 27cbc12c3e on Apr 3, 2022

luke-jr referenced this in commit ff364b8295 on May 21, 2022

DrahtBot locked this on Mar 31, 2023

rpc: Fix documentation assertion for getrawtransaction #24716

Conflicts

rpc: Fix documentation assertion for `getrawtransaction` #24716