Neil Booth
7 years ago
6 changed files with 467 additions and 145 deletions
@ -1,15 +0,0 @@ |
|||
.. method:: mempool.get_fee_histogram() |
|||
|
|||
Return a histogram of the fee rates paid by transactions in the |
|||
memory pool, weighted by transaction size. |
|||
|
|||
**Response** |
|||
|
|||
The histogram is an array of [*fee*, *vsize*] pairs, where *vsize_n* is |
|||
the cumulative virtual size of mempool transactions with a fee rate |
|||
in the interval [*fee*_(n-1), *fee*_n)], and *fee*_(n-1) > *fee*_n. |
|||
|
|||
Fee intervals may have variable size. The choice of appropriate |
|||
intervals is currently not part of the protocol. |
|||
|
|||
.. versionadded:: 1.2 |
|||
@ -0,0 +1,125 @@ |
|||
Protocol Basics |
|||
=============== |
|||
|
|||
Message Stream |
|||
-------------- |
|||
|
|||
Clients and servers communicate using **JSON RPC** over an unspecified |
|||
underlying stream transport protocol, typically TCP or SSL. |
|||
|
|||
Two standards `JSON RPC 1.0 |
|||
<http://www.jsonrpc.org/specification_v1>`_ and `JSON RPC 2.0 |
|||
<http://www.jsonrpc.org/specification>`_ are specified; use of version |
|||
2.0 is encouraged but not required. Server support of batch requests |
|||
is encouraged for version 1.0 but not required. Clients making batch |
|||
requests should limit their size depending on the nature of their |
|||
query, because servers will limit response size as an anti-DoS |
|||
mechanism. |
|||
|
|||
Eeach RPC call, and each response, is separated by a single newline in |
|||
their respective streams. The JSON specification does not permit |
|||
control characters within strings, so no confusion is possible there. |
|||
However it does permit newlines as extraneous whitespace between |
|||
elements; client and server MUST NOT use newlines in such a way. |
|||
|
|||
If using JSON RPC 2.0's feature of parameter passing by name, the |
|||
names shown in the description of the method in question MUST be used. |
|||
|
|||
A server advertising support for a particular protocol version MUST |
|||
support each method documented for that protocol version, unless the |
|||
method is explicitly marked optional. It may support other methods or |
|||
additional parameters with unspecified behaviour. Use of additional |
|||
parameters is discouraged as it may conflict with future versions of |
|||
the protocol. |
|||
|
|||
|
|||
Notifications |
|||
------------- |
|||
|
|||
Some RPC calls are subscriptions, which, after the initial response, |
|||
will send a JSON RPC :dfn:`notification` each time the thing |
|||
subscribed to changes. The `method` of the notification is the same |
|||
as the method of the subscription, and the `params` of the |
|||
notification (and their names) are given in the documentation of the |
|||
method. |
|||
|
|||
|
|||
Version Negotiation |
|||
------------------- |
|||
|
|||
It is desirable to have a way to enhance and improve the protocol |
|||
without forcing servers and clients to upgrade at the same time. |
|||
Protocol negotiation is not implemented in any client or server at |
|||
present to the best of my knowledge, so care is needed to ensure |
|||
current clients and servers continue to operate as expected. |
|||
|
|||
Protocol versions are denoted by dotted "a.b" strings, where *m* is |
|||
the major version number and *n* the minor version number. For |
|||
example: "1.5". |
|||
|
|||
A party to a connection will speak all protocol versions in a range, |
|||
say from `protocol_min` to `protocol_max`, which may be the same. |
|||
When a connection is made, both client and server must initially |
|||
assume the protocol to use is their own `protocol_min`. |
|||
|
|||
The client should send a :func:`server.version` RPC call as early as |
|||
possible in order to negotiate the precise protocol version; see its |
|||
description for more detail. All responses received in the stream |
|||
from and including the server's response to this call will use the |
|||
negotiated protocol version. |
|||
|
|||
.. _script hashes: |
|||
|
|||
Script Hashes |
|||
------------- |
|||
|
|||
A :dfn:`script hash` is the hash of the binary bytes of the locking |
|||
script (ScriptPubKey), expressed as a hexadecimal string. The hash |
|||
function to use is given by the "hash_function" member of |
|||
:func:`server.features` (currently "sha256" only). Like for block and |
|||
transaction hashes, when converting the big-endian binary hash to a |
|||
hexadecimal string the least-significant byte appears first, and the |
|||
most-significant byte last. |
|||
|
|||
For example, the legacy Bitcoin address from the genesis block:: |
|||
|
|||
1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa |
|||
|
|||
has P2PKH script:: |
|||
|
|||
76a91462e907b15cbf27d5425399ebf6f0fb50ebb88f1888ac |
|||
|
|||
with SHA256 hash:: |
|||
|
|||
6191c3b590bfcfa0475e877c302da1e323497acf3b42c08d8fa28e364edf018b |
|||
|
|||
which is sent to the server reversed as:: |
|||
|
|||
8b01df4e368ea28f8dc0423bcf7a4923e3a12d307c875e47a0cfbf90b5c39161 |
|||
|
|||
By subscribing to this hash you can find P2PKH payments to that address. |
|||
|
|||
One public key for that address (the genesis block public key) is:: |
|||
|
|||
04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb |
|||
649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f |
|||
|
|||
which has P2PK script:: |
|||
|
|||
4104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb |
|||
649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac |
|||
|
|||
with SHA256 hash:: |
|||
|
|||
3318537dfb3135df9f3d950dbdf8a7ae68dd7c7dfef61ed17963ff80f3850474 |
|||
|
|||
which is sent to the server reversed as:: |
|||
|
|||
740485f380ff6379d11ef6fe7d7cdd68aea7f8bd0d953d9fdf3531fb7d531833 |
|||
|
|||
By subscribing to this hash you can find P2PK payments to that public |
|||
key. |
|||
|
|||
.. note:: The Genesis block coinbase is unspendable and therefore not |
|||
indexed. It will not show with the above P2PK script hash |
|||
subscription. |
|||
@ -0,0 +1,268 @@ |
|||
Protocol Methods |
|||
================ |
|||
|
|||
mempool.get_fee_histogram |
|||
------------------------- |
|||
|
|||
Return a histogram of the fee rates paid by transactions in the |
|||
memory pool, weighted by transaction size. |
|||
|
|||
**Signature** |
|||
|
|||
.. function:: mempool.get_fee_histogram() |
|||
|
|||
.. versionadded:: 1.2 |
|||
|
|||
**Result** |
|||
|
|||
The histogram is an array of [*fee*, *vsize*] pairs, where |vsize_n| |
|||
is the cumulative virtual size of mempool transactions with a fee rate |
|||
in the interval [|fee_n1|, |fee_n|], and |fee_n1| > |fee_n|. |
|||
|
|||
.. |vsize_n| replace:: vsize\ :sub:`n` |
|||
.. |fee_n| replace:: fee\ :sub:`n` |
|||
.. |fee_n1| replace:: fee\ :sub:`n-1` |
|||
|
|||
Fee intervals may have variable size. The choice of appropriate |
|||
intervals is currently not part of the protocol. |
|||
|
|||
**Example Result** |
|||
|
|||
:: |
|||
|
|||
[[12, 128812], [4, 92524], [2, 6478638], [1, 22890421]] |
|||
|
|||
|
|||
server.add_peer |
|||
--------------- |
|||
|
|||
This call is intended for a new server to get itself into a server's |
|||
peers list, and should not be used by wallet clients. |
|||
|
|||
**Signature** |
|||
|
|||
.. function:: server.add_peer(features) |
|||
|
|||
.. versionadded:: 1.1 |
|||
|
|||
* **features** |
|||
|
|||
The same information that a call to the sender's |
|||
:func:`server.features` RPC call would return. |
|||
|
|||
**Result** |
|||
|
|||
A boolean indicating whether the request was tentatively accepted. |
|||
The requesting server will appear in :func:`server.peers.subscribe` |
|||
when further sanity checks complete successfully. |
|||
|
|||
|
|||
server.banner |
|||
------------- |
|||
|
|||
Return a banner to be shown in the Electrum console. |
|||
|
|||
**Signature** |
|||
|
|||
.. function:: server.banner() |
|||
|
|||
**Result** |
|||
|
|||
A string. |
|||
|
|||
**Example Result** |
|||
|
|||
:: |
|||
|
|||
"Welcome to Electrum!" |
|||
|
|||
|
|||
server.donation_address |
|||
----------------------- |
|||
|
|||
Return a server donation address. |
|||
|
|||
**Signature** |
|||
|
|||
.. function:: server.donation_address() |
|||
|
|||
**Result** |
|||
|
|||
A string. |
|||
|
|||
**Example Result** |
|||
|
|||
:: |
|||
|
|||
"1BWwXJH3q6PRsizBkSGm2Uw4Sz1urZ5sCj" |
|||
|
|||
|
|||
server.features |
|||
--------------- |
|||
|
|||
Return a list of features and services supported by the server. |
|||
|
|||
**Signature** |
|||
|
|||
.. function:: server.features() |
|||
|
|||
**Result** |
|||
|
|||
A dictionary of keys and values. Each key represents a feature or |
|||
service of the server, and the value gives additional information. |
|||
|
|||
The following features MUST be reported by the server. Additional |
|||
key-value pairs may be returned. |
|||
|
|||
* **hosts** |
|||
|
|||
A dictionary, keyed by host name, that this server can be reached |
|||
at. Normally this will only have a single entry; other entries |
|||
can be used in case there are other connection routes (e.g. Tor). |
|||
|
|||
The value for a host is itself a dictionary, with the following |
|||
optional keys: |
|||
|
|||
* **ssl_port** |
|||
|
|||
An integer. Omit or set to **null** if SSL connectivity is not |
|||
provided. |
|||
|
|||
* **tcp_port** |
|||
|
|||
An integer. Omit or set to **null** if TCP connectivity is not |
|||
provided. |
|||
|
|||
A server should ignore information provided about any host other |
|||
than the one it connected to. |
|||
|
|||
* **genesis_hash** |
|||
|
|||
The hash of the genesis block. This is used to detect if a peer |
|||
is connected to one serving a different network. |
|||
|
|||
* **hash_function** |
|||
|
|||
The hash function the server uses for :ref:`script hashing |
|||
<script hashes>`. The client must use this function to hash |
|||
pay-to-scripts to produce script hashes to send to the server. |
|||
The default is "sha256". "sha256" is currently the only |
|||
acceptable value. |
|||
|
|||
* **server_version** |
|||
|
|||
A string that identifies the server software. Should be the same |
|||
as the response to :func:`server.version` RPC call. |
|||
|
|||
* **protocol_max** |
|||
* **protocol_min** |
|||
|
|||
Strings that are the minimum and maximum Electrum protocol |
|||
versions this server speaks. Example: "1.1". |
|||
|
|||
* **pruning** |
|||
|
|||
An integer, the pruning limit. Omit or set to **null** if there is |
|||
no pruning limit. Should be the same as what would suffix the |
|||
letter **p** in the IRC real name. |
|||
|
|||
**Example Result** |
|||
|
|||
:: |
|||
|
|||
{ |
|||
"genesis_hash": "000000000933ea01ad0ee984209779baaec3ced90fa3f408719526f8d77f4943", |
|||
"hosts": {"14.3.140.101": {"tcp_port": 51001, "ssl_port": 51002}}, |
|||
"protocol_max": "1.0", |
|||
"protocol_min": "1.0", |
|||
"pruning": null, |
|||
"server_version": "ElectrumX 1.0.17", |
|||
"hash_function": "sha256" |
|||
} |
|||
|
|||
|
|||
server.peers.subscribe |
|||
---------------------- |
|||
|
|||
Return a list of peer servers. Despite the name this is not a |
|||
subscription and the server must send no notifications. |
|||
|
|||
**Signature** |
|||
|
|||
.. function:: server.peers.subscribe() |
|||
|
|||
**Result** |
|||
|
|||
An array of peer servers, each returned as a 3-element array. For |
|||
example:: |
|||
|
|||
["107.150.45.210", |
|||
"e.anonyhost.org", |
|||
["v1.0", "p10000", "t", "s995"]] |
|||
|
|||
The first element is the IP address, the second is the host name |
|||
(which might also be an IP address), and the third is a list of |
|||
server features. Each feature and starts with a letter. 'v' |
|||
indicates the server maximum protocol version, 'p' its pruning limit |
|||
and is omitted if it does not prune, 't' is the TCP port number, and |
|||
's' is the SSL port number. If a port is not given for 's' or 't' |
|||
the default port for the coin network is implied. If 's' or 't' is |
|||
missing then the server does not support that transport. |
|||
|
|||
|
|||
server.version |
|||
-------------- |
|||
|
|||
Identify the client to the server and negotiate the protocol version. |
|||
|
|||
|
|||
**Signature** |
|||
|
|||
.. function:: server.version(client_name="", protocol_version="1.1") |
|||
|
|||
* **client_name** |
|||
|
|||
A string identifying the connecting client software. |
|||
|
|||
* **protocol_version** |
|||
|
|||
An array [`protocol_min`, `protocol_max`], each of which is a |
|||
string. If `protocol_min` and `protocol_max` are the same, they |
|||
can be passed as a single string rather than as an array of two |
|||
strings, as for the default value. |
|||
|
|||
.. versionadded:: 1.1 |
|||
**protocol_version** is not ignored. |
|||
|
|||
The server should use the highest protocol version both support:: |
|||
|
|||
version = min(client.protocol_max, server.protocol_max) |
|||
|
|||
If this is below the value:: |
|||
|
|||
max(client.protocol_min, server.protocol_min) |
|||
|
|||
then there is no protocol version in common and the server must |
|||
close the connection. Otherwise it should send a response |
|||
appropriate for that protocol version. |
|||
|
|||
**Result** |
|||
|
|||
An array of 2 strings: |
|||
|
|||
[`server software version`, `protocol version`] |
|||
|
|||
identifying the server and the protocol version that will be used |
|||
for future communication. |
|||
|
|||
*Protocol version 1.0*: A string identifying the server software. |
|||
|
|||
**Examples**:: |
|||
|
|||
server.version("Electrum 3.0.6", ["1.1", "1.2"]) |
|||
server.version("2.7.1", "1.0") |
|||
|
|||
**Example Results**:: |
|||
|
|||
["ElectrumX 1.2.1", "1.2"] |
|||
"ElectrumX 1.2.1" |
|||
Loading…
Reference in new issue