From 70a8249de4753bd65e8a8a82381e43c4013cfc28 Mon Sep 17 00:00:00 2001 From: Sadman Pinon Date: Thu, 21 May 2026 05:14:14 -0400 Subject: [PATCH] Add zero-confirmation risk analysis --- devguide/payment_processing.rst | 47 ++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/devguide/payment_processing.rst b/devguide/payment_processing.rst index 8b759232..109cf545 100644 --- a/devguide/payment_processing.rst +++ b/devguide/payment_processing.rst @@ -229,6 +229,52 @@ Once the transaction is included in a block, double spends are impossible withou **6 confirmations**: The `network <../devguide/p2p_network.html>`__ has spent about an hour working to protect the transaction against double spends and the transaction is buried under six blocks. Even a reasonably lucky attacker would require a large percentage of the total `network <../devguide/p2p_network.html>`__ hashing power to replace six blocks. Although this number is somewhat arbitrary, software handling high-value transactions, or otherwise at risk for fraud, should wait for at least six confirmations before treating a payment as accepted. +Zero-Confirmation Risk Analysis +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A zero-confirmation payment is an unconfirmed transaction your program has +seen before any block has committed it. It can be useful for low-value +orders or for reducing checkout delay, but it is not a consensus result. A +transaction in a node's `memory pool <../devguide/p2p_network.html#memory-pool>`__ is only evidence +that the node accepted the transaction under its own relay and mining +policies. Other nodes may have different memory pools, may not have seen the +transaction yet, or may prefer a conflicting transaction. + +This distinction matters when evaluating double-spend risk. A +zero-confirmation double-spend attempt occurs when two unconfirmed +transactions spend at least one of the same UTXOs. Your program might see the +payment transaction first, a conflict first, both, or only one of them. A +chain-committed double spend occurs later if a block confirms a conflicting +transaction instead of the transaction your program treated as payment. Until +one transaction is confirmed, there is no network-wide final ordering between +the conflicts. + +Programs accepting unconfirmed payments should treat memory-pool monitoring as +risk evidence rather than proof of payment. Useful signals include whether +the transaction propagated to multiple well-connected peers, whether any peer +reports a conflicting spend, whether the transaction pays a fee rate likely to +be mined soon, and whether the spender is trusted for the value at risk. If a +conflict appears, if propagation is poor, or if the payment value is high, the +program should wait for one or more confirmations or require manual review. + +Low-fee transactions can also become stuck. Nodes may stop relaying them, +evict them from their memory pools, or leave them unconfirmed while miners +select higher-fee transactions. A spender can sometimes increase the fee with +replace by fee (RBF), and a receiver can sometimes create a child transaction +that pays for its parent (CPFP), but these techniques change mining incentives +rather than creating instant finality. Applications should keep invoices open +only for an appropriate time, continue monitoring for conflicts, and handle +expiration, refund, or support workflows for transactions that do not confirm. + +Time locks can constrain some protocols but do not make ordinary +zero-confirmation payments final. ``OP_CHECKLOCKTIMEVERIFY`` (CLTV) and +``OP_CHECKSEQUENCEVERIFY`` (CSV) can require a spending path to wait until a +height, time, or relative delay before it becomes valid. These rules are +useful in contracts such as payment channels and refund paths because they +limit when particular alternatives can be confirmed. They do not create +instantaneous consensus about which unconfirmed transaction will be mined, so +a receiver still needs a policy for waiting, monitoring, or limiting risk. + Bitcoin Core provides several `RPCs <../reference/rpc/index.html>`__ which can provide your program with the confirmation score for transactions in your wallet or arbitrary transactions. For example, the `“listunspent” RPC <../reference/rpc/listunspent.html>`__ provides an array of every satoshi you can spend along with its confirmation score. Although confirmations provide excellent double-spend protection most of the time, there are at least three cases where double-spend risk analysis can be required: @@ -347,4 +393,3 @@ Non-automated rebilling can be managed by the same mechanism used before credit- In the future, extensions to the payment protocol and new wallet features may allow some wallet programs to manage a list of recurring transactions. The spender will still need to start the program on a regular basis and authorize payment—but it should be easier and more secure for the spender than clicking an emailed invoice, increasing the chance receivers get paid on time. .. |Warning icon| image:: /img/icons/icon_warning.svg -