Skip to content

Instantly share code, notes, and snippets.

@kilpatty

kilpatty/stratum.md

Last active February 12, 2020 21:21
Show Gist options
  • Save kilpatty/655b053196d76a66cf321f12b0404d5d to your computer and use it in GitHub Desktop.
Save kilpatty/655b053196d76a66cf321f12b0404d5d to your computer and use it in GitHub Desktop.
Download ZIP
Stratum Spec For Handshake (WIP)
Raw
stratum.md

Handshake Stratum RPC Protocol

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

Table of Contents

  1. Messages
    1. Pool Messages
      1. Login
      2. Subscribe
    2. Stratum Messages
      1. getjobtemplate
      2. job
      3. keepalive
      4. status
      5. submit
  2. Error Messages
  3. Miner Behavior

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 authorize) and authorize is required, the miner will receive the following error message.

Field Content
id ID of the request
method method sent by the miner
result null
error {"code":20,"message":"Not Authorized"}

Example:

{  
   "id":"10",
   "method":"notify",
   "error":{  
      "code":20,
      "message":"Not Authorized"
   }
}

if the request is not one of the following, the stratum server will give this error response:

Field Content
id ID of the request
method method sent by the miner
result null
error {"code":21,"message":"Method not found"}

Example:

{  
   "id":"10",
   "method":"getfreehns",
   "result": "null",
   "error":{  
      "code":21,
      "message":"Method not found"
   }
}

Pool Messages

Pool messages are those primarily dictated by the pool. Below we've included an initial template for what those messages would look like. It's important to note that these messages can technically be made different by each pool depending on what their authorize and subscribe workflow looks like.

authorize

A message initiated by the miner. Miner can log in on a Handshake Stratum server with a login and password. This request will return true or false if the authorize succeeded. An error is only returned if something else has gone wrong.

Request

Field Content
id ID of the request
method "authorize"
params ["login", "pass", "client"]

Example:

{  
   "id":"0",
   "method":"authorize",
   "params": ["login", "password", "client"],
}

Response

The response can be of two types:

OK response
Field Content
id ID of the request
method "authorize"
result true
error null

Example:

{  
   "id":"1",
   "method":"authorize",
   "result":true,
   "error":null
}
Error response

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

subscribe

A message initiated by the miner. Miner can subscribe to new work from a Handshake Stratum server with a client-id, and optional subscriber ID (to resume a previous session).

Request

Field Content
id ID of the request
method "subscribe"
params ["worker name", optional("sid"), optional("payout address")]

Example:

{  
   "id":"0",
   "method":"subscribe",
   "params":["worker name", "sid", "payout address"],
}

Response

The response can be of two types:

OK response
Field Content
id ID of the request
method "subscribe"
result "sid"
error null

Example:

{  
   "id":"1",
   "method":"subscribe",
   "result":"sid",
   "error":null
}
Error response

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

Stratum Messages

Stratj messages are those primarily dictated by the specific protocol.

notify

A message initiated by the server. Servers send miners new work through this message. TODO: inidicate clean jobs

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
}

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment