rpc: Properly document return values (submitblock, gettxout, getblocktemplate, scantxoutset)

[maflcko]

Currently a few return values are undocumented. This is causing confusion at the least. See for example #18476

[DrahtBot]

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

Conflicts

Reviewers, this pull request conflicts with the following ones:

• rpc: remove scantxoutset EXPERIMENTAL warning #21426 (rpc: remove scantxoutset EXPERIMENTAL warning by jonatack)
• Refactor versionbits deployments to avoid potential uninitialized variables #21401 (Refactor versionbits deployments to avoid potential uninitialized variables by achow101)
• Genericide BIP9 in variable/type names and comments #21399 (Genericide BIP9 in variable/type names and comments by luke-jr)
• BIP 341: Add Speedy Trial activation parameters #21393 (BIP 341: Add Speedy Trial activation parameters by achow101)
• Implement BIP 8 based Speedy Trial activation #21392 (Implement BIP 8 based Speedy Trial activation by achow101)
• rpc: deprecate addresses and reqSigs from rpc outputs #20286 (rpc: deprecate addresses and reqSigs from rpc outputs by mjdietzx)
• rpc: have raw transaction decoding infer output descriptors #16795 (rpc: have raw transaction decoding infer output descriptors by instagibbs)

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.

[jarolrod]

Testing fa3cbac
Calling gettxout with an invalid utxo returns no output using bitcoin-cli, but returns null in the gui. I think the better behavior would be to return an empty json block like we do with other rpc commands such as listtransactions

[maflcko]

This can be discussed in #18476 further. The goal of this pull is to simply document the return values as they are and always have been.

[jonasschnelli]

Looks good.
What is the rational in renaming STR_AMOUNT to NUM_AMOUNT? It creates a fairly large diff and IMO it still is represented as a string on the JSON layer.

[maflcko]

The (scripted) diff is only 50 lines. If there are any conflicts, it should be trivial to resolve. That the internal representation is a string could be a coincidence. The type is really VNUM (numeric) and not VSTR (string).

I checked that the only conflict due to this scripted diff is #19002.

[laanwj]

Just an aside: there used to be talk of, at some point, of making ValueFromAmount return a decimal string instead of a number, or at least having an option to do so, because it's easier to parse exactly in some languages that interpret javascript numbers as floating point number (which are unwise to use for monetary amounts). See e.g. #3759.

This bled out but seeing them as separate types an abstraction level above JSON string/value distinction makes sense.

[maflcko]

Ok, dropped the scripted diff because it seemed controversial

[maflcko]

Rebased

[amitiuttarwar]

concept ACK. one improvement requested, otherwise generally looks good. I checked most of the documented results actually match up.

[maflcko]

Force pushed to address feedback. Should be easy to re-ACK with git range-diff

[amitiuttarwar]

tACK fa7ff07

• gettxout -> checked we get an empty result if UTXO is not found
• scantxoutset -> checked abort returns bool, status returns empty or progress based on if scan is occurring, the existing docs apply to results from start command.
• getblocktemplate -> checked we get string result if proposal is rejected, didn't test an accepted proposal, but saw in the code that we would return null, saw the existing docs apply to other modes.
• submitblock -> same, saw string for failure, looked at code for success

made sure all the help docs make sense & look good when called from command line

the changes from }, \n }, -> }}, kind of confuse me, but I assume its fine considering code compiles & help docs are showing up correctly.

[fjahr]

utACK fa7ff07

Reviewed changes ignoring whitespace.