-
Notifications
You must be signed in to change notification settings - Fork 91
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add rooch's json-rpc quick start guide (#1050)
* add rpc summary contents * complete rpc guide * sync rpc en doc
- Loading branch information
1 parent
8066026
commit 503a105
Showing
6 changed files
with
122 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,10 +1,69 @@ | ||
# Rooch JSON-RPC | ||
|
||
In the blockchain network, the interaction between the client and the server is carried out through requests and responses. RPC (Remote Process Call) is a protocol for interaction between the client and the server. This protocol standardizes the data format when the client interacts with the server that implements the RPC interface. | ||
|
||
There are many RPC interface implementations on the market, such as `JSON-RPC`, `XML-RPC`, `Protobuf-RPC`, etc. Rooch adopts the JSON-RPC protocol specification. | ||
|
||
The caller writes the RPC request according to the RPC protocol specification. The client serializes the function name and parameters of the RPC interface. After sending it to the server, the server extracts the functions and parameters in the request through deserialization. The server calls Related functions and return the result of the call to the client. This is the general workflow of the RPC interface. | ||
|
||
## Type Conversions | ||
|
||
- `u64`, `u128`, `u256` are represented as strings in JSON. | ||
- `ObjectID` and `address` are represented in JSON as hexadecimal strings beginning with `0x`. | ||
|
||
## Reference | ||
## Examples | ||
|
||
Next, we will use a few small examples to demonstrate how to call Rooch's JSON-RPC interface. | ||
|
||
### rooch_getChainID | ||
|
||
`rooch_getChainID` This interface method is used to obtain the chain ID of Rooch. | ||
|
||
#### Using the command line program curl as a client | ||
|
||
```shell | ||
curl --location 'https://dev-seed.rooch.network/' --header 'Content-Type: application/json' --data '{ | ||
"jsonrpc": "2.0", | ||
"method": "rooch_getChainID", | ||
"params": [], | ||
"id": 0 | ||
}' | ||
``` | ||
|
||
`--location` specifies the node URL to request, which is Rooch's `dev` network node. | ||
|
||
`--header` specifies the header information of the request, such as specifying the data type in JSON format, etc. | ||
|
||
`--date` specifies that we want to request the **method name** and **parameters** in the RPC interface, which must be filled in in JSON data format. | ||
|
||
```shell | ||
{"jsonrpc":"2.0","result":"20230103","id":0} | ||
``` | ||
|
||
This is the response information returned in JSON format from the Rooch node after the RPC request. We focus on the `result` field, which is the execution result of the RPC. The chain ID number of Rooch's `dev` network is `20230103`. | ||
|
||
#### The client using the web page sends a request to the Rooch node | ||
|
||
Above we have introduced how to send RPC requests to Rooch nodes through the command line interface. Next, we will introduce how to use the web client provided by Rooch to send requests. | ||
|
||
![Web JSON-RPC Client](/docs/web-rpc-client.png) | ||
|
||
- Click Connect to use the web version of the [Rooch JSON-RPC](https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/rooch-network/rooch/main/crates/rooch-open-rpc-spec/schemas/openrpc.json) client. | ||
|
||
The `Methods` on the right side of the page are the callable RPC interfaces currently provided by Rooch. | ||
|
||
![](/docs/web-rpc-try.png) | ||
|
||
We click on the `rooch_getChainID` method, click the `TRY IT NOW` button, and the calling page will be displayed at the bottom of the page, as shown below. | ||
|
||
This web program is easier to use than the curl program, and provides a corresponding request template, which only requires us to fill in the necessary request information. | ||
|
||
![](/docs/web-rpc-run.png) | ||
|
||
- The first step is to fill in the node URL of the Rooch network. Here we use the `dev` node network: `https://dev-seed.rooch.network/` | ||
- The second step is to fill in the name of the RPC method to be called, for example: `rooch_getChainID` | ||
- The third step Click the Run button | ||
|
||
When the call is successful, you can see that the prompt on the right has responded successfully, and the corresponding response information is returned below, which is the same as the information returned by the `curl` command: | ||
|
||
- [Rooch RPC spec](https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/rooch-network/rooch/main/crates/rooch-open-rpc-spec/schemas/openrpc.json) | ||
![](/docs/web-rpc-ok.png) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,10 +1,69 @@ | ||
# Rooch JSON-RPC | ||
|
||
在区块链网络中,客户端和服务器端的交互都是通过请求与相应的方式进行的。RPC(Remote Process Call,远程过程调用)是一种客户端与服务器端交互的一种协议,这种协议规范了客户端和实现了 RPC 接口的服务器端交互时的数据格式。 | ||
|
||
市面上有众多的 RPC 接口实现,比如 `JSON-RPC`、`XML-RPC`、`Protobuf-RPC` 等等,Rooch 采用的是 JSON-RPC 的协议规范。 | ||
|
||
调用方按照 RPC 的协议规范编写好 RPC 请求,客户端将 RPC 接口的函数名称和参数进行序列化,发送到服务端后,服务器端通过反序列化将请求中的函数和参数提取出来,服务器调用相关函数并将调用的结果返回给客户端,这就是 RPC 接口的大致工作流程。 | ||
|
||
## 类型转换说明 | ||
|
||
- `u64`、`u128`、`u256` 在 JSON 中用 string 来表示。 | ||
- `ObjectID` 和 `address` 在 JSON 中用以 `0x` 开头的 hex string 来表示。 | ||
|
||
## 引用 | ||
## 示例 | ||
|
||
接下来通过几个小例子来演示如何调用 Rooch 的 JSON-RPC 接口。 | ||
|
||
### rooch_getChainID | ||
|
||
`rooch_getChainID` 这个接口方法是用来获取 Rooch 的链 ID 的。 | ||
|
||
#### 使用命令行程序 curl 作为客户端 | ||
|
||
```shell | ||
curl --location 'https://dev-seed.rooch.network/' --header 'Content-Type: application/json' --data '{ | ||
"jsonrpc": "2.0", | ||
"method": "rooch_getChainID", | ||
"params": [], | ||
"id": 0 | ||
}' | ||
``` | ||
|
||
`--location` 指定要请求的节点 URL,此处指定的是 Rooch 的 `dev` 网络节点。 | ||
|
||
`--header` 指定的是请求的头部信息,比如指定 JSON 格式的数据类型等。 | ||
|
||
`--date` 指定的就是我们要请求 RPC 接口中的**方法名**和**参数**等信息,这里要以 JSON 的数据格式来填写。 | ||
|
||
```shell | ||
{"jsonrpc":"2.0","result":"20230103","id":0} | ||
``` | ||
|
||
这是 RPC 请求后从 Rooch 节点以 JSON 格式返回的响应信息,我们重点关注 `result` 字段,即 RPC 的执行结果,Rooch 的 `dev` 网络的链 ID 号为 `20230103`。 | ||
|
||
#### 使用 Web 页面的客户端向 Rooch 节点发送请求 | ||
|
||
上面我们介绍了如何在命令行界面来向 Rooch 节点发送 RPC 请求,接下来将介绍如何使用 Rooch 提供的 Web 客户端来发送请求。 | ||
|
||
![Web JSON-RPC Client](/docs/web-rpc-client.png) | ||
|
||
- 点击连接,使用 Web 版本的 [Rooch JSON-RPC](https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/rooch-network/rooch/main/crates/rooch-open-rpc-spec/schemas/openrpc.json) 客户端。 | ||
|
||
页面右边的 `Methods` 是目前 Rooch 对外提供的可调用的 RPC 接口。 | ||
|
||
![](/docs/web-rpc-try.png) | ||
|
||
我们点开 `rooch_getChainID` 这个方法,点击 `TRY IT NOW` 按钮,就会在页面下方展示调用页面,如下图。 | ||
|
||
这个 Web 程序相比 curl 程序更易使用,而且提供了相应的请求模板,只需要我们填写必需的请求信息即可。 | ||
|
||
![](/docs/web-rpc-run.png) | ||
|
||
- 第一步,填写 Rooch 网络的节点 URL,这里使用 `dev` 节点网络:`https://dev-seed.rooch.network/` | ||
- 第二步,填写要调用的 RPC 方法名,比如:`rooch_getChainID` | ||
- 第三步,点击运行按钮 | ||
|
||
当调用成功后,可以看到右侧提示成功响应了,并在下方返回了相应的响应信息,跟 `curl` 命令返回的信息是一样的: | ||
|
||
- [Rooch RPC spec](https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/rooch-network/rooch/main/crates/rooch-open-rpc-spec/schemas/openrpc.json) | ||
![](/docs/web-rpc-ok.png) |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.