From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 890D010BA for ; Thu, 17 May 2018 16:50:09 +0000 (UTC) X-Greylist: whitelisted by SQLgrey-1.7.6 Received: from mail-it0-f67.google.com (mail-it0-f67.google.com [209.85.214.67]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id BE345A3 for ; Thu, 17 May 2018 16:50:06 +0000 (UTC) Received: by mail-it0-f67.google.com with SMTP id z6-v6so9644227iti.4 for ; Thu, 17 May 2018 09:50:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=braiins-cz.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:organization:mime-version; bh=gFilt1hOY/z7X7K7ED9KKAtMuxZcKCfGnfTBpknt00M=; b=Fx3Hfb6xyDhY/3QaCig3Ga/MnrJGJiliEHTTAVfGiUcM3dFHutRqSS1xFT2e4K07UU 7Iwz86evhV0K3odf2OHRWuoHMVHey9dYc6B/U5oSTtQcMqJOmgdk/USp9rvPvZwrnJfN pOoeLv6scRcDCw2dM3/wv0vg1A/Z0PXiT8wIhSHi76XtCcThDGJeQotfMn04vdK6Plgs 4+5YBdcqVt3HDn4xEiZ/90HsN3UW+HGqKVEjezmAwHMyHS6IeRhFnzJBEoav3KEIuNum gK4CErXtfga1PEoHQPyGrcua9xzEhM6FawISp6JJcywtKN5DG95Om+U1jVFlq3ao4h/W nLEg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:organization :mime-version; bh=gFilt1hOY/z7X7K7ED9KKAtMuxZcKCfGnfTBpknt00M=; b=OYvO/Pch/mVGyz30Kg31wrlI/iGxogQi2oMQpi9sUU8wlHDvdXd3gkuXZ56Ee2xsKQ ND1NFQFS7OnORdzHRuEF2lr/efwygJVrRo5+aM8pRoeddUlMx+v2iCJq1NPwJdgJiX8N Eg67nuWTTlgH9ZpTzMW49JzTxvu/QETi/vxYQRuG8/HcJp/rmIRSt+nL7HIHO/4GpvqU b43WI3wLdkQSmwboeJCR19RObjaEDaDGMBJqmOFDjY8uW8prOFfVXnPnENBUPuRt+sxb WIwffw/7NJYK6yNIO8K0dGlPJNKPeJrba6rjiKM+gaIcQ4Ty5+1v3tNMlKL0uEJT447A 2FPw== X-Gm-Message-State: ALKqPwfM1Wy+ANF6SsNfekb6KXOwx8Wln1V8hNLXNqgDZEiqWTdyzp7P XMnJVooa/0ZeFy/blwz/XUQF3Lh6atE= X-Google-Smtp-Source: AB8JxZokH6cENG0+Tov4Jp1QDUWVmisZ23RaLSbm4ufGvqVR+Rv87Sy8MD1XMt542qL2bxq1nKuGiA== X-Received: by 2002:a24:b310:: with SMTP id e16-v6mr3582421itf.58.1526575805783; Thu, 17 May 2018 09:50:05 -0700 (PDT) Received: from glum ([12.130.118.40]) by smtp.gmail.com with ESMTPSA id v127-v6sm42715itc.3.2018.05.17.09.49.59 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 17 May 2018 09:50:05 -0700 (PDT) Date: Thu, 17 May 2018 18:49:43 +0200 From: Jan =?UTF-8?B?xIxhcGVr?= To: Bitcoin Protocol Discussion Message-ID: <20180517184943.3b76a1c9@glum> Organization: braiins X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.30; x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; boundary="Sig_/bPI_E74hKOGZGf7Ev5Zvpq6"; protocol="application/pgp-signature" X-Spam-Status: No, score=-0.9 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, FROM_EXCESS_BASE64, RCVD_IN_DNSWL_NONE autolearn=no version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org X-Mailman-Approved-At: Thu, 17 May 2018 16:56:55 +0000 Cc: denis.hodzhadzhikov@etu.umontpellier.fr, kim-son.pham01@etu.umontpellier.fr, pompidor@lirmm.fr, Jules Lamur Subject: [bitcoin-dev] stratum protocol extension - mining.configure, formal version rolling and other extensions X-BeenThere: bitcoin-dev@lists.linuxfoundation.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: Bitcoin Protocol Discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 17 May 2018 16:50:09 -0000 --Sig_/bPI_E74hKOGZGf7Ev5Zvpq6 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable Hello, we (at braiins systems/slushpool) would like to kindly re-open the topic of stratum protocol extension that has been in fact implemented by quite a few pools already (including us). This extension currently allows configuring the stratum session for version rolling and enables a generic mechanism for requesting protocol extensions from the miners. More details are in the specification below.=20 I am aware of LukeJr's comments on why we haven't used https://en.bitcoin.it/wiki/Stratum_mining_protocol#mining.capabilities_.28D= RAFT.29 We are aware that there has been some academic work done on concentrating full stratum protocol specs in one BIP as referred here e.g. https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-February/01572= 8.html Below is a copy of a full extension draft that has been published at this URL: https://github.com/slushpool/stratumprotocol/blob/master/stratum-extensions= .mediawiki We should probably join the effort and unify all the documents in one single BIP if that would be seen as the most efficient way of having the specs. Kind regards, Jan 
  BIP: ????
  Layer: Applications
  Title: Stratum protocol extensions
  Author: Pavel Moravec 
	  Jan Capek 
  Comments-Summary: No comments yet.
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-????
  Status: Draft
  Type: Informational
  Created: 2018-03-10
  License: BSD-3-Clause
           CC0-1.0
=3D=3DAbstract=3D=3D 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. =3D=3DMotivation=3D=3D 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'''. =3D=3DSpecification=3D=3D Currently, the following extensions are defined: * '''"version-rolling"''' * '''"minimum-difficulty"''' * '''"subscribe-extranonce"''' =3D=3D=3DAdditional data types=3D=3D=3D 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 (~[0-9a-fA-F]{8}) * '''TExtensionCode''' - non-empty string with a value equal to the name of some protocol extension. * '''TExtensionResult''' - true / false / ''String''. ** true =3D The requested feature is supported and its configuration understood and applied. ** false =3D The feature is not supported or unknown. ** ''String'' =3D Error message containing information about what went wrong. =3D=3D=3DRequest "mining.configure"=3D=3D=3D 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. {"version-rolling":false} for unsupported version rolling. ::- Some extensions need additional information to be delivered to the miner. The return value map is used for this purpose. Example request (new-lines added): 
 {"method": "mining.configure",
  "id": 1,
  "params": [["minimum-difficulty", "version-rolling"],
	     {"minimum-difficulty.value": 2048,
	      "version-rolling.mask": "1fffe000",
"version-rolling.min-bit-count": 2}]}
(The miner requests extensions "version-rolling" and "minimum-difficulty". It sets the parameters according to the extensions' definitions.) Example result (new-lines added): 
 {"error": null,
  "id": 1,
  "result": {"version-rolling": true,
	     "version-rolling.mask": "18000000",
	     "minimum-difficulty": true}}
=3DDefined extensions=3D =3D=3DExtension "version-rolling"=3D=3D This extension allows the miner to change the value of some bits in the version field in the block header. Currently there are no standard bits used for version rolling so they need to be negotiated between a miner and a server. A miner sends the server a mask describing bits which the miner is capable of changing. 1 =3D changeable bit, 0 =3D not changeable (miner_mask) and a minimum number of bits that it needs for efficient version rolling. A server typically allows you to change only some of the version bits (server_mask) and the rest of the version bits are fixed. E.g. because the block needs to be valid or some signaling is in place. The server responds to the configuration message by sending a mask with common bits intersection of the miner's mask and its a mask (response =3D server_mask & miner_mask) Example request (a miner capable of changing any 2 bits from a 16-bit mask): {"method": "mining.configure", "id": 1, "params": [["version-rolling"], {"version-rolling.mask": "1fffe000", "version-rolling.min-bit-count": 2}]} Example result (success): {"error": null, "id": 1, "result": {"version-rolling": true, "version-rolling.mask": "18000000"}} Example result (unknown extension): {"error": null, "id": 1, "result": {"version-rolling": false}} '''Extension parameters''': * '''"version-rolling.mask"''' (OPTIONAL, ''TMask'', default value "ffffffff") ::- Bits set to 1 can be changed by the miner. This value is expected to be stable for the whole mining session. A miner doesn't have to send the mask, in this case a default full mask is used. '''Extension return values''': * '''"version-rolling"''' (REQUIRED, ''TExtensionResult'') ::- When responded with true, the server will accept new parameter of '''"mining.submit"''', see later. * '''"version-rolling.mask"''' (REQUIRED, ''TMask'') ::- 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. * '''"version-rolling.min-bit-count"''' (REQUIRED, ''TMask'') ::- 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. =3D=3D=3DNotification '''"mining.set_version_mask"'''=3D=3D=3D Server notifies the miner about a new mask valid for the connection. This message can be sent at any time after the successful setup of the version rolling extension by the "mining.configure" message. The new mask is valid '''immediately''', so that the server doesn't wait for the next job. '''Parameters''': * ''mask'' (REQUIRED, ''TMask''): The meaning is the same as the '''"version-rolling.mask"''' return parameter. Example: {"params":["00003000"], "id":null, "method": "mining.set_version_mask"} =3D=3D=3DChanges in request '''"mining.submit"'''=3D=3D=3D 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 (last_mask). This must hold: version_bits & ~last_mask =3D=3D 0 ::- The server computes ''nVersion'' for the submit as follows: nVersion =3D (job_version & ~last_mask) | (version_bits & last_mask) where job_version is the block version sent to miner as part of job with id job_id. =3D=3DExtension "minimum-difficulty"=3D=3D This extension allows miner to request a minimum difficulty for the connected machine. It solves a problem in the original stratum protocol where there is no way how to communicate hard limit of the connected device. '''Extension parameters''': * '''"minimum-difficulty.value"''' (REQUIRED, ''Integer/Float'', >=3D 0) ::- The minimum difficulty value acceptable for the miner/connection. The value can be 0 for essentially disabling the feature. '''Extension return values''': * '''"minimum-difficulty"''' (REQUIRED, ''TExtensionResult'') ::- Whether the minimum difficulty was accepted or not. ::- This extension can be configured multiple times by calling "mining.configure" with "minimum-difficulty" code again. =3D=3DExtension "subscribe-extranonce"=3D=3D Parameter-less extension. Miner advertises its capability of receiving message '''"mining.set_extranonce"''' message (useful for hash rate routing scenarios). =3D=3DExtension "info"=3D=3D Miner provides additional text-based information. '''Extension parameters''': * '''"info.connection-url"''' (OPTIONAL, ''String'') ::- Exact URL used by the mining software to connect to the stratum server. * '''"info.hw-version"''' (OPTIONAL, ''String'') ::- Manufacturer specific hardware revision string. * '''"info.sw-version"''' (OPTIONAL, ''String'') ::- Manufacturer specific software version * '''"info.hw-id"''' (OPTIONAL, ''String'') ::- Unique identifier of the mining device =3D=3DCopyright=3D=3D This document is dual licensed as BSD 3-clause, and Creative Commons CC0 1.0 Universal. --=20 CEO Braiins Systems | Slushpool.com email: jan.capek@braiins.cz http://braiins.cz http://slushpool.com --Sig_/bPI_E74hKOGZGf7Ev5Zvpq6 Content-Type: application/pgp-signature Content-Description: OpenPGP digital signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAEBCAAGBQJa/bKnAAoJEHsopSWtdWV8fSkP/AhNZL38F9NkZ+CT9t4crF0O sPbwJmeeWBurCYqDgDsxqil6PeOCLZ2A7WG1Fswl8h0/aN+L06gBlVSC+L0JGHLX PIMiR3bqj/fApBbPqFigolM6hPafQANgsxhx1S5BhIJxsUOv1S8p+wtg7eMSZYMm CfxLLDTPjGUuESwnI0Kj6qv5OCrgPpuSCV/en55fvQgNeLUW33PA/SBw4eEl/O2x tS+M7/iF8QRS9wkNWEcldzYm+uzQzESLo6re+2Ukcvcbavf6UYXMSSy9HPxpvuFE nwK2cCQUpf7/bm2FfxX5LB8rxFC7wimT4g5KFVjpbfJSz1ihxjK4tzMQIIq5cDo5 WK0PlNJ+wLzVnHDtr0SxETOF/YTHvYcBZcLrZE0aRGgVw1BKqD7fFtakaj0sggsy oGQXS/65ZaOjzppvXPoFY+cgvq1cPfar2GhW7aI8PZxV7ykT1W8oGpq0Mgh3Jlda NRQWTixeTrPg68fC3v5jTIFoRG92GHZHLrwtCeZR8FVuh1mB9+ZyaEBr66/6cW4l tMg4+khWOZN13emt0oB1DqbnzsT70LEXONFINBQwFPHEw2TTwhT9pi8QWR87SzLz 3R0Ghoa3wty47LJ6+EGIqtJQ6rUe8wKxsfxtH258VI1OKMAYzW7gadzuDg+4/eJV O3P63+1dH8/CaVq3wcZw =hkSv -----END PGP SIGNATURE----- --Sig_/bPI_E74hKOGZGf7Ev5Zvpq6--