Stratum protocol for bitcoin mining easy explained
The stratum protocol is a since 2012 used protocol to communicate between miner and mining pool for encrypted currency. It was initial developed by Slush Pool, one of the oldest and biggest Bitcoin mining pools. It was implemented by pool- and mining software, but not defined in a Bitcoin Improvement Proposal (BIP), a document similar to a Request for Comments (RFC), hence it is not part of the Bitcoin standard. The development of such a protocol was need, since the old getwork method delegated all work to build a block to bitcoind. This became very fast a bottleneck, while mining pool powers raised.
How the stratum protocol works:
Stratum describe both the different functions and the transfer method over network. It is designed to works like Remote Procedure Calls (RPC) by defines so-called methods with a name and optional arguments and a return value. Each of these methods exists either on the mining pool or the mining software and gets called from each other.
Methods of the stratum protocol:
|Name||Arguments||Return value||Call direction||Short description|
|client.get_version||Text (String)||Pool → Miner||Ask the Mining software for a text line to identify.|
|client.reconnect||Host (String), Port (Number), Waittime (Number)||Pool → Miner||Ask the software to disconnect, wait the Waittime in seconds and connect to host:port.
Clients have to be very strict on honoring this request for security reasons!
|mining.set_difficulty||Text (String)||Pool → Miner||The mining client should show the text to his user in any way.|
|mining.authorize||Username (String), Password (String)||true if sucessfull, false otherwise (Boolean)||Miner → Pool||Authenticate the miner in the pool. It is usual possible to mine without Authenticate, but you need to authenticate to link the work to your account. Many Pools ignore the password argument.|
|mining.extranonce.subscribe||Miner → Pool||Narrate the pool about the support of mining.set_extranonce|
|mining.get_transactions||Job ID (String)||Bytes as Hexstring||Miner → Pool||Ask the pool for dumps of all transactions in the block of the job with this id.|
|mining.configure||Unsorted List of config extensions, Map with config values.||Map with data about extension support and used values||Miner → Pool||Ask for support of config extensions and suggest values in one step.|
|mining.notify||Job ID (Integer as Hexstring),|
Previous block hash (Bytes as Hexstring),
Coinbase transaction part 1 (Bytes as Hexstring) + ExtraNonce1 (Number as Hexstring) + ExtraNonce2 (Number as Hexstring),
Coinbase transaction part 2 (Bytes as Hexstring),
List of elements to build the merkel root,
Bitcoin block version (Number),
Bits (Bytes as Hexstring),
Time (Number as Hexstring),
Clean Jobs (Boolean)
|Pool → Miner||Transmits the Miner a new job|
|mining.set_difficulty||Difficulty (Number)||Pool → Miner||Inform the client about the pool difficulty for the next job.|
|mining.set_extranonce||Difficulty (Number)||Pool → Miner||Replace the on subscription transmitted extranonce starting with the next job.|
|mining.submit||Username (String), Job ID (String), ExtraNonce2 (Number as Hexstring), Time (Number as Hexstring), Nonce (Number as Hexstring)||true if accepted, false otherwise (Boolean)||Miner → Pool||Send the pool data to construct a matching block.|
|mining.subscribe||Identifier (String, optional), Extranonce (Hexstring, optional)||List(List(List("mining.set_difficulty", initial difficulty), List("mining.notify", Subscription ID)), Extranonce1 (Hexstring), Extranonce2_size (Num))||Miner → Pool||Subscript the mining pool for job broadcasts. Usual the first method called on connect.|
|mining.suggest_difficulty||Difficulty (Number)||Miner → Pool||Prefer the pool a Difficulty to use.|
(Last valid 2019-11-17)
How is a stratum protocol remote procedure call transferred:
The connection is build up from the miner to the pool over TCP. All characters are UTF-8-encoded, after each command follows a line feed (byte 10/0x0A). The commands are JSON Maps with a fixed structure:
- All calls are sent with the key id. It is usual a unique number for methods with return value or the key object null, which means the same as “nothing” for methods without response, but it could be virtually anything. Responses contain the same key with an equal object to refer to the belonging request.
- The key method contains just the name of the method to call as string.
- In the key params is a list of arguments. A request without argument transfer empty brackets.
Stratum protocol example:
So a real method call looks like this:
Byte arrays become transferred as Hexadecimal-encoded strings in little endian byte ordering.
- The field id contains the same, that the request did.
- result contains the return value for the request.
- In error is a string, containing an error description in human readable form, if any occurred.
Much software has a very strict implement of JSON. The last column of a map or list must not end with a comma (,), that will cause in compatibility issues!