Skip to content

Latest commit

 

History

History
539 lines (418 loc) · 15.7 KB

stratum.md

File metadata and controls

539 lines (418 loc) · 15.7 KB

Grin Stratum RPC Protocol

Read this in other languages: Korean.

This document describes the current Stratum RPC protocol implemented in Grin.

Table of Contents

  1. Messages
    1. getjobtemplate
    2. job
    3. keepalive
    4. login
    5. status
    6. submit
  2. Error Messages
  3. Miner Behavior
  4. Reference Implementation

Messages

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
error {"code":-32500,"message":"login first"}

Example:

{  
   "id":"10",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "error":{  
      "code":-32500,
      "message":"login first"
   }
}

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
error {"code":-32601,"message":"Method not found"}

Example:

{  
   "id":"10",
   "jsonrpc":"2.0",
   "method":"getgrins",
   "error":{  
      "code":-32601,
      "message":"Method not found"
   }
}

getjobtemplate

A message initiated by the miner. Miner can request a job with this message.

Request

Field Content
id ID of the request
jsonrpc "2.0"
method "getjobtemplate"
params null

Example:

{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "params":null
}

Response

The response can be of two types:

OK response

Example:

{  
   "id":"0",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "result":{  
      "difficulty":1,
      "height":13726,
      "job_id":4,
      "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"
error {"code":-32701,"message":"Node is syncing - Please wait"}

Example:

{  
   "id":"10",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "error":{  
      "code":-32000,
      "message":"Node is syncing - Please wait"
   }
}

job

A message initiated by the Stratum server. Stratum server will send job automatically to connected miners. The miner SHOULD interrupt current job if job_id = 0, and SHOULD replace the current job with this one after the current graph is complete.

Request

Field Content
id ID of the request
jsonrpc "2.0"
method "job"
params Int difficulty, height, job_id and string pre_pow

Example:

{  
   "id":"Stratum",
   "jsonrpc":"2.0",
   "method":"job",
   "params":{  
      "difficulty":1,
      "height":16375,
      "job_id":5,
      "pre_pow":"00010000000000003ff723bc8c987b0c594794a0487e52260c5343288749c7e288de95a80afa558c5fb8000000005b51f15f00000000003cadef6a45edf92d2520bf45cbd4f36b5ef283c53d8266bbe9aa1b8daaa1458ce5578fcb0978b3995dd00e3bfc5a9277190bb9407a30d66aec26ff55a2b50214b22cdc1f3894f27374f568b2fe94d857b6b3808124888dd5eff7e8de7e451ac805a4ebd6551fa7a529a1b9f35f761719ed41bfef6ab081defc45a64a374dfd8321feac083741f29207b044071d93904986fa322df610e210c543c2f95522c9bdaef5f598000000000000c184000000000000a0cf"
   }
}

Response

No response is required for this message.

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"
params null

Example:

{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"keepalive",
   "params":null
}

Response

Field Content
id ID of the request
jsonrpc "2.0"
method "keepalive"
result "ok"
error null

Example:

{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"keepalive",
   "result":"ok",
   "error":null
}

login

A message initiated by the miner. Miner can log in on a Grin Stratum server with a login, password and agent (usually statically set by the miner program).

Request

Field Content
id ID of the request
jsonrpc "2.0"
method "login"
params Strings: login, pass and agent

Example:

{  
   "id":"0",
   "jsonrpc":"2.0",
   "method":"login",
   "params":{  
      "login":"login",
      "pass":"password",
      "agent":"grin-miner"
   }
}

Response

The response can be of two types:

OK response
Field Content
id ID of the request
jsonrpc "2.0"
method "login"
result "ok"
error null

Example:

{  
   "id":"1",
   "jsonrpc":"2.0",
   "method":"login",
   "result":"ok",
   "error":null
}
Error response

Not yet implemented. Should return error -32500 "Login first" when login is required.

status

A message initiated by the miner. This message allows a miner to get the status of its current worker and the network.

Request

Field Content
id ID of the request
jsonrpc "2.0"
method "status"
params null

Example:

{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"status",
   "params":null
}

Response

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
error null

Example:

{  
   "id":"5",
   "jsonrpc":"2.0",
   "method":"status",
   "result":{  
      "id":"5",
      "height":13726,
      "difficulty":1,
      "accepted":0,
      "rejected":0,
      "stale":0
   },
   "error":null
}

submit

A message initiated by the miner. When a miner find a share, it will submit it to the node.

Request

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 edge_bits,nonce, height, job_id and array of integers pow

Example:

{
   "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
         ]
   }
}

Response

The response can be of three types.

OK response

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"
result "ok"
error null

Example:

{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"submit",
   "result":"ok",
   "error":null
}
Blockfound response

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"
result "block - " + hash of the block
error null

Example:

{  
   "id":"6",
   "jsonrpc":"2.0",
   "method":"submit",
   "result":"blockfound - 23025af9032de812d15228121d5e4b0e977d30ad8036ab07131104787b9dcf10",
   "error":null
}
Error response

The error response can be of two types: stale and rejected.

Stale share error response

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"
error {"code":-32503,"message":"Solution submitted too late"}

Example:

{  
   "id":"5",
   "jsonrpc":"2.0",
   "method":"submit",
   "error":{  
      "code":-32503,
      "message":"Solution submitted too late"
   }
}
Rejected share error responses

Two possibilities: the solution cannot be validated or the solution is of too low difficulty.

Failed to validate solution error

The submitted solution cannot be validated.

Field Content
id ID of the request
jsonrpc "2.0"
method "submit"
error {"code":-32502,"message":"Failed to validate solution"}

Example:

{  
   "id":"5",
   "jsonrpc":"2.0",
   "method":"submit",
   "error":{  
      "code":-32502,
      "message":"Failed to validate solution"
   }
}
Share rejected due to low difficulty error

The submitted solution is of too low difficulty.

Field Content
id ID of the request
jsonrpc "2.0"
method "submit"
error {"code":-32501,"message":"Share rejected due to low difficulty"}

Example:

{  
   "id":"5",
   "jsonrpc":"2.0",
   "method":"submit",
   "error":{  
      "code":-32501,
      "message":"Share rejected due to low difficulty"
   }
}

Error Messages

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
-32502 Failed to validate solution
-32503 Solution Submitted too late
-32600 Invalid Request
-32601 Method not found

Miner behavior

Miners SHOULD, MAY or MUST respect the following rules:

  • Miners SHOULD randomize the job nonce before starting
  • Miners MUST continue mining the same job until the server sends a new one, though a miner MAY request a new job at any time
  • Miners MUST NOT send an rpc response to a job request from the server
  • Miners MAY set the RPC "id" and expect responses to have that same id
  • Miners MAY send a keepalive message
  • Miners MAY send a login request (to identify which miner finds shares / solutions in the logs), the login request MUST have all 3 params.
  • Miners MUST return the supplied job_id with submit messages.

Reference Implementation

The current reference implementation is available at mimblewimble/grin-miner.