Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New BIP: Add OpenRPC Service Discovery To JSON-RPC Services #776

Closed
wants to merge 2 commits into from

Conversation

Projects
None yet
8 participants
@shanejonas
Copy link

commented Apr 3, 2019

This is a proposal to add OpenRPC to JSON-RPC services needed to interact with the Bitcoin blockchain.

The OpenRPC Specification defines a standard, programming language-agnostic interface description for JSON-RPC 2.0 APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

@shanejonas shanejonas changed the title OpenRPC proposal New BIP: Add OpenRPC Service Discovery To JSON-RPC Services Apr 3, 2019

@luke-jr luke-jr added the invalid label Apr 3, 2019

@luke-jr

This comment has been minimized.

Copy link
Member

commented Apr 3, 2019

Looks like OpenRPC is its own, Bitcoin-independent specification. I don't see anything to put in a BIP...

Also, there's no apparent discussion on the mailing list, which is required before opening a PR here.

@luke-jr luke-jr closed this Apr 3, 2019

@shanejonas

This comment has been minimized.

Copy link
Author

commented Apr 3, 2019

@luke-jr this proposal is to add an extra method to bitcoin clients to provide discovery for JSON-RPC methods.

I was told by a bitcoin dev to submit it directly here instead as it is not consensus related. can you please provide next steps?

@MarcoFalke

This comment has been minimized.

Copy link
Member

commented Apr 3, 2019

Is this something that Bitcoin related software needs to agree on? It seems like this is a choice per each software project if they want to support json-rpc or json-openrpc?

@promag

This comment has been minimized.

Copy link
Member

commented Apr 3, 2019

IIRC bitcoin-core doesn't use JSON-RPC 2.0.

@shanejonas

This comment has been minimized.

Copy link
Author

commented Apr 3, 2019

All bitcoin clients give you a JSON-RPC 2.0 API, if we had a machine readable way to define the methods and their return values. We could build automated tooling, documentation, tests.

@luke-jr

This comment has been minimized.

Copy link
Member

commented Apr 3, 2019

Maybe whoever you talked to meant to submit actual code to Bitcoin Core directly? That would make sense.

@shanejonas

This comment has been minimized.

Copy link
Author

commented Apr 3, 2019

I considered this:

layer: API/RPC
type: standards track

If having a standard described interface for bitcoin doesn’t fit that category what would?

@MarcoFalke

This comment has been minimized.

Copy link
Member

commented Apr 3, 2019

Yeah, this repo is about the Bitcoin network (p2p, consensus and wallet interaction) and not about Bitcoin Core specifics (GUI, RPC and data files)

@shanejonas

This comment has been minimized.

Copy link
Author

commented Apr 3, 2019

having a standard described interfaces lets you test interfaces across implementations. i don’t think it’s just applicable to a specific client.

if a client doesn’t provide getblock or doesn’t work the same way it will have unintended consequences.

@luke-jr

This comment has been minimized.

Copy link
Member

commented Apr 3, 2019

A standard interface would, but your thing seems even more abstract than that...?

@shanejonas

This comment has been minimized.

Copy link
Author

commented Apr 3, 2019

openrpc gives you the tools and spec to write the interface, generate rpc clients, docs, etc. here is an example of ethereum geths openrpc.json.

@MarcoFalke

This comment has been minimized.

Copy link
Member

commented Apr 3, 2019

Ah, so similar to how we have some BIPs to normalize Bitcoin wallets, this will normalize the Bitcoin rpc interfaces. Doesn't sound too bad to me. Mind sending a post to the mailing list as per #776 (comment)

@stevanlohja

This comment has been minimized.

Copy link

commented Apr 3, 2019

Yeah, this repo is about the Bitcoin network (p2p, consensus and wallet interaction) and not about Bitcoin Core specifics (GUI, RPC and data files)

Wallets need to broadcast and communicate with the network. OpenRPC provides a standard interface for network clients that wallets would use to interface with the network.

@stevanlohja

This comment has been minimized.

Copy link

commented Apr 3, 2019

any change or addition that affects the interoperability of applications using Bitcoin. Standards Track BIPs consist of two parts, a design document and a reference implementation.

Since OpenRPC can effect BTC applications, then it's arguably standards track. A design and reference implementation is provided in the PR document I believe.

@shanejonas

This comment has been minimized.

Copy link
Author

commented Apr 3, 2019

here is just a concrete example of 1 method for Bitcoin:

{
  "openrpc": "1.0.0",
  "info": {
    "version": "0.0.1",
    "title": "Bitcoin RPC API",
    "description": "This API lets you interact with the blockchain via JSON-RPC"
  },
  "methods": [
    {
      "name": "getblockhash",
      "summary": "Returns hash of block in best-block-chain at <index>",
      "description": "Returns hash of block in best-block-chain at <index>; index 0 is the genesis block.",
      "params": [
        {
          "name": "index",
          "description": "index of best-block-chain.index 0 is the genesis block",
          "required": true,
          "schema": {
            "type": "number”
          }
        }
      ],
      "result": {
        "name": "blockhash",
        "description": "The block hash is the hash of the parent block in the blockchain.",
        "schema": {
          "type": "string",
          "pattern": "[a-fA-F\\d]+$"
        }
      },
      "examples": [
        {
          "name": "getGenesisBlockHash",
          "description": "an example of requesting a block hash for genesis block 0",
          "params": [
            {
              "name": "genesisBlockIndex",
              "description": "index 0 is the genesis block",
              "value": 0
            }
          ],
          "result": {
            "name": "genesisBlockHash",
            "summary": "The hash of the genesis block",
            "description": "The hash of the genesis block has two more leading hex zeroes than were required for an early block.",
            "value": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"
          }
        }
      ]
    }
  ]
}
@skwp

This comment has been minimized.

Copy link

commented Apr 4, 2019

Concept is great, but OpenRPC looks like a pretty new thing (released feb 2019 by eth classic team?). Why not use gRPC (https://grpc.io) which is an industry standard at this point and has tooling for any number of languages? It seems to me that openrpc is reinventing that wheel, unless I'm missing something here.

Update: Nevermind, while grpc can support json encoding, it is not compatible with json-rpc 2.0. Nonetheless, my comment on not using something that just came out a month ago stands.

@jgarzik

This comment has been minimized.

Copy link
Contributor

commented Apr 4, 2019

@skwp It is a standard for reflection -- dynamically discovering JSON-RPC APIs -- something which is both missing and needed.

Agree with both your comments: (1) bitcoind could use a gRPC interface, and (2) OpenRPC is nice but brand new.

Reflection is a bit different from a schema description language (.proto) that is used to generate support for any number of programming languages. Both are useful. JSON-RPC in particular sorely needs dynamic discovery mechanisms like this.

@shanejonas

This comment has been minimized.

Copy link
Author

commented Apr 4, 2019

We saw a big gap in JSON-RPC tooling compared to gRPC and swagger.

OpenRPC fills that gap. I understand it’s a relatively new project but it’s roots are in swagger and OpenAPI, we’re benefiting from their dominance in interface definitions.

Going to gRPC or some other new flavour of the month tech sounds great in theory but in practice there are many blockchains built on JSON-RPC like Bitcoin and Ethereum and their many derivatives that can benefit today from modernized tooling like OpenRPC.

I hope that this process, and other chains, can help OpenRPC mature.

@shanejonas

This comment has been minimized.

Copy link
Author

commented Apr 4, 2019

@jgarzik this can definitely be used to generate support for many programming languages. As of now there is support for client generators for rust and typescript/javascript and plan on supporting many more languages.

other tooling built already includes documentation generation, mock-server, vscode extension and an interactive playground editor.

The idea is to gather support from Bitcoin, Ethereum, Ethereum Classic, and other chains to focus on the vision of levelling up the entire ecosystems tooling.

@luke-jr

This comment has been minimized.

Copy link
Member

commented Apr 4, 2019

Specific OpenRPC specifications for interfaces do make sense as part of BIPs for those interfaces, but I don't think OpenRPC itself does. It'd be like making a BIP for JSON, for JSON-RPC, for HTTP, etc. These things are used by Bitcoin software and BIPs, but they are broader in scope than Bitcoin.

@shanejonas

This comment has been minimized.

Copy link
Author

commented Apr 4, 2019

The benefit of JSON-RPC is that it’s transport agnostic. I think bitcoin only makes use of http, but ethereum provides JSON-RPC over IPC, HTTP, and web sockets.

The problem arises when you update or add methods, and don’t have an interface definition like this, downstream rpc clients painstakingly written by hand break. It is a major source of bugs between existing implementations of Ethereum clients, or in building new ones.

@luke-jr

This comment has been minimized.

Copy link
Member

commented Apr 4, 2019

My point is that the interface definition can be a BIP, but the format for the interface definitions is not.

@BelfordZ

This comment has been minimized.

Copy link

commented Apr 4, 2019

Firstly, thank you @luke-jr @jgarzik @skwp @MarcoFalke @promag For taking the time to look at this.

Apologies for not first reaching out on the mailing list. If you prefer, we may continue discussion there. However, I'd like to ensure that I've understood what is missing to make this a proper BIP:

Would you prefer the generated artifacts be documented, handled and generated from a different repository?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.