This document describes the Stratum wire protocol used in clients such as Electrum, and which also laid the foundation for the Stratum mining protocol, used in many Bitcoin pools.
The specification is intended to set a standard for connections between clients and servers in which the client is able to request data without having to download the full blockchain.
The specification consists of three parts. In the first part, the data format is defined. In the second part, the possible transport protocols (including encapsulation) are described. In the third part, the available methods are documented.
==Motivation==
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.
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.
==History==
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.
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>.
''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.''
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.
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.
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.
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).
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", cookies are used. If a client sends a request with a cookie, the servers knows exactly which session is used and which notifications to send.
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.
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.
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 and 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.
* Default port: <code>8083</code><ref name="extended">This is extended specification information of the Stratum wire protocol to make it more complete. This information will not be found in any code or specification before this BIP.</ref>
In a WebSocket upgrade request, it is possible to use the <code>Sec-WebSocket-Protocol</code> header to let the WebSocket server know which subprotocol is desired to send over the connection. For Stratum, the value <code>stratum</code> is registered. The use of this header is optional. If the server supports the use of this subprotocol too, it will let the client know by sending a <code>Sec-WebSocket-Protocol</code> header back. If the server doesn't send a subprotocol back, the connection will continue without using one. Use of this feature is fully backwards compatible.
