From 4fd87d65da31ddc45cca1bad854936bc3a556360 Mon Sep 17 00:00:00 2001 From: softxp <503672447@qq.com> Date: Thu, 21 May 2026 21:50:23 +0800 Subject: [PATCH] Document zero-confirmation payment risks --- devguide/payment_processing.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/devguide/payment_processing.rst b/devguide/payment_processing.rst index 8b759232..441d6a12 100644 --- a/devguide/payment_processing.rst +++ b/devguide/payment_processing.rst @@ -223,6 +223,14 @@ Once the transaction is included in a block, double spends are impossible withou **0 confirmations**: The transaction has been broadcast but is still not included in any block. Zero confirmation transactions (unconfirmed transactions) should generally not be trusted without risk analysis. Although miners usually confirm the first transaction they receive, fraudsters may be able to manipulate the `network <../devguide/p2p_network.html>`__ into including their version of a transaction. +Accepting an unconfirmed payment is sometimes called accepting a zero-confirmation or zero-conf transaction. Zero-conf acceptance can be useful for small-value, time-sensitive purchases, but it is a policy decision made by the receiver rather than a guarantee provided by Bitcoin consensus. There is no network-wide mempool consensus: each node keeps its own `mempool <../devguide/p2p_network.html#transaction-broadcasting>`__ according to its local relay policy, fee filters, peers, uptime, and memory limits. A transaction appearing in your node's mempool, in a block explorer, or at several peers is evidence that it propagated, but it does not prove that all miners saw it, that it will be mined, or that a conflicting transaction does not exist elsewhere. + +The main zero-conf risk is that a spender can broadcast one transaction to the merchant and a conflicting transaction to miners or other peers. Before either transaction is included in a block, nodes may disagree about which transaction they saw first or which one their policy prefers. A low-fee transaction can also remain unconfirmed for a long time, be evicted from mempools, or be replaced by a higher-fee transaction when replacement policy allows it. Receivers who choose to accept zero-conf payments should treat them as provisional: check whether any input is already spent by another unconfirmed transaction, check whether the transaction opts in to replacement, compare its fee rate to current relay and confirmation conditions, limit the value accepted without confirmation, and pause automatic fulfilment if peers report conflicts. + +This is different from a double spend after confirmation. Once a transaction is in a block, replacing it requires replacing that block and every block built on top of it. That is why each confirmation increases the cost of a successful double spend. With zero confirmations, there is no confirmed history to replace; miners are still deciding which valid spend of the same inputs, if any, to include. + +Some contract protocols use absolute or relative timelocks, such as ``OP_CHECKLOCKTIMEVERIFY`` (CLTV) or ``OP_CHECKSEQUENCEVERIFY`` (CSV), to constrain when particular outputs can be spent. These constraints can reduce some risks in specialized protocols by making certain refund or settlement paths invalid until a height, time, or relative age has passed. They do not make an unrelated zero-conf payment final, and they do not prevent a spender from double spending the funding transaction before it confirms. + **1 confirmation**: The transaction is included in the latest block and double-spend risk decreases dramatically. Transactions which pay sufficient transaction fees need 10 minutes on average to receive one confirmation. However, the most recent block gets replaced fairly often by accident, so a double spend is still a real possibility. **2 confirmations**: The most recent block was chained to the block which includes the transaction. As of March 2014, two block replacements were exceedingly rare, and a two block replacement attack was impractical without expensive mining equipment.