Update protocol documentation
This commit is contained in:
Neil Booth
parent
9c25685eb9
commit
f2f2b1e7b6
@ -606,22 +606,29 @@ subscription and the server must send no notifications.
|
||||
missing then the server does not support that transport.
|
||||
|
||||
|
||||
Version 1.1 (provisional)
|
||||
-------------------------
|
||||
Version 1.1
|
||||
-----------
|
||||
|
||||
This protocol version is the same as version `1.0` except for the
|
||||
following changes:
|
||||
|
||||
* improved semantics of `server.version` to aid protocol negotiation
|
||||
* deprecated methods `blockchain.address.get_proof`,
|
||||
* improved semantics of `server.version` to aid protocol negotiation,
|
||||
and a changed return value.
|
||||
* version 1.0 methods `blockchain.address.get_proof`,
|
||||
`blockchain.utxo.get_address` and `blockchain.numblocks.subscribe`
|
||||
have been removed.
|
||||
* method `blockchain.transaction.get` no longer takes a *height*
|
||||
argument
|
||||
* method `blockchain.transaction.get` no longer takes the *height*
|
||||
argument that was ignored in 1.0, providing one will return an
|
||||
error.
|
||||
* method `blockchain.transaction.broadcast` returns errors like any
|
||||
other JSON RPC call. A *tx_hash* result is only returned on
|
||||
success.
|
||||
* new methods `server.features` and `server.add_peer`
|
||||
* new methods `blockchain.scripthash.get_balance`,
|
||||
`blockchain.scripthash.get_history`,
|
||||
`blockchain.scripthash.get_mempool`,
|
||||
`blockchain.scripthash.listunspent`,
|
||||
`blockchain.scripthash.subscribe`,
|
||||
`server.features` and `server.add_peer`.
|
||||
|
||||
|
||||
server.version
|
||||
@ -641,7 +648,8 @@ protocol versions.
|
||||
Optional with default value ["1.1", "1.1"].
|
||||
|
||||
It must be a pair [`protocol_min`, `protocol_max`], each of which is
|
||||
a string.
|
||||
a string. If `protocol_min` and `protocol_max` are the same, they
|
||||
can be passed as a single string rather than as a pair of strings.
|
||||
|
||||
The server should use the highest protocol version both support:
|
||||
|
||||
@ -649,7 +657,7 @@ The server should use the highest protocol version both support:
|
||||
|
||||
If this is below the value
|
||||
|
||||
min(client.protocol_min, server.protocol_min)
|
||||
max(client.protocol_min, server.protocol_min)
|
||||
|
||||
then there is no protocol version in common and the server must close
|
||||
the connection. Otherwise it should send a response appropriate for
|
||||
@ -657,9 +665,9 @@ that protocol version.
|
||||
|
||||
**Response**
|
||||
|
||||
A string
|
||||
An array of length 2
|
||||
|
||||
"m.n"
|
||||
[<software version string>, <protocol version string>]
|
||||
|
||||
identifying the server and the protocol version that will be used
|
||||
for future communication.
|
||||
@ -668,7 +676,98 @@ that protocol version.
|
||||
|
||||
::
|
||||
|
||||
server.version('2.7.11', ["1.0", "2.0"])
|
||||
server.version('2.7.11', ["0.10", "1.1"])
|
||||
|
||||
**Example Response**
|
||||
|
||||
["ElectrumX 1.0.18", "1.1"]
|
||||
|
||||
|
||||
blockchain.scripthash.get_balance
|
||||
=================================
|
||||
|
||||
Return the confirmed and unconfirmed balances of a script hash.
|
||||
|
||||
blockchain.scripthash.get_balance(**scripthash**)
|
||||
|
||||
**schripthash**
|
||||
|
||||
The script hash as a hexadecimal string.
|
||||
|
||||
**Response**
|
||||
|
||||
As for `blockchain.address.get_balance`.
|
||||
|
||||
|
||||
blockchain.scripthash.get_history
|
||||
=================================
|
||||
|
||||
Return the confirmed and unconfirmed history of a script hash.
|
||||
|
||||
blockchain.scripthash.get_history(**scripthash**)
|
||||
|
||||
**schripthash**
|
||||
|
||||
The script hash as a hexadecimal string.
|
||||
|
||||
**Response**
|
||||
|
||||
As for `blockchain.address.get_history`.
|
||||
|
||||
|
||||
blockchain.scripthash.get_mempool
|
||||
=================================
|
||||
|
||||
Return the unconfirmed transactions of a script hash.
|
||||
|
||||
blockchain.scripthash.get_mempool(**scripthash**)
|
||||
|
||||
**schripthash**
|
||||
|
||||
The script hash as a hexadecimal string.
|
||||
|
||||
**Response**
|
||||
|
||||
As for `blockchain.address.get_mempool`.
|
||||
|
||||
|
||||
blockchain.scripthash.listunspent
|
||||
=================================
|
||||
|
||||
Return an ordered list of UTXOs sent to a script hash.
|
||||
|
||||
blockchain.scripthash.listunspent(**scripthash**)
|
||||
|
||||
**schripthash**
|
||||
|
||||
The script hash as a hexadecimal string.
|
||||
|
||||
**Response**
|
||||
|
||||
As for `blockchain.address.listunspent`.
|
||||
|
||||
|
||||
blockchain.scripthash.subscribe
|
||||
===============================
|
||||
|
||||
Subscribe to a script hash.
|
||||
|
||||
blockchain.scripthash.subscribe(**scripthash**)
|
||||
|
||||
**scripthash**
|
||||
|
||||
The script hash as a hexadecimal string.
|
||||
|
||||
**Response**
|
||||
|
||||
The *status* [1]_ of the script hash.
|
||||
|
||||
**Notifications**
|
||||
|
||||
As this is a subcription, the client will receive a notification
|
||||
when the status of the script hash changes. The parameters are:
|
||||
|
||||
[**scripthash**, **status**]
|
||||
|
||||
|
||||
server.add_peer
|
||||
@ -730,9 +829,9 @@ Get a list of features and services supported by the server.
|
||||
* **hash_function**
|
||||
|
||||
The hash function the server uses for script hashing. The client
|
||||
must use this function to hash scripts to produce script hashes to
|
||||
send to the server. The default is "sha256". "sha256" is currently
|
||||
the only acceptable value.
|
||||
must use this function to hash pay-to-scripts to produce script
|
||||
hashes to send to the server. The default is "sha256". "sha256" is
|
||||
currently the only acceptable value.
|
||||
|
||||
* **server_version**
|
||||
|
||||
|
||||
@ -113,7 +113,7 @@ class ElectrumX(SessionBase):
|
||||
self.hashX_subs = {}
|
||||
self.mempool_statuses = {}
|
||||
self.chunk_indices = []
|
||||
self.set_protocol_handlers(None)
|
||||
self.set_protocol_handlers((1, 0))
|
||||
|
||||
def sub_count(self):
|
||||
return len(self.hashX_subs)
|
||||
@ -323,9 +323,23 @@ class ElectrumX(SessionBase):
|
||||
pass
|
||||
|
||||
self.log_info('protocol version {} requested'.format(protocol_version))
|
||||
self.set_protocol_handlers(protocol_version)
|
||||
|
||||
return version.VERSION
|
||||
# Find the highest common protocol version. Disconnect if
|
||||
# that protocol version in unsupported.
|
||||
ptuple = util.protocol_version(protocol_version, version.PROTOCOL_MIN,
|
||||
version.PROTOCOL_MAX)
|
||||
if ptuple is None:
|
||||
self.log_info('unsupported protocol version request {}'
|
||||
.format(protocol_version))
|
||||
raise RPCError('unsupported protocol version: {}'
|
||||
.format(protocol_version), JSONRPC.FATAL_ERROR)
|
||||
|
||||
self.set_protocol_handlers(ptuple)
|
||||
|
||||
if ptuple < (1, 1):
|
||||
return version.VERSION
|
||||
|
||||
return (version.VERSION, '.'.join(str(part) for part in ptuple))
|
||||
|
||||
async def transaction_broadcast(self, raw_tx):
|
||||
'''Broadcast a raw transaction to the network.
|
||||
@ -367,17 +381,7 @@ class ElectrumX(SessionBase):
|
||||
|
||||
return message
|
||||
|
||||
def set_protocol_handlers(self, version_req):
|
||||
# Find the highest common protocol version. Disconnect if
|
||||
# that protocol version in unsupported.
|
||||
ptuple = util.protocol_version(version_req, version.PROTOCOL_MIN,
|
||||
version.PROTOCOL_MAX)
|
||||
if ptuple is None:
|
||||
self.log_info('unsupported protocol version request {}'
|
||||
.format(version_req))
|
||||
raise RPCError('unsupported protocol version: {}'
|
||||
.format(version_req), JSONRPC.FATAL_ERROR)
|
||||
|
||||
def set_protocol_handlers(self, ptuple):
|
||||
controller = self.controller
|
||||
handlers = {
|
||||
'blockchain.address.get_balance': controller.address_get_balance,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user