RanchiMall/electrumx
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More work on sphinx docs

Browse Source
This commit is contained in:
Neil Booth 2018-03-07 18:13:13 +08:00
parent fe37b470e5
commit d8d2515fc2
7 changed files with 327 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/ARCHITECTURE.rst
View File

@ -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

4
docs/RPC-INTERFACE.rst
View File

@ -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.

20
docs/conf.py
View File

@ -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 ---------------------------------------------
@ -152,4 +162,4 @@ texinfo_documents = [
(master_doc, 'ElectrumX', 'ElectrumX Documentation',
author, 'ElectrumX', 'One line description of project.',
'Miscellaneous'),
]
]

26
docs/features.rst Normal file
View File

@ -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.

47
docs/index.rst
View File

@ -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`

25
docs/protocol-basics.rst
View File

@ -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.

276
docs/protocol-methods.rst
View File

@ -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.