RPC 2.0 Refactor

[Dotcom]

RPC 2.0 will be a major refactor of the existing RPC, targeted for V22. The refactor will be a breaking change, and RPC 1.0 will be deprecated but usable for a few more versions. The goals of RPC 2.0 are as follows:

• Remove unused RPCs, make changes that require breaking the existing functionality, and add new RPC functionality
• Improve performance, both internally and in the endpoint
• Consistent input and output handling

This topic will outline the proposed, accepted and rejected RPC changes from the point of view of the user, i.e., internal changes are out of scope.

[Dotcom]

List of general proposals, ordered alphabetically. For changes affecting a small set of RPCs, see this comment.

Issue	Status	Proposal	Forum Discussion	Github Issue
Categories (basic/advanced, production/debug)	Evaluation
Confirmed blocks only	Evaluation
Error messages revamp	Evaluation	Github		2262
Expand confirmation status to more RPCs	Evaluation
HTTP Status Codes	Evaluation	Github		1782
Input/output naming consistency	Accepted	Github		616
Low memory usage endpoint	Evaluation			1750
Multiple levels of control	Evaluation
No JSON-escaped strings	Evaluation
OpenAPI Specification	Evaluation	Reddit
Overlapping RPCs	Evaluation	Forum
Pending blocks hinting when an account is not found	Evaluation
Report expected complexity	Evaluation
Streams and iterators for large RPCs	Evaluation
Versioning	Evaluation	Github		840
Replace JSON library	Accepted	Github		1871
Differentiate parsing errors and missing parameters	Evaluation	Forum	110/5
Differentiate "0" values from no value given, e.g. work in block_create	Evaluation

[Dotcom]

List of issues affecting a small set of RPCs, ordered alphabetically. For general issues, see this comment. For overlapping RPCs, see this comment.

RPC	Issue	Status	Forum Discussion	Github Issue
accounts_pending	Inconsistent output, confusing optionals	Evaluation
block_info	Lacks optionals from blocks_info	Evaluation
confirmation_quorum	Does not include all representatives, general revamp needed for clarification	Evaluation		2176
representatives + representatives_online	Output and optionals differ	Evaluation
send (+ others?)	Different errors for source and destination not found	Evaluation	Forum	110/5

List of new ideas for specific RPCs ordered alphabetically.

RPC	Idea	Status	Forum Discussion	Github Issue
block_info + blocks_info	Include PoW multiplier	Evaluation
confirmation_info	Rename to election_info	Evaluation
delegators	Add sorting	Evaluation
ledger	Add pending block count	Evaluation
receive_minimum_set	Perform a pending search immediately	Evaluation
work_cancel	Descriptive output (e.g. cancelled/not found)	Evaluation
representatives + representatives_online	Add response field is_principal	Evaluation

[Dotcom]

List of overlapping RPCs, each item corresponding to a set of RPCs that have overlapping functionality.

• account_info - unecessary overlap as it is a lightweight RPC
  • account_balance
  • account_block_count
  • account_representative - not at the moment, but account_info should include representative in the future
  • account_weight
• block_info - unecessary overlap as it is a lightweight RPC
  • block_account

[renesq]

I occasionally spot confusing RPC responses. For example,
"error": "Unable to parse JSON"
sometimes means "request doesn't include all the mandatory parameters"

Another candidate is
"Account not found"
which shows on send if the account is not opened on the ledger yet, whereas the error message makes it look like the account is not part of the wallet

[PlasmaPower]

This might be part of "No JSON-escaped strings", or moving to a different protocol like protobuf, but if a method like pending returns an empty array, it should be an empty array not a string. That's one of the biggest issues when using a typed JSON framework with the RPC. This, and other issues with the current JSON library, are tracked here on GitHub: https://github.com/nanocurrency/nano-node/issues/1871

[Dotcom]

Added to tracking in the 2nd post, we're definitely looking forward to using another library.

[Dotcom]

Great ideas and remarks, thanks! The first one will have to be evaluated, but the second one is likely to happen, splitting into account_not_found and account_not_found_in_wallet errors makes perfect sense.

[AdrianEGraphene]

Oh thank goodness. I feel less incompetent now.
A local dev and I were working on ping-ponging a bunch of high-velocity, conditional transactions between various accounts over the summer and kept getting confused on some of the output of "account_info".
We eventually moved to other RPC calls, but never quite straightened out what we were trying to accomplish.