Skip to content

Commit c0a6ddf

Browse files
committed
docs: describe protocol version 1.5
1 parent 6d7763a commit c0a6ddf

File tree

3 files changed

+302
-49
lines changed

3 files changed

+302
-49
lines changed

docs/protocol-basics.rst

+59-9
Original file line numberDiff line numberDiff line change
@@ -68,14 +68,12 @@ revision number.
6868

6969
A party to a connection will speak all protocol versions in a range,
7070
say from `protocol_min` to `protocol_max`, which may be the same.
71-
When a connection is made, both client and server must initially
72-
assume the protocol to use is their own `protocol_min`.
7371

74-
The client should send a :func:`server.version` RPC call as early as
75-
possible in order to negotiate the precise protocol version; see its
76-
description for more detail. All responses received in the stream
77-
from and including the server's response to this call will use its
78-
negotiated protocol version.
72+
The client must send a :func:`server.version` RPC call as the first
73+
message on the wire, in order to negotiate the precise protocol
74+
version; see its description for more detail.
75+
All responses received in the stream from and including the server's
76+
response to this call will use its negotiated protocol version.
7977

8078

8179
.. _script hashes:
@@ -138,8 +136,60 @@ block public key.
138136

139137
.. _status:
140138

141-
Status
142-
------
139+
Status (protocol 1.5 and later)
140+
-------------------------------
141+
142+
To calculate the `status` of a :ref:`script hash <script hashes>` (or
143+
address):
144+
145+
1. Consider all transactions touching the script hash (both those spending
146+
from it, and those funding it), both confirmed and unconfirmed (in mempool).
147+
148+
2. Order confirmed transactions by increasing height (and position in the
149+
block if there are more than one in a block).
150+
151+
3. For mempool transactions, we define **height** to be ``-1`` if the
152+
transaction has at least one unconfirmed input, and ``0`` if all inputs are
153+
confirmed.
154+
155+
4. Order mempool transactions by ``(-height, tx_hash)``, that is,
156+
``0`` height txs come before ``-1`` height txs, and secondarily the
157+
txid (in network byteorder) is used to arrive at a canonical ordering.
158+
159+
5. For each confirmed tx, form a bytearray: ``tx_hash+height``, where:
160+
161+
* ``tx_hash`` is the 32-byte transaction hash in network byteorder
162+
(reverse of human display endianness)
163+
164+
* ``height`` is the height of the block the tx is included in,
165+
serialised as 8-bytes, little-endian, signed (two's complement)
166+
167+
6. For each mempool tx, form a bytearray: ``tx_hash+height+fee``, where:
168+
169+
* ``tx_hash`` is the 32-byte transaction hash in network byteorder
170+
(reverse of human display endianness)
171+
172+
* ``height`` is either ``0`` or ``-1``, as defined above,
173+
serialised as 8-bytes, little-endian, signed (two's complement)
174+
175+
* ``fee`` is the transaction fee in minimum coin units (satoshis),
176+
serialised as 8-bytes, little-endian, unsigned
177+
178+
7. The :dfn:`status` of the script hash is defined by the following recursion:
179+
180+
* ``status_0`` is 32 zero bytes
181+
182+
* ``status_n`` is calculated as ``sha256(status_(n-1) + tx_n)``
183+
184+
That is, for a script hash with an empty history, the status is ``status_0``.
185+
If the history contains ``n`` txs, the status is ``status_n``. The ``tx_n``
186+
series consists of, first the confirmed txs touching the script hash,
187+
followed by the mempool txs touching it; formatted as described above, as
188+
bytearrays of length 40 or 48.
189+
190+
191+
Old Status (before protocol 1.5)
192+
--------------------------------
143193

144194
To calculate the `status` of a :ref:`script hash <script hashes>` (or
145195
address):

docs/protocol-changes.rst

+32-3
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Protocol Changes
33
================
44

5-
This documents lists changes made by protocol version.
5+
This document lists changes made by protocol version.
66

77
Version 1.0
88
===========
@@ -159,10 +159,39 @@ Changes
159159
Non-AuxPoW chains are unaffected.
160160

161161

162-
Version 1.4.1
162+
Version 1.4.2
163163
=============
164164

165165
New methods
166166
-----------
167167

168-
* :func:`blockchain.scipthash.unsubscribe` to unsubscribe from a script hash.
168+
* :func:`blockchain.scripthash.unsubscribe` to unsubscribe from a script hash.
169+
170+
.. _version 1.5:
171+
172+
Version 1.5
173+
===========
174+
175+
Changes
176+
-------
177+
178+
* Breaking change for the version negotiation: we now mandate that
179+
the :func:`server.version` message must be the first message sent.
180+
That is, version negotiation must happen before any other messages.
181+
* The status of a scripthash has been re-defined. The new definition is
182+
recursive and makes it possible not to redo all hashing for most
183+
updates.
184+
* :func:`blockchain.scripthash.get_history` changed significantly to
185+
allow pagination of long histories.
186+
* :func:`blockchain.scripthash.get_mempool` previously did not define
187+
an order for mempool transactions. We now mandate a specific ordering.
188+
* The previously required *height* argument for
189+
:func:`blockchain.transaction.get_merkle` is now optional.
190+
* Optional *mode* argument added to :func:`blockchain.estimatefee`.
191+
192+
New methods
193+
-----------
194+
195+
* :func:`blockchain.outpoint.subscribe` to subscribe to a transaction
196+
outpoint, and get a notification when it gets spent.
197+
* :func:`blockchain.outpoint.unsubscribe` to unsubscribe from a TXO.

0 commit comments

Comments
 (0)