use scriptPubKeys everywhere instead of scripthashes

related #3

Author: SomberNight

docs/protocol-basics.rst

@@ -76,15 +76,15 @@ All responses received in the stream from and including the server's
 response to this call will use its negotiated protocol version.
 
 
+.. _scriptpubkeys:
 .. _script hashes:
 
 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 :func:`sha256` only).  Like for
+script (scriptPubKey), expressed as a hexadecimal string.  The hash
+function to use is :func:`sha256`.  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.
@@ -93,27 +93,28 @@ For example, the legacy Bitcoin address from the genesis block::
 
     1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
 
-has P2PKH script::
+has P2PKH script (scriptPubKey)::
 
     76a91462e907b15cbf27d5425399ebf6f0fb50ebb88f1888ac
 
 with SHA256 hash::
 
     6191c3b590bfcfa0475e877c302da1e323497acf3b42c08d8fa28e364edf018b
 
-which is sent to the server reversed as::
+the scripthash is defined as the reverse of that::
 
     8b01df4e368ea28f8dc0423bcf7a4923e3a12d307c875e47a0cfbf90b5c39161
 
-By subscribing to this hash you can find P2PKH payments to that address.
+By subscribing to the scriptPubKey or the scripthash,
+you can find P2PKH payments to that address.
 
 One public key, the genesis block public key, among the trillions for
 that address is::
 
     04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb
     649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f
 
-which has P2PK script::
+which has P2PK script (scriptPubKey)::
 
     4104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb
     649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac
@@ -122,11 +123,12 @@ with SHA256 hash::
 
     3318537dfb3135df9f3d950dbdf8a7ae68dd7c7dfef61ed17963ff80f3850474
 
-which is sent to the server reversed as::
+the scripthash is defined as the reverse of that::
 
     740485f380ff6379d11ef6fe7d7cdd68aea7f8bd0d953d9fdf3531fb7d531833
 
-By subscribing to this hash you can find P2PK payments to the genesis
+By subscribing to the scriptPubKey or the scripthash,
+you can find P2PK payments to the genesis
 block public key.
 
 .. note:: The Genesis block coinbase is uniquely unspendable and
@@ -139,10 +141,10 @@ block public key.
 Status
 ------
 
-To calculate the `status` of a :ref:`script hash <script hashes>` (or
-address):
+To calculate the `status` of a :ref:`scriptPubKey <scriptpubkeys>`
+(or :ref:`script hash <script hashes>` or address):
 
-1. Consider all transactions touching the script hash (both those spending
+1. Consider all transactions touching the scriptPubKey (both those spending
 from it, and those funding it), both confirmed and unconfirmed (in mempool).
 
 2. Order confirmed transactions by increasing height (and position in the
@@ -166,7 +168,7 @@ txid (in network byteorder) is used to arrive at a canonical ordering.
 6. Next, with mempool transactions in the specified order, append a similar
 string.
 
-7. The :dfn:`status` of the script hash is the :func:`sha256` hash of the
+7. The :dfn:`status` of the scriptPubKey is the :func:`sha256` hash of the
 full string expressed as a hexadecimal string, or :const:`null` if the
 string is empty because there are no transactions.
 

docs/protocol-changes.rst

@@ -194,7 +194,9 @@ Changes
   * Breaking change for the version negotiation: we now mandate that
     the :func:`server.version` message must be the first message sent.
     That is, version negotiation must happen before any other messages.
-  * The status of a scripthash has its definition tightened in a
+  * The `blockchain.scripthash.*` methods are all replaced with `blockchain.scriptpubkey.*`
+    methods. Note: `sha256(scriptPubKey) == scripthash`.
+  * The status of a scripthash/scriptpubkey has its definition tightened in a
     backwards-compatible way: mempool txs now have a canonical ordering
     defined for the calculation (previously their order was undefined).
   * :func:`blockchain.scripthash.get_mempool` previously did not define
@@ -218,8 +220,24 @@ Changes
 New methods
 -----------
 
+  * :func:`blockchain.scriptpubkey.get_balance`
+  * :func:`blockchain.scriptpubkey.get_history`
+  * :func:`blockchain.scriptpubkey.get_mempool`
+  * :func:`blockchain.scriptpubkey.listunspent`
+  * :func:`blockchain.scriptpubkey.subscribe`
+  * :func:`blockchain.scriptpubkey.unsubscribe`
   * :func:`blockchain.outpoint.subscribe` to subscribe to a transaction
     outpoint, and get a notification when it gets spent.
   * :func:`blockchain.outpoint.unsubscribe` to unsubscribe from a TXO.
   * :func:`blockchain.outpoint.get_status` to get current status of a TXO, without subscribing to changes.
   * :func:`blockchain.transaction.broadcast_package` to broadcast a package of transactions (submitpackage).
+
+Removed methods
+---------------
+
+  * :func:`blockchain.scripthash.get_balance`
+  * :func:`blockchain.scripthash.get_history`
+  * :func:`blockchain.scripthash.get_mempool`
+  * :func:`blockchain.scripthash.listunspent`
+  * :func:`blockchain.scripthash.subscribe`
+  * :func:`blockchain.scripthash.unsubscribe`

docs/protocol-methods.rst

@@ -290,20 +290,19 @@ be accepted to the daemon's memory pool.
 
    0.0
 
-blockchain.scripthash.get_balance
-=================================
+blockchain.scriptpubkey.get_balance
+===================================
 
-Return the confirmed and unconfirmed balances of a :ref:`script hash
-<script hashes>`.
+Return the confirmed and unconfirmed balances of a :ref:`scriptPubKey <scriptpubkeys>`.
 
 **Signature**
 
-  .. function:: blockchain.scripthash.get_balance(scripthash)
-  .. versionadded:: 1.1
+  .. function:: blockchain.scriptpubkey.get_balance(scriptpubkey)
+  .. versionadded:: 1.6
 
-  *scripthash*
+  *scriptpubkey*
 
-    The script hash as a hexadecimal string.
+    The scriptPubKey as a hexadecimal string.
 
 **Result**
 
@@ -322,25 +321,24 @@ Return the confirmed and unconfirmed balances of a :ref:`script hash
     "unconfirmed": 23684400
   }
 
-blockchain.scripthash.get_history
-=================================
+blockchain.scriptpubkey.get_history
+===================================
 
-Return the confirmed and unconfirmed history of a :ref:`script hash
-<script hashes>`.
+Return the confirmed and unconfirmed history of a :ref:`scriptPubKey <scriptpubkeys>`.
 
 **Signature**
 
-  .. function:: blockchain.scripthash.get_history(scripthash)
-  .. versionadded:: 1.1
+  .. function:: blockchain.scriptpubkey.get_history(scriptpubkey)
+  .. versionadded:: 1.6
 
-  *scripthash*
+  *scriptpubkey*
 
-    The script hash as a hexadecimal string.
+    The scriptPubKey as a hexadecimal string.
 
 **Result**
 
   A list of confirmed transactions in blockchain order, with the
-  output of :func:`blockchain.scripthash.get_mempool` appended to the
+  output of :func:`blockchain.scriptpubkey.get_mempool` appended to the
   list.  Each confirmed transaction is a dictionary with the following
   keys:
 
@@ -352,7 +350,7 @@ Return the confirmed and unconfirmed history of a :ref:`script hash
 
     The transaction hash in hexadecimal.
 
-  See :func:`blockchain.scripthash.get_mempool` for how mempool
+  See :func:`blockchain.scriptpubkey.get_mempool` for how mempool
   transactions are returned.
 
 **Result Examples**
@@ -380,27 +378,26 @@ Return the confirmed and unconfirmed history of a :ref:`script hash
     }
   ]
 
-blockchain.scripthash.get_mempool
-=================================
+blockchain.scriptpubkey.get_mempool
+===================================
 
-Return the unconfirmed transactions of a :ref:`script hash <script
-hashes>`.
+Return the unconfirmed transactions of a :ref:`scriptPubKey <scriptpubkeys>`.
 
 **Signature**
 
-  .. function:: blockchain.scripthash.get_mempool(scripthash)
-  .. versionadded:: 1.1
+  .. function:: blockchain.scriptpubkey.get_mempool(scriptpubkey)
+  .. versionadded:: 1.6
   .. versionchanged:: 1.6
      results must be sorted (previously undefined order)
 
-  *scripthash*
+  *scriptpubkey*
 
-    The script hash as a hexadecimal string.
+    The scriptPubKey as a hexadecimal string.
 
 **Result**
 
   A list of mempool transactions. The order is the same as when computing the
-  :ref:`status <status>` of the script hash.
+  :ref:`status <status>` of the scriptPubKey.
   Each mempool transaction is a dictionary with the following keys:
 
   * *height*
@@ -428,19 +425,19 @@ hashes>`.
   ]
 
 
-blockchain.scripthash.listunspent
-=================================
+blockchain.scriptpubkey.listunspent
+===================================
 
-Return an ordered list of UTXOs sent to a script hash.
+Return an ordered list of UTXOs sent to a :ref:`scriptPubKey <scriptpubkeys>`.
 
 **Signature**
 
-  .. function:: blockchain.scripthash.listunspent(scripthash)
-  .. versionadded:: 1.1
+  .. function:: blockchain.scriptpubkey.listunspent(scriptpubkey)
+  .. versionadded:: 1.6
 
-  *scripthash*
+  *scriptpubkey*
 
-    The script hash as a hexadecimal string.
+    The scriptPubKey as a hexadecimal string.
 
 **Result**
 
@@ -501,50 +498,59 @@ Return an ordered list of UTXOs sent to a script hash.
 
 .. _subscribed:
 
-blockchain.scripthash.subscribe
-===============================
+blockchain.scriptpubkey.subscribe
+=================================
 
-Subscribe to a script hash.
+Subscribe to a :ref:`scriptPubKey <scriptpubkeys>`.
 
 **Signature**
 
-  .. function:: blockchain.scripthash.subscribe(scripthash)
-  .. versionadded:: 1.1
+  .. function:: blockchain.scriptpubkey.subscribe(scriptpubkey)
+  .. versionadded:: 1.6
 
-  *scripthash*
+  *scriptpubkey*
 
-    The script hash as a hexadecimal string.
+    The scriptPubKey as a hexadecimal string.
 
 **Result**
 
-  The :ref:`status <status>` of the script hash.
+  The :ref:`status <status>` of the scriptPubKey.
 
 **Notifications**
 
-  The client will receive a notification when the :ref:`status <status>` of the script
-  hash changes.  Its signature is
-
-    .. function:: blockchain.scripthash.subscribe(scripthash, status)
+  The client will receive a notification when the :ref:`status <status>` of the
+  scriptPubKey changes. Importantly, the notifications use :ref:`script hash <script hashes>`
+  instead of scriptPubKey. The scripthash corresponds to the scriptPubKey from the
+  original request.
+  The client is expected to maintain a mapping scripthash->scriptpubkey, or similar,
+  to be able to figure out what the notification refers to.
+  Notably, this way servers do not have to store in memory the scriptpubkey corresponding
+  to the original request (which can be up to 10 KB in size, as per Bitcoin consensus),
+  only the scripthash (which is fixed size). Also, this limits upstream bandwidth usage
+  of servers.
+  The signature is
+
+    .. function:: blockchain.scriptpubkey.subscribe(scripthash, status)
        :noindex:
 
-blockchain.scripthash.unsubscribe
-=================================
+blockchain.scriptpubkey.unsubscribe
+===================================
 
-Unsubscribe from a script hash, preventing future notifications if its :ref:`status
+Unsubscribe from a scriptPubKey, preventing future notifications if its :ref:`status
 <status>` changes.
 
 **Signature**
 
-  .. function:: blockchain.scripthash.unsubscribe(scripthash)
-  .. versionadded:: 1.4.2
+  .. function:: blockchain.scriptpubkey.unsubscribe(scriptpubkey)
+  .. versionadded:: 1.6
 
-  *scripthash*
+  *scriptpubkey*
 
-    The script hash as a hexadecimal string.
+    The scriptPubKey as a hexadecimal string.
 
 **Result**
 
-  Returns :const:`True` if the scripthash was subscribed to, otherwise :const:`False`.
+  Returns :const:`True` if the scriptpubkey was subscribed to, otherwise :const:`False`.
   Note that :const:`False` might be returned even for something subscribed to earlier,
   because the server can drop subscriptions in rare circumstances.
 
@@ -1188,6 +1194,7 @@ Return a list of features and services supported by the server.
   .. function:: server.features()
   .. versionchanged:: 1.6
      added *method_flavours* field to result
+     removed *hash_function* field from result
 
 **Result**
 
@@ -1224,14 +1231,6 @@ Return a list of features and services supported by the server.
     The hash of the genesis block.  This is used to detect if a peer
     is connected to one serving a different network.
 
-  * *hash_function*
-
-    The hash function the server uses for :ref:`script hashing
-    <script hashes>`.  The client 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*
 
     A string that identifies the server software.  Should be the same
@@ -1272,7 +1271,6 @@ Return a list of features and services supported by the server.
       "protocol_min": "1.0",
       "pruning": null,
       "server_version": "ElectrumX 1.0.17",
-      "hash_function": "sha256",
       "method_flavours": {
           "blockchain.outpoint.subscribe": {"requires_spk_hint": true},
           "blockchain.transaction.get": {"supports_verbose_true": false}