rpc: Improve two field's OpenRPC types #36131

1. 
   sedited commented at 3:30 PM on August 31, 2026: contributor

   This corrects the types for two fields in the OpenRPC dump. Both changes have no effect on the rpc help output. The changes to the schema's format are:

   diff dump.json dump_new.json
   11452d11451
   <                 "x-bitcoin-unit": "amount",
   13844,13845c13843
   <               "type": "string",
   <               "pattern": "^[0-9a-fA-F]+$"
   ---
   >               "type": "string"
   

   I asked Claude to flag any inconsistencies in the dump and these were the two, out of many others, that I thought were worthwhile to fix.

2. rpc: Fix private key type in signrawtransactionwithkey

   It is base58, so shouldn't be qualified with STR_HEX. Similarly,
   signmessagewithprivkey also declares the argument as a STR.
   
   This fix is motivated by the OpenRPC dump, where fields tagged with STR_HEX are
   described with a restricting regex that would make its correct usage a
   violation against the unpatched schema.

   73fb9ced56
3. rpc: Change listunspent's ancestorfees type to NUM

   This seems to be the only place where a STR_AMOUNT is used for a sats
   denominated fee amount. Many other places use the raw NUM type for a fee
   amount, for example getblockstats and getblocktemplate. This doesn't
   change the actual result of the RPC call.
   
   The change is motivated by OpenRPC, where the field was previously given
   a 'x-bitcoin-unit' tag. This usually describes a decimal amount, and may
   be confusing for consumers applying this tag.

   78e691ea10
4. DrahtBot added the label RPC/REST/ZMQ on Aug 31, 2026
5. 
   DrahtBot commented at 3:30 PM on August 31, 2026: contributor

   <!--e57a25ab6845829454e8d69fc972939a-->

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

   <!--006a51241073e994b41acfe9ec718e94-->

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/36131.

   <!--021abf342d371248e50ceaed478a90ca-->

   Reviews

   See the guideline and AI policy for information on the review process.

   Type	Reviewers
   ACK	stickies-v, musaHaruna, maflcko

   If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

   <!--5faf32d7da4f0f540f40219e4f7537a3-->

6. 
   sedited commented at 3:31 PM on August 31, 2026: contributor

   cc @willcl-ark and a question: Might it be worthwhile to explain the meaning of x-bitcoin-unit in the help output of getopenrpcinfo?

7. fanquake added this to the milestone 32.0 on Aug 31, 2026
8. stickies-v approved
9. 
   stickies-v commented at 5:56 PM on August 31, 2026: contributor

   ACK 78e691ea10a17092dd65cf0b22c814e9fb3438f0

10. 
    musaHaruna commented at 6:24 AM on September 1, 2026: contributor

    Tested ACK 78e691e

    Verified that signrawtransactionwithkey parses privkeys using DecodeSecret(), which expects Base58Check/WIF keys rather than hexadecimal strings. Therefore, declaring the field as RPCArg::Type::STR_HEX adds a hex-only pattern to the OpenRPC schema.

    Performed a similar check forlistunspent which inserts ancestorfees directly as a CAmount denominated in CURRENCY_ATOM (satoshis), without converting it through ValueFromAmount().

    Added local OpenRPC schema assertions in test/functional/rpc_openrpc.py:

    +        self.uses_wallet = None
    +        assert_equal(find_param(find_method(openrpc, "signrawtransactionwithkey"), "privkeys")["schema"]["items"], {"type": "string"})
    +            assert "x-bitcoin-unit" not in find_method(openrpc, "listunspent")["result"]["schema"]["items"]["properties"]["ancestorfees"]
    

    Verified the assertions fail with these temporary reversions:

    # src/rpc/rawtransaction.cpp
    - RPCArg::Type::STR
    + RPCArg::Type::STR_HEX
    
    # src/wallet/rpc/coins.cpp
    - RPCResult::Type::NUM
    + RPCResult::Type::STR_AMOUNT
    

    After restoring the PR changes and rebuilding, the test passes.

11. 
    maflcko commented at 6:46 AM on September 1, 2026: member

    lgtm ACK 78e691ea10a17092dd65cf0b22c814e9fb3438f0

12. fanquake merged this on Sep 1, 2026
13. fanquake closed this on Sep 1, 2026

    ---

14. 
    willcl-ark commented at 4:25 PM on September 1, 2026: member

    Post-merge ACK.

    cc @willcl-ark and a question: Might it be worthwhile to explain the meaning of x-bitcoin-unit in the help output of getopenrpcinfo?

    Could do, something like this perhaps:

    diff --git a/src/rpc/server.cpp b/src/rpc/server.cpp
    index 1bc8933e624..2d49cda2902 100644
    --- a/src/rpc/server.cpp
    +++ b/src/rpc/server.cpp
    @@ -555,7 +555,8 @@ static RPCResult OpenRPCDocResult()
                             {RPCResult::Type::OBJ, "result", "Method result.",
                                 {
                                     {RPCResult::Type::STR, "name", "Result name."},
    -                                {RPCResult::Type::ANY, "schema", "JSON Schema for the result."},
    +                                {RPCResult::Type::ANY, "schema", "JSON Schema for the result. Numeric schemas may include "
    +                                    "\"x-bitcoin-unit\" property: \"amount\" which denotes a Bitcoin amount in BTC."},
                                 }},
                             {RPCResult::Type::STR, "x-bitcoin-category", "RPC category."},
                         }}}},
    
    

15. 
    sedited commented at 6:46 PM on September 1, 2026: contributor

    Could do, something like this perhaps:

    Yeah, that makes sense to me.

Milestone
32.0