From 70dfaa895de986f2466e1d0b699294725e69bcf8 Mon Sep 17 00:00:00 2001 From: Neil Booth Date: Thu, 8 Mar 2018 12:52:16 +0800 Subject: [PATCH] More sphinx work --- docs/protocol-basics.rst | 91 ++++++++++++-------- docs/protocol-methods.rst | 173 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 227 insertions(+), 37 deletions(-) diff --git a/docs/protocol-basics.rst b/docs/protocol-basics.rst index d729746..763668e 100644 --- a/docs/protocol-basics.rst +++ b/docs/protocol-basics.rst @@ -11,10 +11,19 @@ Two standards `JSON RPC 1.0 `_ and `JSON RPC 2.0 `_ 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. +is encouraged for version 1.0 but not required. + +.. note:: A client or server should only indicate JSON RPC 2.0 by + setting the `jsonrpc + `_ member of + its messages to ``"2.0"`` if it supports the version 2.0 protocol in + its entirety. ElectrumX does and will expect clients advertizing so + to function correctly. Those that do not will be disconnected and + possibly blacklisted. + +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 @@ -23,7 +32,8 @@ 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. +names shown in the description of the method or notification 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 @@ -36,7 +46,7 @@ the protocol. Notifications ------------- -Some RPC calls are subscriptions, which, after the initial response, +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 @@ -49,13 +59,11 @@ 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". +Protocol versions are denoted by dotted number strings with at least +one dot. Examples: "1.5", "1.4.1", "2.0". In "a.b.c" *a* is the +major version number, *b* the minor version number, and *c* the +revision number. 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. @@ -65,16 +73,17 @@ 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 +from and including the server's response to this call will use its negotiated protocol version. + .. _deserialized header: Deserialized Headers -------------------- -A deserialized header is a dictionary that is coin-specific, and may -even vary in its members for the same coin at different heights. +A :dfn:`deserialized header` is a dictionary describing a block at a +given height. A typical example would be similar to this template:: @@ -88,13 +97,17 @@ A typical example would be similar to this template:: "nonce": } -The precise meaning of a block header varies across coins, and also by -coin depending on height, so deserialized headers are deprecated and -will be removed from the protocol in some future version. Instead, -raw headers (as hexadecimal strings) along with their height will be -returned by RPC calls, and it will be up to the client to interpret -them. Detailed knowledge of the meaning of a block header is neither -necessary nor appropriate in the server. +.. note:: The precise format of a deserialized block header varies by + coin, and also potentially by height for the same coin. Detailed + knowledge of the meaning of a block header is neither necessary nor + appropriate in the server. + + Consequently deserialized headers are deprecated and will be removed + from the protocol in a future version. Instead, raw headers (as + hexadecimal strings) along with their height will be returned by new + RPC calls, and it will be up to the client to interpret the meaning + of the raw header. + .. _script hashes: @@ -104,10 +117,10 @@ 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. +:func:`server.features` (currently :func:`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:: @@ -127,7 +140,8 @@ which is sent to the server reversed as:: 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:: +One public key, the genesis block public key, among the trillions for +that address is:: 04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb 649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f @@ -145,12 +159,13 @@ which is sent to the server reversed as:: 740485f380ff6379d11ef6fe7d7cdd68aea7f8bd0d953d9fdf3531fb7d531833 -By subscribing to this hash you can find P2PK payments to that public -key. +By subscribing to this hash you can find P2PK payments to the genesis +block public key. + +.. note:: The Genesis block coinbase is uniquely unspendable and + therefore not indexed. It will not show with the above P2PK script + hash subscription. -.. note:: The Genesis block coinbase is unspendable and therefore not - indexed. It will not show with the above P2PK script hash - subscription. .. _status: @@ -160,8 +175,9 @@ Status To calculate the `status` of a :ref:`script hash