More sphinx work
This commit is contained in:
Neil Booth
parent
a10ff97f2d
commit
70dfaa895d
@ -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.
|
||||
|
||||
@ -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
|
||||
-------------------------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user