diff --git a/docs/PROTOCOL.rst b/docs/PROTOCOL.rst index 09cbd62..1d77ce7 100644 --- a/docs/PROTOCOL.rst +++ b/docs/PROTOCOL.rst @@ -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" + [, ] 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** diff --git a/server/session.py b/server/session.py index e6760d5..5a45de4 100644 --- a/server/session.py +++ b/server/session.py @@ -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,