Skip to content

Commit 8d6f348

Browse files
committed
protocol docs: add more notes to blockchain.outpoint.subscribe
1 parent 6297989 commit 8d6f348

File tree

1 file changed

+14
-3
lines changed

1 file changed

+14
-3
lines changed

docs/protocol-methods.rst

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -667,9 +667,20 @@ as an input (spends it).
667667
**Notifications**
668668

669669
The client will receive a notification when the `status` of the outpoint changes.
670-
The protocol does not guarantee but the client might also receive a notification
671-
if the status does not change but there was a reorg.
672-
Its signature is
670+
That is, any event that changes any field of the `status` dictionary results in a
671+
notification. Some examples:
672+
673+
* a funding/spending tx appearing in the mempool if there was no such tx when the client subbed
674+
* funding/spending tx height changing from -1 to 0 as its inputs got mined
675+
* funding/spending tx height changing from 0 to a (positive) block height when it gets mined
676+
* note that reorgs can change any of the `status` fields and result in notifications
677+
* note that mempool replacement (e.g. due to RBF) or mempool eviction (and potentially other
678+
mempool quirks) can also change some of the `status` fields and hence result in notifications
679+
680+
The client MAY receive a notification even if the status did not change
681+
(when e.g. there was a reorg changing the blockhash the tx is mined in but not the height).
682+
683+
The signature of the notification is
673684

674685
.. function:: blockchain.outpoint.subscribe([tx_hash, txout_idx], status)
675686
:noindex:

0 commit comments

Comments
 (0)