Stratum Protocol Documentation

Protocol Flow Examples

Non AsicBoost

AsicBoost

Client Server
| |

Errors

Whenever an RPC call triggers an error, the response MUST include an `error`
field which maps to a **list** of the following values:

- [ `code` : `int` ]
- [ `message` : `string` ]
- [ `data` : `object` ]

```
{"id": 10, "result": null, "error": [21, "Job not found", null]}
```

Errors SHOULD be identified by their `code` and programs SHOULD do error
handling based on the `code` and not the `message`.
Available error codes, in addition to the codes defined in the [JSON RPC 2.0]() specification, are:

- `20` - Other/Unknown
- `21` - Job not found (=stale)
- `22` - Duplicate share
- `23` - Low difficulty share
- `24` - Unauthorized worker
- `25` - Not subscribed

The `message` field SHOULD be a concise description of the error for human
consumption.

Implementors MAY choose to include an optional `data` object with additional
information relevant to the error.

Methods

### mining.configure

In order to allow easier upgrades in the future, a client MAY send a
configuration as its initial messages to the server, specifying possible
extensions it supports.
The specific mechanism is described by [slushpool here](https://github.com/slushpool/stratumprotocol/blob/master/stratum-extensions.mediawiki)

A client MAY choose to skip this message, which a server SHOULD interpret as the
client adhering to the protocol as described in this document, without any
further extensions.

This method call will only be executed by clients.


### mining.subscribe

In order to initiate or resume a session with the server, a client needs to
call the subscribe method.

This method call will only be executed by clients.


#### Request:

```
{"id": 1, "method": "mining.subscribe", "params": ["MyMiner/1.0.0", null, "my.pool.com", 1234]}\n
```


- [ `id` : `int` ]: request id
- [ `method` : `string` ]: RPC method name
- [ `params` : (`string`, `string`, `string`, `int`) ]: list of method
  parameters
	1. MUST be name and version of mining software in the given format or empty
	   string
	2. MUST be session id received during a previous session or `null` if a new
	   session should be initiated by the server
	3. MUST be the host the client is trying to connect to or `null`
	4. MUST be the port on the given host the client is trying to connect to or
     `null`

Please see the [zcash stratum specification](https://github.com/str4d/zips/blob/77-zip-stratum/drafts/str4d-stratum/draft1.rst#rationale)
for a reason as to why `subscribe` includes a host and port.


#### Response

```
{ "id": 1, "result": ["ed70df83","080000"], "error": null }\n
```

- [ `id` : `int` ]: request id
- [ `result` : (`string`, `string`) ]:
	- MUST be `null` if an error occurred or otherwise
		1. If the server supports session resumption, then this SHOULD be a unique
       session id, `null` otherwise
		2. The last bytes of the 8 byte nonce, hex encoded
- [ `error` : (`int`, `string`, `object`) ]

This nonce sent by the server is usually referred to as the extranonce, i.e.
`nonce = minernonce || extranonce`. The server MAY freely choose the length of
the extranonce and clients SHOULD NOT expect it to be always of the same length.
`extranonce` and `minernonce` MUST be 8 bytes long together.

The nonce is in little-endian form.

The server SHOULD assign disjoint subspaces of the 8 byte nonce space to miners,
avoiding the problem of multiple miners working on the same problem.


### mining.authorize

Before a client can submit solutions to a server it MUST authorize at least one worker.

This method call will only be executed by clients.


#### Request

```
{"id": 2, "method": "mining.authorize", "params": ["WORKER_NAME", "WORKER_PASSWORD"]}\n
```

- [ `id` : `int` ]: request id
- [ `method` : `string` ]: RPC method name
- [ `params` : (`string`, `string`) ]: list of method parameters
	1. The worker name
	2. The worker password


#### Response

```
{"id": 2, "result": true, "error": null}\n
```

- [ `id` : `int` ]: request id
- [ `result` : `bool` ]: authorization success
	- MUST be `true` if successful
	- MUST be `null` if an error occurred
- [ `error` : (`int`, `string`, `object`) ]
	- MUST be `null` if `result` is `true`
	- If authorization failed then it MUST contain error object with the
	  appropriate error id and description


### mining.set_target

The target difficulty for a block can change and a server needs to be able to
notify clients of that.

This method call will only be executed by the server.


#### Request

```
{"id": null, "method": "mining.set_target", "params": ["FFFF000000000000000000000000000000000000000000000000000000000000"]}\n
```

- [ `id` : `int` ]: request id
- [ `method` : `string` ]: RPC method name
- [ `params` : (`string`) ]: list of method parameters
	1. The the 256bit big-endian target, which MUST be hex encoded.

Any subsequent jobs started by a client after receiving this update MUST
honor the new target and servers MUST reject submission above this target.

For jobs started before this update, a server MAY accept submissions if they are
below the previous target.

Please consult the document describing the consensus and proof-of-work
algorithms for details on the target.


#### Response

There is no explicit response for this call.


### mining.notify

The notify call is used to supply a worker with new work packages.

This method call will only be executed by the server.


#### Request

```
{"id": null, "method": "mining.notify", "params": ["d70fd222", "abad8f99f3918bf903c6a909d9bbc0fdfa5a2f4b9cb1196175ec825c6610126c", true ]}\n
```

- [ `id` : `int` ]: request id
- [ `method` : `string` ]: RPC method name
- [ `params` : (`string`, `int`, `string`, `bool`) ]: list of method parameters
	1. Job ID
	2. Block version
	3. Header hash
	4. A boolean indicating whether the miners job queue should be emptied or not

In order to keep the protocol flexible and anticipate changes in both the
structure of blocks and proof of work scheme, the block version should be
considered as a switch for the subsequent parameters.

The following is valid for block version (***TODO:*** insert genesis block version).

In its current iteration, all that is needed as input for the proof of work
puzzle solver is a hash of the block header plus a nonce, as described in the
consensus document.
Thus a client only requires the header hash from the server.


#### Response

There is no explicit response for this call.


### mining.submit

With this method a worker can submit solutions for the mining puzzle.
This method call will only be executed by clients.


#### Request

```
{"id": 4, "method": "mining.submit", "params": ["WORKER_NAME", "d70fd222", "98b6ac44d2", ""]}\n
```

- [ `id` : `int` ]: request id
- [ `method` : `string` ]: RPC method name
- [ `params` : (`string`, `string`, `string`, `solution`) ]: list of method
  parameters
	1. Worker name, mostly for statistics
	2. Job ID
	3. Miner nonce in hex format
	4. Proof of work puzzle solution

As with `mining.notify` all parameters after the job ID should be understood as
being conditional on the block version sent along in `mining.notify`.

The miner nonce MUST be `8 - len(extra_nonce)` bytes long and be little endian,
in order for the server to produce a correct 8 bytes nonce when concatenating
the extra and miner nonce.

A `solution` in our current instantiation of cuckoo cycle is a list of 42 32bit
integers. The solution MUST be formatted according to the rules specified in the
consensus document.


#### Response

```
{"id": 4, "result": true, "error": null}\n
```

- [ `id` : `int` ]: request id
- [ `result`: `bool` ]: submission accepted
	- MUST be `true` if accepted
	- MUST be `null` if an error occurred
- [ `error` : (`int`, `string`, `object`) ]
	- MUST be `null` if `result` is `true`
	- If submission failed then it MUST contain error object with the
	  appropriate error id and description


### client.reconnect

If a pool operator wants to have their clients reconnect to the same or a
different host they use this call.

This method call will only be executed by the server.


#### Request

```
{"id": null, "method": "client.reconnect", "params": [("my.pool.com", 1234, 23)]} \n
```


- [ `id` : `int` ]: request id
- [ `method` : `string` ]: RPC method name
- [ `params`: (`string`, `int`, `int`) ]: list of method parameters
	1. MUST be the new host name or `null` if the name is the same
	2. MUST be the new port name or `null` if the port is the same
	3. MUST be a positive integer wait time in seconds that the client should wait

The `params` list MAY be empty, which signals that the client SHOULD reconnect
to the same host and port immediately.


#### Response

There is no explicit response for this call.

Stratum Protocol Documentation

Protocol Flow Examples

Errors

Methods

Comments

Leave a Reply Cancel reply