Echelon Protocol

Version 1.0.4
The echelon specification repository can be found here.

The stratum protocol is used by ASIC miners, devices created specifically for performing Bitcoin mining.

The echelon protocol is a modified version of the stratum v1 protocol for mining nexa.

Miners use the echelon protocol to reach out to one or more servers (e.g. a mining pool) in order to obtain a mining candidate for a new block. The miner tests solutions by increasing the nonce until a candidate block that meets the specified difficulty requirements is successfully created.

Message Format

Echelon uses the JSON-RPC 2.0 message format. That is, JSON-encoded messages, separated by newline (line feed) characters. There are two high-level message formats: requests and responses.

Requests

Requests all contain the following fields:

Field	Format	Description
id	number or string	A message ID that must be unique per request that expects a response. For requests not expecting a response (called notifications), this is null.
method	string	Indicates the type of request the message represents.
params	array	Additional data which varies based on the request method.

Responses

Responses all contain the following fields:

Field	Format	Description
id	number or string	The ID of the request that this message is a response to.
result	any	Data being returned in response to the request. Must be present, but may be a string, number, array, object, or null.
error	error array	Indicates that the request could not be fulfilled and provides information about what went wrong.

Error Array Format

The error array is a JSON array containing the following elements:

Field	Format	Description
error code	number	An error code indicating the type of error.
message	string	A description of the error.
data	object	Additional data associated with the error (nullable).

Example error: {"result":null,"id":2,"error":[24,"Unauthorized worker",null]}

Beyond those specified by JSON-RPC, the following error codes are used:

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

Echelon Protocol Flow

Client                                Server   
  |                                     |   
  | --------- mining.subscribe -------> |   
  | --------- mining.authorize -------> |   
  | <-------- mining.set_difficulty --- |   
  |                                     |----   
  | <---------- mining.notify --------- |<--/   
  |                                     |   
  | ---------- mining.submit ---------> |

Full Protocol

Client Methods

mining.subscribe

Upon connecting to a server, clients are expected to send a subscribe request, described as follows.

Field	Format	Description
method	string	"mining.subscribe"
params[0] - user_agent_version	string	User agent name and version, separated by a forward slash (e.g. "nxminer/2.0.0").

Example request: {"id": 1, "method": "mining.subscribe", "params": ["nxminer/2.0.0"]}

In response, the server will send the following data in its result object, which is a JSON array:

Field	Format	Description
subscriptions	array	An array containing sub-array that described intended subscriptions. The first value in sub-arrays is the subscription type (e.g. "mining.set_difficulty"), the second is a subscription ID.
extranonce	string	The 64 bit big endian hex encoded value that is to be used the first 8 bytes of the solution nonce.
extranonce2_size	int	The number of bytes that the miner users for its extranonce2 counter.

Example response: {"result":[[["mining.set_difficulty", 0.1 ]],"0000000000000001", 8],"id":1,"error":null}

mining.authorize

In order to authenticate itself, the client send an authorize message:

Field	Format	Description
method	string	"mining.authorize"
params[0] - username	string	The client's user name.
params[1] - password	string	The client's password (if required by the server).

Example request: {"id": 1, "method": "mining.authorize", "params": ["username", "p4ssw0rd"]}

Response format:

Field	Format	Description
result	boolean	The value true if the client has been authorized; false otherwise.

Example response: {"id": 2, "result": true, "error": null}

mining.submit

Once the client has completed a job (received via mining.notify following an accepted mining.authorize), it returns its result using a submit message. This message is also used to submit shares to a mining pool. The format is as follows:

Field	Format	Description
method	string	"mining.submit"
params[0] - username	string	The client's user name.
params[1] - job_id	string	The job ID for the work being submitted.
params[2] - solution_nonce	string	A 128 bit hex encoded value where the first 64 bits are the extranonce and the second 64 bits are the miner nonce.
params[3] - time	string	The 64 bit big endian hex-encoded value of the time. (same value as received in mining.notify)

Example request: {"id": 1, "method": "mining.submit", "params": ["username", "4f", "000000000000000100003e05486566fd", "0000000063b1fb60"]}

Response format:

Field	Format	Description
result	boolean	The value true if the submission has been accepted; false if it was rejected.

Example response: {"id": 2, "result": true, "error": null}

Used to indicate a preference for share difficulty to the pool. Servers are not required to honour this request, even if they support the stratum method.

Server Methods

mining.notify

Once a client successfully connects using the mining.subscribe and mining.authorize messages, the server may send a job to the client, informing it of everything it needs to know in order to mine a new block. The notify message is a notification (does not expect a response) and has the following format:

Field	Format	Description
method	string	"mining.notify"
params[0] - job_id	string	The job ID for the job being sent in this message.
params[1] - header_commitment	string	The 256 bit big endian hex-encoded header commitment.
params[2] - nbits	string	The 32 bit big endian hex-encoded network difficulty required for the block.
params[3] - time	string	The 64 bit big endian hex-encoded current time for the block.
params[4] - clean	boolean string (true/false)	Indicates whether the client should forget any prior jobs. If true, the server will reject any submissions for prior jobs and the miner should forget any prior job IDs so that they can be reused by the server.

Example request: {"id": null, "method": "mining.notify", "params": ["4f", "e9c64cfd6711c5eaa8d20dc4c4a430b1e22141ecc1ad701471492420432d8a4b", "1b02fab2", "0000000063b1fb60", false]}

mining.set_difficulty

The server can adjust the difficulty required for miner shares with the "mining.set_difficulty" method. The miner should begin enforcing the new difficulty on the next job received. Some pools may force a new job out when set_difficulty is sent, using clean_jobs to force the miner to begin using the new difficulty immediately.

Field	Format	Description
method	string	"mining.set_difficulty"
params[0] - new_difficulty	number	The new difficulty threshold for share reporting. Shares are reported using the mining.submit message.

Example request: { "id": null, "method": "mining.set_difficulty", "params": [2]}

mining.set_extranonce

These values, when provided, replace the initial subscription values beginning with the next mining.notify job.

Field	Format	Description
method	string	"mining.set_extranonce"
params[0] - extranonce1	string	The new 64 bit big endian hex encoded value that is to be used the first 8 bytes of the solution nonce.
params[1] - extranonce2_size	number	The new size of extranonce2.

Example request: { "id": null, "method": "mining.set_extranonce", "params": ["0000000000000002", 8]}