lukechilds
/
electrumx
mirror of https://github.com/lukechilds/electrumx.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

More sphinx work

patch-2
Neil Booth 7 years ago
parent
a10ff97f2d
commit
70dfaa895d
2 changed files with 227 additions and 37 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 91
      docs/protocol-basics.rst
  2. 173
      docs/protocol-methods.rst

91
docs/protocol-basics.rst
View File

@ -11,10 +11,19 @@ Two standards `JSON RPC 1.0
<http://www.jsonrpc.org/specification_v1>`_ and `JSON RPC 2.0
<http://www.jsonrpc.org/specification>`_ are specified; use of version
2.0 is encouraged but not required. Server support of batch requests
is encouraged for version 1.0 but not required. Clients making batch
requests should limit their size depending on the nature of their
query, because servers will limit response size as an anti-DoS
mechanism.
is encouraged for version 1.0 but not required.
.. note:: A client or server should only indicate JSON RPC 2.0 by
setting the `jsonrpc
<http://www.jsonrpc.org/specification#request_object>`_ member of
its messages to ``"2.0"`` if it supports the version 2.0 protocol in
its entirety. ElectrumX does and will expect clients advertizing so
to function correctly. Those that do not will be disconnected and
possibly blacklisted.
Clients making batch requests should limit their size depending on the
nature of their query, because servers will limit response size as an
anti-DoS mechanism.
Eeach RPC call, and each response, is separated by a single newline in
their respective streams. The JSON specification does not permit
@ -23,7 +32,8 @@ However it does permit newlines as extraneous whitespace between
elements; client and server MUST NOT use newlines in such a way.
If using JSON RPC 2.0's feature of parameter passing by name, the
names shown in the description of the method in question MUST be used.
names shown in the description of the method or notification in
question MUST be used.
A server advertising support for a particular protocol version MUST
support each method documented for that protocol version, unless the
@ -36,7 +46,7 @@ the protocol.
Notifications
-------------
Some RPC calls are subscriptions, which, after the initial response,
Some RPC calls are subscriptions which, after the initial response,
will send a JSON RPC :dfn:`notification` each time the thing
subscribed to changes. The `method` of the notification is the same
as the method of the subscription, and the `params` of the
@ -49,13 +59,11 @@ Version Negotiation
It is desirable to have a way to enhance and improve the protocol
without forcing servers and clients to upgrade at the same time.
Protocol negotiation is not implemented in any client or server at
present to the best of my knowledge, so care is needed to ensure
current clients and servers continue to operate as expected.
Protocol versions are denoted by dotted "a.b" strings, where *m* is
the major version number and *n* the minor version number. For
example: "1.5".
Protocol versions are denoted by dotted number strings with at least
one dot. Examples: "1.5", "1.4.1", "2.0". In "a.b.c" *a* is the
major version number, *b* the minor version number, and *c* the
revision number.
A party to a connection will speak all protocol versions in a range,
say from `protocol_min` to `protocol_max`, which may be the same.
@ -65,16 +73,17 @@ assume the protocol to use is their own `protocol_min`.
The client should send a :func:`server.version` RPC call as early as
possible in order to negotiate the precise protocol version; see its
description for more detail. All responses received in the stream
from and including the server's response to this call will use the
from and including the server's response to this call will use its
negotiated protocol version.
.. _deserialized header:
Deserialized Headers
--------------------
A deserialized header is a dictionary that is coin-specific, and may
even vary in its members for the same coin at different heights.
A :dfn:`deserialized header` is a dictionary describing a block at a
given height.
A typical example would be similar to this template::
@ -88,13 +97,17 @@ A typical example would be similar to this template::
"nonce": <integer>
}
The precise meaning of a block header varies across coins, and also by
coin depending on height, so deserialized headers are deprecated and
will be removed from the protocol in some future version. Instead,
raw headers (as hexadecimal strings) along with their height will be
returned by RPC calls, and it will be up to the client to interpret
them. Detailed knowledge of the meaning of a block header is neither
necessary nor appropriate in the server.
.. note:: The precise format of a deserialized block header varies by
coin, and also potentially by height for the same coin. Detailed
knowledge of the meaning of a block header is neither necessary nor
appropriate in the server.
Consequently deserialized headers are deprecated and will be removed
from the protocol in a future version. Instead, raw headers (as
hexadecimal strings) along with their height will be returned by new
RPC calls, and it will be up to the client to interpret the meaning
of the raw header.
.. _script hashes:
@ -104,10 +117,10 @@ Script Hashes
A :dfn:`script hash` is the hash of the binary bytes of the locking
script (ScriptPubKey), expressed as a hexadecimal string. The hash
function to use is given by the "hash_function" member of
:func:`server.features` (currently "sha256" only). Like for block and
transaction hashes, when converting the big-endian binary hash to a
hexadecimal string the least-significant byte appears first, and the
most-significant byte last.
:func:`server.features` (currently :func:`sha256` only). Like for
block and transaction hashes, when converting the big-endian binary
hash to a hexadecimal string the least-significant byte appears first,
and the most-significant byte last.
For example, the legacy Bitcoin address from the genesis block::
@ -127,7 +140,8 @@ which is sent to the server reversed as::
By subscribing to this hash you can find P2PKH payments to that address.
One public key for that address (the genesis block public key) is::
One public key, the genesis block public key, among the trillions for
that address is::
04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb
649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f
@ -145,12 +159,13 @@ which is sent to the server reversed as::
740485f380ff6379d11ef6fe7d7cdd68aea7f8bd0d953d9fdf3531fb7d531833
By subscribing to this hash you can find P2PK payments to that public
key.
By subscribing to this hash you can find P2PK payments to the genesis
block public key.
.. note:: The Genesis block coinbase is uniquely unspendable and
therefore not indexed. It will not show with the above P2PK script
hash subscription.
.. note:: The Genesis block coinbase is unspendable and therefore not
indexed. It will not show with the above P2PK script hash
subscription.
.. _status:
@ -160,8 +175,9 @@ 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)
1. order confirmed transactions to the script hash by increasing
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:
@ -170,9 +186,10 @@ position in the block if there are more than one in a block)
* ``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.
3. Next, with mempool transactions in any order, append a similar
string for those transactions, 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.

173
docs/protocol-methods.rst
View File

@ -406,6 +406,179 @@ be accepted to the daemon's memory pool.
0.0
blockchain.transaction.broadcast
--------------------------------
Broadcast a transaction to the network.
**Signature**
.. function:: blockchain.transaction.broadcast(raw_tx)
*raw_tx*
The raw transaction as a hexadecimal string.
**Result**
The transaction hash as a hexadecimal string.
.. note:: protocol version 1.0 (only) does not respond according to
the JSON RPC specification if an error occurs. If the daemon
rejects the transaction, the result is the error message string
from the daemon, as if the call were successful. The client
needs to determine if an error occurred by comparing the result
to the expected transaction hash. Protocol version 1.1 and later
return a JSON RPC error as would be expected.
**Result Examples**
::
"a76242fce5753b4212f903ff33ac6fe66f2780f34bdb4b33b175a7815a11a98e"
Protocol version 1.0 returning an error as the result:
::
"258: txn-mempool-conflict"
blockchain.transaction.get
--------------------------
Return a raw transaction.
**Signature**
.. function:: blockchain.transaction.get(tx_hash, verbose=False)
*tx_hash*
The transaction hash as a hexadecimal string.
*verbose*
.. versionadded:: 1.2
.. 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**
If *verbose* is :const:`False`, the raw transaction as a
hexadecimal string. If :const:`True`, the result is coin-specific
and whatever the coin daemon returns when asked for a verbose form
of the raw transaction.
**Example Results**
When *verbose* is :const:`False`::
"01000000015bb9142c960a838329694d3fe9ba08c2a6421c5158d8f7044cb7c48006c1b48"
"4000000006a4730440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a824"
"6a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee76921"
"3ca8b8b412103bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1"
"f6a4feffffff02c6b68200000000001976a9141041fb024bd7a1338ef1959026bbba86006"
"4fe5f88ac50a8cf00000000001976a91445dac110239a7a3814535c15858b939211f85298"
"88ac61ee0700"
When *verbose* is :const:`True`::
{
"blockhash": "0000000000000000015a4f37ece911e5e3549f988e855548ce7494a0a08b2ad6",
"blocktime": 1520074861,
"confirmations": 679,
"hash": "36a3692a41a8ac60b73f7f41ee23f5c917413e5b2fad9e44b34865bd0d601a3d",
"hex": "01000000015bb9142c960a838329694d3fe9ba08c2a6421c5158d8f7044cb7c48006c1b484000000006a4730440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a8246a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee769213ca8b8b412103bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1f6a4feffffff02c6b68200000000001976a9141041fb024bd7a1338ef1959026bbba860064fe5f88ac50a8cf00000000001976a91445dac110239a7a3814535c15858b939211f8529888ac61ee0700",
"locktime": 519777,
"size": 225,
"time": 1520074861,
"txid": "36a3692a41a8ac60b73f7f41ee23f5c917413e5b2fad9e44b34865bd0d601a3d",
"version": 1,
"vin": [ {
"scriptSig": {
"asm": "30440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a8246a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee769213ca8b8b[ALL|FORKID] 03bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1f6a4",
"hex": "4730440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a8246a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee769213ca8b8b412103bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1f6a4"
},
"sequence": 4294967294,
"txid": "84b4c10680c4b74c04f7d858511c42a6c208bae93f4d692983830a962c14b95b",
"vout": 0}],
"vout": [ { "n": 0,
"scriptPubKey": { "addresses": [ "12UxrUZ6tyTLoR1rT1N4nuCgS9DDURTJgP"],
"asm": "OP_DUP OP_HASH160 1041fb024bd7a1338ef1959026bbba860064fe5f OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a9141041fb024bd7a1338ef1959026bbba860064fe5f88ac",
"reqSigs": 1,
"type": "pubkeyhash"},
"value": 0.0856647},
{ "n": 1,
"scriptPubKey": { "addresses": [ "17NMgYPrguizvpJmB1Sz62ZHeeFydBYbZJ"],
"asm": "OP_DUP OP_HASH160 45dac110239a7a3814535c15858b939211f85298 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a91445dac110239a7a3814535c15858b939211f8529888ac",
"reqSigs": 1,
"type": "pubkeyhash"},
"value": 0.1360904}]}
blockchain.transaction.get_merkle
---------------------------------
Return the markle branch to a confirmed transaction given its hash
and height.
**Signature**
.. function:: blockchain.transaction.get_merkle(tx_hash, height)
*tx_hash*
The transaction hash as a hexadecimal string.
*height*
The height at which it was confirmed, an integer.
**Result**
A dictionary with the following keys:
* *block_height*
The height of the block the transaction was confirmed in.
* *merkle*
A list of transaction hashes the current hash is paired with,
recursively, in order to trace up to obtain merkle root of the
block, deepest pairing first.
* *pos*
The 0-based index of the position of the transaction in the
ordered list of transactions in the block.
**Result Example**
::
{
"merkle":
[
"713d6c7e6ce7bbea708d61162231eaa8ecb31c4c5dd84f81c20409a90069cb24",
"03dbaec78d4a52fbaf3c7aa5d3fccd9d8654f323940716ddf5ee2e4bda458fde",
"e670224b23f156c27993ac3071940c0ff865b812e21e0a162fe7a005d6e57851",
"369a1619a67c3108a8850118602e3669455c70cdcdb89248b64cc6325575b885",
"4756688678644dcb27d62931f04013254a62aeee5dec139d1aac9f7b1f318112",
"7b97e73abc043836fd890555bfce54757d387943a6860e5450525e8e9ab46be5",
"61505055e8b639b7c64fd58bce6fc5c2378b92e025a02583303f69930091b1c3",
"27a654ff1895385ac14a574a0415d3bbba9ec23a8774f22ec20d53dd0b5386ff",
"5312ed87933075e60a9511857d23d460a085f3b6e9e5e565ad2443d223cfccdc",
"94f60b14a9f106440a197054936e6fb92abbd69d6059b38fdf79b33fc864fca0",
"2d64851151550e8c4d337f335ee28874401d55b358a66f1bafab2c3e9f48773d"
],
"block_height": 450538,
"pos": 710
}
mempool.get_fee_histogram
-------------------------

Write Preview
Loading…
Cancel
Save