mirror of
https://github.com/mimblewimble/grin.git
synced 2025-01-21 03:21:08 +03:00
a73a54a10e
* Create grin4bitcoiners_ZH-CN * Rename grin4bitcoiners_ZH-CN to grin4bitcoiners_ZH-CN.md * Create contract_ideas_ZH-CN.md Chinese translation * Create coinbase_maturity_ZH-CN.md * Create contracts_ZH-CN.md * Create stratum_ZH-CN.md * Create switch_commitment_ZH-CN.md * Create table_of_contents_ZH-CN.md * Update contracts_ZH-CN.md * Update contracts.md * Chinese Translation added * Update coinbase_maturity_ZH-CN.md * Update coinbase_maturity.md * Update switch_commitment_ZH-CN.md * Update switch_commitment.md * Update switch_commitment_ZH-CN.md * Update switch_commitment_ZH-CN.md * Update contracts_ZH-CN.md * Update coinbase_maturity_ZH-CN.md * Update table_of_contents_ZH-CN.md * Create table_of_contents.md * Delete table_of_contents_.md * Update switch_commitment_ZH-CN.md * Update stratum_ZH-CN.md * Update stratum.md * Update coinbase_maturity_ZH-CN.md * Update coinbase_maturity_ZH-CN.md * Update contracts_ZH-CN.md * Update switch_commitment_ZH-CN.md
534 lines
15 KiB
Markdown
534 lines
15 KiB
Markdown
# Grin Stratum RPC 协议
|
||
|
||
*阅读其它语言版本: [Korean](stratum_KR.md)，[English](stratum.md).*
|
||
|
||
本文说明在 Grin 部署目前的 Stratum RPC 协议。
|
||
|
||
## 目录
|
||
|
||
1. [信息](#messages)
|
||
1. [获得工作模板](#getjobtemplate)
|
||
1. [工作](#job)
|
||
1. [保持在线](#keepalive)
|
||
1. [登录](#login)
|
||
1. [状态](#status)
|
||
1. [提交](#submit)
|
||
1. [错误信息](#error-messages)
|
||
1. [矿工行为](#miner-behavior)
|
||
1. [参考部署](#reference-implementation)
|
||
|
||
## 信息
|
||
|
||
本节我们讨论每种信息和可能的回复。
|
||
|
||
如果矿工随时最初以下请求（登录除外），且需要登录，矿工会收到以下错误信息。
|
||
|
||
| 栏位 | 内容 |
|
||
| :------ | :--------------------------------------- |
|
||
| id | ID of the request（提出请求的 ID） |
|
||
| jsonrpc | "2.0" |
|
||
| method | method sent by the miner（矿工发送方法） |
|
||
| error | {"code":-32500,"message":"login first"} |
|
||
|
||
范例：
|
||
|
||
```JSON
|
||
{
|
||
"id":"10",
|
||
"jsonrpc":"2.0",
|
||
"method":"getjobtemplate",
|
||
"error":{
|
||
"code":-32500,
|
||
"message":"login first"
|
||
}
|
||
}
|
||
```
|
||
|
||
如果不是如下请求，stratum 服务器会返回错误回复：
|
||
|
||
| Field | Content |
|
||
| :------ | :------------------------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | method sent by the miner |
|
||
| error | {"code":-32601,"message":"Method not found"} |
|
||
|
||
范例：
|
||
|
||
```JSON
|
||
{
|
||
"id":"10",
|
||
"jsonrpc":"2.0",
|
||
"method":"getgrins",
|
||
"error":{
|
||
"code":-32601,
|
||
"message":"Method not found"
|
||
}
|
||
}
|
||
```
|
||
|
||
### `getjobtemplate`
|
||
|
||
矿工发起的信息。
|
||
矿工可以这一信息申请工作。
|
||
|
||
#### 请求
|
||
|
||
| Field栏位 | Content |
|
||
| :-------- | :---------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "getjobtemplate" |
|
||
| params | null |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"2",
|
||
"jsonrpc":"2.0",
|
||
"method":"getjobtemplate",
|
||
"params":null
|
||
}
|
||
```
|
||
|
||
#### 回复
|
||
|
||
回复可分为两种类型：
|
||
|
||
##### 确认回复
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"0",
|
||
"jsonrpc":"2.0",
|
||
"method":"getjobtemplate",
|
||
"result":{
|
||
"difficulty":1,
|
||
"height":13726,
|
||
"job_id":4,
|
||
"pre_pow":"00010000000000003c4d0171369781424b39c81eb39de10cdf4a7cc27bbc6769203c7c9bc02cc6a1dfc6000000005b50f8210000000000395f123c6856055aab2369fe325c3d709b129dee5c96f2db60cdbc0dc123a80cb0b89e883ae2614f8dbd169888a95c0513b1ac7e069de82e5d479cf838281f7838b4bf75ea7c9222a1ad7406a4cab29af4e018c402f70dc8e9ef3d085169391c78741c656ec0f11f62d41b463c82737970afaa431c5cabb9b759cdfa52d761ac451276084366d1ba9efff2db9ed07eec1bcd8da352b32227f452dfa987ad249f689d9780000000000000b9e00000000000009954"
|
||
}
|
||
}
|
||
```
|
||
|
||
##### 错误回复
|
||
|
||
如果节点在同步，会发送如下信息：
|
||
|
||
| Field | Content |
|
||
| :------------ | :-------------------------------------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "getjobtemplate" |
|
||
| error | {"code":-32701,"message":"Node is syncing - Please wait"} |
|
||
|
||
范例：
|
||
|
||
```JSON
|
||
{
|
||
"id":"10",
|
||
"jsonrpc":"2.0",
|
||
"method":"getjobtemplate",
|
||
"error":{
|
||
"code":-32000,
|
||
"message":"Node is syncing - Please wait"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 工作
|
||
|
||
Stratum 服务器发起新消息。Stratum 服务器会自动发送工作给连接的矿工。如果 `job_id = 0` 矿工应该切断目前的工作，并且目前的图形完成后用这一个代替现有工作。
|
||
|
||
#### 请求
|
||
|
||
| Field | Content |
|
||
| :------------ | :------------------------------------------------------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "job" |
|
||
| params | Int `difficulty`, `height`, `job_id` and string `pre_pow` |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"Stratum",
|
||
"jsonrpc":"2.0",
|
||
"method":"job",
|
||
"params":{
|
||
"difficulty":1,
|
||
"height":16375,
|
||
"job_id":5,
|
||
"pre_pow":"00010000000000003ff723bc8c987b0c594794a0487e52260c5343288749c7e288de95a80afa558c5fb8000000005b51f15f00000000003cadef6a45edf92d2520bf45cbd4f36b5ef283c53d8266bbe9aa1b8daaa1458ce5578fcb0978b3995dd00e3bfc5a9277190bb9407a30d66aec26ff55a2b50214b22cdc1f3894f27374f568b2fe94d857b6b3808124888dd5eff7e8de7e451ac805a4ebd6551fa7a529a1b9f35f761719ed41bfef6ab081defc45a64a374dfd8321feac083741f29207b044071d93904986fa322df610e210c543c2f95522c9bdaef5f598000000000000c184000000000000a0cf"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 回复
|
||
|
||
本消息不需要回复
|
||
|
||
### 保持在线
|
||
|
||
为保持在线，矿工发起消息。
|
||
|
||
#### 请求
|
||
|
||
| Field | Content |
|
||
| :------------ | :--------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "keepalive" |
|
||
| params | null |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"2",
|
||
"jsonrpc":"2.0",
|
||
"method":"keepalive",
|
||
"params":null
|
||
}
|
||
```
|
||
|
||
#### 回复
|
||
|
||
| Field | Content |
|
||
| :------------ | :----------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "keepalive" |
|
||
| result | "ok" |
|
||
| error | null |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"2",
|
||
"jsonrpc":"2.0",
|
||
"method":"keepalive",
|
||
"result":"ok",
|
||
"error":null
|
||
}
|
||
```
|
||
|
||
### 登录
|
||
|
||
***
|
||
|
||
矿工发起消息。矿工用用户名、密码和代理（通常由矿工程序设置）登录 Grin Stratum 服务器。
|
||
|
||
#### 请求
|
||
|
||
| Field | Content |
|
||
| :------------ | :----------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "login" |
|
||
| params | Strings: login, pass and agent |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
|
||
{
|
||
"id":"0",
|
||
"jsonrpc":"2.0",
|
||
"method":"login",
|
||
"params":{
|
||
"login":"login",
|
||
"pass":"password",
|
||
"agent":"grin-miner"
|
||
}
|
||
}
|
||
|
||
```
|
||
#### 回复
|
||
|
||
回复可为两种类型：
|
||
|
||
##### 确认回复
|
||
|
||
| Field | Content |
|
||
| :------------ | :----------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "login" |
|
||
| result | "ok" |
|
||
| error | null |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"1",
|
||
"jsonrpc":"2.0",
|
||
"method":"login",
|
||
"result":"ok",
|
||
"error":null
|
||
}
|
||
```
|
||
|
||
##### 错误回复
|
||
|
||
未部署。应该返回`error -32500`，若需要登录，“首先登录”。
|
||
|
||
### 状态
|
||
|
||
矿工发起消息。本消息允许矿工获得目前矿工和网络状态。
|
||
|
||
#### 请求
|
||
|
||
| Field | Content |
|
||
| :------------ | :--------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "status" |
|
||
| params | null |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"2",
|
||
"jsonrpc":"2.0",
|
||
"method":"status",
|
||
"params":null
|
||
}
|
||
```
|
||
|
||
#### 回复
|
||
|
||
回复如下
|
||
|
||
| Field | Content |
|
||
| :------------ | :------------------------------------------------------------------------------------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "status" |
|
||
| result | String `id`. Integers `height`, `difficulty`, `accepted`, `rejected` and `stale` |
|
||
| error | null |
|
||
|
||
范例：
|
||
|
||
```JSON
|
||
{
|
||
"id":"5",
|
||
"jsonrpc":"2.0",
|
||
"method":"status",
|
||
"result":{
|
||
"id":"5",
|
||
"height":13726,
|
||
"difficulty":1,
|
||
"accepted":0,
|
||
"rejected":0,
|
||
"stale":0
|
||
},
|
||
"error":null
|
||
}
|
||
```
|
||
|
||
### 提交
|
||
|
||
矿工发起消息。矿工挖到一份，会提交给节点。
|
||
|
||
#### 请求
|
||
|
||
矿工向 Stratum 服务器提交工作解决方案。
|
||
|
||
| Field | Content |
|
||
| :------------ | :-------------------------------------------------------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "submit" |
|
||
| params | Int `edge_bits`,`nonce`, `height`, `job_id` and array of integers `pow` |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"0",
|
||
"jsonrpc":"2.0",
|
||
"method":"submit",
|
||
"params":{
|
||
"edge_bits":29,
|
||
"height":16419,
|
||
"job_id":0,
|
||
"nonce":8895699060858340771,
|
||
"pow":[
|
||
4210040,10141596,13269632,24291934,28079062,84254573,84493890,100560174,100657333,120128285,130518226,140371663,142109188,159800646,163323737,171019100,176840047,191220010,192245584,198941444,209276164,216952635,217795152,225662613,230166736,231315079,248639876,263910393,293995691,298361937,326412694,330363619,414572127,424798984,426489226,466671748,466924466,490048497,495035248,496623057,502828197, 532838434
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 回复
|
||
|
||
回复可为三种类型。
|
||
|
||
##### 确认回复
|
||
|
||
Stratum 接受份额，但不是目前网络目标难度的有效 cuck(at)oo 解决方案。
|
||
|
||
| Field | Content |
|
||
| :------------ | :----------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "submit" |
|
||
| result | "ok" |
|
||
| error | null |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"2",
|
||
"jsonrpc":"2.0",
|
||
"method":"submit",
|
||
"result":"ok",
|
||
"error":null
|
||
}
|
||
```
|
||
|
||
##### 发现区块回复
|
||
|
||
份额被 Stratum 接受，是目前网络目标难度的有效 cuck(at)oo 解决方案。
|
||
|
||
| Field | Content |
|
||
| :------------ | :----------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "submit" |
|
||
| result | "block - " + hash of the block |
|
||
| error | null |
|
||
|
||
范例：
|
||
|
||
``` JSON
|
||
{
|
||
"id":"6",
|
||
"jsonrpc":"2.0",
|
||
"method":"submit",
|
||
"result":"blockfound - 23025af9032de812d15228121d5e4b0e977d30ad8036ab07131104787b9dcf10",
|
||
"error":null
|
||
}
|
||
```
|
||
|
||
##### 错误回复
|
||
|
||
错误回复有两种类型：过期和被拒绝。
|
||
|
||
##### 过期份额错误回复
|
||
|
||
份额是上一工作而不是目前工作的有效解决方案。
|
||
|
||
| Field | Content |
|
||
| :------------ | :-------------------------------------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "submit" |
|
||
| error | {"code":-32503,"message":"Solution submitted too late"} |
|
||
|
||
范例：
|
||
|
||
```JSON
|
||
{
|
||
"id":"5",
|
||
"jsonrpc":"2.0",
|
||
"method":"submit",
|
||
"error":{
|
||
"code":-32503,
|
||
"message":"Solution submitted too late"
|
||
}
|
||
}
|
||
```
|
||
|
||
##### 拒绝份额错误回复
|
||
|
||
两种可能：解决方案无效或解决方案难度太低。
|
||
|
||
###### 未能验证解决方案错误
|
||
|
||
提交的解决方案无法验证。
|
||
|
||
| Field | Content |
|
||
| :------------ | :-------------------------------------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "submit" |
|
||
| error | {"code":-32502,"message":"Failed to validate solution"} |
|
||
|
||
范例：
|
||
|
||
```JSON
|
||
{
|
||
"id":"5",
|
||
"jsonrpc":"2.0",
|
||
"method":"submit",
|
||
"error":{
|
||
"code":-32502,
|
||
"message":"Failed to validate solution"
|
||
}
|
||
}
|
||
```
|
||
|
||
###### 因低难度错误份额拒绝
|
||
|
||
提交的解决方案难度太低。
|
||
|
||
| Field | Content |
|
||
| :------------ | :--------------------------------------------------------------- |
|
||
| id | ID of the request |
|
||
| jsonrpc | "2.0" |
|
||
| method | "submit" |
|
||
| error | {"code":-32501,"message":"Share rejected due to low difficulty"} |
|
||
|
||
范例：
|
||
|
||
```JSON
|
||
{
|
||
"id":"5",
|
||
"jsonrpc":"2.0",
|
||
"method":"submit",
|
||
"error":{
|
||
"code":-32501,
|
||
"message":"Share rejected due to low difficulty"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 错误信息
|
||
|
||
Grin Stratum 协议部署包含以下错误信息：
|
||
|
||
| Error code | Error Message |
|
||
| :---------- | :------------------------------------- |
|
||
| -32000 | Node is syncing - please wait |
|
||
| -32500 | Login first |
|
||
| -32501 | Share rejected due to low difficulty |
|
||
| -32502 | Failed to validate solution |
|
||
| -32503 | Solution Submitted too late |
|
||
| -32600 | Invalid Request |
|
||
| -32601 | Method not found |
|
||
|
||
## 矿工行为准则
|
||
|
||
矿工须遵守以下规则：
|
||
|
||
- 矿工开始挖矿前需要随机算工作随机数
|
||
- 矿工必须一直进行相同工作，直到服务器发送新的，尽管矿工有可能随时申请工作
|
||
- 矿工不得从服务器给工作请求发送 RPC 回复
|
||
- 矿工可设置 RPC "id" 并获得回复
|
||
- 矿工可发送保持在线信息
|
||
- 矿工可发送登录请求（确认哪个矿工在历史记录发现份额 / 解决方案），登录请求必须有三个参数
|
||
- 矿工提交信息必须提供 job_id
|
||
|
||
## 部署参考
|
||
|
||
挖矿部署请参阅：[mimblewimble/grin-miner](https://github.com/mimblewimble/grin-miner/blob/master/src/bin/client.rs)
|