More sphinx work

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
+is encouraged for version 1.0 but not required.
-requests should limit their size depending on the nature of their
+
-query, because servers will limit response size as an anti-DoS
+.. note:: A client or server should only indicate JSON RPC 2.0 by
-mechanism.
+  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
+Protocol versions are denoted by dotted number strings with at least
-the major version number and *n* the minor version number.  For
+one dot.  Examples: "1.5", "1.4.1", "2.0".  In "a.b.c" *a* is the
-example: "1.5".
+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
+A :dfn:`deserialized header` is a dictionary describing a block at a
-even vary in its members for the same coin at different heights.
+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
+.. note:: The precise format of a deserialized block header varies by
-coin depending on height, so deserialized headers are deprecated and
+  coin, and also potentially by height for the same coin.  Detailed
-will be removed from the protocol in some future version.  Instead,
+  knowledge of the meaning of a block header is neither necessary nor
-raw headers (as hexadecimal strings) along with their height will be
+  appropriate in the server.
-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
+  Consequently deserialized headers are deprecated and will be removed
-necessary nor appropriate in the server.
+  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
+:func:`server.features` (currently :func:`sha256` only).  Like for
-transaction hashes, when converting the big-endian binary hash to a
+block and transaction hashes, when converting the big-endian binary
-hexadecimal string the least-significant byte appears first, and the
+hash to a hexadecimal string the least-significant byte appears first,
-most-significant byte last.
+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
+By subscribing to this hash you can find P2PK payments to the genesis
-key.
+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
+1. order confirmed transactions to the script hash by increasing
-position in the block if there are more than one in a block)
+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
+3. Next, with mempool transactions in any order, append a similar
-is the same, but where **height** is ``-1`` if the transaction has at
+string for those transactions, but where **height** is ``-1`` if the
-least one unconfirmed input, and ``0`` if all inputs are confirmed.
+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.

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
 -------------------------