Explore possible open-rpc migration

[2qx]

I have begun sketching out this protocol in open-rpc:

https://json.cash

It is still a work in progress.

This is a finished example for ethereum:

https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/etclabscore/ethereum-json-rpc-specification/master/openrpc.json&uiSchema%5BappBar%5D%5Bui:input%5D=false&uiSchema%5BappBar%5D%5Bui:title%5D=Ethereum%20JSON-RPC%20API/

The open-rpc tooling seems to be a bit rougher than grpc or swagger but overall I think it might be an improvement.

[dagurval]

Could you describe in short what open-rpc is and how the protocol benefits? The playground tooling looks nice, but the benefits are not obvious to me at least.

By migration, do you mean to do a non-backward compatible changing the RPC interface? For that to happen, the changes would probably need to be a significant improvement over what we have today, as a lot of infrastructure uses the current format and migrating that would be a lot of work.

[2qx]

So open-rpc is a machine readable schema for specifying JSON 2.0 RPC protocols in a language agnostic way. (Like swagger, openapi3, or grpc/protocol buffers, but for json-rpc)

In this case, it should be capable of documenting and specifying the existing JSON2.0 electrum-cash schema exactly, without changing the protocol at all.

It is a way to harden documentation hosted at bitcoincash.network by migrating it to a system that can be validated, produce generated clients and automated mock test cases—as well as providing interactive documentation the user can test in the browser.

It aims to solve the long term maintenance issues associated with writing clients and servers by hand. As well as making the protocol available to a broader audience of developers.

Right now, to my knowledge, we have several copies of the electrum-cash specification:

1. The documentation
2. The Fulcrum implementation
3. The Electrum-Cash implementation
4. Anyone who uses the electrum-cash typescript library is coding actually a bespoke specification, i.e. their new implementation.

The above is the normal way of doing things, but doesn't really work as the number of implementations grows.

Migrating to open-rpc would allow javascript/typescript users to generate clients from the specification, locking number 1 and number 4 to each other in a maintenance free way. In the case of 3, a mock server can be generated from the specification for testing like so: https://medium.com/@stevan.blog/using-openrpc-mock-server-to-test-against-an-ethereum-json-rpc-api-50b86b6d02d6. Or electron-cash could generate rust client bindings and use those from python, resolving compliance with the specification permanently.

The Fulcrum implementation could continue to be maintained as is, or a c++ generator could be developed for openrpc/generator to lock the implementation to the spec.

I'm not that familiar with the JSON 1.0 RPC requirements, but it doesn't look like open-rpc attempts to support it in anyway.

EDIT:

In short, it should not change Fulcrum, Electron-Cash, or the protocol, it would just documentation cleaner and lock new rust and typescript clients to the spec.

[dagurval]

That does sound good, I don't see why we would not want to support this if someone is willing to do the initial work.

Migrating to open-rpc would allow javascript/typescript users to generate clients from the specification, locking number 1 and number 4 to each other in a maintenance free way. In the case of 3, a mock server can be generated from the specification

That sounds helpful. Curious to hear what the electrum-cash devs think (ping @monsterbitar and @rkalis).

(btw, I also maintain an implementation in Rust, ElectrsCash)

[2qx]

So I don't think it would replace the high level functionality of the electrum-cash typescript library, but it would provide typing and completion for the low level calls.

In comparison to something like swagger, or grpc, open-rpc is very much in the early stages, There are generators for typescript and rust clients, but only typescript servers, TMK. So it could provide rust mocking but not rust server stubs.

[rkalis]

That definitely sounds interesting. So does that mean that thise generated client would look something like this:

class GeneratedClient {
  functions: {
    'blockchain.transaction.broadcast': function(raw_tx: string): Promise<string> { ... }
  }
}

[2qx]

@rkalis Something like that, for typescript and rust clients, where methods, parameters and validation are locked to the specification.

[monsterbitar]

electrum-cash is explicitly agnostic to the protocol methods, with the exception that is supports the "subscribe" pattern.

From what I understand, this open-rpc would help make the protocol itself easier to implement, better documented and could provide a list of available method names and their parameterization, which electrum-cash could then provide information on / warn when not properly used / demand.

I'm torn about if I'd want to require strictness, but I'm open to it. An obvious drawback would be that diverging protocol in the future wouldn't work, and the compatibility with BTC's electrum servers would be removed.

[2qx]

@monsterbitar I'm thinking that the electrum-cash typescript library could take optional array of low-level client libraries, i.e my implementation can communicate via [electrum-cash-v1.4.2, electrum-cash-v1.4.4], to users who what the BTC version or just want to implement a few common calls, they wouldn't need to specify a low level library.

[monsterbitar]

@2qx it would be great to be able to provide better error messages when users try to use features outside of the negotiated protocol version.

[monsterbitar]

@2qx any progress on this? I'm warming up to the idea of having a basic engine that talks with the clients and is agnostic to the protocol definition, then building out a wrapper that uses the definition to generate its functions so that developers using the library would get cleaner-looking code.

I'm somewhat unsure about the versioning support in the protocol and how that plays into things, but this is something I'd love to see more work being done on.

[2qx]

@monsterbitar We are preparing for an initial release at mainnet this week. If that goes well I might get time to wrap it up over the weekend.

We want it for typed errors on mainnet, which may not be in that sprint.