More work on sphinx docs

docs/ARCHITECTURE.rst

@@ -1,5 +1,5 @@
-Components
-==========
+Architecture
+============
 
 .. image:: https://docs.google.com/drawings/d/1Su_DR2c8__-4phm12hAzV65fL2tNm_1IhKr4XivkW6Q/pub?w=720&h=540
     :target: https://docs.google.com/drawings/d/1Su_DR2c8__-4phm12hAzV65fL2tNm_1IhKr4XivkW6Q/pub?w=960&h=720

docs/RPC-INTERFACE.rst

@@ -1,5 +1,5 @@
-The ElectrumX RPC Interface
-===========================
+RPC Interface
+=============
 
 You can query the status of a running server, and affect its behaviour
 by sending JSON RPC commands to the LocalRPC port it is listening on.

docs/conf.py

@@ -20,7 +20,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'ElectrumX'
-copyright = '2018, Neil Booth'
+copyright = '2016-2018, Neil Booth'
 author = 'Neil Booth'
 
 # The short X.Y version
@@ -80,7 +80,14 @@ html_theme = 'alabaster'
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'description': 'Lightweight Electrum Server in Python',
+    'github_user': 'kyuupichan',
+    'github_repo': 'electrumx',
+    'github_button': True,
+    'github_type': 'star',
+    'github_banner': True,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -94,9 +101,12 @@ html_static_path = ['_static']
 # defined by theme itself.  Builtin themes are using these templates by
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
-#
-# html_sidebars = {}
 
+html_sidebars = {
+    '**': [
+        'about.html', 'navigation.html', 'searchbox.html',
+    ]
+}
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

docs/features.rst

@@ -0,0 +1,26 @@
+Features
+========
+
+- Efficient, lightweight reimplementation of electrum-server
+- Fast synchronization of bitcoin mainnet from Genesis.  Recent
+  hardware should synchronize in well under 24 hours.  The fastest
+  time to height 448k (mid January 2017) reported is under 4h 30m.  On
+  the same hardware JElectrum would take around 4 days and
+  electrum-server probably around 1 month.
+- The full current Electrum protocol is implemented.
+- Various configurable means of controlling resource consumption and
+  handling denial of service attacks.  These include maximum
+  connection counts, subscription limits per-connection and across all
+  connections, maximum response size, per-session bandwidth limits,
+  and session timeouts.
+- Minimal resource usage once caught up and serving clients; tracking the
+  transaction mempool appears to be the most expensive part.
+- Fully asynchronous processing of new blocks, mempool updates, and
+  client requests.  Busy clients should not noticeably impede other
+  clients' requests and notifications, nor the processing of incoming
+  blocks and mempool updates.
+- Daemon failover.  More than one daemon can be specified, and
+  ElectrumX will failover round-robin style if the current one fails
+  for any reason.
+- Peer discovery protocol removes need for IRC
+- Coin abstraction makes compatible altcoin and testnet support easy.

docs/index.rst

@@ -1,17 +1,12 @@
-.. ElectrumX documentation master file, created by
-   sphinx-quickstart on Mon Mar  5 22:39:16 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+=========
+ElectrumX
+=========
 
 .. image:: https://travis-ci.org/kyuupichan/electrumx.svg?branch=master
     :target: https://travis-ci.org/kyuupichan/electrumx
 .. image:: https://coveralls.io/repos/github/kyuupichan/electrumx/badge.svg
     :target: https://coveralls.io/github/kyuupichan/electrumx
 
-=========
-ElectrumX
-=========
-
 A reimplementation of Electrum-Server for a future with bigger blocks.
 
   :Licence: MIT
@@ -32,43 +27,14 @@ available .
 .. _Dockerfile: https://github.com/lukechilds/docker-electrumx
 
 
-Features
-========
-
-- Efficient, lightweight reimplementation of electrum-server
-- Fast synchronization of bitcoin mainnet from Genesis.  Recent
-  hardware should synchronize in well under 24 hours.  The fastest
-  time to height 448k (mid January 2017) reported is under 4h 30m.  On
-  the same hardware JElectrum would take around 4 days and
-  electrum-server probably around 1 month.
-- The full current Electrum protocol is implemented.
-- Various configurable means of controlling resource consumption and
-  handling denial of service attacks.  These include maximum
-  connection counts, subscription limits per-connection and across all
-  connections, maximum response size, per-session bandwidth limits,
-  and session timeouts.
-- Minimal resource usage once caught up and serving clients; tracking the
-  transaction mempool appears to be the most expensive part.
-- Fully asynchronous processing of new blocks, mempool updates, and
-  client requests.  Busy clients should not noticeably impede other
-  clients' requests and notifications, nor the processing of incoming
-  blocks and mempool updates.
-- Daemon failover.  More than one daemon can be specified, and
-  ElectrumX will failover round-robin style if the current one fails
-  for any reason.
-- Peer discovery protocol removes need for IRC
-- Coin abstraction makes compatible altcoin and testnet support easy.
-
-
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
 
-   ENVIRONMENT
+   features
    HOWTO
+   ENVIRONMENT
+   protocol-new
    PEER_DISCOVERY
    RPC-INTERFACE
-   protocol-new
    ARCHITECTURE
 
 
@@ -76,5 +42,4 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`

docs/protocol-basics.rst

@@ -123,3 +123,28 @@ key.
 .. note:: The Genesis block coinbase is unspendable and therefore not
    indexed.  It will not show with the above P2PK script hash
    subscription.
+
+.. _status:
+
+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
+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:
+
+  * ``tx_hash`` is the transaction hash in hexadecimal
+
+  * ``height`` is the height of the block it is in.
+
+3. Next, with mempool transactions in any order, append a string that
+is the same, but where **height** is ``-1`` if the 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

@@ -1,6 +1,232 @@
 Protocol Methods
 ================
 
+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)
+
+  * *address*
+
+    The address as a Base58 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.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)
+
+  * *address*
+
+    The address as a Base58 string.
+
+**Result**
+
+    A list of confirmed transactions in blockchain order, with the
+    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)
+
+  * *address*
+
+    The address as a Base58 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.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)
+
+  * *address*
+
+    The address as a Base58 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.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)
+
+  *address*
+
+    The address as a Base58 string.
+
+**Result**
+
+  The :ref:`status <status>` of the address.
+
+**Notifications**
+
+  As this is a subcription, the client will receive a notification
+  when the :ref:`status <status>` of the address changes.  Its
+  signature is
+
+  .. function:: blockchain.address.subscribe(address, status)
+
 mempool.get_fee_histogram
 -------------------------
 
@@ -45,7 +271,7 @@ server.add_peer
 
   .. versionadded:: 1.1
 
-  * **features**
+  * *features*
 
     The same information that a call to the sender's
     :func:`server.features` RPC call would return.
@@ -114,7 +340,7 @@ server.features
   The following features MUST be reported by the server.  Additional
   key-value pairs may be returned.
 
-  * **hosts**
+  * *hosts*
 
     A dictionary, keyed by host name, that this server can be reached
     at.  Normally this will only have a single entry; other entries
@@ -123,25 +349,25 @@ server.features
     The value for a host is itself a dictionary, with the following
     optional keys:
 
-    * **ssl_port**
+    * *ssl_port*
 
-      An integer.  Omit or set to **null** if SSL connectivity is not
-      provided.
+      An integer.  Omit or set to :const:`null` if SSL connectivity
+      is not provided.
 
-    * **tcp_port**
+    * *tcp_port*
 
-      An integer.  Omit or set to **null** if TCP connectivity is not
-      provided.
+      An integer.  Omit or set to :const:`null` if TCP connectivity is
+      not provided.
 
     A server should ignore information provided about any host other
     than the one it connected to.
 
-  * **genesis_hash**
+  * *genesis_hash*
 
     The hash of the genesis block.  This is used to detect if a peer
     is connected to one serving a different network.
 
-  * **hash_function**
+  * *hash_function*
 
     The hash function the server uses for :ref:`script hashing
     <script hashes>`.  The client must use this function to hash
@@ -149,22 +375,22 @@ server.features
     The default is "sha256".  "sha256" is currently the only
     acceptable value.
 
-  * **server_version**
+  * *server_version*
 
     A string that identifies the server software.  Should be the same
     as the response to :func:`server.version` RPC call.
 
-  * **protocol_max**
-  * **protocol_min**
+  * *protocol_max*
+  * *protocol_min*
 
     Strings that are the minimum and maximum Electrum protocol
     versions this server speaks.  Example: "1.1".
 
-  * **pruning**
+  * *pruning*
 
-    An integer, the pruning limit.  Omit or set to **null** if there is
-    no pruning limit.  Should be the same as what would suffix the
-    letter **p** in the IRC real name.
+    An integer, the pruning limit.  Omit or set to :const:`null` if
+    there is no pruning limit.  Should be the same as what would
+    suffix the letter ``p`` in the IRC real name.
 
 **Example Result**
 
@@ -220,19 +446,19 @@ server.version
 
   .. function:: server.version(client_name="", protocol_version="1.1")
 
-  * **client_name**
+  * *client_name*
 
     A string identifying the connecting client software.
 
-  * **protocol_version**
+  * *protocol_version*
 
-    An array [`protocol_min`, `protocol_max`], each of which is a
-    string.  If `protocol_min` and `protocol_max` are the same, they
-    can be passed as a single string rather than as an array of two
-    strings, as for the default value.
+    An array ``[protocol_min, protocol_max]``, each of which is a
+    string.  If ``protocol_min`` and ``protocol_max`` are the same,
+    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.
+       *protocol_version* is not ignored.
 
   The server should use the highest protocol version both support::
 
@@ -250,7 +476,7 @@ server.version
 
   An array of 2 strings:
 
-     [`server software version`, `protocol version`]
+     ``[server_software_version, protocol_version]``
 
   identifying the server and the protocol version that will be used
   for future communication.