Stratum mining protocol
![Stratum mining pool](http://bitcoinwiki.org/wp-content/uploads/2023/12/560px-Stratum.jpg)
Stratum-mining is a pooled mining protocol. It is a replacement for network based pooling servers by allowing clients to generate work. The stratum protocol is described here in full detail. This is a implementation of stratum-mining for most coins. It is compatible with MPOS as it complies with the standards of pushpool. The end goal is to build on these standards to come up with a more stable solution.
The goal is to make a reliable stratum mining server for a wide range of coins unlike other forks where the code is limited to specific algorithm’s. Over time I will develop this to be more feature rich and very stable. If you would like to see a feature please file a feature request[1].
The stratum overlay protocol was extended to support pooled mining as a replacement for obsolete getwork protocol in late 2012. The mining service specification was initially announced via Slush’s pool‘s website. Shortly thereafter, alternative “cheat sheet” style documentation was provided by BTC Guild. As the extension lacks a formal BIP describing an official standard, it has further developed only by discussion and implementation.
Contents
What is Stratum?
Features
- Stratum Mining Pool
- Solved Block Confirmation
- Job Based Vardiff support
- Solution Block Hash Support
- Log Rotation
- Initial low difficulty share confirmation
- Multiple coind Stratum wallets
- On the fly addition of new coind wallets
- MySQL/PostGres/SQLite database support
- Adjustable database commit parameters
- Bypass password check for workers
- Proof-of-work and Proof-of-stake Coin Support
- Transaction Messaging Support
Methods (client to server)
mining.authorize
mining.authorize("username", "password")
The result from an authorize request is usually true (successful), or false. The password may be omitted if the server does not require passwords.
mining.capabilities (DRAFT)
NOTE: This is a draft extension proposal. It is not yet in use, and may change at any moment.
mining.capabilities({"notify":[], "set_difficulty":{}, "set_goal":{}, "suggested_target": "hex target"})
The client may send this to inform the server of its capabilities and options. The singleton parameter is an Object describing capabilities; by default, it is considered as {“notify”:{}, “set_difficulty”:[]}, but as soon as this method is used these must be explicitly included if desired. The “suggested_target” key may supersede the mining.suggest_target method.
Note that most of the keys do not have any meaningful value at this time, and the values thereof should be ignored (ie, only their presence matters).
mining.extranonce.subscribe
mining.extranonce.subscribe()
Indicates to the server that the client supports the mining.set_extranonce method[2].
mining.get_transactions
mining.get_transactions("job id")
Server should send back an array with a hexdump of each transaction in the block specified for the given job id.
mining.submit
mining.submit("username", "job id", "ExtraNonce2", "nTime", "nOnce")
Miners submit shares using the method “mining.submit”. Client submissions contain:
- Worker Name.
- Job ID.
- ExtraNonce2.
- nTime.
- nOnce.
Server response is result: true for accepted, false for rejected (or you may get an error with more details).
mining.subscribe
mining.subscribe("user agent/version", "extranonce1")
The optional second parameter specifies a mining.notify subscription id the client wishes to resume working with (possibly due to a dropped connection). If provided, a server MAY (at its option) issue the connection the same extranonce1. Note that the extranonce1 may be the same (allowing a resumed connection) even if the subscription id is changed!
The client receives a result:
[[["mining.set_difficulty", "subscription id 1"], ["mining.notify", "subscription id 2"]], "extranonce1", extranonce2_size]
The result contains three items:
- Subscriptions. – An array of 2-item tuples, each with a subscription type and id.
- ExtraNonce1. – Hex-encoded, per-connection unique string which will be used for creating generation transactions later.
- ExtraNonce2_size. – The number of bytes that the miner users for its ExtraNonce2 counter.
mining.suggest_difficulty
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.
mining.suggest_target
mining.suggest_target("full hex share target")
Used to indicate a preference for share target to the pool, usually prior to mining.subscribe. Servers are not required to honour this request, even if they support the stratum method.
Methods (server to client)
client.get_version
client.get_version()
The client should send a result String with its name and version.
client.reconnect
client.reconnect("hostname", port, waittime)
The client should disconnect, wait waittime seconds (if provided), then connect to the given host/port (which defaults to the current server). Note that for security purposes, clients may ignore such requests if the destination is not the same or similar.
client.show_message
client.show_message("human-readable message")
The client should display the message to its user in some reasonable way.
mining.notify
mining.notify(...)
Fields in order:
- Job ID. This is included when miners submit a results so work can be matched with proper transactions.
- Hash of previous block. Used to build the header.
- Generation transaction (part 1). The miner inserts ExtraNonce1 and ExtraNonce2 after this section of the transaction data.
- Generation transaction (part 2). The miner appends this after the first part of the transaction data and the two ExtraNonce values.
- List of merkle branches. The generation transaction is hashed against the merkle branches to build the final merkle root.
- Bitcoin block version. Used in the block header.
- nBits. The encoded network difficulty. Used in the block header.
- nTime. The current time. nTime rolling should be supported, but should not increase faster than actual time.
- Clean Jobs. If true, miners should abort their current work and immediately use the new job. If false, they can still use the current job, but should move to the new one after exhausting the current nonce range.
mining.set_difficulty
mining.set_difficulty(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.
mining.set_extranonce
mining.set_extranonce("extranonce1", extranonce2_size)
These values, when provided, replace the initial subscription values beginning with the next mining.notify job.
mining.set_goal (DRAFT)
NOTE: This is a draft extension proposal. It is not yet in use, and may change at any moment.
mining.set_goal("goal name", {"malgo": "SHA256d", ...})
Informs the client that future jobs will be working on a specific named goal, with various parameters (currently only “malgo” is defined as the mining algorithm). Miners may assume goals with the same name are equivalent, but should recognise parameter changes in case a goal varies its parameters.
Stratum mining proxy
Stratum mining proxy allows mining software supporting the old Getwork protocol to use modern Stratum mining protocol provided by our pool. We will not cover full technical details and reasoning for designing the Stratum protocol here. If you are looking for those, please find your way over here.
We do however believe that you should know some basic facts and reasons. The old Getwork protocol was designed as an easy solution for standalone miners in times, where there was no mining pool and mining rigs had just about few GHash per second. Back then it was just good enough to get by, but the situation has changed radically. Now you can easily get miner which is capable of producing even 6 THash/s. Such performance would require a considerably great network bandwidth on user side (~1428 getwork requests at once) and ridiculously great one on the server side (imagine few hundred users, each polling the server for work).
Stratum protocol reduces network load and significantly improves miner performance on slower and unstable networks[3].
Stratum pool software
Tables showing miner/server support for Stratum mining protocol:
Criticism
Closed development
The mining extensions have been criticised as having been developed behind closed doors without input from the wider development and mining community, resulting in various obvious problems that could have been addressed had it followed the standard BIP drafting process.
Displacing GBT
The mining extensions were announced after the community had spent months developing a mostly superior open standard protocol for mining (getblocktemplate). Because stratum’s mining extensions launched backed by a major mining pool, GBT adoption suffered, and decentralised mining is often neglected while stratum is deployed.