Update protocol documentation

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
+* improved semantics of `server.version` to aid protocol negotiation,
-* deprecated methods `blockchain.address.get_proof`,
+  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*
+* method `blockchain.transaction.get` no longer takes the *height*
-  argument
+  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
+  must use this function to hash pay-to-scripts to produce script
-  send to the server.  The default is "sha256".  "sha256" is currently
+  hashes to send to the server.  The default is "sha256".  "sha256" is
-  the only acceptable value.
+  currently the only acceptable value.
 
 * **server_version**
 

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):
+    def set_protocol_handlers(self, ptuple):
-        # 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)
-
         controller = self.controller
         handlers = {
             'blockchain.address.get_balance': controller.address_get_balance,