Skip to main content

Stratum Protocol in Conflux-Rust

Design Goal​

Rust is an excellent language to develop distributed systems like Conflux, but it is not very so good for developing miners. Miners are typically developed via languages like C/C++ that can operate with high performance and GPUs. We therefore design a stratum-like protocol in Conflux-Rust to enable external miners to connect to Conflux.

Note that to keep the protocol simple, the design goal of the stratum-like protocol is for solo-mining only, i.e., Conflux-Rust are connected with miner processes in local or remote machines that belong to the same entity. It is not designed to run as a mining pool server. For those who wish to run a mining pool, it is recommended to build their own customized proxy server that connects to Conflux-Rust.

General Workflow​

In the scenario where an external miner connecting to Conflux-Rust via its stratum port (default 32525), here is the typical workflow.

  1. The miner connects via TCP to the stratum port. Conflux-Rust must run with the configuration that enables stratum.

  2. The miner sends a mining.subscribe RPC call via the TCP stream. It informs Conflux-Rust the miner name. mining.subscribe also performs a basic password based authentication, where the password can be set at the configuration file of Conflux-Rust.

  3. After successful subscription, Conflux-Rust will continue to send mining.notify RPC calls to the miner via the TCP stream. Each mining.notify corresponds to a new proof-of-work (PoW) problem for the miner to solve. Miners are expected to work on the last received job.

  4. Whenever miner solves a PoW problem, it returns the solution (i.e., the nonce) to Conflux-Rust via calling mining.submit RPC calls.

  5. Miner can simply disconnect any time in this process to quit.

RPC Interface​

Server-side RPCs​

mining.subscribe​

Start to subscribe the proof-of-work notification from the stratum server

Parameters​
  1. WORKER_ID, string - the name of the miner
  2. Secret, empty or 32-bytes, the secret that corresponds to the keccak result of the password in the configuration. Empty if password is not enabled.
Returns​

Bool - true if successful, false if not.

Example​
// Request
'{"jsonrpc":"2.0","method":"mining.subscribe","params":["cfxmine", ""],"id":1}'

// Response
{
  "jsonrpc": "2.0",
  "result": "true",
  "id": 1
}

mining.submit​

Submit a PoW solution to the stratum server

Parameters​
  1. WORKER_ID, string - the name of the miner
  2. JOB_ID, hex-string - the identifier of the job, which is typically same as the hash of the PoW problem.
  3. NONCE, hex-string of 32-bytes - the nonce solution of the PoW problem
  4. HASH, hex-string of 32-bytes - the hash of the solved PoW problem.
Returns​

Array - A single element of true if successful, the first element will be false if not and the second element will explain reasons in string.

Example​
// Request
'{"jsonrpc":"2.0","method":"mining.submit","params":["cfxmine", "0x2106e1162d1199483fa010bcaa7d4f05b23b85d456b4a7089d787ae2e880deaf","0x21b49d385865819a171ed8cd9d9f80acc468e501f3486d3600000000000c786c","0x2106e1162d1199483fa010bcaa7d4f05b23b85d456b4a7089d787ae2e880deaf"],"id":1}'

// Response
{
  "jsonrpc": "2.0",
  "result": ["true"],
  "id": 1
}

{
  "jsonrpc": "2.0",
  "result": ["false", "invlaid nonce"],
  "id": 1
}

Client-side Notification​

Note that although the server notifies the mining client via a RPC like request, it is not a true RPC -- it does not expect the client to return any response. Instead, the client will just update the PoW problem it works on and submits whenever it finds solution.

mining.notify​

Notify the client about a new PoW problem.

Parameters​
  1. JOB_ID, hex-string - the identifier of the job.
  2. HASH, 32-bytes - the hash of the PoW problem.
  3. BOUNDARY, U256 - the difficulty boundary of the problem. For a nonce to be valid, the resulting hash must be smaller than the BOUNDARY.
Example​
// Request
'{"jsonrpc":"2.0","method":"mining.notify","params":["0x4e08db21d43a7696afa3d00ed948568210f3ab3f34673f1d17198625ec175a9c","0x4e08db21d43a7696afa3d00ed948568210f3ab3f34673f1d17198625ec175a9c","0x1a4e3422948568210f3ab3f34673f1d17198625ec175a9c"],"id":3}'

---