RPC 2.0 Refactor

Protocol Design
#1

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.

5 Likes
#2

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) Rejected
Confirmed blocks only Evaluation
Error messages revamp Accepted Github 2262
Expand confirmation status to more RPCs Accepted
HTTP Status Codes Accepted 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
Rate limiting Evaluation
1 Like
Creating blocks without work
#3

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_create Make it more friendly, require full head block to prevent accidents 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
process Enforce "subtype" to prevent accidents Evaluation
process Drop support for legacy blocks Evaluation

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
representatives Add timestamp of last vote Evaluation
representatives Add "weight" parameter Evaluation
update_work (new) Update the work of a block Evaluation
1 Like
#4

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

1 Like
#5

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

5 Likes
#6

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

5 Likes
#7

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

#8

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.

1 Like
#9

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.

#10

Had an integration ask about whether there was an RPC that you could get the block details based on the account and block height. Unsure of the specific use case there, but perhaps that is worth exploring in the next version.

1 Like