From f280811202ba80df4e217fd503ebd40d8aeb6d0c Mon Sep 17 00:00:00 2001
From: Neil Booth <kyuupichan@gmail.com>
Date: Wed, 6 Sep 2017 17:56:23 +0900
Subject: [PATCH] Update protocol documentation

---
 PROTOCOL.rst | 129 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 114 insertions(+), 15 deletions(-)

diff --git a/PROTOCOL.rst b/PROTOCOL.rst
index 09cbd62..1d77ce7 100644
--- a/PROTOCOL.rst
+++ b/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**