Stratum
Last updated
Was this helpful?
Last updated
Was this helpful?
This document describes a protocol, that allows a group of miners to connect to a server, which coordinates the distribution of work packages among miners.
The initial protocol was written for Bitcoin and contains several pieces that need adjustment in order to be usable with æternity.
Pool operators looking to implement this specification should note, that the usage of the Bitcoin-NG protocol changes the dynamics of the mining game. With Bitcoin-NG pools will end up authoring the microblocks containing transactions while the miners try to find keyblocks, which are used for leader election. This procedure puts both more power into the hands of pool operators while also adding more burden. This burden comes in the form of increased book keeping complexity—the full revenue of one epoch can only be computed after the fact—and an increase in computational resources required for signing microblocks.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .
The stratum protocol mostly adheres to the specification.
This specification derives from works by , and .
Communication happens over a bidirectional channel with messages encoded as
JSON with LF delimiter—in this document written as .
Since requests can be handled out of order, each request in a session SHOULD
have an unique id. In order to be able to match request and response,
responses MUST have the same id as their matching request. Notifications
sent by the server or calls that do not trigger any response MAY have an id ofnull.
For further details on the members of request and response objects consult the.
The following shows what a session might look like from subscription to submitting a solution.
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 ]
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.
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.
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.
[ id : int ]: request id
[ method : string ]: RPC method name
[ params : (string, string, string, int) ]: list of method
parameters
MUST be name and version of mining software in the given format or empty string
MUST be session id received during a previous session or null if a new
session should be initiated by the server
MUST be the host the client is trying to connect to or null
MUST be the port on the given host the client is trying to connect to ornull
[ id : int ]: request id
[ result : (string, string) ]:
MUST be null if an error occurred or otherwise
If the server supports session resumption, then this SHOULD be a unique
session id, null otherwise
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.
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.
[ id : int ]: request id
[ method : string ]: RPC method name
[ params : (string, string) ]: list of method parameters
The worker name
The worker password
[ 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
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.
[ id : int ]: request id
[ method : string ]: RPC method name
[ params : (string) ]: list of method parameters
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.
There is no explicit response for this call.
The notify call is used to supply a worker with new work packages.
This method call will only be executed by the server.
[ id : int ]: request id
[ method : string ]: RPC method name
[ params : (string, int, string, bool) ]: list of method parameters
Job ID
Block version
Header hash
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.
There is no explicit response for this call.
With this method a worker can submit solutions for the mining puzzle. This method call will only be executed by clients.
[ id : int ]: request id
[ method : string ]: RPC method name
[ params : (string, string, string, solution) ]: list of method
parameters
Worker name, mostly for statistics
Job ID
Miner nonce in hex format
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.
[ 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
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.
[ id : int ]: request id
[ method : string ]: RPC method name
[ params: (string, int, int) ]: list of method parameters
MUST be the new host name or null if the name is the same
MUST be the new port name or null if the port is the same
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.
There is no explicit response for this call.
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 specification, are:
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
Please see the
for a reason as to why subscribe includes a host and port.