How should I handle cases like this where the documentation for Bitcoin Core states one thing, and the actual program does something else?

Question

Bitcoin Core's RPC API call "getnewaddress" is documented here: https://bitcoincore.org/en/doc/0.18.0/rpc/wallet/getnewaddress/

It claims:

Result: "address" (string) The new bitcoin address

In other words, it is supposed to return an associative array containing only the element 'address' which is a string representing the new Bitcoin receive address.

However, it actually returns just an "untitled" string without an array/object. It's just a plain string immediately outputted, not wrapped in any array/object/container. Perhaps this is what they mean by "(string)", but it sure looks to me that the "address" part makes it an associative array with one element. This appears to be the case elsewhere in the API:

The "sendtoaddress" call does return an associative array with just a "txid" element, and it's documented just like "getnewaddress": https://bitcoincore.org/en/doc/0.18.0/rpc/wallet/sendtoaddress/

Result: "txid" (string) The transaction id.

(Or all my previous work was in vain and I have actually got that wrong. I cannot easily try sending Bitcoin.)

Should I assume that they won't change the behaviour of the program, but rather the documentation? Or will they really change the program to reflect the documentation? If they ever do, my code breaks since it expects the returned value to be a string and not an array with one element called 'address'.

This kind of thing gives me a great deal of stress, especially as money is involved and the slightest mistake could cause huge losses or (at best) a ton of nightmarish manual work to attempt to "restore the state" after something is messed up halfways.

Note: I cannot report bugs to their GitHub page because MS GitHub doesn't let me register an account. I gave up on even trying.

Answer 1

In the example RPC results, it will show whether the result is a JSON array by including brackets [] or it will show if it is a JSON object (associative array) by using curly brackets {}. If the result does not come with any JSON encoding and is a single string or other data type, then you will not see that in the example.

You can see an example of a result that comes in the form of a JSON array by using listlockunspent:

Result:
[
  {
    "txid" : "transactionid",     (string) The transaction id locked
    "vout" : n                      (numeric) The vout value
  }
  ,...
]

An example of a JSON object using createwallet:

Result:
{
  "name" :    <wallet_name>,        (string) The wallet name if created successfully. If the wallet was created using a full path, the wallet_name will be the full path.
  "warning" : <warning>,            (string) Warning message if wallet was not loaded cleanly.
}

An example of a return value that is not JSON encoded using getbalance:

Result:
amount              (numeric) The total amount in BTC received for this wallet.

I believe you may be mistaken with the assumption that sendtoaddress return a JSON object. The code clearly shows that the result is not JSON encoded:

return tx->GetHash().GetHex();

That is a transaction object, which retrieves the transaction hash (256 bit opaque blob), which is then converted to a string using the GetHex() method.

The code would use UniValue if it were to encode JSON. For example in the code of createwallet:

UniValue obj(UniValue::VOBJ);
obj.pushKV("name", wallet->GetName());
obj.pushKV("warning", warning);

return obj;