From 70dfaa895de986f2466e1d0b699294725e69bcf8 Mon Sep 17 00:00:00 2001
From: Neil Booth <kyuupichan@gmail.com>
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
<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.
+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
+ <http://www.jsonrpc.org/specification#request_object>`_ 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": <integer>
}
-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 <script hashes>` (or
address):
-1. order confirmed transactions to the script hash by height (and
-position in the block if there are more than one in a block)
+1. order confirmed transactions to the script hash by increasing
+height (and position in the block if there are more than one in a
+block)
2. form a string that is the concatenation of strings
``"tx_hash:height:"`` for each transaction in order, where:
@@ -170,9 +186,10 @@ position in the block if there are more than one in a block)
* ``height`` is the height of the block it is in.
-3. Next, with mempool transactions in any order, append a string that
-is the same, but where **height** is ``-1`` if the transaction has at
-least one unconfirmed input, and ``0`` if all inputs are confirmed.
+3. Next, with mempool transactions in any order, append a similar
+string for those transactions, but where **height** is ``-1`` if the
+transaction has at least one unconfirmed input, and ``0`` if all
+inputs are confirmed.
4. The :dfn:`status` of the script hash is the :func:`sha256` hash of the
full string expressed as a hexadecimal string.
diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index 7c28fe0..6168afc 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -406,6 +406,179 @@ be accepted to the daemon's memory pool.
0.0
+blockchain.transaction.broadcast
+--------------------------------
+
+Broadcast a transaction to the network.
+
+**Signature**
+
+ .. function:: blockchain.transaction.broadcast(raw_tx)
+
+ *raw_tx*
+
+ The raw transaction as a hexadecimal string.
+
+**Result**
+
+ The transaction hash as a hexadecimal string.
+
+ .. note:: protocol version 1.0 (only) does not respond according to
+ the JSON RPC specification if an error occurs. If the daemon
+ rejects the transaction, the result is the error message string
+ from the daemon, as if the call were successful. The client
+ needs to determine if an error occurred by comparing the result
+ to the expected transaction hash. Protocol version 1.1 and later
+ return a JSON RPC error as would be expected.
+
+**Result Examples**
+
+::
+
+ "a76242fce5753b4212f903ff33ac6fe66f2780f34bdb4b33b175a7815a11a98e"
+
+Protocol version 1.0 returning an error as the result:
+
+::
+
+ "258: txn-mempool-conflict"
+
+blockchain.transaction.get
+--------------------------
+
+Return a raw transaction.
+
+**Signature**
+
+ .. function:: blockchain.transaction.get(tx_hash, verbose=False)
+
+ *tx_hash*
+
+ The transaction hash as a hexadecimal string.
+
+ *verbose*
+
+ .. versionadded:: 1.2
+
+ .. note:: Protocol version 1.0 also had a 2nd argument but ignored
+ it. This was removed in protocol 1.1 which took a single argument
+ only.
+
+**Result**
+
+ If *verbose* is :const:`False`, the raw transaction as a
+ hexadecimal string. If :const:`True`, the result is coin-specific
+ and whatever the coin daemon returns when asked for a verbose form
+ of the raw transaction.
+
+**Example Results**
+
+When *verbose* is :const:`False`::
+
+ "01000000015bb9142c960a838329694d3fe9ba08c2a6421c5158d8f7044cb7c48006c1b48"
+ "4000000006a4730440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a824"
+ "6a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee76921"
+ "3ca8b8b412103bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1"
+ "f6a4feffffff02c6b68200000000001976a9141041fb024bd7a1338ef1959026bbba86006"
+ "4fe5f88ac50a8cf00000000001976a91445dac110239a7a3814535c15858b939211f85298"
+ "88ac61ee0700"
+
+When *verbose* is :const:`True`::
+
+ {
+ "blockhash": "0000000000000000015a4f37ece911e5e3549f988e855548ce7494a0a08b2ad6",
+ "blocktime": 1520074861,
+ "confirmations": 679,
+ "hash": "36a3692a41a8ac60b73f7f41ee23f5c917413e5b2fad9e44b34865bd0d601a3d",
+ "hex": "01000000015bb9142c960a838329694d3fe9ba08c2a6421c5158d8f7044cb7c48006c1b484000000006a4730440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a8246a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee769213ca8b8b412103bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1f6a4feffffff02c6b68200000000001976a9141041fb024bd7a1338ef1959026bbba860064fe5f88ac50a8cf00000000001976a91445dac110239a7a3814535c15858b939211f8529888ac61ee0700",
+ "locktime": 519777,
+ "size": 225,
+ "time": 1520074861,
+ "txid": "36a3692a41a8ac60b73f7f41ee23f5c917413e5b2fad9e44b34865bd0d601a3d",
+ "version": 1,
+ "vin": [ {
+ "scriptSig": {
+ "asm": "30440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a8246a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee769213ca8b8b[ALL|FORKID] 03bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1f6a4",
+ "hex": "4730440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a8246a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee769213ca8b8b412103bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1f6a4"
+ },
+ "sequence": 4294967294,
+ "txid": "84b4c10680c4b74c04f7d858511c42a6c208bae93f4d692983830a962c14b95b",
+ "vout": 0}],
+ "vout": [ { "n": 0,
+ "scriptPubKey": { "addresses": [ "12UxrUZ6tyTLoR1rT1N4nuCgS9DDURTJgP"],
+ "asm": "OP_DUP OP_HASH160 1041fb024bd7a1338ef1959026bbba860064fe5f OP_EQUALVERIFY OP_CHECKSIG",
+ "hex": "76a9141041fb024bd7a1338ef1959026bbba860064fe5f88ac",
+ "reqSigs": 1,
+ "type": "pubkeyhash"},
+ "value": 0.0856647},
+ { "n": 1,
+ "scriptPubKey": { "addresses": [ "17NMgYPrguizvpJmB1Sz62ZHeeFydBYbZJ"],
+ "asm": "OP_DUP OP_HASH160 45dac110239a7a3814535c15858b939211f85298 OP_EQUALVERIFY OP_CHECKSIG",
+ "hex": "76a91445dac110239a7a3814535c15858b939211f8529888ac",
+ "reqSigs": 1,
+ "type": "pubkeyhash"},
+ "value": 0.1360904}]}
+
+blockchain.transaction.get_merkle
+---------------------------------
+
+Return the markle branch to a confirmed transaction given its hash
+and height.
+
+**Signature**
+
+ .. function:: blockchain.transaction.get_merkle(tx_hash, height)
+
+ *tx_hash*
+
+ The transaction hash as a hexadecimal string.
+
+ *height*
+
+ The height at which it was confirmed, an integer.
+
+**Result**
+
+ A dictionary with the following keys:
+
+ * *block_height*
+
+ The height of the block the transaction was confirmed in.
+
+ * *merkle*
+
+ A list of transaction hashes the current hash is paired with,
+ recursively, in order to trace up to obtain merkle root of the
+ block, deepest pairing first.
+
+ * *pos*
+
+ The 0-based index of the position of the transaction in the
+ ordered list of transactions in the block.
+
+**Result Example**
+
+::
+
+ {
+ "merkle":
+ [
+ "713d6c7e6ce7bbea708d61162231eaa8ecb31c4c5dd84f81c20409a90069cb24",
+ "03dbaec78d4a52fbaf3c7aa5d3fccd9d8654f323940716ddf5ee2e4bda458fde",
+ "e670224b23f156c27993ac3071940c0ff865b812e21e0a162fe7a005d6e57851",
+ "369a1619a67c3108a8850118602e3669455c70cdcdb89248b64cc6325575b885",
+ "4756688678644dcb27d62931f04013254a62aeee5dec139d1aac9f7b1f318112",
+ "7b97e73abc043836fd890555bfce54757d387943a6860e5450525e8e9ab46be5",
+ "61505055e8b639b7c64fd58bce6fc5c2378b92e025a02583303f69930091b1c3",
+ "27a654ff1895385ac14a574a0415d3bbba9ec23a8774f22ec20d53dd0b5386ff",
+ "5312ed87933075e60a9511857d23d460a085f3b6e9e5e565ad2443d223cfccdc",
+ "94f60b14a9f106440a197054936e6fb92abbd69d6059b38fdf79b33fc864fca0",
+ "2d64851151550e8c4d337f335ee28874401d55b358a66f1bafab2c3e9f48773d"
+ ],
+ "block_height": 450538,
+ "pos": 710
+ }
+
mempool.get_fee_histogram
-------------------------