BIP: 40
Layer: Applications
Title: Stratum wire protocol
Author: Marek Palatinus
Ben van Hartingsveldt
Comments-Summary: No comments yet.
Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0040
Status: Draft
Type: Standards Track
Created: 2024-03-07
License: PD
==Abstract==
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.
Later in 2012, Marek Palatinus introduced Stratum also for mining pools: The Stratum mining protocol, as defined in [[bip-0041.mediawiki|BIP 41]].
==Specification: Data Format==
Stratum leverages [https://www.jsonrpc.org/ JSON-RPC]. Both versions 1.0 and 2.0 are allowed. Rules of that version apply accordingly.
Additionally, it is a convention to give all Stratum methods in the method property a name in the following form: ., where blockchain.block.subscribe.
''Note: In JSON-RPC 1.0, the param 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 params being an array, because it doesn't know how to handle the named ones, even if it supports JSON-RPC 2.0.''
==Specification: Transport Protocols==
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.
===TCP===
Stratum over a TCP connection. Every JSON-RPC message (including batch messages) is send on a single line, ending with a line-feed (\n), so \r\n 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.
* Default port: 50001
* Letter: t
===TCP over SSL/TLS===
Stratum over a TCP connection with SSL/TLS. Just the same as normal TCP, but with SSL/TLS enabled.
* Default port: 50002
* Letter: s
===HTTP===
Stratum over an HTTP connection.
* Default port: 8081
* Letter: h
===HTTP over SSL/TLS===
Stratum over an HTTP connection with SSL/TLS. Just the same as normal HTTP, but with SSL/TLS enabled.
* Default port: 8082
* Letter: g
===WebSocket===
Stratum over a WebSocket connection. Every JSON-RPC message (including batch messages) is sent encapsulated in a WebSocket message and therefore line-feeds are not needed. Still, 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.
* Default port: 8083[This is extended specification information of the Stratum protocol to make it more complete. This information will not be found in any code or specification before this BIP.]
* Letter: w8084u