[RFC] Dealing with RPCs that have a lot of positional options

achow101 commented at 9:18 pm on July 28, 2021: member

There are several RPCs that have several positional options which make them difficult to work with. The following RPCs have 3 or more optional arguments:

gettxoutsetinfo
createwallet
getbalance
listreceivedbyaddress
listreceivedbylabel
listsinceblock
listtransactions
send
sendmany
sendtoaddress
walletcreatefundedpsbt
walletprocesspsbt

What can we do to make it easier for users to use these RPCs?

Here are a few possible solutions.

Options object

An oft suggested method is to use an options JSON object. This would replace all of the positional options with a single argument that contains a JSON object with each option named explicitly in it. This is a pattern we already use for several RPCs. This could be done in a backwards compatible way to minimize disruption to current users of those RPCs and new options would simply be added to this options object. However typing correctly formatted JSON can be difficult.

Encourage the use of named arguments

Since all positional arguments have names, it is possible to use named arguments rather than specifying them all positionally. Through the use of named parameters, users would be able to have largely the same effect as an options object but without needing to make correctly formatted JSON. Bitcoin Core already supports named parameters as described in the JSON-RPC 2.0 spec. Any client that conforms to JSON-RPC 2.0 would be able to use named arguments. Furthermore, bitcoin-cli has -named switch so that it is also easy for command line users and does not require correct JSON formatting.

achow101 added the label Feature on Jul 28, 2021

promag commented at 10:23 pm on July 28, 2021: member

I think #19762 is an improvement as it allows to mix them. Regardless of that, named arguments are (IMHO) a better approach since it makes explicit for the reader what values are used for.

fanquake added the label Brainstorming on Jul 29, 2021

fanquake added the label RPC/REST/ZMQ on Jul 29, 2021

ryanofsky commented at 3:40 pm on July 29, 2021: contributor

I think #19762 is an improvement as it allows to mix them. Regardless of that, named arguments are (IMHO) a better approach since it makes explicit for the reader what values are used for.

I think another important thing our RPC server is missing is the ability to require option-style parameters to be passed by name, and to disallow passing them by position. Combined with #19762 this would let us safely provide RPC methods accepting only a small number of positional arguments, but a large number of named options, so there is no need for command line users to use json object syntax, but also no risk of getting options confused by trying to pass them by position. This should probably be simple to implement as RPCHelpMan extension after #19762 and would be equivalent to python’s keyword-only argument feature def fun(arg1, arg2, *, option1, option2) https://www.python.org/dev/peps/pep-3102/#rationale

luke-jr commented at 5:39 pm on September 11, 2021: member

It is possible to do both.

IMO we should continue to support positional arguments, with a clean API (ie, options object), while at the same time having a cleaner named argument interface (ie, don’t require options to have an object wrapper).

#17356 would have made a good path forward to this end, but unfortunately saw no review.

Absent a perfect solution, using options objects seems like the next best approach.

I think #19762 is an improvement as it allows to mix them.

This isn’t a JSON-RPC standard mixing, and while I think it’s a good extension, it isn’t an alternative to a real positional API.

I think another important thing our RPC server is missing is the ability to require option-style parameters to be passed by name, and to disallow passing them by position.

This is essentially the same as deprecating positional argument support. I don’t think it’s a good idea.

willcl-ark commented at 11:49 am on March 10, 2023: contributor

Can this be closed now that we have #19762 ? Or are we leaving it open to remember to address this comment:

I think another important thing our RPC server is missing is the ability to require option-style parameters to be passed by name, and to disallow passing them by position.

maflcko commented at 11:56 am on March 10, 2023: member

Can this be closed now that we have #19762 ? Or are we leaving it open to remember to address this comment:

I think another important thing our RPC server is missing is the ability to require option-style parameters to be passed by name, and to disallow passing them by position.

That is implemented in #26485, no?

willcl-ark commented at 12:03 pm on March 10, 2023: contributor

Oh yea, looks like it. Cool!

willcl-ark closed this on Apr 10, 2024

[RFC] Dealing with RPCs that have a lot of positional options #22575

Options object

Encourage the use of named arguments