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.
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 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?
I considered this:
layer: API/RPC type: standards track
If having a standard described interface for bitcoin doesn’t fit that category what would?
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.
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.
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.
here is just a concrete example of 1 method for Bitcoin:
0{
1 "openrpc": "1.0.0",
2 "info": {
3 "version": "0.0.1",
4 "title": "Bitcoin RPC API",
5 "description": "This API lets you interact with the blockchain via JSON-RPC"
6 },
7 "methods": [
8 {
9 "name": "getblockhash",
10 "summary": "Returns hash of block in best-block-chain at <index>",
11 "description": "Returns hash of block in best-block-chain at <index>; index 0 is the genesis block.",
12 "params": [
13 {
14 "name": "index",
15 "description": "index of best-block-chain.index 0 is the genesis block",
16 "required": true,
17 "schema": {
18 "type": "number”
19 }
20 }
21 ],
22 "result": {
23 "name": "blockhash",
24 "description": "The block hash is the hash of the parent block in the blockchain.",
25 "schema": {
26 "type": "string",
27 "pattern": "[a-fA-F\\d]+$"
28 }
29 },
30 "examples": [
31 {
32 "name": "getGenesisBlockHash",
33 "description": "an example of requesting a block hash for genesis block 0",
34 "params": [
35 {
36 "name": "genesisBlockIndex",
37 "description": "index 0 is the genesis block",
38 "value": 0
39 }
40 ],
41 "result": {
42 "name": "genesisBlockHash",
43 "summary": "The hash of the genesis block",
44 "description": "The hash of the genesis block has two more leading hex zeroes than were required for an early block.",
45 "value": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"
46 }
47 }
48 ]
49 }
50 ]
51}
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.
@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.
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.
@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.
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.
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?