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:

Responses

Responses all contain the following fields:

Error Array Format

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

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

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

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.

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:

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:

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

Response format:

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:

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

Response format:

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

mining.suggest_difficulty(preferred share difficulty Number)

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:

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.

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.

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