From bbbef6a1e4c5a77dd2b8ecfe6322368eec10925c Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Thu, 6 Feb 2025 15:18:30 +0000
Subject: [PATCH 01/13] add new protocol version 1.6

- This is mostly split off from the protocol 1.5/2.0 specs and ideas
  in https://github.com/spesmilo/electrumx/pull/90
  - notably it does not include the history pagination, and the recursive scripthash status,
    which are deferred for now
---
 docs/protocol-basics.rst  |  38 ++++---
 docs/protocol-changes.rst |  39 ++++++-
 docs/protocol-methods.rst | 229 ++++++++++++++++++++++++++++++++++++--
 3 files changed, 277 insertions(+), 29 deletions(-)

diff --git a/docs/protocol-basics.rst b/docs/protocol-basics.rst
index ffdfee7..623ba6c 100644
--- a/docs/protocol-basics.rst
+++ b/docs/protocol-basics.rst
@@ -68,14 +68,12 @@ 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.
-When a connection is made, both client and server must initially
-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 its
-negotiated protocol version.
+The client must send a :func:`server.version` RPC call as the first
+message on the wire, 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 its negotiated protocol version.
 
 
 .. _script hashes:
@@ -144,23 +142,31 @@ Status
 To calculate the `status` of a :ref:`script hash <script hashes>` (or
 address):
 
-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)
+1. Consider all transactions touching the script hash (both those spending
+from it, and those funding it), both confirmed and unconfirmed (in mempool).
 
-2. form a string that is the concatenation of strings
+2. Order confirmed transactions by increasing height (and position in the
+block if there are more than one in a block).
+
+3. form a string that is the concatenation of strings
 ``"tx_hash:height:"`` for each transaction in order, where:
 
   * ``tx_hash`` is the transaction hash in hexadecimal
 
   * ``height`` is the height of the block it is in.
 
-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. For mempool transactions, we define **height** to be ``-1`` if the
+transaction has at least one unconfirmed input, and ``0`` if all inputs are
+confirmed.
+
+5. Order mempool transactions by ``(-height, tx_hash)``, that is,
+``0`` height txs come before ``-1`` height txs, and secondarily the
+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.
 
-4. The :dfn:`status` of the script hash is the :func:`sha256` hash of the
+7. The :dfn:`status` of the script hash 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.
 
diff --git a/docs/protocol-changes.rst b/docs/protocol-changes.rst
index d4d0abb..bf9e82c 100644
--- a/docs/protocol-changes.rst
+++ b/docs/protocol-changes.rst
@@ -2,7 +2,7 @@
 Protocol Changes
 ================
 
-This documents lists changes made by protocol version.
+This document lists changes made by protocol version.
 
 Version 1.0
 ===========
@@ -175,3 +175,40 @@ New methods
 -----------
 
   * :func:`blockchain.name.get_value_proof` to resolve a name (with proof).  Name index coins (e.g. Namecoin) only.
+
+
+Version 1.5
+===========
+
+(this version number was skipped, no corresponding protocol is defined)
+
+
+.. _version 1.6:
+
+Version 1.6
+===========
+
+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
+    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
+    an order for mempool transactions. We now mandate a specific ordering.
+  * The previously required *height* argument for
+    :func:`blockchain.transaction.get_merkle` is now optional.
+  * Optional *mode* argument added to :func:`blockchain.estimatefee`.
+  * :func:`blockchain.block.headers` now returns headers as a list,
+    instead of a single concatenated hex string.
+
+New methods
+-----------
+
+  * :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.
diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index 3d9d73b..87d2ca8 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -76,7 +76,7 @@ With *cp_height* 8::
 blockchain.block.headers
 ========================
 
-Return a concatenated chunk of block headers from the main chain.
+Return a chunk of block headers from the main chain.
 
 **Signature**
 
@@ -85,6 +85,8 @@ Return a concatenated chunk of block headers from the main chain.
   .. versionchanged:: 1.4
      *cp_height* parameter added
   .. versionchanged:: 1.4.1
+  .. versionchanged:: 1.6
+     response contains *headers* field instead of *hex*
 
   *start_height*
 
@@ -106,17 +108,16 @@ Return a concatenated chunk of block headers from the main chain.
   A dictionary with the following members:
 
   * *count*
-
     The number of headers returned, between zero and the number
     requested.  If the chain has not extended sufficiently far, only
     the available headers will be returned.  If more headers than
     *max* were requested at most *max* will be returned.
 
-  * *hex*
+  * *headers*
 
-    The binary block headers concatenated together in-order as a
-    hexadecimal string.  Starting with version 1.4.1, AuxPoW data (if present
-    in the original header) is truncated if *cp_height* is nonzero.
+    An array containing the binary block headers in-order; each header is a
+    hexadecimal string.  AuxPoW data (if present in the original header) is
+    truncated if *cp_height* is nonzero.
 
   * *max*
 
@@ -149,7 +150,11 @@ See :ref:`here <cp_height example>` for an example of *root* and
 
   {
     "count": 2,
-    "hex": "0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299"
+    "headers":
+    [
+      "0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c",
+      "010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299"
+    ],
     "max": 2016
   }
 
@@ -161,12 +166,21 @@ be confirmed within a certain number of blocks.
 
 **Signature**
 
-  .. function:: blockchain.estimatefee(number)
+  .. function:: blockchain.estimatefee(number, mode=None)
+  .. versionchanged:: 1.6
+     *mode* argument added
 
   *number*
 
     The number of blocks to target for confirmation.
 
+  *mode*
+
+    A string to pass to the bitcoind *estimatesmartfee* RPC as the
+    *estimate_mode* parameter. Optional. If omitted, the corresponding
+    parameter to the bitcoind RPC is also omitted, i.e. the default
+    value is determined by bitcoind.
+
 **Result**
 
   The estimated transaction fee in whole coin units per kilobyte, as a
@@ -359,6 +373,8 @@ hashes>`.
 
   .. function:: blockchain.scripthash.get_mempool(scripthash)
   .. versionadded:: 1.1
+  .. versionchanged:: 1.6
+     results must be sorted (previously undefined order)
 
   *scripthash*
 
@@ -366,8 +382,9 @@ hashes>`.
 
 **Result**
 
-  A list of mempool transactions in arbitrary order.  Each mempool
-  transaction is a dictionary with the following keys:
+  A list of mempool transactions. The order is the same as when computing the
+  :ref:`status <status>` of the script hash.
+  Each mempool transaction is a dictionary with the following keys:
 
   * *height*
 
@@ -514,6 +531,190 @@ Unsubscribe from a script hash, preventing future notifications if its :ref:`sta
   Note that :const:`False` might be returned even for something subscribed to earlier,
   because the server can drop subscriptions in rare circumstances.
 
+blockchain.outpoint.subscribe
+=============================
+
+Subscribe to a transaction outpoint (TXO), to get notifications about its status.
+A status involves up to two transactions: the funding transaction that creates
+the TXO (as one of its outputs), and the spending transaction that uses it
+as an input (spends it).
+
+**Signature**
+
+  .. function:: blockchain.outpoint.subscribe(tx_hash, txout_idx, spk_hint=None)
+  .. versionadded:: 1.6
+
+  *tx_hash*
+
+    The TXID of the funding transaction as a hexadecimal string.
+    (sometimes called prevout_hash, in inputs)
+
+  *txout_idx*
+
+    The output index, a non-negative integer. (sometimes called prevout_n, in inputs)
+
+  *spk_hint*
+
+    The scriptPubKey (output script) corresponding to the outpoint, as a hexadecimal
+    string. This is optional, and if provided might be used by the server to find
+    the outpoint. The behaviour is undefined if an incorrect value is provided.
+    The server (especially lighter ones such as EPS/BWT) might require this parameter
+    to be able to serve the request, in which case the server must indicate so in its
+    :func:`server.features` response, by including an `requires_spk_hint_for_outpoint` key
+    with value `1`.
+
+.. note::  The server MAY automatically clean up subscriptions (unsubscribe the client)
+  where the spending transaction is already deeply mined at a reorg-safe height (typically
+  100+ blocks deep).
+  Similarly, the server MAY ignore new subscription requests if the spending tx is already
+  mined at a reorg-safe height but it still MUST send at least one full response.
+
+**Result**
+
+  The status of the TXO, taking the mempool into consideration.
+  The output is a dictionary, containing 0, 1, or 3 of the following items:
+
+  * *height*
+
+    The integer height of the block the funding transaction was confirmed in.
+    If the funding transaction is in the mempool; the value is
+    ``0`` if all its inputs are confirmed, and ``-1`` otherwise.
+    This key must be present if and only if there exists a funding transaction
+    (either in the best chain or in the mempool), regardless of spentness.
+
+  * *spender_txhash*
+
+    The TXID of the spending transaction as a hexadecimal string.
+    This key is present if and only if there exists a spending transaction
+    (either in the best chain or in the mempool).
+
+  * *spender_height*
+
+    The integer height of the block the spending transaction was confirmed in.
+    If the spending transaction is in the mempool; the value is
+    ``0`` if all its inputs are confirmed, and ``-1`` otherwise.
+    This key is present if and only if the *spender_txhash* key is present.
+
+**Result Examples**
+
+::
+
+  {}
+
+::
+
+  {
+    "height": 1866594
+  }
+
+::
+
+  {
+    "height": 1866594,
+    "spender_txhash": "4a19a360f71814c566977114c49ccfeb8a7e4719eda26cee27fa504f3f02ca09",
+    "spender_height": 0
+  }
+
+**Notifications**
+
+  The client will receive a notification when the `status` of the outpoint changes.
+  That is, any event that changes any field of the `status` dictionary results in a
+  notification. Some examples:
+
+  * a funding/spending tx appearing in the mempool if there was no such tx when the client subbed
+    (note: the server MUST save the subscription even if the outpoint does not exist yet)
+  * funding/spending tx height changing from -1 to 0 as its inputs got mined
+  * funding/spending tx height changing from 0 to a (positive) block height when it gets mined
+  * note that reorgs can change any of the `status` fields and result in notifications
+  * note that mempool replacement (e.g. due to RBF) or mempool eviction (and potentially other
+    mempool quirks) can also change some of the `status` fields and hence result in notifications
+
+  The client MAY receive a notification even if the status did not change
+  (when e.g. there was a reorg changing the blockhash the tx is mined in but not the height).
+
+  The signature of the notification is
+
+    .. function:: blockchain.outpoint.subscribe([tx_hash, txout_idx], status)
+       :noindex:
+
+**Full JSON-RPC Example**
+
+Here is an example where the client sends a request, gets an immediate response,
+and then at some point later - while the connection is still open -
+receives a notification.
+
+::
+
+  -> {
+    "jsonrpc": "2.0",
+    "id": 4,
+    "method": "blockchain.outpoint.subscribe",
+    "params": ["1872b27abc497492a775fe335abfe368af575733144a7ecd4b249d8fd885b3cf", 1]
+  }
+  <- {
+    "jsonrpc": "2.0",
+    "result": {"height": 1866594},
+    "id": 4
+  }
+
+  # notification after broadcasting tx 4a19a360f71814c566977114c49ccfeb8a7e4719eda26cee27fa504f3f02ca09
+  <- {
+    "jsonrpc": "2.0",
+    "method": "blockchain.outpoint.subscribe",
+    "params": [
+      ["1872b27abc497492a775fe335abfe368af575733144a7ecd4b249d8fd885b3cf", 1],
+      {
+        "height": 1866594,
+        "spender_txhash": "4a19a360f71814c566977114c49ccfeb8a7e4719eda26cee27fa504f3f02ca09",
+        "spender_height": 0
+      }
+    ]
+  }
+
+
+blockchain.outpoint.get_status
+==============================
+
+Get the status of a transaction outpoint (TXO).
+Same as :func:`blockchain.outpoint.subscribe`, but without subscribing to future changes of status
+(i.e. no subsequent notifications).
+
+**Signature**
+
+  .. function:: blockchain.outpoint.get_status(tx_hash, txout_idx, spk_hint=None)
+  .. versionadded:: 1.6
+
+  (same as :func:`blockchain.outpoint.subscribe`)
+
+**Result**
+
+  (same as :func:`blockchain.outpoint.subscribe`)
+
+blockchain.outpoint.unsubscribe
+===============================
+
+Unsubscribe from a transaction outpoint (TXO), preventing future notifications
+if its `status` changes.
+
+**Signature**
+
+  .. function:: blockchain.outpoint.unsubscribe(tx_hash, txout_idx)
+  .. versionadded:: 1.6
+
+  *tx_hash*
+
+    The TXID of the funding transaction as a hexadecimal string.
+
+  *txout_idx*
+
+    The output index, a non-negative integer.
+
+**Result**
+
+  Returns :const:`True` if the outpoint 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.
+
 blockchain.transaction.broadcast
 ================================
 
@@ -640,7 +841,9 @@ and height.
 
 **Signature**
 
-  .. function:: blockchain.transaction.get_merkle(tx_hash, height)
+  .. function:: blockchain.transaction.get_merkle(tx_hash, height=None)
+  .. versionchanged:: 1.6
+     *height* argument made optional (previously mandatory)
 
   *tx_hash*
 
@@ -648,7 +851,8 @@ and height.
 
   *height*
 
-    The height at which it was confirmed, an integer.
+    Optionally, the height at which it was confirmed, an integer.
+    Clients are encouraged to provide this field when they can, to reduce server load.
 
 **Result**
 
@@ -991,6 +1195,7 @@ server.version
 ==============
 
 Identify the client to the server and negotiate the protocol version.
+This must be the first message sent on the wire.
 Only the first :func:`server.version` message is accepted.
 
 **Signature**

From 9f20980ddde73a59f57ce824a87af8edaa5f1be4 Mon Sep 17 00:00:00 2001
From: f321x <f321x@tutamail.com>
Date: Thu, 6 Feb 2025 11:33:39 +0000
Subject: [PATCH 02/13] add submitpackage methods

---
 docs/protocol-changes.rst |  1 +
 docs/protocol-methods.rst | 86 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)

diff --git a/docs/protocol-changes.rst b/docs/protocol-changes.rst
index bf9e82c..78a6151 100644
--- a/docs/protocol-changes.rst
+++ b/docs/protocol-changes.rst
@@ -212,3 +212,4 @@ New methods
     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).
diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index 87d2ca8..3c9e5cd 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -753,6 +753,92 @@ Protocol version 1.0 returning an error as the result:
 
   "258: txn-mempool-conflict"
 
+blockchain.transaction.broadcast_package
+========================================
+
+Broadcast a package of transactions to the network (submitpackage). The package must consist of a child with its parents,
+and none of the parents may depend on one another. The package must be topologically sorted,
+with the child being the last element in the array.
+
+**Signature**
+
+  .. function:: blockchain.transaction.broadcast_package(raw_txs, verbose=false)
+
+  *raw_txs*
+
+    An array of raw transactions, each as a hexadecimal string.
+
+  *verbose*
+
+    Whether a verbose coin-specific response is required.
+
+**Result**
+
+  If *verbose* is :const:`false`:
+
+    A dictionary with the following keys:
+
+    * `success`
+        * Type: bool
+        * Value: Indicating the result of the package submission
+    * `errors`
+        * Type: Optional[List[Dict]]
+        * Value: Error message and txid (NOT wtxid) of transactions that were not accepted
+
+  If *verbose* is :const:`true`:
+
+    The bitcoind response according to its RPC API documentation.
+    Note that the exact structure and semantics can depend on the bitcoind version,
+    and hence the electrum protocol can make no guarantees about it.
+
+**Result Example**
+
+When *verbose* is :const:`false`::
+
+    {
+      "success": true
+    }
+
+    With errors:
+
+    {
+      "success": false,
+      "errors":
+      [
+        {
+          "txid": "ec6f295cd4b1b91f59cabb0ab8fdc7c76580db08be6426e465f75a69d82b9659",
+          "error": "bad-txns-inputs-missingorspent"
+        }
+      ]
+    }
+
+When *verbose* is :const:`true`::
+
+    {                                   (json object)
+      "package_msg" : "str",            (string) The transaction package result message. "success" indicates all transactions were accepted into or are already in the mempool.
+      "tx-results" : {                  (json object) transaction results keyed by wtxid
+        "wtxid" : {                     (json object) transaction wtxid
+          "txid" : "hex",               (string) The transaction hash in hex
+          "other-wtxid" : "hex",        (string, optional) The wtxid of a different transaction with the same txid but different witness found in the mempool. This means the submitted transaction was ignored.
+          "vsize" : n,                  (numeric, optional) Sigops-adjusted virtual transaction size.
+          "fees" : {                    (json object, optional) Transaction fees
+            "base" : n,                 (numeric) transaction fee in BTC
+            "effective-feerate" : n,    (numeric, optional) if the transaction was not already in the mempool, the effective feerate in BTC per KvB. For example, the package feerate and/or feerate with modified fees from prioritisetransaction.
+            "effective-includes" : [    (json array, optional) if effective-feerate is provided, the wtxids of the transactions whose fees and vsizes are included in effective-feerate.
+              "hex",                    (string) transaction wtxid in hex
+              ...
+            ]
+          },
+          "error" : "str"               (string, optional) The transaction error string, if it was rejected by the mempool
+        },
+        ...
+      },
+      "replaced-transactions" : [       (json array, optional) List of txids of replaced transactions
+        "hex",                          (string) The transaction id
+        ...
+      ]
+    }
+
 blockchain.transaction.get
 ==========================
 

From ecda781f74947f47d9297908f711ba29fa005cd4 Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Fri, 7 Feb 2025 16:47:50 +0000
Subject: [PATCH 03/13] add note about estimatefee caching

---
 docs/protocol-methods.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index 3c9e5cd..c663e46 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -193,6 +193,11 @@ be confirmed within a certain number of blocks.
 
   0.00101079
 
+.. note:: This estimate typically comes from the Bitcoin daemon, which only updates
+  its estimate when new blocks are mined. The server is free to cache this internally
+  for performance reasons, however it SHOULD avoid sending stale estimates
+  by e.g. invalidating the cache before notifying clients of a new block header.
+
 
 blockchain.headers.subscribe
 ============================

From ccfce5163ecf703e205de72f688243aef4d1f8cc Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Mon, 17 Feb 2025 16:31:46 +0000
Subject: [PATCH 04/13] add "method_flavours" to "server.features"

---
 docs/protocol-methods.rst | 44 +++++++++++++++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 4 deletions(-)

diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index c663e46..9061986 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -14,6 +14,8 @@ Return the block header at the given height.
   .. versionchanged:: 1.4
      *cp_height* parameter added
   .. versionchanged:: 1.4.1
+  .. versionchanged:: 1.6
+     *cp_height* support made optional
 
   *height*
 
@@ -26,6 +28,10 @@ Return the block header at the given height.
 
       *height* <= *cp_height*
 
+    The server CAN decide not to support a non-zero cp_height value, but if so,
+    it MUST indicate that in its :func:`server.features` response by setting
+    `method_flavours["blockchain.block.header"]["supports_cp_height"]=false`.
+
 **Result**
 
   If *cp_height* is zero, the raw block header as a hexadecimal
@@ -87,6 +93,7 @@ Return a chunk of block headers from the main chain.
   .. versionchanged:: 1.4.1
   .. versionchanged:: 1.6
      response contains *headers* field instead of *hex*
+     *cp_height* support made optional
 
   *start_height*
 
@@ -103,6 +110,11 @@ Return a chunk of block headers from the main chain.
 
       *start_height* + (*count* - 1) <= *cp_height*
 
+    The server CAN decide not to support a non-zero cp_height value, but if so,
+    it MUST indicate that in its :func:`server.features` response by setting
+    `method_flavours["blockchain.block.header"]["supports_cp_height"]=false`.
+    (the flavour key `"blockchain.block.header"` is reused with the other header method).
+
 **Result**
 
   A dictionary with the following members:
@@ -565,8 +577,8 @@ as an input (spends it).
     the outpoint. The behaviour is undefined if an incorrect value is provided.
     The server (especially lighter ones such as EPS/BWT) might require this parameter
     to be able to serve the request, in which case the server must indicate so in its
-    :func:`server.features` response, by including an `requires_spk_hint_for_outpoint` key
-    with value `1`.
+    :func:`server.features` response, by setting
+    `method_flavours["blockchain.outpoint.subscribe"]["requires_spk_hint"]=true`.
 
 .. note::  The server MAY automatically clean up subscriptions (unsubscribe the client)
   where the spending transaction is already deeply mined at a reorg-safe height (typically
@@ -775,7 +787,7 @@ with the child being the last element in the array.
 
   *verbose*
 
-    Whether a verbose coin-specific response is required.
+    Whether the verbose bitcoind response is required.
 
 **Result**
 
@@ -856,6 +868,8 @@ Return a raw transaction.
      ignored argument *height* removed
   .. versionchanged:: 1.2
      *verbose* argument added
+  .. versionchanged:: 1.6
+     support of *verbose=true* made optional
 
   *tx_hash*
 
@@ -864,6 +878,10 @@ Return a raw transaction.
   *verbose*
 
     Whether the verbose bitcoind response is required.
+    The server MUST support the verbose=false option (which is the default).
+    The server CAN decide not to support the verbose=true option, but if so,
+    it MUST indicate that in its :func:`server.features` response by setting
+    `method_flavours["blockchain.transaction.get"]["supports_verbose_true"]=false`.
 
 **Result**
 
@@ -1162,6 +1180,8 @@ Return a list of features and services supported by the server.
 **Signature**
 
   .. function:: server.features()
+  .. versionchanged:: 1.6
+     added *method_flavours* field to result
 
 **Result**
 
@@ -1223,6 +1243,18 @@ Return a list of features and services supported by the server.
     there is no pruning limit.  Should be the same as what would
     suffix the letter ``p`` in the IRC real name.
 
+  * *method_flavours*
+
+    A dictionary that describes whether optional features of certain protocol methods
+    are supported by the server. The server might also require an otherwise optional
+    argument to be set by the client, that too should be clearly advertised here.
+    The keys are protocol method name strings, and the values are dictionaries
+    that are specific to the given protocol method.
+
+    If a server supports all functionality defined for the negotiated protocol version,
+    it can just set this to the empty dict (but the `method_flavours` key itself
+    must always be present).
+
 **Example Result**
 
 ::
@@ -1234,7 +1266,11 @@ 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"
+      "hash_function": "sha256",
+      "method_flavours": {
+          "blockchain.outpoint.subscribe": {"requires_spk_hint": true},
+          "blockchain.transaction.get": {"supports_verbose_true": false}
+      }
   }
 
 

From cf498adbe68c1b9d98432bee1fef6adec53926aa Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Mon, 17 Feb 2025 17:12:00 +0000
Subject: [PATCH 05/13] list more protocol changes

---
 docs/protocol-changes.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/protocol-changes.rst b/docs/protocol-changes.rst
index 78a6151..10c8ace 100644
--- a/docs/protocol-changes.rst
+++ b/docs/protocol-changes.rst
@@ -204,6 +204,13 @@ Changes
   * Optional *mode* argument added to :func:`blockchain.estimatefee`.
   * :func:`blockchain.block.headers` now returns headers as a list,
     instead of a single concatenated hex string.
+  * Support for *cp_height* in :func:`blockchain.block.header` and
+    :func:`blockchain.block.headers` has been made optional.
+  * Support for :const:`verbose=true` in :func:`blockchain.transaction.get`
+    has been made optional.
+  * :func:`server.features` now has a new mandatory field, *method_flavours*,
+    which aims to provide some clarity re whether the server supports optional features.
+
 
 New methods
 -----------

From daab1a7eb5a734f35b8b47976a882bb30ab82d67 Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Mon, 17 Feb 2025 18:45:11 +0000
Subject: [PATCH 06/13] re-design "server.ping", to be used against traffic
 analysis

---
 docs/protocol-changes.rst |  2 +
 docs/protocol-methods.rst | 92 +++++++++++++++++++++++++++++++++++++--
 2 files changed, 91 insertions(+), 3 deletions(-)

diff --git a/docs/protocol-changes.rst b/docs/protocol-changes.rst
index 10c8ace..031ff54 100644
--- a/docs/protocol-changes.rst
+++ b/docs/protocol-changes.rst
@@ -210,6 +210,8 @@ Changes
     has been made optional.
   * :func:`server.features` now has a new mandatory field, *method_flavours*,
     which aims to provide some clarity re whether the server supports optional features.
+  * :func:`server.ping` can now be sent by both the client and the server, and both
+    parties must handle and respond to it. The request/response signature also changed.
 
 
 New methods
diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index 9061986..1857021 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -1305,18 +1305,104 @@ subscription and the server must send no notifications.
 server.ping
 ===========
 
-Ping the server to ensure it is responding, and to keep the session
+Ping the remote to ensure it is responding, and to keep the session
 alive.  The server may disconnect clients that have sent no requests
 for roughly 10 minutes.
 
+Besides keeping the TCP connection alive, this can also be used
+to obfuscate traffic patterns.
+
+  **Note** This method is special, in that it is symmetric: both the client and
+  the server are allowed to send it, and both MUST support receiving it
+  and responding to it.
+
 **Signature**
 
-  .. function:: server.ping()
+  .. function:: server.ping(pong_len=0, data="")
   .. versionadded:: 1.2
+  .. versionchanged:: 1.6
+     both parties are now allowed to send this
+     and significant changes to signature/fields
+
+  * *pong_len*
+
+    The number of hex characters the other party should send in the *data* part of the response.
+    A non-negative integer, or :const:`-1`.
+    A value of :const:`-1` means the other party is asked not to respond. (This can be useful
+    against traffic analysis)
+
+  * *data*
+
+    A hexadecimal string. Its value is to be ignored by the recipient.
 
 **Result**
 
-  Returns :const:`null`.
+  A dictionary with the following keys:
+
+  * *data*
+
+    A hexadecimal string. Its value is to be ignored by the recipient.
+    However, the length MUST match the *pong_len* that was requested.
+
+
+**Note** Both *data* fields should support reasonably long strings, at least as long as
+would be needed to encode the largest consensus-valid transaction. No limits here
+would mean an easy DOS-vector and waste of bandwidth using *pong_len*. The client could
+already send or request transactions using other protocol methods, so limiting below that
+does not make sense.
+
+**Full JSON-RPC Examples**
+
+::
+
+  -> {
+    "jsonrpc": "2.0",
+    "id": 4,
+    "method": "server.ping",
+    "params": [0, "deadbeefdeadbeefdeadbeefdeadbeef"]
+  }
+  <- {
+    "jsonrpc": "2.0",
+    "result": {"data": ""},
+    "id": 4
+  }
+
+::
+
+  -> {
+    "jsonrpc": "2.0",
+    "id": 4,
+    "method": "server.ping",
+    "params": [5]
+  }
+  <- {
+    "jsonrpc": "2.0",
+    "result": {"data": "00000"},
+    "id": 4
+  }
+  <- {
+    "jsonrpc": "2.0",
+    "id": 7,
+    "method": "server.ping",
+    "params": [14, "0000000000000000000000000000000000000000000000000000000000000000"]
+  }
+  -> {
+    "jsonrpc": "2.0",
+    "result": {"data": "deadbeefdeadbe"},
+    "id": 7
+  }
+
+::
+
+  -> {
+    "jsonrpc": "2.0",
+    "id": 4,
+    "method": "server.ping",
+    "params": [-1, "deadbeefdeadbeefdeadbeefdeadbeef"]
+  }
+  (no response)
+
+
 
 server.version
 ==============

From a22b8b9ce8d3efc307624db25830d5da0f0d62f3 Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Wed, 26 Feb 2025 18:46:08 +0000
Subject: [PATCH 07/13] follow-up "server.ping": use notifications instead of
 pong_len=-1

---
 docs/protocol-methods.rst | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index 1857021..636080d 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -1312,9 +1312,17 @@ for roughly 10 minutes.
 Besides keeping the TCP connection alive, this can also be used
 to obfuscate traffic patterns.
 
+This method can be sent either as a JSON-RPC "Request" or as a JSON-RPC "Notification".
+If sent as a notification, the receiver is expected not to respond.
+This is useful to mimic the traffic pattern of a "useful" notification.
+
+Unlike with other methods, these notifications are not sent as a consequence of prior
+subscriptions. We simply abuse the JSON-RPC "Notification" mechanism to allow
+sending an "unrequested" message that does not warrant a response.
+
   **Note** This method is special, in that it is symmetric: both the client and
-  the server are allowed to send it, and both MUST support receiving it
-  and responding to it.
+  the server are allowed to send it (both as a request and as a notification),
+  and both MUST support receiving it and responding to it.
 
 **Signature**
 
@@ -1327,9 +1335,7 @@ to obfuscate traffic patterns.
   * *pong_len*
 
     The number of hex characters the other party should send in the *data* part of the response.
-    A non-negative integer, or :const:`-1`.
-    A value of :const:`-1` means the other party is asked not to respond. (This can be useful
-    against traffic analysis)
+    A non-negative integer.
 
   * *data*
 
@@ -1344,8 +1350,16 @@ to obfuscate traffic patterns.
     A hexadecimal string. Its value is to be ignored by the recipient.
     However, the length MUST match the *pong_len* that was requested.
 
+**Notifications**
+
+    .. function:: server.ping(data="")
+       :noindex:
 
-**Note** Both *data* fields should support reasonably long strings, at least as long as
+    * *data*
+
+      See **Result** above.
+
+**Note** The *data* fields should support reasonably long strings, at least as long as
 would be needed to encode the largest consensus-valid transaction. No limits here
 would mean an easy DOS-vector and waste of bandwidth using *pong_len*. The client could
 already send or request transactions using other protocol methods, so limiting below that
@@ -1396,11 +1410,10 @@ does not make sense.
 
   -> {
     "jsonrpc": "2.0",
-    "id": 4,
     "method": "server.ping",
-    "params": [-1, "deadbeefdeadbeefdeadbeefdeadbeef"]
+    "params": ["deadbeefdeadbeefdeadbeefdeadbeef"]
   }
-  (no response)
+  (No response. This was a notification.)
 
 
 

From 33d465218401242e8d1efa60d504b021e0b7b3aa Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Fri, 21 Feb 2025 15:03:29 +0000
Subject: [PATCH 08/13] add 'block_hash' field to 'transaction.get_merkle'

related: https://github.com/kyuupichan/electrumx/issues/385
---
 docs/protocol-changes.rst | 5 +++--
 docs/protocol-methods.rst | 6 ++++++
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/protocol-changes.rst b/docs/protocol-changes.rst
index 031ff54..ada391f 100644
--- a/docs/protocol-changes.rst
+++ b/docs/protocol-changes.rst
@@ -199,8 +199,9 @@ Changes
     defined for the calculation (previously their order was undefined).
   * :func:`blockchain.scripthash.get_mempool` previously did not define
     an order for mempool transactions. We now mandate a specific ordering.
-  * The previously required *height* argument for
-    :func:`blockchain.transaction.get_merkle` is now optional.
+  * For :func:`blockchain.transaction.get_merkle`, the previously required
+    *height* argument is now optional, and the result now includes a
+    *block_hash* field.
   * Optional *mode* argument added to :func:`blockchain.estimatefee`.
   * :func:`blockchain.block.headers` now returns headers as a list,
     instead of a single concatenated hex string.
diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index 636080d..a30e4d5 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -953,6 +953,7 @@ and height.
   .. function:: blockchain.transaction.get_merkle(tx_hash, height=None)
   .. versionchanged:: 1.6
      *height* argument made optional (previously mandatory)
+     added *block_hash* field to result
 
   *tx_hash*
 
@@ -971,6 +972,10 @@ and height.
 
     The height of the block the transaction was confirmed in.
 
+  * *block_hash*
+
+    The hash of the block the transaction was confirmed in, as a hexadecimal string.
+
   * *merkle*
 
     A list of transaction hashes the current hash is paired with,
@@ -1002,6 +1007,7 @@ and height.
       "2d64851151550e8c4d337f335ee28874401d55b358a66f1bafab2c3e9f48773d"
     ],
     "block_height": 450538,
+    "block_hash": "0000000000000000029bb9b476f1c66403a151f1da007470f8b9c1d9e4b9106d",
     "pos": 710
   }
 

From c4f87d9a695a296c57b8b3d34f6f9b43de547e20 Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Fri, 21 Feb 2025 16:40:12 +0000
Subject: [PATCH 09/13] use scriptPubKeys everywhere instead of scripthashes

related https://github.com/spesmilo/electrum-protocol/issues/3
---
 docs/protocol-basics.rst  |  28 +++++----
 docs/protocol-changes.rst |  20 +++++-
 docs/protocol-methods.rst | 124 +++++++++++++++++++-------------------
 3 files changed, 95 insertions(+), 77 deletions(-)

diff --git a/docs/protocol-basics.rst b/docs/protocol-basics.rst
index 623ba6c..1158864 100644
--- a/docs/protocol-basics.rst
+++ b/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,7 +93,7 @@ For example, the legacy Bitcoin address from the genesis block::
 
     1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
 
-has P2PKH script::
+has P2PKH script (scriptPubKey)::
 
     76a91462e907b15cbf27d5425399ebf6f0fb50ebb88f1888ac
 
@@ -101,11 +101,12 @@ 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::
@@ -113,7 +114,7 @@ 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.
 
diff --git a/docs/protocol-changes.rst b/docs/protocol-changes.rst
index ada391f..81b5e96 100644
--- a/docs/protocol-changes.rst
+++ b/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`
diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index a30e4d5..95a3b63 100644
--- a/docs/protocol-methods.rst
+++ b/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}

From 337b0063da51397d6cee9536d6e93c9c8c800344 Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Wed, 26 Feb 2025 18:17:51 +0000
Subject: [PATCH 10/13] (TODO) witness-spv

---
 docs/protocol-methods.rst | 83 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 3 deletions(-)

diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index 95a3b63..3cd4b2b 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -968,7 +968,10 @@ and height.
   *height*
 
     Optionally, the height at which it was confirmed, an integer.
-    Clients are encouraged to provide this field when they can, to reduce server load.
+    The server (especially lighter ones such as EPS/BWT) might require this parameter
+    to be able to serve the request, in which case the server must indicate so in its
+    :func:`server.features` response, by setting
+    `method_flavours["blockchain.transaction.get_merkle"]["requires_height"]=true`.
 
 **Result**
 
@@ -976,7 +979,7 @@ and height.
 
   * *block_height*
 
-    The height of the block the transaction was confirmed in.
+    The height of the block the transaction was confirmed in, an integer.
 
   * *block_hash*
 
@@ -991,7 +994,7 @@ and height.
   * *pos*
 
     The 0-based index of the position of the transaction in the
-    ordered list of transactions in the block.
+    ordered list of transactions in the block, an integer.
 
 **Result Example**
 
@@ -1017,6 +1020,80 @@ and height.
     "pos": 710
   }
 
+blockchain.transaction.get_merkle_witness
+=========================================
+
+Witness-SPV. Proves that a transaction with a given wtxid was mined in a particular block.
+
+**Signature**
+
+  .. function:: blockchain.transaction.get_merkle_witness(txid, height=None, cb=false)
+  .. versionadded:: 1.6
+
+  *txid*
+
+    The txid (NOT wtxid) as a hexadecimal string.
+
+  *height*
+
+    Optionally, the height at which it was confirmed, an integer.
+    The server (especially lighter ones such as EPS/BWT) might require this parameter
+    to be able to serve the request, in which case the server must indicate so in its
+    :func:`server.features` response, by setting
+    `method_flavours["blockchain.transaction.get_merkle"]["requires_height"]=true`.
+    (the flavour key `"blockchain.transaction.get_merkle"` is reused with the other merkle method).
+
+  *cb*
+
+    A boolean.
+    If set to :const:`true`, the result MUST also include the *cb_tx* and *cb_proof* fields.
+    If set to :const:`false`, those fields are omitted.
+
+**Result**
+
+  A dictionary with the following keys:
+
+  * *wtxid*
+
+    The wtxid of the mined transaction, as a hexadecimal string.
+
+  * *block_height*
+
+    The height of the block the transaction was confirmed in, an integer.
+
+  * *block_hash*
+
+    The hash of the block the transaction was confirmed in, as a hexadecimal string.
+
+  * *pos*
+
+    The 0-based index of the position of the transaction in the
+    ordered list of transactions in the block, an integer.
+
+  * *cb_tx*
+
+    The raw coinbase transaction from the block, as a hexadecimal string.
+
+  * *cb_proof*
+
+    Merkle branch to prove `cb_tx` (against block header merkle root).
+    A list of transaction hashes the current hash is paired with,
+    recursively, in order to trace up to obtain merkle root of the
+    block (in header), deepest pairing first.
+
+  * *wmerkle*
+
+    A witness merkle branch to prove `wtxid` (against `cb_tx`).
+    A list of hashes the current hash is paired with,
+    recursively, in order to trace up to obtain `witness root hash`
+    (committed to in the coinbase), deepest pairing first.
+
+**Result Example**
+
+::
+
+  TODO
+
 blockchain.transaction.id_from_pos
 ==================================
 

From 662a4d61953b2b6d8ee23148d3f7ce376135cef9 Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Tue, 17 Jun 2025 23:00:32 +0000
Subject: [PATCH 11/13] witness-spv is non-trivial

---
 docs/protocol-methods.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst
index 3cd4b2b..320f876 100644
--- a/docs/protocol-methods.rst
+++ b/docs/protocol-methods.rst
@@ -1087,6 +1087,19 @@ Witness-SPV. Proves that a transaction with a given wtxid was mined in a particu
     A list of hashes the current hash is paired with,
     recursively, in order to trace up to obtain `witness root hash`
     (committed to in the coinbase), deepest pairing first.
+    This field in the dict is present IFF the coinbase tx contains a witness commitment.
+    Note that even after segwit activation, if the block does not contain any segwit txs,
+    the witness commitment is optional.
+    Exactly one of the *wmerkle* and *merkle* keys are present.
+
+  * *merkle*
+
+    An old-style merkle branch to prove `txid` (against merkle root in block header).
+    Same format as in :func:`blockchain.transaction.get_merkle`.
+    This field in the dict is present IFF the coinbase tx does NOT contain a witness commitment.
+    Note that even after segwit activation, if the block does not contain any segwit txs,
+    the witness commitment is optional.
+    Exactly one of the *wmerkle* and *merkle* keys are present.
 
 **Result Example**
 

From 605de652dd5b23775265f38ebe4ae41a3d1e9b65 Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Fri, 25 Jul 2025 17:54:33 +0000
Subject: [PATCH 12/13] add section: buffer and pad msgs to protect against
 traffic analysis

---
 docs/protocol-basics.rst | 100 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/docs/protocol-basics.rst b/docs/protocol-basics.rst
index 1158864..8f74a3e 100644
--- a/docs/protocol-basics.rst
+++ b/docs/protocol-basics.rst
@@ -32,6 +32,9 @@ within strings, so no confusion is possible there.  However it does permit newli
 extraneous whitespace between elements; client and server MUST NOT use newlines in such a
 way.
 
+Messages SHOULD be :ref:`padded <padding_messages>` to bucketed lengths,
+and buffered (to introduce delays) to protect against traffic analysis.
+
 If using JSON RPC 2.0's feature of parameter passing by name, the
 names shown in the description of the method or notification in
 question MUST be used.
@@ -211,3 +214,100 @@ and confirm the returned roots match.
   implementation would require hashing approximately 88MB of data to
   provide a single merkle proof.  ElectrumX implements an optimization
   such that it hashes only approximately 180KB of data per proof.
+
+
+.. _padding_messages:
+
+Traffic analysis
+----------------
+
+The goal is to defend against a passive network Man-in-the-Middle, such as an ISP
+or a Tor exit node, observing the encrypted TLS stream, and making educated guesses
+of the message contents based on TCP packet flow: timing, direction, and sizes of TCP packets.
+
+.. note:: Raw cleartext TCP as transport for the JSON-RPC payloads is clearly out-of-scope here.
+  Without encryption, a passive network observer could just see all the plaintext messages anyway.
+
+As a generic mitigation, implementations (both client and server) SHOULD
+
+- pad messages to bucketed lengths (e.g. powers of 2, with a min size), and
+
+- introduce small timing delays, ideally by buffering messages.
+
+We can fully backwards-compatibly add padding to the JSON-RPC messages by adding extra
+whitespaces inside the JSON objects in a way that parsers ignore.
+This can be done at any protocol version.
+
+For example, instead of sending::
+
+  {"jsonrpc":"2.0","method":"server.version","id":0,"params":["electrum/4.5.8","1.4"]}\n
+
+
+the client could send::
+
+  {"jsonrpc":"2.0","method":"server.version","id":0,"params":["electrum/4.5.8","1.4"]           }\n
+
+
+For better results, both the client and the server SHOULD implement logic to pad the messages
+that they send. So that requests and responses (and notifications) SHOULD all be padded.
+This does not have to be rolled out simultaneously: it is ok for only a client to pad what
+they send and not the server (or the other way around),
+that just limits the effectiveness of the defense against traffic analysis.
+
+Note when the JSON-RPC messages are sent in the TLS stream, they are sometimes batched together.
+That is, a single TCP packet might contain multiple small JSON-RPC messages,
+e.g. if the client tries to send multiple messages in a short burst.
+Also, many protocol requests are <100 bytes, so it would be wasteful to pad all to e.g. 1 kbyte.
+
+To save bandwidth, instead of padding individual JSON-RPC messages,
+participants (the client and the server) COULD implement an application-level buffer,
+write the messages into that buffer, periodically empty the buffer into the TLS stream
+and only add the padding into e.g. the last JSON-RPC message when emptying the buffer.
+
+.. note:: Example implementation
+  in the `Electrum client <https://github.com/spesmilo/electrum/pull/9875>`_
+  and in the `electrumx server <https://github.com/spesmilo/electrumx/pull/301>`_:
+
+  Both the client and the server writes raw JSON-RPC protocol messages into a buffer,
+  which is then occasionally flushed to the wire. When it is flushed, padding is added
+  to round up the total length to 1 KB, or to the next power of 2.
+  The buffer is flushed if it reaches 1 KB, plus there is extra logic that periodically polls
+  if the oldest message in the buffer is older than 1 second, in which case it is also flushed.
+
+.. note:: Many protocol requests are <100 bytes. Contrast that with broadcasting a transaction,
+  which could potentially be several megabytes of data.
+  (max consensus-valid tx is 4 MB, times 2 for hex-encoding)
+  Hence padding to a constant size is not practical.
+  Instead it is recommended to pad to bucketed lengths, e.g. to powers of 2.
+
+The specific details of the size of the buffer, how often it is flushed, and how the padding
+is done is not specified by the protocol at the moment.
+
+.. note:: Some server implementations do not deal with TLS at all,
+  they only implement the raw cleartext TCP protocol, and just recommend operators
+  to put a reverse proxy in front that does TLS termination.
+  Such protocol implementations (both client and server) are nevertheless still
+  SHOULD implement all mentioned traffic analysis protections.
+  That way, if the operator tunnels the traffic over TLS externally,
+  the resulting stream meaningfully receives the protections.
+
+.. note:: Buffering the messages to introduce timing delays
+  and padding to ~bucketed sizes is a good baseline.
+  However even approximate timing and direction of TCP packets
+  can leak too much information in some scenarios.
+
+  To combat timing analysis, both the client and the server
+  COULD send noise with a random timer, but more importantly at strategically selected events.
+  For example, when the client receives a new block header notification,
+  it COULD probabilistically send a random number of "server.ping" messages
+  with small random sleeps in-between.
+
+  Protocol version 1.6 extends "server.ping" so that either party can send it, and
+  that it can be sent either as a JSON-RPC "Request" or as a JSON-RPC "Notification".
+  If sent as a notification, the receiver is expected not to respond.
+
+  When the server sends a block header notification to the client,
+  it COULD also probabilistically send noise ("server.ping") notifications to the client,
+  perhaps conditioned on whether it will also send
+  :func:`blockchain.scriptpubkey.subscribe` notifications.
+  (so server could send noise if there are no status notifications to be sent)

From 79113967cab8cf6ae7da1ae8b42d196b29832b5b Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Tue, 29 Jul 2025 15:05:09 +0000
Subject: [PATCH 13/13] traffic analysis: follow-ups

---
 docs/protocol-basics.rst | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/docs/protocol-basics.rst b/docs/protocol-basics.rst
index 8f74a3e..35a5082 100644
--- a/docs/protocol-basics.rst
+++ b/docs/protocol-basics.rst
@@ -225,8 +225,8 @@ The goal is to defend against a passive network Man-in-the-Middle, such as an IS
 or a Tor exit node, observing the encrypted TLS stream, and making educated guesses
 of the message contents based on TCP packet flow: timing, direction, and sizes of TCP packets.
 
-.. note:: Raw cleartext TCP as transport for the JSON-RPC payloads is clearly out-of-scope here.
-  Without encryption, a passive network observer could just see all the plaintext messages anyway.
+.. note:: When using raw cleartext TCP as transport for the JSON-RPC payloads, without encryption,
+  a passive network observer can see all the plaintext messages.
 
 As a generic mitigation, implementations (both client and server) SHOULD
 
@@ -273,6 +273,10 @@ and only add the padding into e.g. the last JSON-RPC message when emptying the b
   to round up the total length to 1 KB, or to the next power of 2.
   The buffer is flushed if it reaches 1 KB, plus there is extra logic that periodically polls
   if the oldest message in the buffer is older than 1 second, in which case it is also flushed.
+  The worst-case 1 second delay is a performance hit that might in cases be felt by the user.
+  This is a tradeoff to make the flow of packets harder to analyse for an observer.
+
+  Implementations COULD make the buffer size and the max time delay configurable.
 
 .. note:: Many protocol requests are <100 bytes. Contrast that with broadcasting a transaction,
   which could potentially be several megabytes of data.
@@ -281,23 +285,36 @@ and only add the padding into e.g. the last JSON-RPC message when emptying the b
   Instead it is recommended to pad to bucketed lengths, e.g. to powers of 2.
 
 The specific details of the size of the buffer, how often it is flushed, and how the padding
-is done is not specified by the protocol at the moment.
+is done is not specified by the protocol at the moment. Consequently, neither the client nor
+the server can enforce the other to pad and much less to delay messages.
 
 .. note:: Some server implementations do not deal with TLS at all,
   they only implement the raw cleartext TCP protocol, and just recommend operators
   to put a reverse proxy in front that does TLS termination.
-  Such protocol implementations (both client and server) are nevertheless still
+  Such protocol implementations (both client and server) nevertheless still
   SHOULD implement all mentioned traffic analysis protections.
   That way, if the operator tunnels the traffic over TLS externally,
   the resulting stream meaningfully receives the protections.
 
+.. note:: An alternative approach to the buffer-based delaying and padding
+  could be to more aggressively use JSON-RPC batching to batch messages, and to use the
+  optional Record Padding of
+  `TLS 1.3 <https://www.rfc-editor.org/rfc/rfc8446#section-5.4>`_.
+  See `SSL_CONF_cmd RecordPadding` in openssl. However this only allows
+  padding to multiples of a constant, while above the recommendation was to pad to powers of 2.
+  The implementation might still want to delay messages a bit
+  to accumulate them into a larger JSON-RPC batch. Also note if users
+  (e.g. server operators) are expected to do their own TLS termination
+  (e.g. using a reverse proxy), configuring TLS RecordPadding would become an externality
+  for them to do, which they might forget.
+
 .. note:: Buffering the messages to introduce timing delays
   and padding to ~bucketed sizes is a good baseline.
   However even approximate timing and direction of TCP packets
   can leak too much information in some scenarios.
 
   To combat timing analysis, both the client and the server
-  COULD send noise with a random timer, but more importantly at strategically selected events.
+  COULD send dummy RPCs with a random timer, but more importantly at strategically selected events.
   For example, when the client receives a new block header notification,
   it COULD probabilistically send a random number of "server.ping" messages
   with small random sleeps in-between.