BIP40: Stratum wire protocol

ben221199 commented at 3:46 pm on March 7, 2024: none

The Stratum wire protocol has a long history since @slush0 introduced it. However, the protocol never got standardized in a formal way, so many implementations have been based on incomplete documents or on other implementations. With this document I finally want to give Stratum its place between the other BIPs, so that developers can just read this document and don’t have to search through years of code or dead pages that need to be revived with Wayback Machine.

Write initial draft of BIP 40 47ca202e1f

Fix inline code 914fb7c40c

ben221199 marked this as a draft on Mar 7, 2024

Allow public domain 72bfc4d01b

ben221199 force-pushed on Mar 7, 2024

Improve specification of transport protocols abe08e4b5f

Minicoolboy77777 approved

Add letters and default ports a5aee5bd6c

Add more information about WebSockets 8658be8faa

ben221199 commented at 8:52 am on March 20, 2024: none

Yesterday, I sent two registration requests to IANA to get some information officially egistered. The registries are:

Media Types (https://www.iana.org/assignments/media-types/media-types.xhtml)
WebSocket Subprotocol Name Registry (https://www.iana.org/assignments/websocket/websocket.xml#subprotocol-name)

Today, I got a response that for both registrations some things have to be done first, before IANA can add these records to their registry. In case of the Media Types, this is process is a little bit more difficult. For the WebSocket Subprotocol Name Registry it is just letting them know when this pull request is merged and I have a permalink to the specification.

Also, it is possible that I will send more registration requests for other IANA registries too. For example, the Service Name and Transport Protocol Port Number Registry (https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml) is a possible candidate. In that case, I will post new comments about that too.

Add information about WebSocket subprotocol e13def41e5

Add information about HTTP polling e2807713e0

Improve text 83647b1b20

Add note 3d217b09b8

Add information about HTTP Push c82a2a11b7

Add two methods 805559f695

Improve commands ec52ae1321

jonatack added the label New BIP on Apr 23, 2024

in bip-0040.mediawiki:27 in ec52ae1321 outdated

22+
23+==Motivation==
24+
25+Many clients want to give users access to the Bitcoin ecosystem. However, for specific reasons not every user is able to download the full blockchain to their machine.
26+
27+The Stratum wire protocol defines a way to access the blockchain without having it downloaded. For example, a client can request both the genesis block and the latest block with the same latency, because the server does synchronize and index all blocks for us.

jonatack commented at 6:25 pm on May 6, 2024:

0The Stratum wire protocol defines a way to access the blockchain without having it downloaded. For example, a client can request both the genesis block and the latest block with the same latency, because the server synchronizes and indexes all the blocks for us.

in bip-0040.mediawiki:31 in ec52ae1321 outdated

26+
27+The Stratum wire protocol defines a way to access the blockchain without having it downloaded. For example, a client can request both the genesis block and the latest block with the same latency, because the server does synchronize and index all blocks for us.
28+
29+==History==
30+
31+Stratum wire protocol was introduced by Marek Palatinus in late 2011 and early 2012. It was a language independent alternative for the Python-based protocol in early versions of Electrum, created by Thomas Voegtlin. The Stratum wire protocol made it possible to create compatible servers which Electrum could connect to, but it also made it possible to write alternative clients.

jonatack commented at 6:26 pm on May 6, 2024:

0The Stratum wire protocol was introduced by Marek Palatinus in late 2011 and early 2012. It was a language-independent alternative to the Python-based protocol in early versions of Electrum, created by Thomas Voegtlin. The Stratum wire protocol made it possible to create compatible servers that Electrum could connect to, but it also made it possible to write alternative clients.

in bip-0040.mediawiki:33 in ec52ae1321 outdated

28+
29+==History==
30+
31+Stratum wire protocol was introduced by Marek Palatinus in late 2011 and early 2012. It was a language independent alternative for the Python-based protocol in early versions of Electrum, created by Thomas Voegtlin. The Stratum wire protocol made it possible to create compatible servers which Electrum could connect to, but it also made it possible to write alternative clients.
32+
33+Later in 2012, Marek Palatinus introduced Stratum also for mining pools: The Stratum mining protocol, as defined in [[bip-0041.mediawiki|BIP 41]].

jonatack commented at 6:27 pm on May 6, 2024:

0Later in 2012, Marek Palatinus introduced Stratum for mining pools as well: The Stratum mining protocol, as defined in [[bip-0041.mediawiki|BIP 41]].

in bip-0040.mediawiki:37 in ec52ae1321 outdated

32+
33+Later in 2012, Marek Palatinus introduced Stratum also for mining pools: The Stratum mining protocol, as defined in [[bip-0041.mediawiki|BIP 41]].
34+
35+==Specification: Data Format==
36+
37+Stratum leverages [https://www.jsonrpc.org/ JSON-RPC]. Both versions 1.0 and 2.0 are allowed. Rules of that version apply accordingly.

jonatack commented at 6:31 pm on May 6, 2024:

0Stratum leverages [https://www.jsonrpc.org/ JSON-RPC]. Both versions 1.0 and 2.0 are allowed. The rules of each version apply accordingly.

or

0Stratum leverages [https://www.jsonrpc.org/ JSON-RPC]. Both versions 1.0 and 2.0 are allowed, according to their respective rules.

in bip-0040.mediawiki:39 in ec52ae1321 outdated

34+
35+==Specification: Data Format==
36+
37+Stratum leverages [https://www.jsonrpc.org/ JSON-RPC]. Both versions 1.0 and 2.0 are allowed. Rules of that version apply accordingly.
38+
39+Additionally, it is a convention to give all Stratum methods in the <code>method</code> property a name in the following form: <code><service>.<method></code>, where <code><service></code> is allowed to have dots and <code><method></code> isn't. For example, the the value <code>blockchain.block.subscribe</code>.

jonatack commented at 6:34 pm on May 6, 2024:

0Additionally, it is a convention to give all Stratum methods in the <code>method</code> property a name in the following form: <code><service>.<method></code>, where <code><service></code> is allowed to have dots and <code><method></code> isn't. For example, the value <code>blockchain.block.subscribe</code>.

in bip-0040.mediawiki:41 in ec52ae1321 outdated

36+
37+Stratum leverages [https://www.jsonrpc.org/ JSON-RPC]. Both versions 1.0 and 2.0 are allowed. Rules of that version apply accordingly.
38+
39+Additionally, it is a convention to give all Stratum methods in the <code>method</code> property a name in the following form: <code><service>.<method></code>, where <code><service></code> is allowed to have dots and <code><method></code> isn't. For example, the the value <code>blockchain.block.subscribe</code>.
40+
41+''Note: In JSON-RPC 1.0, the <code>param</code> property is an array, so everything should be passed in the right order. In JSON-RPC 2.0, also named parameters are allowed. In that case, the parameter names that are documented should be used. If not, the method can fail. It is maybe also possible that a specific method (or server) only does support <code>params</code> being an array, because it doesn't know how to handle the named ones, even if it supports JSON-RPC 2.0.''

jonatack commented at 6:35 pm on May 6, 2024:

0''Note: In JSON-RPC 1.0, the <code>param</code> property is an array, so everything should be passed in the right order. In JSON-RPC 2.0, named parameters are also allowed. In that case, only the parameter names that are documented should be used; otherwise, the method can fail. It is maybe also possible that a specific method (or server) only supports <code>params</code> as an array, because it doesn't know how to handle named params, even if it supports JSON-RPC 2.0.''

in bip-0040.mediawiki:47 in ec52ae1321 outdated

42+
43+==Specification: Transport Protocols==
44+
45+It is possible to send JSON-RPC messages over different transport protocols, like TCP and HTTP. It is also possible to protect these protocols with SSL/TLS.
46+
47+''Note: Because HTTP and WebSockets support virtual hosting (<code>Host</code> header or <code>:authority</code> pseudo-header), it is possible to create a server on a single IP address that supports multiple coins by checking the domain name. The same is the case for the transport protocols with SSL/TLS when SNI is used. On plain TCP, virtual hosting is not possible. A similar experience can be reached by using multiple IP addresses. For IPv6, a network of /96 would be enough to hypothetically support all coins ever listed in SLIP-44. For IPv4, you would need all IPv4 addresses that exist to do the same, even the invalid ones, so a suggestion is to only use the server only for coins you really need. Also, other ports could possibly be used and in that case, a /16 IP block with all 65536 TCP ports in use will be enough to support all coins. However, because using non-standard ports is not user-friendly, this is also not recommended.''

jonatack commented at 6:48 pm on May 6, 2024:

double “only” in only use the server only

0''Note: Because HTTP and WebSockets support virtual hosting (<code>Host</code> header or <code>:authority</code> pseudo-header), it is possible to create a server on a single IP address that supports multiple coins by checking the domain name. The same is the case for the transport protocols with SSL/TLS when SNI is used. On plain TCP, virtual hosting is not possible. A similar experience can be reached by using multiple IP addresses. For IPv6, a network of /96 would be enough to hypothetically support all coins ever listed in SLIP-44. For IPv4, you would need all IPv4 addresses that exist to do the same, even the invalid ones, so a suggestion is to only use the server for coins you really need. Also, other ports could possibly be used, and in that case, a /16 IP block with all 65536 TCP ports in use will be enough to support all coins. However, because using non-standard ports is not user-friendly, this is also not recommended.''

in bip-0040.mediawiki:51 in ec52ae1321 outdated

46+
47+''Note: Because HTTP and WebSockets support virtual hosting (<code>Host</code> header or <code>:authority</code> pseudo-header), it is possible to create a server on a single IP address that supports multiple coins by checking the domain name. The same is the case for the transport protocols with SSL/TLS when SNI is used. On plain TCP, virtual hosting is not possible. A similar experience can be reached by using multiple IP addresses. For IPv6, a network of /96 would be enough to hypothetically support all coins ever listed in SLIP-44. For IPv4, you would need all IPv4 addresses that exist to do the same, even the invalid ones, so a suggestion is to only use the server only for coins you really need. Also, other ports could possibly be used and in that case, a /16 IP block with all 65536 TCP ports in use will be enough to support all coins. However, because using non-standard ports is not user-friendly, this is also not recommended.''
48+
49+===TCP===
50+
51+Stratum over a TCP connection. Every JSON-RPC message (including batch messages) is send on a single line, ending with a line-feed (<code>\n</code>), so <code>\r\n</code> is also allowed. Line-feeds inside the JSON should be encoded as usual. Both client and server can initiate a request on which the other side could respond with a result or an error.

jonatack commented at 6:49 pm on May 6, 2024:

0Stratum over a TCP connection. Every JSON-RPC message (including batch messages) is sent on a single line, ending with a line-feed (<code>\n</code>), so <code>\r\n</code> is also allowed. Line-feeds inside the JSON should be encoded as usual. Both client and server can initiate a request on which the other side could respond with a result or an error.

in bip-0040.mediawiki:58 in ec52ae1321 outdated

53+* Default port: <code>50001</code>
54+* Letter: <code>t</code>
55+
56+===TCP over SSL/TLS===
57+
58+Stratum over a TCP connection with SSL/TLS. Just the same as normal TCP, but with SSL/TLS enabled.

jonatack commented at 6:52 pm on May 6, 2024:

0Stratum over a TCP connection with SSL/TLS: the same as normal TCP, but with SSL/TLS enabled.

in bip-0040.mediawiki:65 in ec52ae1321 outdated

60+* Default port: <code>50002</code>
61+* Letter: <code>s</code>
62+
63+===HTTP===
64+
65+Stratum over an HTTP connection. When communicating over HTTP, there 2 possible options: polling and pushing. In both cases, the request and response have a <code>Content-Type</code> header with the value <code>application/stratum</code>. Like in the TCP transport, the messages have to end with a line-feed (\n). It is possible to send more messages in one HTTP request or response.

jonatack commented at 6:54 pm on May 6, 2024:

0Stratum over an HTTP connection. When communicating over HTTP, there 2 possible options: polling and pushing. In both cases, the request and response have a <code>Content-Type</code> header with the value <code>application/stratum</code>. Like in the TCP transport, the messages have to end with a line-feed (<code>\n</code>). It is possible to send multiple messages in one HTTP request or response.

in bip-0040.mediawiki:67 in ec52ae1321 outdated

62+
63+===HTTP===
64+
65+Stratum over an HTTP connection. When communicating over HTTP, there 2 possible options: polling and pushing. In both cases, the request and response have a <code>Content-Type</code> header with the value <code>application/stratum</code>. Like in the TCP transport, the messages have to end with a line-feed (\n). It is possible to send more messages in one HTTP request or response.
66+
67+It could be possible that a request or response also has a <code>Content-MD5</code> header, so it is possible for the receiver to detect any modifications to the content. It is up to clients and servers how to handle upon a mismatch. A suggestion for a client would be to retry the command. A suggestion for a server would be to return a 400 error (or return a 200 error with a JSON-RPC error message).

jonatack commented at 6:55 pm on May 6, 2024:

0A request or response may contain a <code>Content-MD5</code> header to allow the receiver to detect any modification to the content. It is up to clients and servers how to handle a mismatch. A suggestion for a client would be to retry the command. A suggestion for a server would be to return a 400 error (or return a 200 error with a JSON-RPC error message).

in bip-0040.mediawiki:76 in ec52ae1321 outdated

71+
72+====Session====
73+
74+Because it is not sure if an HTTP connection will stay open, it is highly possible that messages will be sent over multiple connections. To keep track of the same "session", a cookie with the name <code>STRATUM_SESSION</code> is used. If a client sends a request with a cookie, the servers knows exactly which session is used and which notifications to send.
75+
76+Servers could send the <code>Stratum-Session-Timeout</code><ref name="extended"/> header to tell the client when a session with the same session id will be seen as a new session by the server. The header contains a number that indicates how many seconds are left. This is different from <code>Expires</code> or <code>Max-Age</code> parameters of the <code>Set-Cookie</code> header, that indicate when a cookie (not necessarily a session) should have been expired by the client. For backwards compatibility, a <code>X-Session-Timeout</code> header with the same value should be sent in those requests too.

jonatack commented at 6:57 pm on May 6, 2024:

0Servers could send the <code>Stratum-Session-Timeout</code><ref name="extended"/> header to tell the client when a session with the same session id will be seen as a new session by the server. The header contains a number that indicates how many seconds are left. This is different from <code>Expires</code> or <code>Max-Age</code> parameters of the <code>Set-Cookie</code> header that indicate when a cookie (not necessarily a session) should have been expired by the client. For backwards compatibility, a <code>X-Session-Timeout</code> header with the same value should be sent in those requests, too.

in bip-0040.mediawiki:80 in ec52ae1321 outdated

75+
76+Servers could send the <code>Stratum-Session-Timeout</code><ref name="extended"/> header to tell the client when a session with the same session id will be seen as a new session by the server. The header contains a number that indicates how many seconds are left. This is different from <code>Expires</code> or <code>Max-Age</code> parameters of the <code>Set-Cookie</code> header, that indicate when a cookie (not necessarily a session) should have been expired by the client. For backwards compatibility, a <code>X-Session-Timeout</code> header with the same value should be sent in those requests too.
77+
78+====HTTP Poll====
79+
80+When polling, an HTTP POST request is sent with <code>application/stratum</code> in the <code>Content-Type</code> header. In the body, there could be one or more messages. If the body is empty, the client just wants to check for notifications.

jonatack commented at 6:58 pm on May 6, 2024:

0When polling, an HTTP POST request is sent with <code>application/stratum</code> in the <code>Content-Type</code> header. In the body, there could be one or more messages. If the body is empty, the client only wants to check for notifications.

in bip-0040.mediawiki:82 in ec52ae1321 outdated

77+
78+====HTTP Poll====
79+
80+When polling, an HTTP POST request is sent with <code>application/stratum</code> in the <code>Content-Type</code> header. In the body, there could be one or more messages. If the body is empty, the client just wants to check for notifications.
81+
82+If no error occurred, the server will respond with a 200 status code and with <code>application/stratum</code> in the <code>Content-Type</code> header. If there are one or more notifications or other messages, the body will contain those messages. Else, the body will be empty.

jonatack commented at 6:59 pm on May 6, 2024:

0If no error occurred, the server will respond with a 200 status code and with <code>application/stratum</code> in the <code>Content-Type</code> header. If there are one or more notifications or other messages, the body will contain those messages. Otherwise, the body will be empty.

in bip-0040.mediawiki:86 in ec52ae1321 outdated

81+
82+If no error occurred, the server will respond with a 200 status code and with <code>application/stratum</code> in the <code>Content-Type</code> header. If there are one or more notifications or other messages, the body will contain those messages. Else, the body will be empty.
83+
84+====HTTP Push====
85+
86+HTTP Poll is the default mode when connecting with a server over HTTP. To get the session in HTTP Push mode, a client should send a regular HTTP Poll request with an additional <code>Stratum-Callback-URL</code><ref name="extended"/> header. This will let the server send notifications using the callback URL without the client needing to send HTTP poll requests in with a very small interval. To disable HTTP Push mode, a regular HTTP poll request should be sent with an additional empty <code>Stratum-Callback-URL</code><ref name="extended"/> header. For backwards compatibility, a <code>X-Callback-URL</code> header with the same value should be sent in those requests too.

jonatack commented at 7:00 pm on May 6, 2024:

0HTTP Poll is the default mode when connecting with a server over HTTP. To get the session in HTTP Push mode, a client should send a regular HTTP Poll request with an additional <code>Stratum-Callback-URL</code><ref name="extended"/> header. This will let the server send notifications using the callback URL without the client needing to send HTTP poll requests with a very small interval. To disable HTTP Push mode, a regular HTTP poll request should be sent with an additional empty <code>Stratum-Callback-URL</code><ref name="extended"/> header. For backwards compatibility, a <code>X-Callback-URL</code> header with the same value should be sent in those requests too.

in bip-0040.mediawiki:88 in ec52ae1321 outdated

83+
84+====HTTP Push====
85+
86+HTTP Poll is the default mode when connecting with a server over HTTP. To get the session in HTTP Push mode, a client should send a regular HTTP Poll request with an additional <code>Stratum-Callback-URL</code><ref name="extended"/> header. This will let the server send notifications using the callback URL without the client needing to send HTTP poll requests in with a very small interval. To disable HTTP Push mode, a regular HTTP poll request should be sent with an additional empty <code>Stratum-Callback-URL</code><ref name="extended"/> header. For backwards compatibility, a <code>X-Callback-URL</code> header with the same value should be sent in those requests too.
87+
88+The callback URL will be called when there are notifications. This request is an HTTP POST request with a <code>Content-Type</code> header and a <code>Stratum-Session-ID</code><ref name="extended"/> header. The <code>Stratum-Session-ID</code><ref name="extended"/> contains the same id as the <code>STRATUM_SESSION</code> cookie. This makes it possible to use the callback URL for multiple sessions. The response is of the callback URL is expected to be empty, so any response body will likely be ignored. For backwards compatibility, a <code>X-Session-ID</code> header with the same value should be sent in those requests too.

jonatack commented at 7:01 pm on May 6, 2024:

0The callback URL will be called when there are notifications. This request is an HTTP POST request with a <code>Content-Type</code> header and a <code>Stratum-Session-ID</code><ref name="extended"/> header. The <code>Stratum-Session-ID</code><ref name="extended"/> contains the same id as the <code>STRATUM_SESSION</code> cookie. This makes it possible to use the callback URL for multiple sessions. The response of the callback URL is expected to be empty, so any response body will likely be ignored. For backwards compatibility, a <code>X-Session-ID</code> header with the same value should be sent in those requests too.

in bip-0040.mediawiki:92 in ec52ae1321 outdated

87+
88+The callback URL will be called when there are notifications. This request is an HTTP POST request with a <code>Content-Type</code> header and a <code>Stratum-Session-ID</code><ref name="extended"/> header. The <code>Stratum-Session-ID</code><ref name="extended"/> contains the same id as the <code>STRATUM_SESSION</code> cookie. This makes it possible to use the callback URL for multiple sessions. The response is of the callback URL is expected to be empty, so any response body will likely be ignored. For backwards compatibility, a <code>X-Session-ID</code> header with the same value should be sent in those requests too.
89+
90+===HTTP over SSL/TLS===
91+
92+Stratum over an HTTP connection with SSL/TLS. Just the same as normal HTTP, but with SSL/TLS enabled.

jonatack commented at 7:02 pm on May 6, 2024:

0Stratum over an HTTP connection with SSL/TLS: the same as normal HTTP, but with SSL/TLS enabled.

in bip-0040.mediawiki:99 in ec52ae1321 outdated

94+* Default port: <code>8082</code>
95+* Letter: <code>g</code>
96+
97+===WebSocket===
98+
99+Stratum over a WebSocket connection. When using WebSockets, the JSON-RPC messages (including batch messages) are encapsulated in a WebSocket message. It is also possible to send more JSON-RPC messages in one WebSocket message. Every JSON-RPC message should end with a line-feed (\n). Both client and server can initiate a message request on which the other side could respond with a result or an error, like Stratum over TCP.

jonatack commented at 7:03 pm on May 6, 2024:

0Stratum over a WebSocket connection. When using WebSockets, the JSON-RPC messages (including batch messages) are encapsulated in a WebSocket message. It is also possible to send multiple JSON-RPC messages in one WebSocket message. Every JSON-RPC message should end with a line-feed (<code>\n</code>). Both client and server can initiate a message request on which the other side could respond with a result or an error, like Stratum over TCP.

in bip-0040.mediawiki:120 in ec52ae1321 outdated

115+  new WebSocket('ws://stratum.example.com:8083');
116+</pre>
117+
118+===WebSocket over SSL/TLS===
119+
120+Stratum over a WebSocket connection with SSL/TLS. Just the same as normal WebSocket, but with SSL/TLS enabled.

jonatack commented at 7:05 pm on May 6, 2024:

0Stratum over a WebSocket connection with SSL/TLS: the same as normal WebSocket, but with SSL/TLS enabled.

in bip-0040.mediawiki:157 in ec52ae1321 outdated

152+! Description
153+|-
154+! Result
155+| <code>array</code>
156+|
157+| The history of the a blockchain address.

jonatack commented at 7:07 pm on May 6, 2024:

“the a” -> one of these seems redundant

0| The history of the blockchain address.

jonatack commented at 7:08 pm on May 6, 2024: member

Some editorial feedback.

jonatack commented at 7:27 pm on May 6, 2024: member

This BIP refers to BIP41, The Stratum mining protocol, for which a BIP number was assigned and an entry exists in the README, but there doesn’t seem to be pull request to add the BIP draft – any update on that?

ben221199 commented at 7:36 pm on May 6, 2024: none

Hi @jonatack, thank you for feedback. I will take a look at it. I didn’t have time to work on BIP 40 lately. Yes, both BIP 40 and BIP 41 are already assigned by the README and BIP 41 is also mentioned in this BIP 40. The goal is to finish BIP 40 (Stratum wire protocol) first and then start working on BIP 41 (Stratum mining protocol), referring back to BIP 40, because the mining protocol is based on the wire protocol.

Process editorial feedback 84f851926e

ben221199 force-pushed on May 6, 2024

Merge branch 'master' into add-bip40

Signed-off-by: Ben van Hartingsveldt <ben.vanhartingsveldt@yocto.com>

b50e9e5de4

ben221199 force-pushed on May 6, 2024

Add IANA considerations 0cdfcb5d2e

Fix links 19a39e2e5b

Add information about service vendor 1cf59837c7

Fix layer 2f620f54ec

ben221199 commented at 11:18 am on May 7, 2024: none

The media type application/stratum has been registered by IANA at Media Types (https://www.iana.org/assignments/media-types/media-types.xhtml).

Merge branch 'master' into add-bip40 48adb0ff93

Add IANA consideration for HTTP fields b5a9b10216

Add example commands 19cf447939

Add example pub/sub commands 6e26691db9

Move services to seperate file 73f8ad180a

Add information about discovery service 2787db0163

Improve service documentation 40bc7213f7

Improve blockchain service documentation 05e11947bd

in bip-0040.mediawiki:157 in 05e11947bd outdated

152+
153+==IANA Considerations==
154+
155+===HTTP Field===
156+
157+IANA maintains the registry of HTTP Fields at https://www.iana.org/assignments/http-fields.

jonatack commented at 5:42 pm on May 21, 2024:

0The IANA maintains the registry of HTTP Fields at https://www.iana.org/assignments/http-fields.

ben221199 commented at 7:10 pm on May 21, 2024:

I see many RFCs that just use IANA instead of The IANA. I don’t see how this suggestion is better.

jonatack commented at 7:19 pm on May 21, 2024:

In English the article prefixes the noun.

See how the article the prefixes IANA on their website at https://www.iana.org/about. For instance, The global coordination of the DNS Root, IP addressing, and other Internet protocol resources is performed as the Internet Assigned Numbers Authority (IANA) functions.

ben221199 commented at 7:28 pm on May 21, 2024:

Example: https://www.rfc-editor.org/rfc/rfc6355

IANA has assigned the value 4 for use by the DHCPv6 DUID-UUID type.

in bip-0040.mediawiki:163 in 05e11947bd outdated

158+
159+This document serves as the specification for the HTTP fields "Stratum-Session-ID", "Stratum-Session-Timeout" and "Stratum-Callback-URL".
160+
161+===Media Type===
162+
163+IANA maintains the registry of Media Types [https://www.rfc-editor.org/info/bcp13 BCP13] at http://www.iana.org/assignments/media-types.

jonatack commented at 5:43 pm on May 21, 2024:

0The IANA maintains the registry of Media Types [https://www.rfc-editor.org/info/bcp13 BCP13] at http://www.iana.org/assignments/media-types.

ben221199 commented at 7:10 pm on May 21, 2024:

I see many RFCs that just use IANA instead of The IANA. I don’t see how this suggestion is better.

in bip-0040.mediawiki:169 in 05e11947bd outdated

164+
165+This document serves as the specification for the media type "application/stratum". It has been registered with IANA.
166+
167+===WebSocket Subprotocol Name===
168+
169+IANA maintains the registry of WebSocket Subprotocol Names at https://www.iana.org/assignments/websocket.

jonatack commented at 5:44 pm on May 21, 2024:

0The IANA maintains the registry of WebSocket Subprotocol Names at https://www.iana.org/assignments/websocket.

ben221199 commented at 7:10 pm on May 21, 2024:

I see many RFCs that just use IANA instead of The IANA. I don’t see how this suggestion is better.

in bip-0040.mediawiki:165 in 05e11947bd outdated

160+
161+===Media Type===
162+
163+IANA maintains the registry of Media Types [https://www.rfc-editor.org/info/bcp13 BCP13] at http://www.iana.org/assignments/media-types.
164+
165+This document serves as the specification for the media type "application/stratum". It has been registered with IANA.

jonatack commented at 5:44 pm on May 21, 2024:

0This document serves as the specification for the media type "application/stratum". It has been registered with the IANA.

ben221199 commented at 7:10 pm on May 21, 2024:

I see many RFCs that just use IANA instead of The IANA. I don’t see how this suggestion is better.

in bip-0040/service-example.mediawiki:98 in 05e11947bd outdated

93+| A string that tells that the command has finished running.
94+|}
95+
96+==Method: Throw Exception==
97+
98+Ask the server throw exception.

jonatack commented at 6:06 pm on May 21, 2024:

0Ask the server to throw an exception.

in bip-0040/service-example.mediawiki:124 in 05e11947bd outdated

119+| The error object.
120+|}
121+
122+==Method: Throw Signed Exception==
123+
124+Ask the server throw exception in a signed JSON-RPC object.

jonatack commented at 6:07 pm on May 21, 2024:

0Ask the server to throw an exception in a signed JSON-RPC object.

in bip-0040.mediawiki:141 in 05e11947bd outdated

136+
137+===Vendor: Electrum===
138+
139+* [[bip-0040/service-blockchain.address.mediawiki|Blockchain Address]]
140+* [[bip-0040/service-blockchain.block.mediawiki|Blockchain Block]]
141+* [[bip-0040/service-blockchain.transaction.mediawiki|Blockchain Translation]]

jonatack commented at 6:11 pm on May 21, 2024:

This seems to be incorrect.

0* [[bip-0040/service-blockchain.transaction.mediawiki|Blockchain Transaction]]

in bip-0040.mediawiki:147 in 05e11947bd outdated

142+* [[bip-0040/service-node.mediawiki|Node]]
143+* [[bip-0040/service-wallet.mediawiki|Wallet]]
144+
145+===Vendor: blockchain.info===
146+
147+* [[bip-0040/service-firstbits.mediawiki|Firstbits]]

jonatack commented at 6:12 pm on May 21, 2024:

This entry seems incorrect (and is identical to the next one).

ben221199 commented at 7:15 pm on May 21, 2024:

It is not incorrect. This service is created by two vendors, both firstbits.com and blockchain.info. They have the same methods, parameters, etc., so they are referencing to the same document, but listed twice.

jonatack commented at 6:18 pm on May 21, 2024: member

Thanks for updating. Took a look at the new additions.

jonatack commented at 6:53 pm on May 21, 2024: member

@ben221199 This draft might be missing the following:

- [ ] Backwards compatibility section describing incompatibilities, severity, and suggest mitigations
- [ ] Reference implementation (necessary before status "Final", but not necessary to be accepted)

ben221199 commented at 7:08 pm on May 21, 2024: none

Where should I place that?

Apply suggestions 16b6d5c5d3

jonatack renamed this:
~~Add draft of BIP 40~~
BIP40: Stratum wire protocol
on May 21, 2024

jonatack commented at 11:27 pm on May 21, 2024: member

Where should I place that?

They are generally the last two sections in other BIPs.

murchandamus added the label PR Author action required on May 31, 2024

plebhash commented at 5:20 pm on June 16, 2024: none

It seems BIP41 doesn’t have any PR yet, so I’ll write a comment on this one.

My goal is to inform BIP41 authors (@ben221199 or whoever else volunteers) that the Stratum Reference Implementation community is aiming for a similar effort for Stratum V2

ben221199 commented at 7:30 am on June 17, 2024: none

Hi @plebhash, thanks for commenting. You are correct that there is no BIP 41 pull request yet. This is because BIP 41 is an implementation of BIP 40 specifically for mining. I will start working on that one when BIP 40 is finished.

As far as I’m aware, Stratum V2 is specifically for mining. When people want to make improvements on Stratum V1, I think that is solely a BIP 41 improvement, because BIP 40 only describes the wire protocol (the basics) and the Electrum implementation, not the mining one.

I think there are some things that could be done:

Create a BIP for Stratum V2.
Make a decision if you want to create a new BIP for the V1 improvements, or if you want those improvements merged into BIP 41.

Also, can you give me some examples on what those improvments could be?

Thanks

plebhash commented at 7:54 pm on June 18, 2024: none

Create a BIP for Stratum V2.

that is an interesting idea!

plebhash commented at 7:55 pm on June 18, 2024: none

@ben221199 on the context of BIP40, could you provide some wayback machine link for the original (non-mining) stratum wire protocol?

this is a very interesting unknown fact in the mining community, and everyone I tell about this is surprised about this historical fact

Davidson-Souza commented at 7:00 pm on June 19, 2024: none

Hi @ben221199. Thank you for taking time to document the stratum protocol. However, I have some comments about your description of the electrum flavor of stratum. I’m not sure some of the specified endpoints are actually part of their protocol, for example: blockchain.address is long deprecated in favor of blockchain.scripthash. They also don’t have any method to get a full block.

Here is a doc of the latest protocol and all methods they currently support.

ben221199 commented at 8:38 pm on June 19, 2024: none

Hi @plebhash, the second message on https://bitcointalk.org/?topic=557866 is one of the source I have used. There are some other sources too, but I think this is the most important one.

ben221199 commented at 8:49 pm on June 19, 2024: none

Hi @Davidson-Souza, Stratum is invented by @slush0 especially for Electrum. Stratum wouldn’t be here without Electrum and Electrum would possibly not have been a success without Stratum. I think it is okay to have Electrum commands specified next to the more general commands like discovery.

I’m aware of the fact that blockchain.address has been deprecated by blockchain.scripthash. However, the Electrum commands specify also a versioning system (where Stratum itself does not), so I think it is also good to have every version documented. Technically, it is possible to write a client and/or server that implements the Stratum protocol with Electrum commands and support multiple protocol versions. Removing deprecated commands seems to be a bad practice in my eyes.

Davidson-Souza commented at 9:44 pm on June 19, 2024: none

Hi @Davidson-Souza, Stratum is invented by @slush0 especially for Electrum. Stratum wouldn’t be here without Electrum and Electrum would possibly not have been a success without Stratum. I think it is okay to have Electrum commands specified next to the more general commands like discovery.

I’m aware of the fact that blockchain.address has been deprecated by blockchain.scripthash. However, the Electrum commands specify also a versioning system (where Stratum itself does not), so I think it is also good to have every version documented. Technically, it is possible to write a client and/or server that implements the Stratum protocol with Electrum commands and support multiple protocol versions. Removing deprecated commands seems to be a bad practice in my eyes.

Hi, thank you for your reply. I do agree with the general direction you propose, I was a bit confused that this is not clear in the text. My understanding after reading it is that it defines the currently used commands by wallets and servers, but this is not the case.

ben221199 commented at 9:52 pm on June 19, 2024: none

@Davidson-Souza If you see improvements in text, don’t hesitate to give suggestions. GitHub makes it possible to make comments on code lines. 😄

ben221199 commented at 8:14 pm on November 25, 2024: none

Okay, I have to pick up this task again.

Improve sentences 4cf8985789

Improve documents of Stratum methods 1936b49803

Fix type and description bbad8a0a0c

Add examples to Firstbits methods 387af0f819

ben221199 commented at 6:06 pm on November 26, 2024: none

Some information about old commits…

Oldest commits with same server code:

Server code removed from client repository:

https://github.com/spesmilo/electrum/commit/2e5d015917be5989f82d94b9c18c68b40f443da3 (Client)

First appearance of Stratum in Electrum source code:

All commits where protocol versions changed:

https://github.com/spesmilo/electrum-server/commit/f5e9e2ef81050ba5d0e0798f86be2be84054a862 (Server; 0.1)
https://github.com/spesmilo/electrum-server/commit/cf7aed705dbfeaa8b9e56a0649fd70f48d80d33f (Server; 0.2)
https://github.com/spesmilo/electrum-server/commit/6a80f4b4a5315ed9d00f2b3117a5e0d447465cda (Server; 0.3)
https://github.com/spesmilo/electrum-server/commit/d600c3be009f131a35a622bc83e1ca9d40c241d7 (Server; 0.4)
https://github.com/spesmilo/electrum/commit/8ed812830f8880d02ffb521ff8835bff71d2fa24 (Client; 0.5)
https://github.com/spesmilo/electrum-server/commit/c293b5a5d4e71f555981ba934ec53dedcce36fea (Server; 0.5)
https://github.com/spesmilo/electrum/commit/8ec6a60daf7b0f3019677f27a20f59d311730c0f (Client; 0.6)
https://github.com/spesmilo/electrum-server/commit/1abbd5675d40b85eb339c90c4082cdc22e620a86 (Server; 0.6)
https://github.com/spesmilo/electrum-server/commit/24aa687775d6eac180088f72b2e8226cb572d7ef (Server; 0.7)
https://github.com/spesmilo/electrum-server/commit/a71f02d33aceec0b70bb365c7d89663a55c47f0a (Server; 0.8)
https://github.com/spesmilo/electrum-server/commit/fdf26dcd063af1cc68adcaf278c7d0180296d6c5 (Server; 0.9)
https://github.com/spesmilo/electrum/commit/118052d81597eff3eb636d242eacdd0437dabdd6 (Client; 0.10)
https://github.com/spesmilo/electrum-server/commit/1774ec1496ac8545b4d1b6b88f53d20d966afa29 (Server; 0.10)
https://github.com/spesmilo/electrum/commit/68873d92f9973b3d6befe9d2b69f67be71217501 (Client; 0.11)
https://github.com/spesmilo/electrum-server/commit/2baa164fc842bf39309c78c15bf89ef2f90a7b95 (Server; 1.0)
https://github.com/spesmilo/electrum/commit/7f9b473a988fc8461750f4f8f1622c429d11e0df (Client; 1.1)
https://github.com/spesmilo/electrum/commit/c3f3843cc3f31862f7e3bea1126cb42150c405c4 (Client; 1.2)
https://github.com/spesmilo/electrum/commit/8f36c9167de1bfd2505ef5516cd43661962b9c27 (Client; 1.4)

ben221199 commented at 6:30 pm on November 26, 2024: none

And for the ElectrumX server…

Protocol Minimum:

https://github.com/spesmilo/electrumx/commit/151da40d5b6be87bb95b7c8641262138f0333163 (ElectrumX; 1.0)
https://github.com/spesmilo/electrumx/commit/135ab68f7419b36d4d565eb47c254ac3240831bd (ElectrumX; 0.10)
https://github.com/spesmilo/electrumx/commit/09783aeacc3bae679fa599aae14d9bba23260d63 (ElectrumX; 0.9)
https://github.com/spesmilo/electrumx/commit/fec2ee1d8f2590a2ef5c970326e378415b4f6d6e (ElectrumX; 1.0)
https://github.com/spesmilo/electrumx/commit/7d9ffbbed001e512222b57f2161bb087b6b7e86c (ElectrumX; 1.1)
https://github.com/spesmilo/electrumx/commit/98ca2adc5e38c73738e2ff6a2838fced130729d8 (ElectrumX; 1.2)
https://github.com/spesmilo/electrumx/commit/9bc102f34a2811a2702995e3b3181568d3e53ff2 (ElectrumX; 1.4)
https://github.com/spesmilo/electrumx/commit/e3e915323c77cc22ea565993a3b8aeea85c84b31 (ElectrumX; 1.2)
https://github.com/spesmilo/electrumx/commit/f89cea536c475267ddf869eed9b25fb300414b54 (ElectrumX; 1.4)

Protocol Maximum:

https://github.com/spesmilo/electrumx/commit/151da40d5b6be87bb95b7c8641262138f0333163 (ElectrumX; 1.0)
https://github.com/spesmilo/electrumx/commit/135ab68f7419b36d4d565eb47c254ac3240831bd (ElectrumX; 1.1)
https://github.com/spesmilo/electrumx/commit/2d7403f2efed7e8f33c5cb93e2cd9144415cbb9f (ElectrumX; 1.2)
https://github.com/spesmilo/electrumx/commit/c35ac6d9bb1df107e09ee5acf25ef50a96bea8cd (ElectrumX; 1.3)
https://github.com/spesmilo/electrumx/commit/46d8e0c6086f87787fbc35eb329d10ba74e7cc58 (ElectrumX; 1.4)
https://github.com/spesmilo/electrumx/commit/936251aa960eac928729ba78b5ac11e64a958948 (ElectrumX; 1.4.1)
https://github.com/spesmilo/electrumx/commit/39817eec7e05c701c0760aeae37aa4dd568e005d (ElectrumX; 1.4.2)
https://github.com/spesmilo/electrumx/commit/714058794a69ec56563009509a1d6df54ff482f2 (ElectrumX; 1.4.3)

murchandamus commented at 7:44 pm on November 26, 2024: contributor

Hey @ben221199, this proposal has been emitting a lot of notifications recently without actually requiring editor input. I’m going to temporarily unsubscribe from this pull request while the document is taking shape. Please feel free to mention my handle when it is ready for an editor review. In the future, please consider opening early drafts of proposals against a personal fork of the BIPs repository instead of against the main BIPs repository.

ben221199 commented at 7:50 pm on November 26, 2024: none

Hey, @murchandamus. Thank you for letting me know. I will mention you when the draft is done.

Improve documentation of server commands db5ed7530c

Add remaining Stratum services 996724fe79

BIP40: Stratum wire protocol #1557