This BIP provides a generic mechanism for specifying stratum protocol
extensions. At the same time, one of the important extensions that is
specified by this BIP is configuration of bits for "version rolling"
in nVersion field of bitcoin block header.
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 RFC 2119.
==Motivation==
The initial motivation for specifying some general support for stratum
protocol extensions was a need to allow miners to do so called
"version rolling", changing value in the first field of the Bitcoin
block header.
Version rolling is backwards incompatible change to the stratum protocol
because the miner couldn't communicate different block version value to
the server in the original version of the stratum protocol. Similarly,
a server couldn't communicate safe bits for rolling to a miner. So
both miners and pools need to implement some protocol extension to
support version rolling.
Typically, if a miner sends an unknown message to a server, the server
closes the connection (not all implementations do that but some
do). So it is not very safe to try to send unknown messages to
servers.
We can use this opportunity to make one backwards incompatible
change to the protocol to support multiple extensions in the
future. In a way that a miner can advertise its capabilities and at
the same time it can request some needed features from the server.
It is preferable that the same mechanism for feature negotiation can
be used for not yet known features. It SHOULD be easy to implement in
the mining software too.
We introduce one new message to the stratum protocol ('''"mining.configure"''') which handles the initial configuration/negotiation of features in a generic way. So that adding features in the future can be done without a necessity to add new messages to stratum protocol.
Each extension has its unique string name, so called '''extension code'''.
==Specification==
Currently, the following extensions are defined:
* '''"version-rolling"'''
* '''"minimum-difficulty"'''
* '''"subscribe-extranonce"'''
===Additional data types===
The following names are used as type aliases, making the message
description easier.
* '''TMask''' - case independent hexadecimal string of length 8, encoding an unsigned 32-bit integer (~<code>[0-9a-fA-F]{8}</code>)
* '''TExtensionCode''' - non-empty string with a value equal to the name of some protocol extension.
** <code>true</code> = The requested feature is supported and its configuration understood and applied.
** <code>false</code> = The feature is not supported or unknown.
** ''String'' = Error message containing information about what went wrong.
===Request "mining.configure"===
This message (JSON RPC Request) SHOULD be the '''first message''' sent
by the miner after the connection with the server is established. The client
uses the message to advertise its features and to request/allow some
protocol extensions.
The reason for it being the first is that we want the implementation and
possible interactions to be as easy and simple as possible. An extension
can define explicitly what does a repeated configuration of that
extension mean.
Each extension code provides a namespace for its extension parameters
and extension return values. By convention, the names are formed from
extension codes by adding "." and a parameter name. The same applies
for the return values, which are transferred in a result map
too. E.g. "version-rolling.mask" is the name of the parameter "mask" of
extension "version-rolling".
'''Parameters''':
* '''extensions''' (REQUIRED, List of ''TExtensionCode'')
::- Each string in the list MUST be a valid extension code. The meaning of each code is described independently as part of the extension definition. A miner SHOULD advertise all its available features.
* '''extension-parameters''' (REQUIRED, ''Map of (String -> Any)'')
::- Parameters of the requested/allowed extensions from the first parameter.
'''Return value''':
* ''Map of (String -> Any)''
::- Each code from the '''extensions''' list MUST have a defined return value (''TExtensionCode'' -> ''TExtensionResult''). This way the miner knows if the extension is activated or not. E.g. <code>{"version-rolling":false}</code> for unsupported version rolling.
::- Some extensions need additional information to be delivered to the miner. The return value map is used for this purpose.
::- Bits set to 1 are allowed to be changed by the miner. If a miner changes bits with mask value 0, the server will reject the submit.
::- The server SHOULD return the largest mask possible (as many bits set to 1 as possible). This can be useful in a mining proxy setup when a proxy needs to negotiate the best mask for its future clients. There is a [Draft BIP](https://github.com/bitcoin/bips/pull/661/files) describing available nVersion bits. The server SHOULD pick a mask that preferably covers all bits specified in the BIP.
::- The miner also provides a minimum number of bits that it needs for efficient version rolling in hardware. Note that this parameter provides important diagnostic information to the pool server. If the requested bit count exceeds the limit of the pool server, the miner always has the chance to operate in a degraded mode without using full hashing power. The pool server SHOULD NOT terminate miner connection if this rare mismatch case occurs.
Immediately after successful activation of the version-rolling extension
(result to '''"mining.configure"''' sent by server), the server MUST accept
an additional parameter of the message '''"mining.submit"'''. The client MUST
send one additional parameter, '''version_bits''' (6th parameter, after
''worker_name'', ''job_id'', ''extranonce2'', ''ntime'' and ''nonce'').
'''Additional parameters''':
* ''version_bits'' (REQUIRED, ''TMask'') - Version bits set by miner.
::- Miner can set only bits corresponding to the set bits in the last received mask from the server either as response to "mining.configure" or "mining.set_version_mask" notification (<code>last_mask</code>). This must hold:
version_bits & ~last_mask == 0
::- The server computes ''nVersion'' for the submit as follows:
