Update protocol documentation

7 years ago · f2f2b1e7b6
2 changed files with 132 additions and 29 deletions
--- a/docs/PROTOCOL.rst
+++ b/docs/PROTOCOL.rst
@ -606,22 +606,29 @@ subscription and the server must send no notifications.
  missing then the server does not support that transport.


-Version 1.1 (provisional)
-------------------------
+Version 1.1
+-----------

 This protocol version is the same as version `1.0` except for the
 following changes:

-* improved semantics of `server.version` to aid protocol negotiation
-* deprecated methods `blockchain.address.get_proof`,
+* improved semantics of `server.version` to aid protocol negotiation,
+  and a changed return value.
+* version 1.0 methods `blockchain.address.get_proof`,
  `blockchain.utxo.get_address` and `blockchain.numblocks.subscribe`
  have been removed.
-* method `blockchain.transaction.get` no longer takes a *height*
-  argument
+* method `blockchain.transaction.get` no longer takes the *height*
+  argument that was ignored in 1.0, providing one will return an
+  error.
 * method `blockchain.transaction.broadcast` returns errors like any
  other JSON RPC call.  A *tx_hash* result is only returned on
  success.
-* new methods `server.features` and `server.add_peer`
+* new methods `blockchain.scripthash.get_balance`,
+  `blockchain.scripthash.get_history`,
+  `blockchain.scripthash.get_mempool`,
+  `blockchain.scripthash.listunspent`,
+  `blockchain.scripthash.subscribe`,
+  `server.features` and `server.add_peer`.


 server.version
@ -641,7 +648,8 @@ protocol versions.
  Optional with default value ["1.1", "1.1"].

  It must be a pair [`protocol_min`, `protocol_max`], each of which is
-  a string.
+  a string.  If `protocol_min` and `protocol_max` are the same, they
+  can be passed as a single string rather than as a pair of strings.

 The server should use the highest protocol version both support:

@ -649,7 +657,7 @@ The server should use the highest protocol version both support:

 If this is below the value

-  min(client.protocol_min, server.protocol_min)
+  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
@ -657,9 +665,9 @@ that protocol version.

 **Response**

-  A string
+  An array of length 2

-     "m.n"
+     [<software version string>, <protocol version string>]

  identifying the server and the protocol version that will be used
  for future communication.
@ -668,7 +676,98 @@ that protocol version.

 ::

-  server.version('2.7.11', ["1.0", "2.0"])
+  server.version('2.7.11', ["0.10", "1.1"])
+
+**Example Response**
+
+  ["ElectrumX 1.0.18", "1.1"]
+
+
+blockchain.scripthash.get_balance
+=================================
+
+Return the confirmed and unconfirmed balances of a script hash.
+
+  blockchain.scripthash.get_balance(**scripthash**)
+
+  **schripthash**
+
+    The script hash as a hexadecimal string.
+
+**Response**
+
+  As for `blockchain.address.get_balance`.
+
+
+blockchain.scripthash.get_history
+=================================
+
+Return the confirmed and unconfirmed history of a script hash.
+
+  blockchain.scripthash.get_history(**scripthash**)
+
+  **schripthash**
+
+    The script hash as a hexadecimal string.
+
+**Response**
+
+  As for `blockchain.address.get_history`.
+
+
+blockchain.scripthash.get_mempool
+=================================
+
+Return the unconfirmed transactions of a script hash.
+
+  blockchain.scripthash.get_mempool(**scripthash**)
+
+  **schripthash**
+
+    The script hash as a hexadecimal string.
+
+**Response**
+
+  As for `blockchain.address.get_mempool`.
+
+
+blockchain.scripthash.listunspent
+=================================
+
+Return an ordered list of UTXOs sent to a script hash.
+
+  blockchain.scripthash.listunspent(**scripthash**)
+
+  **schripthash**
+
+    The script hash as a hexadecimal string.
+
+**Response**
+
+  As for `blockchain.address.listunspent`.
+
+
+blockchain.scripthash.subscribe
+===============================
+
+Subscribe to a script hash.
+
+  blockchain.scripthash.subscribe(**scripthash**)
+
+  **scripthash**
+
+    The script hash as a hexadecimal string.
+
+**Response**
+
+  The *status* [1]_ of the script hash.
+
+**Notifications**
+
+  As this is a subcription, the client will receive a notification
+  when the status of the script hash changes.  The parameters are:
+
+    [**scripthash**, **status**]


 server.add_peer
@ -730,9 +829,9 @@ Get a list of features and services supported by the server.
 * **hash_function**

  The hash function the server uses for script hashing.  The client
-  must use this function to hash scripts to produce script hashes to
-  send to the server.  The default is "sha256".  "sha256" is currently
-  the only acceptable value.
+  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/server/session.py
+++ b/server/session.py
@ -113,7 +113,7 @@ class ElectrumX(SessionBase):
        self.hashX_subs = {}
        self.mempool_statuses = {}
        self.chunk_indices = []
-        self.set_protocol_handlers(None)
+        self.set_protocol_handlers((1, 0))

    def sub_count(self):
        return len(self.hashX_subs)
@ -323,9 +323,23 @@ class ElectrumX(SessionBase):
                pass

        self.log_info('protocol version {} requested'.format(protocol_version))
-        self.set_protocol_handlers(protocol_version)

-        return version.VERSION
+        # Find the highest common protocol version.  Disconnect if
+        # that protocol version in unsupported.
+        ptuple = util.protocol_version(protocol_version, version.PROTOCOL_MIN,
+                                       version.PROTOCOL_MAX)
+        if ptuple is None:
+            self.log_info('unsupported protocol version request {}'
+                          .format(protocol_version))
+            raise RPCError('unsupported protocol version: {}'
+                           .format(protocol_version), JSONRPC.FATAL_ERROR)
+
+        self.set_protocol_handlers(ptuple)
+
+        if ptuple < (1, 1):
+            return version.VERSION
+
+        return (version.VERSION, '.'.join(str(part) for part in ptuple))

    async def transaction_broadcast(self, raw_tx):
        '''Broadcast a raw transaction to the network.
@ -367,17 +381,7 @@ class ElectrumX(SessionBase):

            return message

-    def set_protocol_handlers(self, version_req):
-        # Find the highest common protocol version.  Disconnect if
-        # that protocol version in unsupported.
-        ptuple = util.protocol_version(version_req, version.PROTOCOL_MIN,
-                                       version.PROTOCOL_MAX)
-        if ptuple is None:
-            self.log_info('unsupported protocol version request {}'
-                          .format(version_req))
-            raise RPCError('unsupported protocol version: {}'
-                           .format(version_req), JSONRPC.FATAL_ERROR)
-
+    def set_protocol_handlers(self, ptuple):
        controller = self.controller
        handlers = {
            'blockchain.address.get_balance': controller.address_get_balance,