From 67bc8914558276fa26f6642be35a88f56c23323c Mon Sep 17 00:00:00 2001 From: Quentin Le Sceller Date: Tue, 16 Oct 2018 19:31:57 -0400 Subject: [PATCH] Update stratum documentation (#1760) --- doc/stratum.md | 88 +++++++++++++++++++------------------------------- 1 file changed, 34 insertions(+), 54 deletions(-) diff --git a/doc/stratum.md b/doc/stratum.md index 03375be04..c51b53ea5 100644 --- a/doc/stratum.md +++ b/doc/stratum.md @@ -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. | Field | Content | -| ------------- |:---------------------------------------:| +| :------------ | :-------------------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | 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: | Field | Content | -| ------------- |:--------------------------------------------:| +| :------------ | :------------------------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | method sent by the miner | @@ -65,7 +65,7 @@ Example: } ``` -### ```getjobtemplate``` +### `getjobtemplate` A message initiated by the miner. Miner can request a job with this message. @@ -73,7 +73,7 @@ Miner can request a job with this message. #### Request | Field | Content | -| ------------- |:------------------------------:| +| :------------ | :----------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "getjobtemplate" | @@ -82,14 +82,12 @@ Miner can request a job with this message. Example: ``` JSON - { "id":"2", "jsonrpc":"2.0", "method":"getjobtemplate", "params":null } - ``` #### Response @@ -101,7 +99,6 @@ The response can be of two types: Example: ``` JSON - { "id":"0", "jsonrpc":"2.0", @@ -113,15 +110,14 @@ Example: "pre_pow":"00010000000000003c4d0171369781424b39c81eb39de10cdf4a7cc27bbc6769203c7c9bc02cc6a1dfc6000000005b50f8210000000000395f123c6856055aab2369fe325c3d709b129dee5c96f2db60cdbc0dc123a80cb0b89e883ae2614f8dbd169888a95c0513b1ac7e069de82e5d479cf838281f7838b4bf75ea7c9222a1ad7406a4cab29af4e018c402f70dc8e9ef3d085169391c78741c656ec0f11f62d41b463c82737970afaa431c5cabb9b759cdfa52d761ac451276084366d1ba9efff2db9ed07eec1bcd8da352b32227f452dfa987ad249f689d9780000000000000b9e00000000000009954" } } - - ``` +``` ##### Error response If the node is syncing, it will send the following message: | Field | Content | -| ------------- |:---------------------------------------------------------:| +| :------------ | :-------------------------------------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "getjobtemplate" | @@ -141,7 +137,7 @@ Example: } ``` -### ```job``` +### `job` A message initiated by the Stratum server. 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 | Field | Content | -| ------------- |:-------------------------------------------------------------------------:| +| :------------ | :------------------------------------------------------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "job" | -| params | Int ```difficulty```, ```height```, ```job_id``` and string ```pre_pow``` | +| params | Int `difficulty`, `height`, `job_id` and string `pre_pow` | Example: ``` JSON - { "id":"Stratum", "jsonrpc":"2.0", @@ -171,21 +166,20 @@ Example: "pre_pow":"00010000000000003ff723bc8c987b0c594794a0487e52260c5343288749c7e288de95a80afa558c5fb8000000005b51f15f00000000003cadef6a45edf92d2520bf45cbd4f36b5ef283c53d8266bbe9aa1b8daaa1458ce5578fcb0978b3995dd00e3bfc5a9277190bb9407a30d66aec26ff55a2b50214b22cdc1f3894f27374f568b2fe94d857b6b3808124888dd5eff7e8de7e451ac805a4ebd6551fa7a529a1b9f35f761719ed41bfef6ab081defc45a64a374dfd8321feac083741f29207b044071d93904986fa322df610e210c543c2f95522c9bdaef5f598000000000000c184000000000000a0cf" } } - ``` #### Response No response is required for this message. -### ```keepalive``` +### `keepalive` A message initiated by the miner in order to keep the connection alive. #### Request | Field | Content | -| ------------- |:----------------------:| +| :------------ | :--------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "keepalive" | @@ -194,20 +188,18 @@ A message initiated by the miner in order to keep the connection alive. Example: ``` JSON - { "id":"2", "jsonrpc":"2.0", "method":"keepalive", "params":null } - ``` #### Response | Field | Content | -| ------------- |:------------------------------:| +| :------------ | :----------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "keepalive" | @@ -217,7 +209,6 @@ Example: Example: ``` JSON - { "id":"2", "jsonrpc":"2.0", @@ -225,10 +216,9 @@ Example: "result":"ok", "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 | Field | Content | -| ------------- |:------------------------------:| +| :------------ | :----------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "login" | @@ -260,7 +250,6 @@ Example: } ``` - #### Response The response can be of two types: @@ -268,7 +257,7 @@ The response can be of two types: ##### OK response | Field | Content | -| ------------- |:------------------------------:| +| :------------ | :----------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "login" | @@ -278,7 +267,6 @@ The response can be of two types: Example: ``` JSON - { "id":"1", "jsonrpc":"2.0", @@ -286,14 +274,13 @@ Example: "result":"ok", "error":null } - ``` ##### 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. 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 | Field | Content | -| ------------- |:----------------------:| +| :------------ | :--------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "status" | @@ -310,14 +297,12 @@ This message allows a miner to get the status of its current worker and the netw Example: ``` JSON - { "id":"2", "jsonrpc":"2.0", "method":"status", "params":null } - ``` #### Response @@ -325,11 +310,11 @@ Example: The response is the following: | Field | Content | -| ------------- |:--------------------------------------------------------------------------------------------------------:| +| :------------ | :------------------------------------------------------------------------------------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "status" | -| result | String ```id```. Integers ```height```, ```difficulty```, ```accepted```, ```rejected``` and ```stale``` | +| result | String `id`. Integers `height`, `difficulty`, `accepted`, `rejected` and `stale` | | error | null | Example: @@ -351,7 +336,7 @@ Example: } ``` -### ```submit``` +### `submit` A message initiated by the miner. 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. | Field | Content | -| ------------- |:---------------------------------------------------------------------------:| +| :------------ | :-------------------------------------------------------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | 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: ``` JSON - -{ +{ "id":"0", "jsonrpc":"2.0", "method":"submit", - "params":{ + "params":{ + "edge_bits":29, "height":16419, "job_id":0, "nonce":8895699060858340771, @@ -384,7 +369,6 @@ Example: ] } } - ``` #### Response @@ -393,10 +377,10 @@ The response can be of three types. ##### 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 | -| ------------- |:------------------------------:| +| :------------ | :----------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "submit" | @@ -406,7 +390,6 @@ The share is accepted by the Stratum but is not a valid cuckoo solution at the n Example: ``` JSON - { "id":"2", "jsonrpc":"2.0", @@ -414,15 +397,14 @@ Example: "result":"ok", "error":null } - ``` ##### 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 | -| ------------- |:------------------------------:| +| :------------ | :----------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "submit" | @@ -432,7 +414,6 @@ The share is accepted by the Stratum and is a valid cuckoo solution at the netwo Example: ``` JSON - { "id":"6", "jsonrpc":"2.0", @@ -440,7 +421,6 @@ Example: "result":"blockfound - 23025af9032de812d15228121d5e4b0e977d30ad8036ab07131104787b9dcf10", "error":null } - ``` ##### 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. | Field | Content | -| ------------- |:---------------------------------------------------------:| +| :------------ | :-------------------------------------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | 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. | Field | Content | -| ------------- |:---------------------------------------------------------:| +| :------------ | :-------------------------------------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "submit" | @@ -506,7 +486,7 @@ Example: The submitted solution is of too low difficulty. | Field | Content | -| ------------- |:----------------------------------------------------------------:| +| :------------ | :--------------------------------------------------------------- | | id | ID of the request | | jsonrpc | "2.0" | | method | "submit" | @@ -531,7 +511,7 @@ Example: Grin Stratum protocol implementation contains the following error message: | Error code | Error Message | -| ----------- |:--------------------------------------:| +| :---------- | :------------------------------------- | | -32000 | Node is syncing - please wait | | -32500 | Login first | | -32501 | Share rejected due to low difficulty |