Core/grin
0
0
Fork 0
mirror of https://github.com/mimblewimble/grin.git synced 2025-02-01 17:01:09 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update stratum documentation (#1760)

Browse source
This commit is contained in:
Quentin Le Sceller 2018-10-16 19:31:57 -04:00 committed by Ignotus Peverell
parent 85433c659d
commit 67bc891455
1 changed files with 34 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

84
doc/stratum.md
View file

@ -22,7 +22,7 @@ In this section, we detail each message and the potential response.
At any point, if miner the tries to do one of the following request (except login) and login is required, the miner will receive the following error message. At any point, if miner the tries to do one of the following request (except login) and login is required, the miner will receive the following error message.
| Field | Content | | Field | Content |
| ------------- |:---------------------------------------:| | :------------ | :-------------------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | method sent by the miner | | method | method sent by the miner |
@ -45,7 +45,7 @@ Example:
if the request is not one of the following, the stratum server will give this error response: if the request is not one of the following, the stratum server will give this error response:
| Field | Content | | Field | Content |
| ------------- |:--------------------------------------------:| | :------------ | :------------------------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | method sent by the miner | | method | method sent by the miner |
@ -65,7 +65,7 @@ Example:
} }
``` ```
### ```getjobtemplate``` ### `getjobtemplate`
A message initiated by the miner. A message initiated by the miner.
Miner can request a job with this message. Miner can request a job with this message.
@ -73,7 +73,7 @@ Miner can request a job with this message.
#### Request #### Request
| Field | Content | | Field | Content |
| ------------- |:------------------------------:| | :------------ | :----------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "getjobtemplate" | | method | "getjobtemplate" |
@ -82,14 +82,12 @@ Miner can request a job with this message.
Example: Example:
``` JSON ``` JSON
{ {
"id":"2", "id":"2",
"jsonrpc":"2.0", "jsonrpc":"2.0",
"method":"getjobtemplate", "method":"getjobtemplate",
"params":null "params":null
} }
``` ```
#### Response #### Response
@ -101,7 +99,6 @@ The response can be of two types:
Example: Example:
``` JSON ``` JSON
{ {
"id":"0", "id":"0",
"jsonrpc":"2.0", "jsonrpc":"2.0",
@ -113,15 +110,14 @@ Example:
"pre_pow":"00010000000000003c4d0171369781424b39c81eb39de10cdf4a7cc27bbc6769203c7c9bc02cc6a1dfc6000000005b50f8210000000000395f123c6856055aab2369fe325c3d709b129dee5c96f2db60cdbc0dc123a80cb0b89e883ae2614f8dbd169888a95c0513b1ac7e069de82e5d479cf838281f7838b4bf75ea7c9222a1ad7406a4cab29af4e018c402f70dc8e9ef3d085169391c78741c656ec0f11f62d41b463c82737970afaa431c5cabb9b759cdfa52d761ac451276084366d1ba9efff2db9ed07eec1bcd8da352b32227f452dfa987ad249f689d9780000000000000b9e00000000000009954" "pre_pow":"00010000000000003c4d0171369781424b39c81eb39de10cdf4a7cc27bbc6769203c7c9bc02cc6a1dfc6000000005b50f8210000000000395f123c6856055aab2369fe325c3d709b129dee5c96f2db60cdbc0dc123a80cb0b89e883ae2614f8dbd169888a95c0513b1ac7e069de82e5d479cf838281f7838b4bf75ea7c9222a1ad7406a4cab29af4e018c402f70dc8e9ef3d085169391c78741c656ec0f11f62d41b463c82737970afaa431c5cabb9b759cdfa52d761ac451276084366d1ba9efff2db9ed07eec1bcd8da352b32227f452dfa987ad249f689d9780000000000000b9e00000000000009954"
} }
} }
```
```
##### Error response ##### Error response
If the node is syncing, it will send the following message: If the node is syncing, it will send the following message:
| Field | Content | | Field | Content |
| ------------- |:---------------------------------------------------------:| | :------------ | :-------------------------------------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "getjobtemplate" | | method | "getjobtemplate" |
@ -141,7 +137,7 @@ Example:
} }
``` ```
### ```job``` ### `job`
A message initiated by the Stratum server. A message initiated by the Stratum server.
Stratum server will send job automatically to connected miners. Stratum server will send job automatically to connected miners.
@ -150,16 +146,15 @@ The miner SHOULD interrupt current job if job_id = 0, and SHOULD replace the cur
#### Request #### Request
| Field | Content | | Field | Content |
| ------------- |:-------------------------------------------------------------------------:| | :------------ | :------------------------------------------------------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "job" | | method | "job" |
| params | Int ```difficulty```, ```height```, ```job_id``` and string ```pre_pow``` | | params | Int `difficulty`, `height`, `job_id` and string `pre_pow` |
Example: Example:
``` JSON ``` JSON
{ {
"id":"Stratum", "id":"Stratum",
"jsonrpc":"2.0", "jsonrpc":"2.0",
@ -171,21 +166,20 @@ Example:
"pre_pow":"00010000000000003ff723bc8c987b0c594794a0487e52260c5343288749c7e288de95a80afa558c5fb8000000005b51f15f00000000003cadef6a45edf92d2520bf45cbd4f36b5ef283c53d8266bbe9aa1b8daaa1458ce5578fcb0978b3995dd00e3bfc5a9277190bb9407a30d66aec26ff55a2b50214b22cdc1f3894f27374f568b2fe94d857b6b3808124888dd5eff7e8de7e451ac805a4ebd6551fa7a529a1b9f35f761719ed41bfef6ab081defc45a64a374dfd8321feac083741f29207b044071d93904986fa322df610e210c543c2f95522c9bdaef5f598000000000000c184000000000000a0cf" "pre_pow":"00010000000000003ff723bc8c987b0c594794a0487e52260c5343288749c7e288de95a80afa558c5fb8000000005b51f15f00000000003cadef6a45edf92d2520bf45cbd4f36b5ef283c53d8266bbe9aa1b8daaa1458ce5578fcb0978b3995dd00e3bfc5a9277190bb9407a30d66aec26ff55a2b50214b22cdc1f3894f27374f568b2fe94d857b6b3808124888dd5eff7e8de7e451ac805a4ebd6551fa7a529a1b9f35f761719ed41bfef6ab081defc45a64a374dfd8321feac083741f29207b044071d93904986fa322df610e210c543c2f95522c9bdaef5f598000000000000c184000000000000a0cf"
} }
} }
``` ```
#### Response #### Response
No response is required for this message. No response is required for this message.
### ```keepalive``` ### `keepalive`
A message initiated by the miner in order to keep the connection alive. A message initiated by the miner in order to keep the connection alive.
#### Request #### Request
| Field | Content | | Field | Content |
| ------------- |:----------------------:| | :------------ | :--------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "keepalive" | | method | "keepalive" |
@ -194,20 +188,18 @@ A message initiated by the miner in order to keep the connection alive.
Example: Example:
``` JSON ``` JSON
{ {
"id":"2", "id":"2",
"jsonrpc":"2.0", "jsonrpc":"2.0",
"method":"keepalive", "method":"keepalive",
"params":null "params":null
} }
``` ```
#### Response #### Response
| Field | Content | | Field | Content |
| ------------- |:------------------------------:| | :------------ | :----------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "keepalive" | | method | "keepalive" |
@ -217,7 +209,6 @@ Example:
Example: Example:
``` JSON ``` JSON
{ {
"id":"2", "id":"2",
"jsonrpc":"2.0", "jsonrpc":"2.0",
@ -225,10 +216,9 @@ Example:
"result":"ok", "result":"ok",
"error":null "error":null
} }
``` ```
### ```login``` ### `login`
*** ***
@ -238,7 +228,7 @@ Miner can log in on a Grin Stratum server with a login, password and agent (usua
#### Request #### Request
| Field | Content | | Field | Content |
| ------------- |:------------------------------:| | :------------ | :----------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "login" | | method | "login" |
@ -260,7 +250,6 @@ Example:
} }
``` ```
#### Response #### Response
The response can be of two types: The response can be of two types:
@ -268,7 +257,7 @@ The response can be of two types:
##### OK response ##### OK response
| Field | Content | | Field | Content |
| ------------- |:------------------------------:| | :------------ | :----------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "login" | | method | "login" |
@ -278,7 +267,6 @@ The response can be of two types:
Example: Example:
``` JSON ``` JSON
{ {
"id":"1", "id":"1",
"jsonrpc":"2.0", "jsonrpc":"2.0",
@ -286,14 +274,13 @@ Example:
"result":"ok", "result":"ok",
"error":null "error":null
} }
``` ```
##### Error response ##### Error response
Not yet implemented. Should return error -32500 "Login first". Not yet implemented. Should return error -32500 "Login first" when login is required.
### ```status``` ### `status`
A message initiated by the miner. A message initiated by the miner.
This message allows a miner to get the status of its current worker and the network. This message allows a miner to get the status of its current worker and the network.
@ -301,7 +288,7 @@ This message allows a miner to get the status of its current worker and the netw
#### Request #### Request
| Field | Content | | Field | Content |
| ------------- |:----------------------:| | :------------ | :--------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "status" | | method | "status" |
@ -310,14 +297,12 @@ This message allows a miner to get the status of its current worker and the netw
Example: Example:
``` JSON ``` JSON
{ {
"id":"2", "id":"2",
"jsonrpc":"2.0", "jsonrpc":"2.0",
"method":"status", "method":"status",
"params":null "params":null
} }
``` ```
#### Response #### Response
@ -325,11 +310,11 @@ Example:
The response is the following: The response is the following:
| Field | Content | | Field | Content |
| ------------- |:--------------------------------------------------------------------------------------------------------:| | :------------ | :------------------------------------------------------------------------------------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "status" | | method | "status" |
| result | String ```id```. Integers ```height```, ```difficulty```, ```accepted```, ```rejected``` and ```stale``` | | result | String `id`. Integers `height`, `difficulty`, `accepted`, `rejected` and `stale` |
| error | null | | error | null |
Example: Example:
@ -351,7 +336,7 @@ Example:
} }
``` ```
### ```submit``` ### `submit`
A message initiated by the miner. A message initiated by the miner.
When a miner find a share, it will submit it to the node. When a miner find a share, it will submit it to the node.
@ -361,21 +346,21 @@ When a miner find a share, it will submit it to the node.
The miner submit a solution to a job to the Stratum server. The miner submit a solution to a job to the Stratum server.
| Field | Content | | Field | Content |
| ------------- |:---------------------------------------------------------------------------:| | :------------ | :-------------------------------------------------------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "submit" | | method | "submit" |
| params | Int ```nonce```, ```height```, ```job_id``` and array of integers ```pow``` | | params | Int `edge_bits`,`nonce`, `height`, `job_id` and array of integers `pow` |
Example: Example:
``` JSON ``` JSON
{ {
"id":"0", "id":"0",
"jsonrpc":"2.0", "jsonrpc":"2.0",
"method":"submit", "method":"submit",
"params":{ "params":{
"edge_bits":29,
"height":16419, "height":16419,
"job_id":0, "job_id":0,
"nonce":8895699060858340771, "nonce":8895699060858340771,
@ -384,7 +369,6 @@ Example:
] ]
} }
} }
``` ```
#### Response #### Response
@ -393,10 +377,10 @@ The response can be of three types.
##### OK response ##### OK response
The share is accepted by the Stratum but is not a valid cuckoo solution at the network target difficulty. The share is accepted by the Stratum but is not a valid cuck(at)oo solution at the network target difficulty.
| Field | Content | | Field | Content |
| ------------- |:------------------------------:| | :------------ | :----------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "submit" | | method | "submit" |
@ -406,7 +390,6 @@ The share is accepted by the Stratum but is not a valid cuckoo solution at the n
Example: Example:
``` JSON ``` JSON
{ {
"id":"2", "id":"2",
"jsonrpc":"2.0", "jsonrpc":"2.0",
@ -414,15 +397,14 @@ Example:
"result":"ok", "result":"ok",
"error":null "error":null
} }
``` ```
##### Blockfound response ##### Blockfound response
The share is accepted by the Stratum and is a valid cuckoo solution at the network target difficulty. The share is accepted by the Stratum and is a valid cuck(at)oo solution at the network target difficulty.
| Field | Content | | Field | Content |
| ------------- |:------------------------------:| | :------------ | :----------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "submit" | | method | "submit" |
@ -432,7 +414,6 @@ The share is accepted by the Stratum and is a valid cuckoo solution at the netwo
Example: Example:
``` JSON ``` JSON
{ {
"id":"6", "id":"6",
"jsonrpc":"2.0", "jsonrpc":"2.0",
@ -440,7 +421,6 @@ Example:
"result":"blockfound - 23025af9032de812d15228121d5e4b0e977d30ad8036ab07131104787b9dcf10", "result":"blockfound - 23025af9032de812d15228121d5e4b0e977d30ad8036ab07131104787b9dcf10",
"error":null "error":null
} }
``` ```
##### Error response ##### Error response
@ -452,7 +432,7 @@ The error response can be of two types: stale and rejected.
The share is a valid solution to a previous job not the current one. The share is a valid solution to a previous job not the current one.
| Field | Content | | Field | Content |
| ------------- |:---------------------------------------------------------:| | :------------ | :-------------------------------------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "submit" | | method | "submit" |
@ -481,7 +461,7 @@ Two possibilities: the solution cannot be validated or the solution is of too lo
The submitted solution cannot be validated. The submitted solution cannot be validated.
| Field | Content | | Field | Content |
| ------------- |:---------------------------------------------------------:| | :------------ | :-------------------------------------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "submit" | | method | "submit" |
@ -506,7 +486,7 @@ Example:
The submitted solution is of too low difficulty. The submitted solution is of too low difficulty.
| Field | Content | | Field | Content |
| ------------- |:----------------------------------------------------------------:| | :------------ | :--------------------------------------------------------------- |
| id | ID of the request | | id | ID of the request |
| jsonrpc | "2.0" | | jsonrpc | "2.0" |
| method | "submit" | | method | "submit" |
@ -531,7 +511,7 @@ Example:
Grin Stratum protocol implementation contains the following error message: Grin Stratum protocol implementation contains the following error message:
| Error code | Error Message | | Error code | Error Message |
| ----------- |:--------------------------------------:| | :---------- | :------------------------------------- |
| -32000 | Node is syncing - please wait | | -32000 | Node is syncing - please wait |
| -32500 | Login first | | -32500 | Login first |
| -32501 | Share rejected due to low difficulty | | -32501 | Share rejected due to low difficulty |