diff --git a/README.mediawiki b/README.mediawiki index fdd27ac499..25cf8ab8e2 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -210,12 +210,12 @@ Those proposing changes should consider that ultimately consent may rest with th | Standard | Proposed |- -| 40 +| [[bip-0040.mediawiki|40]] | API/RPC | Stratum wire protocol -| Marek Palatinus +| Marek Palatinus, Ben van Hartingsveldt | Standard -| BIP number allocated +| Draft |- | 41 | API/RPC diff --git a/bip-0040.mediawiki b/bip-0040.mediawiki new file mode 100644 index 0000000000..47fdf7464b --- /dev/null +++ b/bip-0040.mediawiki @@ -0,0 +1,200 @@ +
+  BIP: 40
+  Layer: API/RPC
+  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 four 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. In the fourth part, signed messages are explained. + +==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 Stratum server synchronizes and indexes all the blocks for us. + +==History== + +The 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. + +Later in 2012, Marek Palatinus introduced Stratum for mining pools as well: The Stratum mining protocol, as defined in [[bip-0041.mediawiki|BIP 41]]. + +==Extension== + +This BIP has some extended specification information that isn't found in the older, legacy specifications.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. For backwards compatibility, it is recommended to implement the legacy specification information too, which is also described in this specification. + +==Specification: Data Format== + +Stratum leverages [https://www.jsonrpc.org/ JSON-RPC]. Both versions 1.0 and 2.0 are allowed, according to their respective rules. + +Additionally, it is a convention to give all Stratum methods in the method property a name that meets the following EBNF notation: method ::= serviceType ("[" serviceVendor "]")? "." methodName, where serviceType and serviceVendor are allowed to have dots and methodName isn't. For example, the values blockchain.block.subscribe and blockchain.block[Electrum].subscribe. + +The service vendor is optional. However, multiple vendors can define the same service type, so the service vendor is introduced to distinguish them. If the service vendor is absent, the default service type is executed. It is up to the server implementer which service vendor is the default. + +''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, 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 params as an array, because it doesn't know how to handle named params, 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. + +''Note: Implementers may write servers that support multiple coins, assuming that those coins all use the same port (e.g. 50001). Because HTTP and WebSockets support virtual hosting (Host header or :authority 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 and non-default ports is not user-friendly, this is also not recommended.'' + +===TCP=== + +Stratum over a TCP connection. Every JSON-RPC message (including batch messages) is sent 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. Below, the default ports of Stratum for Bitcoin are defined. Other coins may define other default ports. + +* Default port: 50001 +* Letter: t + +===TCP over SSL/TLS=== + +Stratum over a TCP connection with SSL/TLS: the same as normal TCP, but with SSL/TLS enabled. + +* Default port: 50002 +* Letter: s + +===HTTP=== + +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 Content-Type header with the value application/stratum. Like in the TCP transport, the messages have to end with a line-feed (\n). It is possible to send multiple messages in one HTTP request or response. + +A request or response may contain a Content-MD5 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). + +* Default port: 8081 +* Letter: h + +====Session==== + +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 STRATUM_SESSION is used. If a client sends a request with a cookie, the servers knows exactly which session is used and which notifications to send. + +Servers could send the Stratum-Session-Timeout 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 Expires or Max-Age parameters of the Set-Cookie header that indicate when a cookie (not necessarily a session) should have been expired by the client. For backwards compatibility, a X-Session-Timeout header with the same value should be sent in those requests, too. + +====HTTP Poll==== + +When polling, an HTTP POST request is sent with application/stratum in the Content-Type header. In the body, there could be one or more messages. If the body is empty, the client only wants to check for notifications. + +If no error occurred, the server will respond with a 200 status code and with application/stratum in the Content-Type header. If there are one or more notifications or other messages, the body will contain those messages. Otherwise, the body will be empty. + +====HTTP Push==== + +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 Stratum-Callback-URL 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 Stratum-Callback-URL header. For backwards compatibility, a X-Callback-URL header with the same value should be sent in those requests too. + +The callback URL will be called when there are notifications. This request is an HTTP POST request with a Content-Type header and a Stratum-Session-ID header. The Stratum-Session-ID contains the same id as the STRATUM_SESSION 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 X-Session-ID header with the same value should be sent in those requests too. + +===HTTP over SSL/TLS=== + +Stratum over an HTTP connection with SSL/TLS: the same as normal HTTP, but with SSL/TLS enabled. + +* Default port: 8082 +* Letter: g + +===WebSocket=== + +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 multiple 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. + +* Default port: 8083 +* Letter: w + +====Subprotocol==== + +In a WebSocket upgrade request, it is possible to use the Sec-WebSocket-Protocol header to let the WebSocket server know which subprotocol is desired to send over the connection. For Stratum, the value stratum 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 Sec-WebSocket-Protocol 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. + +====Example==== + +
+  // Open WebSocket with using a subprotocol
+  new WebSocket('ws://stratum.example.com:8083',['stratum']);
+
+  // Open WebSocket without using a subprotocol
+  new WebSocket('ws://stratum.example.com:8083');
+
+ +===WebSocket over SSL/TLS=== + +Stratum over a WebSocket connection with SSL/TLS: the same as normal WebSocket, but with SSL/TLS enabled. + +* Default port: 8084 +* Letter: u + +==Specification: Services== + +On top of Stratum, some services are defined. They are listed below, grouped by vendor. + +{{Note|type=warn|text=For protocol versions on and below 1.0, correctness of documentation about services "blockchain" and "server" cannot assured due to lack of information. Use with caution.}} + +===Vendor: Stratum=== + +* [[bip-0040/service-discovery.mediawiki|Discovery]] +* [[bip-0040/service-example.mediawiki|Example]] +* [[bip-0040/service-example.pubsub.mediawiki|Example Publish-Subscribe]] +* [[bip-0040/service-server.mediawiki|Server]] +* [[bip-0040/service-server.peers.mediawiki|Server Peers]] + +===Vendor: Electrum=== + +* [[bip-0040/service-blockchain.mediawiki|Blockchain]] +* [[bip-0040/service-blockchain.address.mediawiki|Blockchain Address]] +* [[bip-0040/service-blockchain.block.mediawiki|Blockchain Block]] +* [[bip-0040/service-blockchain.headers.mediawiki|Blockchain Headers]] +* [[bip-0040/service-blockchain.numblocks.mediawiki|Blockchain Number of Blocks]] +* [[bip-0040/service-blockchain.scripthash.mediawiki|Blockchain Script Hash]] +* [[bip-0040/service-blockchain.transaction.mediawiki|Blockchain Transaction]] +* [[bip-0040/service-blockchain.utxo.mediawiki|Blockchain Unspent Transaction Output]] +* [[bip-0040/service-mempool.mediawiki|Memory Pool]] + +===Vendor: blockchain.info=== + +* [[bip-0040/service-firstbits.mediawiki|Firstbits]] + +===Vendor: firstbits.com=== + +* [[bip-0040/service-firstbits.mediawiki|Firstbits]] + +==Specification: Signature== + +In Stratum, it is possible to sign messages. Before signing, the sign_time property is added to the root object. After that, the JSON is converted to canonical format with RFC 8785. This JSON is put through the sign function. The output of the sign function is added to the root object in the sign property. Also, the properties sign_id is added to the root object, where this ID can be used to know which private key is used and which public key needs to be used to verify the signature. Also, the sign_algo is added to indicate which algorithm is used. For now, only ecdsa;SECP256k1 is defined. + +For verification, from the received message JSON the sign property, sign_id property, and sign_algo need to be removed and the JSON must be converted to canonical format with RFC 8785. After that, the JSON can be put in the verification function, in combination with the public key that is retrieved by the sign_id. + +==IANA Considerations== + +===HTTP Field=== + +IANA maintains the registry of HTTP Fields at https://www.iana.org/assignments/http-fields. + +This document serves as the specification for the HTTP fields "Stratum-Session-ID", "Stratum-Session-Timeout" and "Stratum-Callback-URL". + +===Media Type=== + +IANA maintains the registry of Media Types [https://www.rfc-editor.org/info/bcp13 BCP13] at http://www.iana.org/assignments/media-types. + +This document serves as the specification for the media type "application/stratum". It has been registered with IANA. + +===Service Name and Transport Protocol Port Number=== + +IANA maintains the registry of Service Names and Transport Protocol Port Numbers [https://www.rfc-editor.org/info/bcp165 BCP165] at https://www.iana.org/assignments/service-names-port-numbers. + +This document serves as the specification for the service name "stratum" with TCP and UDP port number 50001 and description "Stratum Protocol". It has been registered with IANA. + +This document serves as the specification for the service name "stratums" with TCP and UDP port number 50002 and description "Stratum Protocol over SSL/TLS". It has been registered with IANA. + +===WebSocket Subprotocol Name=== + +IANA maintains the registry of WebSocket Subprotocol Names at https://www.iana.org/assignments/websocket. + +This document serves as the specification for the WebSocket subprotocol name "stratum". It has been registered with IANA. + +==References== + \ No newline at end of file diff --git a/bip-0040/service-blockchain.address.mediawiki b/bip-0040/service-blockchain.address.mediawiki new file mode 100644 index 0000000000..0dcfd5bbfc --- /dev/null +++ b/bip-0040/service-blockchain.address.mediawiki @@ -0,0 +1,423 @@ +=Service: Blockchain Address= + +* Service type: blockchain.address +* Service vendor: Electrum + +==Method: Get Balance== + +* Method name: get_balance +* Introduced in: 0.9 +* Deprecated in: 1.2 +* Removed in: 1.3 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.get_balance +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| int or object +| 103873966 {"confirmed":103873966,"unconfirmed":23684400} or 103873966 +| The balance. In version 0.9 it returns an integer containing the confirmed balance. In version 0.10/1.0 or higher, it returns an object with both confirmed and unconfirmed balance. +|- +! Result ["confirmed"] (if version is 0.10/1.0 or higher) +| int +| 103873966 +| The confirmed appropriate balance in minimum coin units. +|- +! Result ["unconfirmed"] (if version is 0.10/1.0 or higher) +| int +| 23684400 +| The confirmed appropriate balance in minimum coin units. +|} + +==Method: Get History== + +* Method name: get_history +* Introduced in: 0.1 +* Deprecated in: 1.2 +* Removed in: 1.3 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.get_history +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array +| [ { "height": 200004, "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412" }, { "height": 0, "tx_hash": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec" } ] +| The transaction history of the address. +|- +! Result [index]["tx_hash"] +| string +| 45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3 +| The hash of the transaction +|- +! Result [index]["height"] +| int +| 200004 or 0 or -1 +| The height of the block. +|} + +==Method: Get History 2== + +* Method name: get_history2 +* Introduced in: 0.5 +* Removed in: 0.7 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.get_history2 +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array +| [ { "height": 200004, "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412" } ] +| The transaction history of the address. +|- +! Result [index]["tx_hash"] +| string +| 45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3 +| The hash of the transaction +|- +! Result [index]["height"] +| int +| 200004 +| The height of the block. +|} + +==Method: Get Memory Pool== + +* Method name: get_mempool +* Introduced in: 0.10/1.0 +* Deprecated in: 1.2 +* Removed in: 1.3 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.get_mempool +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| object +| [ { "tx_hash": "45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3", "height": 0 } ] +| The balance. +|- +! Result [index]["tx_hash"] +| string +| 45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3 +| The hash of the transaction in the memory pool +|- +! Result [index]["height"] +| int +| 0 or -1 +| The height of the block: 0 if all inputs are confirmed, -1 if not. +|} + +==Method: Get Path== + +* Method name: get_path +* Introduced in: 0.9 +* Removed in: 0.10/1.0 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.get_path +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of arrayss +| [ ["AABBCC","DDEEFF"],["AABBCC","DDEEFF"] ] +| An array, where each item is another array with 2 elements. Both elements are hexadecimal strings. The first string is a key, the second string is a value. +|} + +==Method: Get Proof== + +* Method name: get_proof +* Introduced in: 0.10/1.0 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.get_proof +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of arrayss +| [ ["AABBCC","DDEEFF"],["AABBCC","DDEEFF"] ] +| An array, where each item is another array with 2 elements. Both elements are hexadecimal strings. The first string is a key, the second string is a value. +|} + +==Method: List Unspent== + +* Method name: listunspent +* Introduced in: 0.9 +* Deprecated in: 1.2 +* Removed in: 1.3 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.listunspent +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of objects +| [ { "tx_pos": 0, "value": 45318048, "tx_hash": "9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf", "height": 437146 } ] +| A list of unspent outputs. +|- +! Result [index]["tx_pos"] +| int +| 0 +| The position of the unspent output in a transaction. +|- +! Result [index]["value"] +| int +| 45318048 +| The amount of this output in coin units. +|- +! Result [index]["tx_hash"] +| string +| 9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf +| The hash of transaction the unspent output is in. +|- +! Result [index]["height"] +| int +| 437146 +| The height of the block, or 0 if in the memory pool. +|} + +==Method: Subscribe== + +* Method name: subscribe +* Introduced in: 0.1 +* Deprecated in: 1.2 +* Removed in: 1.3 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.subscribe +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address to subscribe to. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| ecbb16a0de5361fe241d426613bd10a3a7003bbcf0d6a1270993d0cc1810f777 +| The hexadecimal representation of the SHA256 hash of the address status. +|} + +{| +! [Notification] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.subscribe +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! Params [1] +| string +| ecbb16a0de5361fe241d426613bd10a3a7003bbcf0d6a1270993d0cc1810f777 +| The hexadecimal representation of the SHA256 hash of the address status. +|} + +==Method: Subscribe 2== + +* Method name: subscribe2 +* Introduced in: 0.5 +* Removed in: 0.7 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.subscribe2 +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| ecbb16a0de5361fe241d426613bd10a3a7003bbcf0d6a1270993d0cc1810f777 +| The hexadecimal representation of the SHA256 hash of the address status. +|} + +{| +! [Notification] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.subscribe2 +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address. +|- +! Params [1] +| string +| ecbb16a0de5361fe241d426613bd10a3a7003bbcf0d6a1270993d0cc1810f777 +| The hexadecimal representation of the SHA256 hash of the address status. +|} + +==Method: Unsubscribe== + +* Method name: unsubscribe +* Introduced in: 0.7 +* Removed in: 0.9 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.address.unsubscribe +|- +! Params [0] +| string +| My-Secret-Password +| The password of the server owner. +|- +! Params [1] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address to subscribe to. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| ok or authentication error +| Message about if unsubscribing is successful. +|} \ No newline at end of file diff --git a/bip-0040/service-blockchain.block.mediawiki b/bip-0040/service-blockchain.block.mediawiki new file mode 100644 index 0000000000..ca5179b188 --- /dev/null +++ b/bip-0040/service-blockchain.block.mediawiki @@ -0,0 +1,293 @@ +=Service: Blockchain Block= + +* Service type: blockchain.block +* Service vendor: Electrum + +==Method: Get Chunk== + +* Method name: get_chunk +* Introduced in: 0.3 +* Deprecated in: 1.2 +* Removed in: 1.4 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.block.get_chunk +|- +! Params [0] +| int +| 4 +| The zero-based chunk index. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| AABBCCDDEEFF +| The hexadecimal representation of concatenated block headers. In case of Bitcoin, each block header is 80 bytes and each chunk is 2016 block headers. +|} + +==Method: Get Header== + +* Method name: get_header +* Introduced in: 0.2 +* Deprecated in: 1.3 +* Removed in: 1.4 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.block.get_header +|- +! Params [0] +| int +| 2345344 +| The block height. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| object +| { "bits": 392292856, "block_height": 510000, "merkle_root": "297cfcc6a66e063692b20650d21cc0ac7a2a80f7277ebd7c5d6c7010a070d25c", "nonce": 3347656422, "prev_block_hash": "0000000000000000002292de0d9f03dfa15a04dbf09102d5d4552117b717fa86", "timestamp": 1519083654, "version": 536870912 } +| The deserialized header. +|- +! Result ["bits"] +| int +| 392292856 +| The block bits. +|- +! Result ["block_height"] +| int +| 510000 +| The height of the block. +|- +! Result ["merkle_root"] +| string +| 297cfcc6a66e063692b20650d21cc0ac7a2a80f7277ebd7c5d6c7010a070d25c +| The hexadecimal representation of the merkle root of the block. +|- +! Result ["nonce"] +| int +| 3347656422 +| The nonce of the block. +|- +! Result ["prev_block_hash"] +| string +| 0000000000000000002292de0d9f03dfa15a04dbf09102d5d4552117b717fa86 +| The hexadecimal representation of the hash of the previous block. +|- +! Result ["timestamp"] +| int +| 1519083654 +| The timestamp the block was created. +|- +! Result ["version"] +| int +| 536870912 +| The version of the block. +|} + +==Method: Header== + +* Method name: header +* Introduced in: 1.3 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.block.header +|- +! Params [0] +| int +| 2345344 +| The start block height. +|- +! Params [1] +| int +| 0 or 2345354 +| The checkpoint block height. Ignored if 0 or absent. Introduced in: 1.4 +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string or object +| 0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299 or { "branch": [ "000000004ebadb55ee9096c9a2f8880e09da59c0d68b1c228da88e48844a1485", "96cbbc84783888e4cc971ae8acf86dd3c1a419370336bb3c634c97695a8c5ac9", "965ac94082cebbcffe458075651e9cc33ce703ab0115c72d9e8b1a9906b2b636", "89e5daa6950b895190716dd26054432b564ccdc2868188ba1da76de8e1dc7591" ], "header": "0100000085144a84488ea88d221c8bd6c059da090e88f8a2c99690ee55dbba4e00000000e11c48fecdd9e72510ca84f023370c9a38bf91ac5cae88019bee94d24528526344c36649ffff001d1d03e477", "root": "e347b1c43fd9b5415bf0d92708db8284b78daf4d0e24f9c3405f45feb85e25db" } +| Information about the header. It returns an object if cp_height is non-zero. +|- +! Result ["header"] (if cp_height is non-zero) +| string +| 0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299 +| The hexadecimal representation of the binary block header. Since version 1.4.1, the AuxPoW data is truncated (if present in the header). +|- +! Result ["root"] (if cp_height is non-zero) +| string +| e347b1c43fd9b5415bf0d92708db8284b78daf4d0e24f9c3405f45feb85e25db +| The merkle root of all headers up to cp_height. +|- +! Result ["branch"] (if cp_height is non-zero) +| array +| [ "000000004ebadb55ee9096c9a2f8880e09da59c0d68b1c228da88e48844a1485","96cbbc84783888e4cc971ae8acf86dd3c1a419370336bb3c634c97695a8c5ac9"] +| The merkle branch the last returned header up to root; deepest pairing first. +|} + +==Method: Headers== + +* Method name: headers +* Introduced in: 1.2 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.block.headers +|- +! Params [0] +| int +| 2345344 +| The start block height. +|- +! Params [1] +| int +| 20 +| Te amount of headers to be returned. +|- +! Params [2] +| int +| 0 or 2345354 +| The checkpoint block height. Ignored if 0 or absent. Introduced in: 1.4 +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| object +| { "count": 2, "hex": "0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299", "max": 2016, "root":"AABBCC", "branch":"DDEEFF" } +| Information about multiple headers. +|- +! Result ["count"] +| int +| 2 +| The amount of returned headers. +|- +! Result ["hex"] +| string +| 0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299 +| The hexadecimal representation of the concatenated binary block headers. Since version 1.4.1, the AuxPoW data is truncated (if present in the header), if cp_height is non-zero. +|- +! Result ["max"] +| int +| 2016 +| The maximum amount of headers this method will return. +|- +! Result ["root"] +| string +| e347b1c43fd9b5415bf0d92708db8284b78daf4d0e24f9c3405f45feb85e25db +| The merkle root of all headers up to cp_height. Present if cp_height is non-zero. +|- +! Result ["branch"] +| array +| [ "000000004ebadb55ee9096c9a2f8880e09da59c0d68b1c228da88e48844a1485","96cbbc84783888e4cc971ae8acf86dd3c1a419370336bb3c634c97695a8c5ac9"] +| The merkle branch the last returned header up to root; deepest pairing first. Present if cp_height is non-zero. +|} + +==Method: Subscribe== + +* Method name: subscribe +* Introduced in: Stratum Reference Implementation (never implemented in Electrum) + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.block.subscribe +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| Unknown +| +| UNKNOWN +|} + +==Method: Unsubscribe== + +* Method name: unsubscribe +* Introduced in: Stratum Reference Implementation (never implemented in Electrum) + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.block.unsubscribe +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| Unknown +| +| UNKNOWN +|} + +==Method: Get Block Number== + +* Method name: get_blocknum +* Introduced in: Stratum Reference Implementation (never implemented in Electrum) + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.block.get_blocknum +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| int +| 2345344 +| The block number (block height). +|} \ No newline at end of file diff --git a/bip-0040/service-blockchain.headers.mediawiki b/bip-0040/service-blockchain.headers.mediawiki new file mode 100644 index 0000000000..86fc08d62e --- /dev/null +++ b/bip-0040/service-blockchain.headers.mediawiki @@ -0,0 +1,59 @@ +=Service: Blockchain Headers= + +* Service type: blockchain.headers +* Service vendor: Electrum + +==Method: Subscribe== + +* Method name: subscribe +* Introduced in: 0.3 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.headers.subscribe +|- +! Params [0] +| boolean +| true or false +| Introduced in: 1.2. Removed in: 1.4. In 1.2 the default value false was deprecated. In 1.3 the default value was changed to true. If raw is false, it returns the same object as blockchain.block.get_header, but than for the tip. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| object +| { "height": 520481, "hex": "00000020890208a0ae3a3892aa047c5468725846577cfcd9b512b50000000000000000005dc2b02f2d297a9064ee103036c14d678f9afc7e3d9409cf53fd58b82e938e8ecbeca05a2d2103188ce804c4" } +| Information about the header of the current block tip. See blockchain.block.get_header for result if raw is false. +|- +! Result ["height"] (if raw is true) +| int +| 520481 +| The height of the current block tip. +|- +! Result ["hex"] (if raw is true) +| string +| 00000020890208a0ae3a3892aa047c5468725846577cfcd9b512b50000000000000000005dc2b02f2d297a9064ee103036c14d678f9afc7e3d9409cf53fd58b82e938e8ecbeca05a2d2103188ce804c4 +| The header of the current block tip. +|} + +{| +! [Notification] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.headers.subscribe +|- +! Params [0] +| string or object +| 00000020890208a0ae3a3892aa047c5468725846577cfcd9b512b50000000000000000005dc2b02f2d297a9064ee103036c14d678f9afc7e3d9409cf53fd58b82e938e8ecbeca05a2d2103188ce804c4 +| The header of the new current block tip. Type is string if raw is true. See blockchain.block.get_header for result if raw is false. +|} \ No newline at end of file diff --git a/bip-0040/service-blockchain.mediawiki b/bip-0040/service-blockchain.mediawiki new file mode 100644 index 0000000000..a046a4f7be --- /dev/null +++ b/bip-0040/service-blockchain.mediawiki @@ -0,0 +1,61 @@ +=Service: Blockchain= + +* Service type: blockchain +* Service vendor: Electrum + +==Method: Estimate Fee== + +* Method name: estimatefee +* Introduced in: 0.10/1.0 +* Deprecated in: 1.4.2 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.estimatefee +|- +! Params [0] +| int +| 123 +| The number of blocks to target for confirmation. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| float +| 0.00001 or -1 +| The estimated transaction fee in coin units per kilobyte, as a floating point number, or -1 if cannot estimate. +|} + +==Method: Relay Fee== + +* Method name: relayfee +* Introduced in: after 0.10/1.0 +* Deprecated in: 1.4.2 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.relayfee +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| float +| 0.00001 +| The fee in whole coin units as a floating point number. +|} \ No newline at end of file diff --git a/bip-0040/service-blockchain.numblocks.mediawiki b/bip-0040/service-blockchain.numblocks.mediawiki new file mode 100644 index 0000000000..f6f1a1d5b5 --- /dev/null +++ b/bip-0040/service-blockchain.numblocks.mediawiki @@ -0,0 +1,46 @@ +=Service: Blockchain Number of Blocks= + +* Service type: blockchain.numblocks +* Service vendor: Electrum + +==Method: Subscribe== + +* Method name: subscribe +* Introduced in: 0.1 +* Deprecated in: 1.0 +* Removed in: 1.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.numblocks.subscribe +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| int +| 2345344 +| The current block number (block height). +|} + +{| +! [Notification] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.numblocks.subscribe +|- +! Params [0] +| int +| 2345344 +| The new current block number (block height). +|} \ No newline at end of file diff --git a/bip-0040/service-blockchain.scripthash.mediawiki b/bip-0040/service-blockchain.scripthash.mediawiki new file mode 100644 index 0000000000..25cb798335 --- /dev/null +++ b/bip-0040/service-blockchain.scripthash.mediawiki @@ -0,0 +1,264 @@ +=Service: Blockchain Script Hash= + +* Service type: blockchain.scripthash +* Service vendor: Electrum + +==Method: Get Balance== + +* Method name: get_balance +* Introduced in: 1.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.scripthash.get_balance +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The script hash. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| object +| {"confirmed":103873966,"unconfirmed":23684400} +| The balance. +|- +! Result ["confirmed"] +| int +| 103873966 +| The confirmed appropriate balance in minimum coin units. +|- +! Result ["unconfirmed"] +| int +| 23684400 +| The confirmed appropriate balance in minimum coin units. +|} + +==Method: Get History== + +* Method name: get_history +* Introduced in: 1.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.scripthash.get_history +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The script hash. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array +| [ { "height": 200004, "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412" }, { "fee": 20000, "height": 0, "tx_hash": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec" } ] +| The transaction history of the script hash, both confirmed (in blockchain order) and unconfirmed (memory pool). The unconfirmed items come after the confirmed items and are the same as returned by blockchain.scripthash.get_mempool. +|- +! Result [index]["tx_hash"] +| string +| 45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3 +| The hash of the transaction +|- +! Result [index]["height"] +| int +| 200004 or 0 or -1 +| The height of the block, or if in memory pool: 0 if all inputs are confirmed, -1 if not. +|- +! Result [index]["fee"] +| int +| 24310 +| The fee of the transaction in coin units. Only present when in memory pool. +|} + +==Method: Get Memory Pool== + +* Method name: get_mempool +* Introduced in: 1.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.scripthash.get_mempool +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The script hash. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| object +| [ { "tx_hash": "45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3", "height": 0, "fee": 24310 } ] +| The balance. +|- +! Result [index]["tx_hash"] +| string +| 45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3 +| The hash of the transaction in the memory pool +|- +! Result [index]["height"] +| int +| 0 or -1 +| The height of the block: 0 if all inputs are confirmed, -1 if not. +|- +! Result [index]["fee"] +| int +| 24310 +| The fee of the transaction in coin units. +|} + +==Method: List Unspent== + +* Method name: listunspent +* Introduced in: 1.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.scripthash.listunspent +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The script hash. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of objects +| [ { "tx_pos": 0, "value": 45318048, "tx_hash": "9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf", "height": 437146 } ] +| A list of unspent outputs. +|- +! Result [index]["tx_pos"] +| int +| 0 +| The position of the unspent output in a transaction. +|- +! Result [index]["value"] +| int +| 45318048 +| The amount of this output in coin units. +|- +! Result [index]["tx_hash"] +| string +| 9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf +| The hash of transaction the unspent output is in. +|- +! Result [index]["height"] +| int +| 437146 +| The height of the block, or 0 if in the memory pool. +|} + +==Method: Subscribe== + +* Method name: subscribe +* Introduced in: 1.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.scripthash.subscribe +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The script hash. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string or null +| f80c94a96dcb2fe7daf2c5437bd1315d27802a30bb23507f444cbd9bb093ea1a or null +| The status of the script hash, of null if there are no transactions. +|} + +{| +! [Notification] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.scripthash.subscribe +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The script hash. +|- +! Params [1] +| string +| f80c94a96dcb2fe7daf2c5437bd1315d27802a30bb23507f444cbd9bb093ea1a +| The status of the script hash. +|} + +==Method: Unsubscribe== + +* Method name: unsubscribe +* Introduced in: 1.4.1 or 1.4.2 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.scripthash.unsubscribe +|- +! Params [0] +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The script hash. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| boolean +| true or false +| True if unsubscribing succeeded, false if it failed. +|} \ No newline at end of file diff --git a/bip-0040/service-blockchain.transaction.mediawiki b/bip-0040/service-blockchain.transaction.mediawiki new file mode 100644 index 0000000000..bcc7c50fb6 --- /dev/null +++ b/bip-0040/service-blockchain.transaction.mediawiki @@ -0,0 +1,261 @@ +=Service: Blockchain Transaction= + +* Service type: blockchain.transaction +* Service vendor: Electrum + +==Method: Guess Fee== + +* Method name: guess_fee +* Introduced in: Bitcoin Forum (never implemented in Electrum) + +''No information available.'' + +==Method: Broadcast== + +* Method name: broadcast +* Introduced in: 0.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.transaction.broadcast +|- +! Params [0] +| string +| 4a5e1e4baa4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33bb89f3a32518a88c34a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b1bc87f4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b618f76673e2cc77ab2127b7afdeda33b +| The raw transaction. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string or absent +| a76242fce5753b4212f903ff33ac6fe66f2780f34bdb4b33b175a7815a11a98e or 258: txn-mempool-conflict +| The transaction hash or an error. Since 1.1 the error is not returned as a JSON-RPC result, but as a JSON-RPC error. +|} + +==Method: Get== + +* Method name: get +* Introduced in: 0.5 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.transaction.get +|- +! Params [0] +| string +| 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b +| The transaction hash. Removed in: 1.1 +|- +! Params [1] +| int +| 346343 +| The block height. +|- +! Params [2] +| boolean +| true or false +| If verbose. Introduced in: 1.2 +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string or object +| AABBCCDD or {} +| A hexadecimal representation of the transaction, or a verbose coin-specific object. +|} + +==Method: Get Merkle== + +* Method name: get_merkle +* Introduced in: 0.2 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.transaction.get_merkle +|- +! Params [0] +| string +| 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b +| The transaction hash. +|- +! Params [1] +| int +| 346343 +| The block height. Introduced in: 0.6 +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| object +| { "merkle": [ "713d6c7e6ce7bbea708d61162231eaa8ecb31c4c5dd84f81c20409a90069cb24", "03dbaec78d4a52fbaf3c7aa5d3fccd9d8654f323940716ddf5ee2e4bda458fde" ], "block_height": 450538, "pos": 710 } +| The transaction hash, optionally with merkle information. +|- +! Result ["block_height"] +| int +| 464353 +| The block height. +|- +! Result ["pos"] +| int +| 12 +| The position of the transaction in a block. +|- +! Result ["merkle"] +| array of strings +| [ "928c4275dfd6270349e76aa5a49b355eefeb9e31ffbe95dd75fed81d219a23f8", "5f35bfb3d5ef2ba19e105dcd976928e675945b9b82d98a93d71cbad0e714d04e" ] +| An array of merkle proof information. +|} + +==Method: Get TSC Bitcoin Association Merkle== + +* Method name: get_tsc_merkle +* Introduced in: Electrum Documentation (never implemented in Electrum) + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.transaction.get_tsc_merkle +|- +! Params [0] +| string +| 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b +| The transaction hash. +|- +! Params [1] +| int +| 553453 +| The block height. +|- +! Params [2] +| string +| txid or tx +| Return only transaction ID, or whole transaction. Default is transaction ID ("txid"). +|- +! Params [3] +| string +| block_hash, block_header, or merkle_root +| The target type. The selected type is returned. Default is transaction ID ("block_hash"). +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| object +| { "composite": false, "index": 4, "nodes": [ "*", "*", "80c0100bc080eb0d2e205dc687056dc13c2079d0959c70cad8856fea88c74aba"], "proofType": "branch", "target": "29442cb6e2ee547fcf5200dfb1b4018f4fc5ce5a220bb5ec3729a686885692fc", "targetType": "block_hash", "txOrId": "ed5a81e439e1cd9139ddb81da80bfa7cfc31e323aea544ca92a9ee1d84b9fb2f" } +| The merkle information. +|- +! Result ["composite"] +| boolean +| false or true +| Whether or not this is a composite merkle proof. +|- +! Result ["index"] +| int +| 4 +| The position index of the transaction in the block. +|- +! Result ["nodes"] +| array of strings +| [ "*", "*", "80c0100bc080eb0d2e205dc687056dc13c2079d0959c70cad8856fea88c74aba"] +| The list of hash pairs making up the merkle branch. +|- +! Result ["proofType"] +| string +| branch or tree +| The proof type. +|- +! Result ["target"] +| string +| 29442cb6e2ee547fcf5200dfb1b4018f4fc5ce5a220bb5ec3729a686885692fc +| The target value. +|- +! Result ["targetType"] +| string +| block_hash, block_header, or merkle_root +| The same target type as in the request. +|- +! Result ["txOrId"] +| string +| ed5a81e439e1cd9139ddb81da80bfa7cfc31e323aea544ca92a9ee1d84b9fb2f +| Either the transaction hash or the whole transaction. +|} + +==Method: ID from Position== + +* Method name: id_from_pos +* Introduced in: 1.4 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.transaction.id_from_pos +|- +! Params [0] +| int +| 553453 +| The block height. +|- +! Params [1] +| int +| 2 +| The transaction position in a block. +|- +! Params [2] +| boolean +| true or false +| If a merkle proof should be returned. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string or object +| fc12dfcb4723715a456c6984e298e00c479706067da81be969e8085544b0ba08 or { "tx_hash": "fc12dfcb4723715a456c6984e298e00c479706067da81be969e8085544b0ba08", "merkle": [ "928c4275dfd6270349e76aa5a49b355eefeb9e31ffbe95dd75fed81d219a23f8", "5f35bfb3d5ef2ba19e105dcd976928e675945b9b82d98a93d71cbad0e714d04e" ] } +| The transaction hash, optionally with merkle information. +|- +! Result ["tx_hash"] (if merkle is true) +| string +| fc12dfcb4723715a456c6984e298e00c479706067da81be969e8085544b0ba08 +| The hash of the transaction. +|- +! Result ["merkle"] (if merkle is true) +| array of strings +| [ "928c4275dfd6270349e76aa5a49b355eefeb9e31ffbe95dd75fed81d219a23f8", "5f35bfb3d5ef2ba19e105dcd976928e675945b9b82d98a93d71cbad0e714d04e" ] +| An array of merkle proof information. +|} \ No newline at end of file diff --git a/bip-0040/service-blockchain.utxo.mediawiki b/bip-0040/service-blockchain.utxo.mediawiki new file mode 100644 index 0000000000..da046fcae4 --- /dev/null +++ b/bip-0040/service-blockchain.utxo.mediawiki @@ -0,0 +1,41 @@ +=Service: Blockchain Unspent Transaction Output= + +* Service type: blockchain.utxo +* Service vendor: Electrum + +==Method: Get Address== + +* Method name: get_address +* Introduced in: 0.10/1.0 +* Deprecated in: 1.0 +* Removed in: 1.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | blockchain.utxo.get_address +|- +! Params [0] +| string +| 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b +| The transaction hash. +|- +! Params [1] +| int +| 3 +| The index position of the output in the transaction. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string or null +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address of the output, or null if transaction or output does not exist. If the output is spent, it MAY return null too. +|} \ No newline at end of file diff --git a/bip-0040/service-discovery.mediawiki b/bip-0040/service-discovery.mediawiki new file mode 100644 index 0000000000..9ad91eb12b --- /dev/null +++ b/bip-0040/service-discovery.mediawiki @@ -0,0 +1,145 @@ +=Service: Discovery= + +* Service type: discovery +* Service vendor: Stratum + +==Method: List Services== + +* Method name: list_services + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | discovery.list_services +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of strings +| ["discovery","example","example.pubsub"] +| The services that are implemented by the server. +|} + +==Method: List Vendors== + +* Method name: list_vendors + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | discovery.list_vendors +|- +! Params [0] (service_type) +| string +| firstbits +| The service you want all the vendors of. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of strings +| ["blockchain.info","firstbits.com"] +| The vendors of the requested service. +|} + +==Method: List Methods== + +* Method name: list_methods + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | discovery.list_methods +|- +! Params [0] (service_name) +| string +| firstbits[firstbits.com] +| The service name (eventually including a service vendor in square brackets). +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of strings +| ["create","resolve"] +| The methods of the requested service. +|} + +==Method: List Params== + +* Method name: list_params + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | discovery.list_params +|- +! Params [0] (method) +| string +| firstbits[firstbits.com].create +| The full method name, including the service name (and possibly the service vendor in square brackets). +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array +| ["Some method help text",[ ["address","string","String containing full Bitcoin address."] ]] +| The help text and parameters of the requested method. +|- +! Result [0] (help_text) +| string +| Some method help text +| The help text of requested method. +|- +! Result [1] (params) +| array of arrays +| [ ["address","string","String containing full Bitcoin address."] ] +| The parameters of requested method. +|- +! Result [1][index] (params[index]) +| array +| ["address","string","String containing full Bitcoin address."] +| The parameter at position index of requested method. +|- +! Result [1][index][0] +| string +| address +| The name of the parameter at position index of requested method. +|- +! Result [1][index][1] +| string +| string +| The type of the parameter at position index of requested method. +|- +! Result [1][index][2] +| string +| String containing full Bitcoin address. +| The description of the parameter at position index of requested method. +|} \ No newline at end of file diff --git a/bip-0040/service-example.mediawiki b/bip-0040/service-example.mediawiki new file mode 100644 index 0000000000..d4439e16b5 --- /dev/null +++ b/bip-0040/service-example.mediawiki @@ -0,0 +1,146 @@ +=Service: Example= + +This service is an example service. It doesn't have any other purpose than testing. + +* Service type: example +* Service vendor: Stratum + +==Method: Hello World== + +Ask the server to send a "Hello world!" back. + +* Method name: hello_world + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | example.hello_world +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| Hello world! +| The "Hello world" text. +|} + +==Method: Ping== + +Ping the server and get a pong back with the same text. + +* Method name: ping + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | example.ping +|- +! Params [0] (payload) +| mixed +| 12345678 +| The ping payload. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| mixed +| 12345678 +| The pong payload, same as the ping payload. +|} + +==Method: Synchronous== + +Ask the server to run a synchronous command for a specific amount of seconds. + +* Method name: synchronous + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | example.synchronous +|- +! Params [0] (how_long) +| int (or a string or a float that can be casted to an int) +| 123 +| The time to run. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| Request finished in 123 seconds +| A string that tells that the command has finished running. +|} + +==Method: Throw Exception== + +Ask the server to throw an exception. + +* Method name: throw_exception + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | example.throw_exception +|- +! [Response] +! Type +! Example +! Description +|- +! Error +| object +| {"code":-1,"data":"Some traceback","message":"Some error"} +| The error object. +|} + +==Method: Throw Signed Exception== + +Ask the server to throw an exception in a signed JSON-RPC object. + +* Method name: throw_signed_exception + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | example.throw_signed_exception +|- +! [Response] +! Type +! Example +! Description +|- +! Error +| object +| {"code":-1,"data":"Some traceback","message":"Some error"} +| The error object. +|} \ No newline at end of file diff --git a/bip-0040/service-example.pubsub.mediawiki b/bip-0040/service-example.pubsub.mediawiki new file mode 100644 index 0000000000..77af2bc027 --- /dev/null +++ b/bip-0040/service-example.pubsub.mediawiki @@ -0,0 +1,99 @@ +=Service: Example Publish-Subscribe= + +This service is an example service. It doesn't have any other purpose than testing. + +* Service type: example.pubsub +* Service vendor: Stratum + +==Method: Subscribe== + +Subscribe on an event. + +* Method name: subscribe + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | example.pubsub.subscribe +|- +! Params [0] (period) +| int +| 12 +| Period to wait for next emission. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array +| ["example.pubsub.time_event", "some-subscription-key"] +| The subscription information. +|- +! Result [0] (event) +| string +| example.pubsub.time_event +| The subscription event name. In this case, it is example.pubsub.time_event. +|- +! Result [1] (subscription_key) +| string +| some-subscription-key +| The subscription key of the event subscription. +|} + +==Method: Time Event== + +The time event that gets emitted. + +* Method name: time_event + +{| +! [Notification] +! Type +! Example +! Description +|- +! Method +| colspan="3" | example.pubsub.time_event +|- +! Params [0] (t) +| int +| 1231006505 +| The time when the time event was emitted. +|} + +==Method: Unsubscribe== + +Unsubscribe from an event. + +* Method name: unsubscribe + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | example.pubsub.unsubscribe +|- +! Params [0] (subscription_key) +| string +| some-subscription-key +| The subscription key of the event subscription. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| boolean +| true +| True if subscription is removed from session, false if failed. +|} \ No newline at end of file diff --git a/bip-0040/service-firstbits.mediawiki b/bip-0040/service-firstbits.mediawiki new file mode 100644 index 0000000000..c440597116 --- /dev/null +++ b/bip-0040/service-firstbits.mediawiki @@ -0,0 +1,62 @@ +=Service: Firstbits= + +* Service type: firstbits +* Service vendor: blockchain.info and firstbits.com + +==Method: Create== + +* Method name: create + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | firstbits.create +|- +! Params [0] (address) +| string +| 1MarekMKDKRb6PEeHeVuiCGayk9avyBGBB +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| 1marekm +| The firstbits string. +|} + +==Method: Resolve== + +* Method name: resolve + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | firstbits.resolve +|- +! Params [0] (firstbits) +| string +| 1marekm +| The address. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| 1MarekMKDKRb6PEeHeVuiCGayk9avyBGBB +| The address. +|} \ No newline at end of file diff --git a/bip-0040/service-mempool.mediawiki b/bip-0040/service-mempool.mediawiki new file mode 100644 index 0000000000..07015f8244 --- /dev/null +++ b/bip-0040/service-mempool.mediawiki @@ -0,0 +1,30 @@ +=Service: Memory Pool= + +* Service type: mempool +* Service vendor: Electrum + +==Method: Get Fee Histogram== + +* Method name: get_fee_histogram +* Introduced in: 1.2 +* Deprecated in: 1.4.2 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | mempool.get_fee_histogram +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of arrays of ints +| [ [12, 128812], [4, 92524], [2, 6478638], [1, 22890421] ] +| An array where each item is an array with 2 integers, where the first integer is the fee and the second integer is cumulative virtual size of mempool transactions. The fee is always lower than the fee of the previous item. +|} \ No newline at end of file diff --git a/bip-0040/service-server.mediawiki b/bip-0040/service-server.mediawiki new file mode 100644 index 0000000000..b2eaacc06d --- /dev/null +++ b/bip-0040/service-server.mediawiki @@ -0,0 +1,438 @@ +=Service: Server= + +* Service type: server +* Service vendor: Electrum + +==Method: Add Peer== + +A command to add the node to the peer list. + +* Method name: add_peer +* Introduced in: 1.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.add_peer +|- +! Params [0] +| object +| {"hosts":{"1.2.3.4":{"ssl_port":50002,"tcp_port":50001}},"genesis_hash":"000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f","hash_function":"sha256","server_version":"Electrum Server 4.5.6","protocol_max":"1.1","protocol_min":"1.0","pruning":1000} +| The features of the server. See server.features for more details. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| boolean +| true or false +| Indication if the server features are accepted by now. If so, more tests can follow before the server will become visible at server.peers.subscribe +|} + +==Method: Banner== + +A command to get the server banner. + +* Method name: banner +* Introduced in: 0.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.banner +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| Welcome to Electrum! +| The server banner. +|} + +==Method: Cache== + +A command to get the server cache size. + +* Method name: cache +* Introduced in: 0.1 +* Removed in: 0.9 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.cache +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| int +| 1234 +| The amount of cache in bytes. +|} + +==Method: Debug== + +* Method name: debug +* Introduced in: 0.9 +* Removed in: 0.10/1.0 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.debug +|- +! Params [0] +| string +| My-Secret-Password +| The password of the server owner. +|- +! Params [1] +| string +| repr({str(i): i**2 for i in range(5)}) +| The data that will be evaluated by the server. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| 1234 or error +| The string version of the evaluated data. +|} + +==Method: Donation Address== + +A command to get the server donation address. + +* Method name: donation_address +* Introduced in: 0.10/1.0 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.donation_address +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJDE9L +| The address you can donate to if you want to help the server owner. +|} + +==Method: Features== + +A command to get the server features. + +* Method name: features +* Introduced in: 1.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.features +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| object +| {"hosts":{"1.2.3.4":{"ssl_port":50002,"tcp_port":50001}},"genesis_hash":"000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f","hash_function":"sha256","server_version":"Electrum Server 4.5.6","protocol_max":"1.1","protocol_min":"1.0","pruning":1000} +| The features of the server. +|- +! Result ["hosts"] +| object +| {"1.2.3.4":{"ssl_port":50002,"tcp_port":50001}} +| The hosts that this server can be reached at. The key is a hostname (or IP address) and the value is an object with ports. +|- +! Result ["hosts"][hostname]["tcp_port"] +| int +| 50001 +| The TCP port this server can be reached at. +|- +! Result ["hosts"][hostname]["ssl_port"] +| int +| 50002 +| The SSL/TLS port this server can be reached at. +|- +! Result ["genesis_hash"] +| string +| 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f +| The hash of the genesis block. +|- +! Result ["hash_function"] +| string +| sha256 +| The hash function the server uses for script hashing. Only sha256 allowed. +|- +! Result ["server_version"] +| string +| Electrum Server 4.5.6 +| The name of the server. +|- +! Result ["protocol_max"] +| string +| 1.1 +| The maximum protocol version supported by the server. +|- +! Result ["protocol_min"] +| string +| 1.0 +| The minimum protocol version supported by the server. +|- +! Result ["pruning"] +| int or null +| 1000 +| The pruning limit. Omitted or null if no pruning limit. +|} + +==Method: Info== + +A command to get information about the active sessions. + +* Method name: info +* Introduced in: 0.1 +* Removed in: 0.10/1.0 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.info +|- +! Params [0] +| string +| My-Secret-Password +| The password of the server owner. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of objects +| [ {"time":null,"name":null,"address":null,"version":null,"subscriptions":1234} ] +| An array of connected clients. +|- +! Result [index] +| object +| {"time":null,"name":null,"address":null,"version":null,"subscriptions":1234} +| A single connected client. +|- +! Result [index]["time"] +| float +| 1753381329.5 +| The Epoch time when this client connected to the server. +|- +! Result [index]["name"] +| string +| HTTP, TCP or SSL +| The name of the session. Can be HTTP, TCP, or SSL when TCP over SSL/TLS. +|- +! Result [index]["address"] +| string +| 1.2.3.4 or dfjgfjsdfhsfgsdfgdffs +| The host (IP address) in case of TCP and the session ID in case of HTTP. +|- +! Result [index]["version"] +| string +| unknown or Electrum Client 1.2.3 +| The name of the parameter at position index of requested method. +|- +! Result [index]["subscriptions"] +| int +| 1234 +| The amount of subscriptions this client is subscribed to. +|} + +==Method: Load== + +A command to get the load on the server. + +* Method name: load +* Introduced in: 0.1 +* Removed in: 0.9 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.load +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| int +| 1234 +| The approximate amount of requests to the server waiting in the queue. +|} + +==Method: Peers== + +A event to announce peers. + +* Method name: peers +* Introduced in: 0.1 +* Deprecated in: 0.9 +* Removed in: 0.10/1.0 + +{| +! [Notification] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.peers +|- +! Params [0] (t) +| array of arrayss +| [ ["1.2.3.4","stratum.example.com", ["v0.7", "p10000", "t", "h", "s", "g" ] ] ] +| An array with the elements IP, host and an array with version, pruning and port information. The version is the letter v followed by the protocol version. The pruning limit is letter p followed by the limit value. This element can be omitted if the server doesn't prune. The other letters are indicators for supported protocols (e.g. HTTP or TCP). If there is no number after the letter, the server uses the default port. See the main document for all possible protocols. +|} + +==Method: Ping== + +A command to ping the server. + +* Method name: ping +* Introduced in: 1.2 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.ping +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| null +| null +| Null. +|} + +==Method: Stop== + +A command to stop the server. + +* Method name: stop +* Introduced in: 0.1 +* Removed in: 0.10/1.0 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.stop +|- +! Params [0] +| string +| My-Secret-Password +| The password of the server owner. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string +| The server is stopping! +| Some text indicating the server is stopping. +|} + +==Method: Version== + +A command to set the client version, get the server version and negotiate the protocol version. + +* Method name: version +* Introduced in: 0.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.version +|- +! Params [0] +| string +| Electrum Client 1.2.3 or 0.4 +| The client name. On version 0.5 and lower, this parameter contains the protocol version of the client. +|- +! Params [1] +| float, a string that represents a float, or an array of strings. +| 0.8 (in 0.6 and later) or ["1.1","1.4"] or 1.3 (in 1.1 and later) +| Protocol version. Introduced in: 0.6, required since 1.1. Since 1.1, if the protocol version is a string, this protocol version is used for both minimum and maximum. +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| string or array +| ok (in 0.1), 0.4 (in 0.2 and later), or ["Electrum Server 4.5.6","1.3"] (in 1.1 and later) +| The server version. +|} \ No newline at end of file diff --git a/bip-0040/service-server.peers.mediawiki b/bip-0040/service-server.peers.mediawiki new file mode 100644 index 0000000000..32bb30757d --- /dev/null +++ b/bip-0040/service-server.peers.mediawiki @@ -0,0 +1,31 @@ +=Service: Server Peers= + +* Service type: server.peers +* Service vendor: Electrum + +==Method: Subscribe== + +A command to get current peers. + +* Method name: subscribe +* Introduced in: 0.1 + +{| +! [Request] +! Type +! Example +! Description +|- +! Method +| colspan="3" | server.peers.subscribe +|- +! [Response] +! Type +! Example +! Description +|- +! Result +| array of arrayss +| [ ["1.2.3.4","stratum.example.com", ["v0.7", "p10000", "t", "h", "s", "g" ] ] ] +| An array with the elements IP, host and an array with version, pruning and port information. The version is the letter v followed by the protocol version. The pruning limit is letter p followed by the limit value. This element can be omitted if the server doesn't prune. The other letters are indicators for supported protocols (e.g. HTTP or TCP). If there is no number after the letter, the server uses the default port. See the main document for all possible protocols. +|} \ No newline at end of file diff --git a/scripts/buildtable.pl b/scripts/buildtable.pl index 4923a9ed4f..fde26ef2dc 100755 --- a/scripts/buildtable.pl +++ b/scripts/buildtable.pl @@ -87,7 +87,7 @@ 'OPL' => undef, 'PD' => undef, ); -my %GrandfatheredPD = map { $_ => undef } qw(9 36 37 38 42 49 50 60 65 67 69 74 80 81 83 90 99 105 107 109 111 112 113 114 122 124 125 126 130 131 132 133 140 141 142 143 144 146 147 150 151 152); +my %GrandfatheredPD = map { $_ => undef } qw(9 36 37 38 40 42 49 50 60 65 67 69 74 80 81 83 90 99 105 107 109 111 112 113 114 122 124 125 126 130 131 132 133 140 141 142 143 144 146 147 150 151 152); my %TolerateMissingLicense = map { $_ => undef } qw(1 10 11 12 13 14 15 16 21 31 33 34 35 39 43 44 45 47 61 64 68 70 71 72 73 101 102 106 120 121); my %TolerateTitleTooLong = map { $_ => undef } qw(39 44 45 47 49 60 67 68 69 73 74 75 80 81 99 105 106 109 113 122 126 131 143 145 147 173 327);