Finish protocol documentation switch

docs/index.rst

@@ -32,7 +32,7 @@ available .
    features
    HOWTO
    ENVIRONMENT
-   protocol-new
+   PROTOCOL
    PEER_DISCOVERY
    RPC-INTERFACE
    ARCHITECTURE

docs/protocol-changes.rst

@@ -0,0 +1,73 @@
+================
+Protocol Changes
+================
+
+This documents lists changes made by protocol version.
+
+Version 1.0
+===========
+
+Deprecated methods
+------------------
+
+  * :func:`blockchain.utxo.get_address`
+  * :func:`blockchain.numblocks.subscribe`
+
+Version 1.1
+===========
+
+Changes
+-------
+
+  * improved semantics of :func:`server.version` to aid protocol
+    negotiation, and a changed return value.
+  * :func:`blockchain.transaction.get` no longer takes the *height*
+    argument that was ignored anyway.
+  * :func:`blockchain.transaction.broadcast` returns errors like any
+    other JS RPC call.  A transaction hash result is only returned on
+    success.
+
+New methods
+-----------
+
+  * :func:`blockchain.scripthash.get_balance`
+  * :func:`blockchain.scripthash.get_history`
+  * :func:`blockchain.scripthash.get_mempool`
+  * :func:`blockchain.scripthash.listunspent`
+  * :func:`blockchain.scripthash.subscribe`
+  * :func:`server.features`
+  * :func:`server.add_peer`
+
+Removed methods
+---------------
+
+  * :func:`blockchain.utxo.get_address`
+  * :func:`blockchain.numblocks.subscribe`
+
+Version 1.2
+===========
+
+Changes:
+
+  * :func:`blockchain.transaction.get` now has an optional parameter
+    *verbose*.
+
+New methods:
+
+  * :func:`blockchain.block.headers`
+  * :func:`mempool.get_fee_histogram`
+
+Deprecated methods:
+
+  * :func:`blockchain.block.get_chunk`.  Switch to
+    :func:`blockchain.block.headers`
+  * :func:`blockchain.address.get_balance`.  Switch to
+    :func:`blockchain.scripthash.get_balance`.
+  * :func:`blockchain.address.get_history`.  Switch to
+    :func:`blockchain.scripthash.get_history`.
+  * :func:`blockchain.address.get_mempool`.  Switch to
+    :func:`blockchain.scripthash.get_mempool`.
+  * :func:`blockchain.address.listunspent`.  Switch to
+    :func:`blockchain.scripthash.listunspent`.
+  * :func:`blockchain.address.subscribe`.  Switch to
+    :func:`blockchain.scripthash.subscribe`.

docs/protocol-methods.rst

@@ -6,12 +6,10 @@ blockchain.address.get_balance
 
 Return the confirmed and unconfirmed balances of a bitcoin address.
 
-.. note:: This method is deprecated; support will be removed in a later
-   protocol version.  Use :func:`blockchain.scripthash.get_balance` instead.
-
 **Signature**
 
   .. function:: blockchain.address.get_balance(address)
+  .. deprecated:: 1.2
 
   * *address*
 
@@ -19,28 +17,17 @@ Return the confirmed and unconfirmed balances of a bitcoin address.
 
 **Result**
 
-  A dictionary with keys `confirmed` and `unconfirmed`.  The value of
+  See :func:`blockchain.scripthash.get_balance`.
-  each is the appropriate balance in coin units as a string.
-
-**Result Example**::
-
-  {
-    "confirmed": "1.03873966",
-    "unconfirmed": "0.236844"
-  }
-
 
 blockchain.address.get_history
 ------------------------------
 
 Return the confirmed and unconfirmed history of a bitcoin address.
 
-.. note:: This method is deprecated; support will be removed in a later
-   protocol version.  Use :func:`blockchain.scripthash.get_history` instead.
-
 **Signature**
 
   .. function:: blockchain.address.get_history(address)
+  .. deprecated:: 1.2
 
   * *address*
 
@@ -48,60 +35,17 @@ Return the confirmed and unconfirmed history of a bitcoin address.
 
 **Result**
 
-    A list of confirmed transactions in blockchain order, with the
+  As for :func:`blockchain.scripthash.get_history`.
-    output of :func:`blockchain.address.get_mempool` appended to the
-    list.  Each confirmed transaction is a dictionary with the following
-    keys:
-
-    * *height*
-
-      The integer height of the block the transaction was confirmed
-      in.
-
-    * *tx_hash*
-
-      The transaction hash in hexadecimal.
-
-    See :func:`blockchain.address.get_mempool` for how mempool
-    transactions are returned.
-
-**Result Examples**
-
-::
-
-  [
-    {
-      "height": 200004,
-      "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412"
-    },
-    {
-      "height": 215008,
-      "tx_hash": "f3e1bf48975b8d6060a9de8884296abb80be618dc00ae3cb2f6cee3085e09403"
-    }
-  ]
-
-::
-
-  [
-    {
-      "fee": 20000,
-      "height": 0,
-      "tx_hash": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec"
-    }
-  ]
-
 
 blockchain.address.get_mempool
 ------------------------------
 
 Return the unconfirmed transactions of a bitcoin address.
 
-.. note:: This method is deprecated; support will be removed in a later
-   protocol version.  Use :func:`blockchain.scripthash.get_mempool` instead.
-
 **Signature**
 
   .. function:: blockchain.address.get_mempool(address)
+  .. deprecated:: 1.2
 
   * *address*
 
@@ -109,45 +53,17 @@ Return the unconfirmed transactions of a bitcoin address.
 
 **Result**
 
-    A list of mempool transactions in arbitrary order.  Each mempool
+  As for :func:`blockchain.scripthash.get_mempool`.
-    transaction is a dictionary with the following keys:
-
-    * *height*
-
-      ``0`` if all inputs are confirmed, and ``-1`` otherwise.
-
-    * *tx_hash*
-
-      The transaction hash in hexadecimal.
-
-    * *fee*
-
-      The transaction fee in minimum coin units (satoshis).
-
-**Result Example**
-
-::
-
-  [
-    {
-      "tx_hash": "45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3",
-      "height": 0,
-      "fee": 24310
-    }
-  ]
-
 
 blockchain.address.listunspent
 ------------------------------
 
 Return an ordered list of UTXOs sent to a bitcoin address.
 
-.. note:: This method is deprecated; support will be removed in a later
-   protocol version.  Use :func:`blockchain.scripthash.get_mempool` instead.
-
 **Signature**
 
   .. function:: blockchain.address.listunspent(address)
+  .. deprecated:: 1.2
 
   * *address*
 
@@ -155,61 +71,17 @@ Return an ordered list of UTXOs sent to a bitcoin address.
 
 **Result**
 
-    A list of unspent outputs in blockchain order.  This function
+  As for :func:`blockchain.scripthash.listunspent`.
-    takes the mempool into account.  Mempool transactions paying to
-    the address are included at the end of the list in an undefined
-    order.  Any output that is spent in the mempool does not appear.
-    Each output is a dictionary with the following keys:
-
-    * *height*
-
-      The integer height of the block the transaction was confirmed
-      in.  ``0`` if the transaction is in the mempool.
-
-    * *tx_pos*
-
-      The zero-based index of the output in the transaction's list of
-      outputs.
-
-    * *tx_hash*
-
-      The output's transaction hash as a hexadecimal string.
-
-    * *value*
-
-      The output's value in minimum coin units (satoshis).
-
-**Result Example**
-
-::
-
-  [
-    {
-      "tx_pos": 0,
-      "value": 45318048,
-      "tx_hash": "9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf",
-      "height": 437146
-    },
-    {
-      "tx_pos": 0,
-      "value": 919195,
-      "tx_hash": "3d2290c93436a3e964cfc2f0950174d8847b1fbe3946432c4784e168da0f019f",
-      "height": 441696
-    }
-  ]
-
 
 blockchain.address.subscribe
 ----------------------------
 
 Subscribe to a bitcoin address.
 
-.. note:: This method is deprecated; support will be removed in a later
-   protocol version.  Use :func:`blockchain.scripthash.subscribe` instead.
-
 **Signature**
 
   .. function:: blockchain.address.subscribe(address)
+  .. deprecated:: 1.2
 
   *address*
 
@@ -227,7 +99,6 @@ Subscribe to a bitcoin address.
 
   .. function:: blockchain.address.subscribe(address, status)
 
-
 blockchain.block.get_header
 ---------------------------
 
@@ -263,9 +134,10 @@ block at the given height.
 blockchain.block.get_chunk
 --------------------------
 
-Return a concatenated chunk of block headers.  Typically, a chunk
+Return a concatenated chunk of block headers from the main chain.
-consists of a fixed number of block headers over which difficulty is
+Typically, a chunk consists of a fixed number of block headers over
-constant, and at the end of which difficulty is retargeted.
+which difficulty is constant, and at the end of which difficulty is
+retargeted.
 
 In the case of Bitcoin a chunk is 2,016 headers, each of 80 bytes, so
 chunk 5 consists of the block headers from height 10,080 to 12,095
@@ -276,6 +148,7 @@ bandwidth-intensive request.
 **Signature**
 
   .. function:: blockchain.block.get_chunk(index)
+  .. deprecated:: 1.2
 
   *index*
 
@@ -288,6 +161,55 @@ bandwidth-intensive request.
     implied starting height will be returned; this may range from zero
     to the coin-specific chunk size.
 
+blockchain.block.headers
+------------------------
+
+Return a concatenated chunk of block headers from the main chain.
+
+**Signature**
+
+  .. function:: blockchain.block.headers(start_height, count)
+  .. versionadded:: 1.2
+
+  *start_height*
+
+    The height of the first header requested, a non-negative integer.
+
+  *count*
+
+    The number of headers requested, a non-negative integer.
+
+**Result**
+
+  A dictionary with the following members:
+
+  * *count*
+
+    The number of headers returned, between zero and the number
+    requested.  If the chain has not extended sufficiently far, only
+    the available headers will be returned.  If more headers than
+    *max* were requested at most *max* will be returned.
+
+  * *hex*
+
+    The binary block headers concatenated together in-order as a
+    hexadecimal string.
+
+  * *max*
+
+    The maximum number of headers the server will return in a single
+    request.
+
+**Example Response**
+
+::
+
+  {
+    "count": 2,
+    "hex": "0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299"
+     "max": 2016
+  }
+
 blockchain.estimatefee
 ----------------------
 
@@ -355,14 +277,12 @@ blockchain.numblocks.subscribe
 
 Subscribe to receive the block height when a new block is found.
 
-.. note:: This subscription is deprecated in favour of
-  :func:`blockchain.headers.subscribe` which provides more detailed
-  and useful information.
-
 **Signature**
 
   .. function:: blockchain.numblocks.subscribe()
 
+  *Removed in version 1.1.*
+
 **Result**
 
   The height of the current block, an integer.
@@ -406,6 +326,222 @@ be accepted to the daemon's memory pool.
 
    0.0
 
+blockchain.scripthash.get_balance
+---------------------------------
+
+Return the confirmed and unconfirmed balances of a :ref:`script hash
+<script hashes>`.
+
+**Signature**
+
+  .. function:: blockchain.scripthash.get_balance(scripthash)
+  .. versionadded:: 1.1
+
+  *scripthash*
+
+    The script hash as a hexadecimal string.
+
+**Result**
+
+  A dictionary with keys `confirmed` and `unconfirmed`.  The value of
+  each is the appropriate balance in coin units as a string.
+
+**Result Example**
+
+::
+
+  {
+    "confirmed": "1.03873966",
+    "unconfirmed": "0.236844"
+  }
+
+blockchain.scripthash.get_history
+---------------------------------
+
+Return the confirmed and unconfirmed history of a :ref:`script hash
+<script hashes>`.
+
+**Signature**
+
+  .. function:: blockchain.scripthash.get_history(scripthash)
+  .. versionadded:: 1.1
+
+  *scripthash*
+
+    The script hash as a hexadecimal string.
+
+**Result**
+
+  A list of confirmed transactions in blockchain order, with the
+  output of :func:`blockchain.scripthash.get_mempool` appended to the
+  list.  Each confirmed transaction is a dictionary with the following
+  keys:
+
+  * *height*
+
+    The integer height of the block the transaction was confirmed in.
+
+  * *tx_hash*
+
+    The transaction hash in hexadecimal.
+
+  See :func:`blockchain.scripthash.get_mempool` for how mempool
+  transactions are returned.
+
+**Result Examples**
+
+::
+
+  [
+    {
+      "height": 200004,
+      "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412"
+    },
+    {
+      "height": 215008,
+      "tx_hash": "f3e1bf48975b8d6060a9de8884296abb80be618dc00ae3cb2f6cee3085e09403"
+    }
+  ]
+
+::
+
+  [
+    {
+      "fee": 20000,
+      "height": 0,
+      "tx_hash": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec"
+    }
+  ]
+
+blockchain.scripthash.get_mempool
+---------------------------------
+
+Return the unconfirmed transactions of a :ref:`script hash <script
+hashes>`.
+
+**Signature**
+
+  .. function:: blockchain.scripthash.get_mempool(scripthash)
+  .. versionadded:: 1.1
+
+  *scripthash*
+
+    The script hash as a hexadecimal string.
+
+**Result**
+
+  A list of mempool transactions in arbitrary order.  Each mempool
+  transaction is a dictionary with the following keys:
+
+  * *height*
+
+    ``0`` if all inputs are confirmed, and ``-1`` otherwise.
+
+  * *tx_hash*
+
+    The transaction hash in hexadecimal.
+
+  * *fee*
+
+    The transaction fee in minimum coin units (satoshis).
+
+**Result Example**
+
+::
+
+  [
+    {
+      "tx_hash": "45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3",
+      "height": 0,
+      "fee": 24310
+    }
+  ]
+
+blockchain.scripthash.listunspent
+---------------------------------
+
+Return an ordered list of UTXOs sent to a script hash.
+
+**Signature**
+
+  .. function:: blockchain.scripthash.listunspent(scripthash)
+  .. versionadded:: 1.1
+
+  *scripthash*
+
+    The script hash as a hexadecimal string.
+
+**Result**
+
+  A list of unspent outputs in blockchain order.  This function takes
+  the mempool into account.  Mempool transactions paying to the
+  address are included at the end of the list in an undefined order.
+  Any output that is spent in the mempool does not appear.  Each
+  output is a dictionary with the following keys:
+
+  * *height*
+
+    The integer height of the block the transaction was confirmed in.
+    ``0`` if the transaction is in the mempool.
+
+  * *tx_pos*
+
+    The zero-based index of the output in the transaction's list of
+    outputs.
+
+  * *tx_hash*
+
+    The output's transaction hash as a hexadecimal string.
+
+  * *value*
+
+    The output's value in minimum coin units (satoshis).
+
+**Result Example**
+
+::
+
+  [
+    {
+      "tx_pos": 0,
+      "value": 45318048,
+      "tx_hash": "9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf",
+      "height": 437146
+    },
+    {
+      "tx_pos": 0,
+      "value": 919195,
+      "tx_hash": "3d2290c93436a3e964cfc2f0950174d8847b1fbe3946432c4784e168da0f019f",
+      "height": 441696
+    }
+  ]
+
+blockchain.scripthash.subscribe
+-------------------------------
+
+Subscribe to a script hash.
+
+**Signature**
+
+  .. function:: blockchain.scripthash.subscribe(scripthash)
+  .. versionadded:: 1.1
+
+  *scripthash*
+
+    The script hash as a hexadecimal string.
+
+**Result**
+
+  The :ref:`status <status>` of the script hash.
+
+**Notifications**
+
+  As this is a subcription, the client will receive a notification
+  when the :ref:`status <status>` of the script hash changes.  Its
+  signature is
+
+  .. function:: blockchain.scripthash.subscribe(address, status)
+
 blockchain.transaction.broadcast
 --------------------------------
 
@@ -414,6 +550,8 @@ Broadcast a transaction to the network.
 **Signature**
 
   .. function:: blockchain.transaction.broadcast(raw_tx)
+  .. versionchanged:: 1.1
+     errors returned as JSON RPC errors rather than as a result.
 
   *raw_tx*
 
@@ -423,13 +561,12 @@ Broadcast a transaction to the network.
 
   The transaction hash as a hexadecimal string.
 
-  .. note:: protocol version 1.0 (only) does not respond according to
+  **Note** protocol version 1.0 (only) does not respond according to
-     the JSON RPC specification if an error occurs.  If the daemon
+  the JSON RPC specification if an error occurs.  If the daemon
-     rejects the transaction, the result is the error message string
+  rejects the transaction, the result is the error message string from
-     from the daemon, as if the call were successful.  The client
+  the daemon, as if the call were successful.  The client needs to
-     needs to determine if an error occurred by comparing the result
+  determine if an error occurred by comparing the result to the
-     to the expected transaction hash.  Protocol version 1.1 and later
+  expected transaction hash.
-     return a JSON RPC error as would be expected.
 
 **Result Examples**
 
@@ -451,6 +588,10 @@ Return a raw transaction.
 **Signature**
 
   .. function:: blockchain.transaction.get(tx_hash, verbose=False)
+  .. versionchanged:: 1.1
+     ignored argument *height* removed
+  .. versionchanged:: 1.2
+     *verbose* argument added
 
   *tx_hash*
 
@@ -458,11 +599,7 @@ Return a raw transaction.
 
   *verbose*
 
-    .. versionadded:: 1.2
+    Whether a verbose coin-specific response is required.
-
-    .. 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**
 
@@ -541,20 +678,20 @@ and height.
 
   A dictionary with the following keys:
 
-    * *block_height*
+  * *block_height*
 
-      The height of the block the transaction was confirmed in.
+    The height of the block the transaction was confirmed in.
 
-    * *merkle*
+  * *merkle*
 
-      A list of transaction hashes the current hash is paired with,
+    A list of transaction hashes the current hash is paired with,
-      recursively, in order to trace up to obtain merkle root of the
+    recursively, in order to trace up to obtain merkle root of the
-      block, deepest pairing first.
+    block, deepest pairing first.
 
-    * *pos*
+  * *pos*
 
-      The 0-based index of the position of the transaction in the
+    The 0-based index of the position of the transaction in the
-      ordered list of transactions in the block.
+    ordered list of transactions in the block.
 
 **Result Example**
 
@@ -579,6 +716,32 @@ and height.
     "pos": 710
   }
 
+blockchain.utxo.get_address
+---------------------------
+
+Return the address paid to by a UTXO.
+
+**Signature**
+
+  .. function:: blockchain.utxo.get_address(tx_hash, index)
+  *Optional in version 1.0.*
+  *Removed in version 1.1.*
+
+  *tx_hash*
+
+    The transaction hash as a hexadecimal string.
+
+  *index*
+
+    The zero-based index of the UTXO in the transaction.
+
+**Result**
+
+  A Base58 address string, or :const:`null`.  If the transaction
+  doesn't exist, the index is out of range, or the output is not paid
+  to an address, :const:`null` must be returned.  If the output is
+  spent :const:`null` *may* be returned.
+
 mempool.get_fee_histogram
 -------------------------
 
@@ -588,7 +751,6 @@ mempool.get_fee_histogram
 **Signature**
 
   .. function:: mempool.get_fee_histogram()
-
   .. versionadded:: 1.2
 
 **Result**
@@ -793,10 +955,11 @@ server.version
 
   Identify the client to the server and negotiate the protocol version.
 
-
 **Signature**
 
   .. function:: server.version(client_name="", protocol_version="1.1")
+  .. versionchanged:: 1.1
+     *protocol_version* is not ignored.
 
   * *client_name*
 
@@ -809,9 +972,6 @@ server.version
     they can be passed as a single string rather than as an array of
     two strings, as for the default value.
 
-    .. versionadded:: 1.1
-       *protocol_version* is not ignored.
-
   The server should use the highest protocol version both support::
 
     version = min(client.protocol_max, server.protocol_max)

docs/protocol-new.rst

@@ -1,11 +0,0 @@
-Electrum Protocol
-=================
-
-This is intended to be a reference for client and server authors
-alike.
-
-.. toctree::
-   :maxdepth: 1
-
-   protocol-basics
-   protocol-methods