Note: There doesn’t appear to be any RPC-friendly API documentation standard, otherwise I’d be open to using that over markdown. Still, this EIP is meant to provide a human-readable RPC specification and isn’t necessarily meant to be program-readable or to drive other documentation tooling (though the markdown itself could drive tooling if desired).
My expectation is that if the RPC specification is only human readable, then it will quickly become outdated just like the current wiki. A human-readable spec relies on volunteers (client developers and users) to update the documentation, which is a laborious burden that people tend to grow tired of.
It only has the JSON schema specs for a handful of rpc methods, so the main remaining todo is to add the rest. Additionally, I was planning to the description field in the json schema to auto-generate the wiki documentation. This way we would not be relying on volunteers to keep the documentation up to date. Rather, the testrunner automatically checks which clients are compatible with the spec, and the human-readable documentation is generated from the spec.
I totally support the idea that the spec should be machine readable. The human readable spec should be an output of the machine readable spec. The test results could be added to the human-readable machine-generated documentation.
I think this is a fine suggestion. Backporting or supporting older callers is possible but likely to be an extreme pain and disruption.
Here is a real example of where the inconsistencies causes errors in projects like Metamask. Inconsistencies in these error cases cause wild and unexpected behaviours.
"status": "reverted" I don’t particularly want to bikeshed on this but usually this is a hex value no?
eth_call is a simple way to validate a transaction has a chance of success before sending. So defining the failure case and standardising will help projects a lot.
Any thoughts on what to do about things in the ecosystem which hijack certain JSONRPC requests. For example, Metamask handles eth_sign but forwards all data fetching, though the responses can be different when going through Metamask versus a client directly.
Is it easy to add additional less conventional “clients” to this test suite?
As I have argued in the past, signers and clients should be separated! There is “the thing that signs stuff” and there is "the thing that sends/receives data from the blockchain. It is most unfortunate that the early Ethereum clients combined these two functionalities into the same API rather than keeping them as separate APIs.
I would love it if we could split the current API into two separate APIs, one for signing and one for fetching/submitting data from/to the blockchain. Some tools would fulfill both APIs, but having them separate would allow you to mix and match as appropriate.
Agree and we can definitely see the carving up of responsibilities, its just at the library level right now. We do this in 0x.js and we encourage all developers to do this (via our developer docs and samples). Mix and match Ledger/Trezor/MM/Generic with a general JSONRPC data provider.
At the very least I think we can section them off and call it out in the JSONRPC spec/wiki. Do you have thoughts on what this would ultimately look like? I imagine their specs should follow similar behaviour (in terms of errors and layout of results).
I haven’t thought super deep on the implementation details. In general, anything that requires a private key to complete should be part of the signer API and antsything that requires chain interaction would be part of the other API.
This does get murky when you want to do things like verifiable signing UIs, because the signer needs chain access. In such cases I would argue that should be part of the signing API, as the signer can gracefully degrade if it doesn’t have chain access.
@charles-cooper: That works for me. If you tag me in a PR, I’ll be sure to review it. I’m also open to adding an additional EIP maintainer to 1474 so I’m not the sole reviewer and don’t be come bottleneck.
I posted something similar to this in the EIP PR for discussion on OpenRPC, but can these OpenRPC documents be composed? i.e. if we had a standard set of documents “these OpenRPC files represent the standard eth_* RPCs for 1.0” can I then publish a document on my node that includes the standard RPCs and includes my server specific endpoint name?
My reason for asking is that a spec for this should not consist of “please use OpenRPC” but instead it should be “here are the standard OpenRPC mappings for EIP X, EIP Y, and EIP Z, they live at URLs A, B, and C, and here is a sample of MultiGeth composing those into one endpoint.” Otherwise this EIP is noting more than “OpenRPC is cool, please use it.”
Yes! Excellently phrased. Same goes for GraphQL and anything else.
@bitpshr want to take another crack at making a separate JSON-RPC repo? I don’t have time to lead this process, but much like devp2p now has a separate repo to gather interested parties I think this would be valuable.
I think that having 1 canonical EIP that contains ALL the methods will help get everyone on the same page, rather than breaking it out to separate files. The same way the #1474 gets updated. Any client can easily extend it.
My concern with one canonical EIP is then clients that do not implement all the endpoints will need to edit the canonical file to remove them, and if clients are chopping up canonical files their value is diminished.
As an example Pantheon does not implement eth_send* and eth_sign* methods because we do not integrate a key management system for wallet keys in the node (this is a deliberate security decision).
I like the idea of just removing eth_send* and eth_sign* (except send raw) from the specification altogether. I’d rather users not be able to keep their funds in clients either.
EIP-1767 (the GraphQL EIP) also didn’t implement the send and sign transactions as a non-essential call for nodes. There appears to be some consensus on that. A second file with those APIs may be useful to clients who do implement it.
The draft says the following with regard to eth_getLogs -
Note: The return value of eth_getLogs when retrieving logs from eth_newBlockFilter and eth_newPendingTransactionFilter filters will be an array of hashes, not an array of Log objects.
I think it would be nice to clarify how to use eth_getLogs with block/pendingTransaction filters.
