From 6a71fbc9a39e48ced696973c7fad931f48ead18c Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Wed, 3 Sep 2025 14:52:04 +0200 Subject: [PATCH 01/17] start work adversarial-guide --- website/docs/guides/adversarial.md | 50 ++++++++++++++++++++++++++++++ website/sidebars.js | 3 +- 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 website/docs/guides/adversarial.md diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md new file mode 100644 index 00000000..24815303 --- /dev/null +++ b/website/docs/guides/adversarial.md @@ -0,0 +1,50 @@ +--- +title: Adversarial Analysis +sidebar_label: Adversarial Analysis +--- + +In this guide we'll focus on "adversarial analysis" of your smart contract system. Adversarial analysis means to analyze your system from the point of a potential malicious 3rd party which might want to hamper or attack your system. + +## Mempool and Block-Inclusion + +Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. Before transactions are included in a block they are waiting for inclusing in the mempool of the full nodes. + +Miners can choose which transactions to include in their block. Some miners might set a higher minimum fee or mine empty blocks so transactions can remain pending in the mempool even though a new block was mined. + +:::tip +In Bitcoin Cash it is standard for transactions to be included in very next mined block. Because there is no network congestion, +the mempool can get cleared with the arrivial of a new block. +::: + +Because transactions in the mempool are "seen" but not included in the blockchain yet, the latest state of the blockchain of who owns what is somewhat fuzzy. In some sense only the transaction with 6 confirmations are truly finalized but on the other hand in the normal scenario it's only a matter of time before transactions in the mempool get included in blocks and are 6 blocks deep in the blockchain. + +Where things get more complex however is if there are **competing unconfirmed transactions**. In this scenario it is **not** necessarily the case that a transaction is destined to be included in the blockchain. In other words, the latest state of the blockchain is still undecided. + +:::note +This is why many BCH indexers will allow you to query UTXOs with the option to include or exclude unconfirmed transactions. +::: + +## Unconfirmed Transaction Chains + +Unconfirmed transactions can be chained after one another meaning that even an output of an unconfirmed transaction can already be spent in a new transaction. This means you can have competing unconfirmed transaction **chains** where child transactions are chained to an unconfirmed parent. Any competing transaction for one of the parent tranactions then presents a cancellation of the whole chain of dependent child transactions. + +There is no maximum to the length of an unconfirmed transaction chain on BCH, software of full nodes has been upgraded to allow for arbitrary length unconfirmed tx chains. This is very important for public covenants which might have many users interacting and transacting with the same smart contract UTXO. + +:::tip +On Bitcoin Cash it is possible to design smart contract systems which utilize long unconfirmed transaction chain, avoiding the need for blockchain confirmations. However contract developers should keep in front of mind that a competing transaction chain can in effect "cancel" pending unconfirmed transactions. +::: + +## First-Seen Rule + +The "first-seen rule" is a a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. Because the first-seen rule is subjective based on time, different part of the network might enforce this rule for conflicting transactions in case of a race condition. + +:::note +In case of normal a P2PKH trasnaction this time window for race conditions is the risk window where it's beneficial to listen for double spends with [double-spend-proofs (DSPs)](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/). +::: + +Importantly, the "first-seen rule" is just a default and a network relay rule, advanced actors might send double-spend transactions with a sigificantly higher fee (bribe) to miners directly. Custom configured miners who actively maximize transaction fee revenue would accept the bribe transaction and switch off the "first-seen rule" altogether. However the majority of the Bitcoin Cash network will not relay such late double spend attempts in accordance with the first-seen rule. + +:::caution +On BTC the node default got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with oridinals. +::: + diff --git a/website/sidebars.js b/website/sidebars.js index a0e85883..f29522e2 100755 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -60,7 +60,8 @@ module.exports = { 'guides/infrastructure', 'guides/walletconnect', 'guides/debugging', - 'guides/optimization' + 'guides/optimization', + 'guides/adversarial', ], }, { From 95734fe28caeac2c68f53ee554a0e1b35c72c34f Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Wed, 3 Sep 2025 15:46:35 +0200 Subject: [PATCH 02/17] add sections on 'competing tx chains' and on MEV --- website/docs/guides/adversarial.md | 51 +++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 4 deletions(-) diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index 24815303..fe6a54f8 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -11,7 +11,7 @@ Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 min Miners can choose which transactions to include in their block. Some miners might set a higher minimum fee or mine empty blocks so transactions can remain pending in the mempool even though a new block was mined. -:::tip +:::note In Bitcoin Cash it is standard for transactions to be included in very next mined block. Because there is no network congestion, the mempool can get cleared with the arrivial of a new block. ::: @@ -20,8 +20,8 @@ Because transactions in the mempool are "seen" but not included in the blockchai Where things get more complex however is if there are **competing unconfirmed transactions**. In this scenario it is **not** necessarily the case that a transaction is destined to be included in the blockchain. In other words, the latest state of the blockchain is still undecided. -:::note -This is why many BCH indexers will allow you to query UTXOs with the option to include or exclude unconfirmed transactions. +:::tip +This is why many BCH indexers will allow you to query UTXOs with the option to include or exclude unconfirmed transactions. By default indexers will include unconfirmed UTXOs/unconfirmed transactions in the query result. ::: ## Unconfirmed Transaction Chains @@ -31,7 +31,23 @@ Unconfirmed transactions can be chained after one another meaning that even an o There is no maximum to the length of an unconfirmed transaction chain on BCH, software of full nodes has been upgraded to allow for arbitrary length unconfirmed tx chains. This is very important for public covenants which might have many users interacting and transacting with the same smart contract UTXO. :::tip -On Bitcoin Cash it is possible to design smart contract systems which utilize long unconfirmed transaction chain, avoiding the need for blockchain confirmations. However contract developers should keep in front of mind that a competing transaction chain can in effect "cancel" pending unconfirmed transactions. +On Bitcoin Cash it is possible to design smart contract systems which utilize long unconfirmed transaction chain, avoiding the need for blockchain confirmations. However contract developers should be mindful of the possibility of competing transaction chains. +::: + +## Competing Transactions + +When there are competing transactions (double spends) being propagated on the network, only one of the conflicting transactions can be included, the other transactions will in effect be cancelled. In the case of an unconfirmed transaction chain, any competing transaction for one of the tranactions in this newly formed chain then presents a cancellation of all child transactions dependent on this parent transaction with a conflict. + +:::note +Unlike on Ethereum, on Bitcoin Cash you can never have a transaction which has to pay fees but does not get included in the blockchain. Either it gets included and the fee is paid, or it's like it never happened. +::: + +In open contract systems competing transactions can happen organically and by accident, when 2 different users who might be on different sides of the world, interact with your on-chain system at roughly the same time. This situation can be called "UTXO contention" because 2 users simultaneously try to spend the same anyone-can-spend covenant. + +However, it is also possible double-spends are created intentioanlly. For example in the case of a DEX naively updating its price state, a rational economic actors might be incentivized to ignore the latest unconfirmed transaction chain and to **intentially** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. + +:::caution +Smart contract developers developing applications at scale should consider the game-theorethic interaction of advanced, rational economic actors who might benefit from competing against intead of cooparating on building a transaction chain. ::: ## First-Seen Rule @@ -48,3 +64,30 @@ Importantly, the "first-seen rule" is just a default and a network relay rule, a On BTC the node default got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with oridinals. ::: +## Miner-Extractable-Value (MEV) + +Miner-Extractable-Value (MEV) refers to the value (either in dollars or in BCH) which miners can "extract" by having the ability to decide transaction inclusion and the ability to prioritize or insert their own transactions in their new block. + +MEV works quite differently on a UTXO-model blockchain than on an account-based chain. So even if you are very familiar with the MEV meechanisms on Ethereum it will still be helpful to consider how they do - or do not - apply to Bitcoin Cash. + +:::note +On Ethereum they changed the acronym to mean "Maximum-Extractable-Value" because ETH is now a proof-of-stake system and does not have miners. The modified concept still applies to the ETH block producers. +::: + +The reason why block producers are better positioned than other economic actors such as on-chain traders or arbitrageurs is that they can priorize their own transactions even if conflicting transactions exist in the mempool. + +### Abandoning First-Seen + +As should be clear from the explenation higher up, the "first-seen rule" is just a convention and a way to play nice, however it is not per se economically maximizing. If we see more "bribe" double spends then we can expect over times that some miners will deflect from the covention and use custom transaction selection software to extract MEV from bribe transactions. + +### Bounty for Transaction Building + +A 1st source of potential MEV on Bitcoin Cash comes from smart contract systems which have a "bounty for transaction building" mechanism. Miners can automate the transaction building or possibly even modify an existing tansaction to claim the bounties for such a system. + +### Profitable DEX trades + +If DEXes don't cleverly aggregate their prices, then miners may be incentived to strategically create a competing transaction chain which takes advange of an older price state/ratio which has not yet been confirmed in the blockchain. + +### Not possible on UTXO + +What is not possible to do on UTXO chains is a "sandwich" strategy where a miner would insert a transaction in the middle of a valid transaction chain. In UTXO each transaction explicitly consumes inputs of a previous transaction and creates outputs. Because of this it is not possible to "insert" a transaction in the middle of an unconfirmed chain and thus sandwich strategies are not possible. From 09f1d91f93a25b81efdb10e66f87d2adc5348a55 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Wed, 3 Sep 2025 16:01:26 +0200 Subject: [PATCH 03/17] spelling fixes --- website/docs/guides/adversarial.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index fe6a54f8..fba87b3f 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -7,7 +7,7 @@ In this guide we'll focus on "adversarial analysis" of your smart contract syste ## Mempool and Block-Inclusion -Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. Before transactions are included in a block they are waiting for inclusing in the mempool of the full nodes. +Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. Before transactions are included in a block they are waiting for inclusion in the mempool of the full nodes. Miners can choose which transactions to include in their block. Some miners might set a higher minimum fee or mine empty blocks so transactions can remain pending in the mempool even though a new block was mined. @@ -26,7 +26,7 @@ This is why many BCH indexers will allow you to query UTXOs with the option to i ## Unconfirmed Transaction Chains -Unconfirmed transactions can be chained after one another meaning that even an output of an unconfirmed transaction can already be spent in a new transaction. This means you can have competing unconfirmed transaction **chains** where child transactions are chained to an unconfirmed parent. Any competing transaction for one of the parent tranactions then presents a cancellation of the whole chain of dependent child transactions. +Unconfirmed transactions can be chained after one another meaning that even an output of an unconfirmed transaction can already be spent in a new transaction. This means you can have competing unconfirmed transaction **chains** where child transactions are chained to an unconfirmed parent. Any competing transaction for one of the parent transactions then presents a cancellation of the whole chain of dependent child transactions. There is no maximum to the length of an unconfirmed transaction chain on BCH, software of full nodes has been upgraded to allow for arbitrary length unconfirmed tx chains. This is very important for public covenants which might have many users interacting and transacting with the same smart contract UTXO. @@ -36,7 +36,7 @@ On Bitcoin Cash it is possible to design smart contract systems which utilize lo ## Competing Transactions -When there are competing transactions (double spends) being propagated on the network, only one of the conflicting transactions can be included, the other transactions will in effect be cancelled. In the case of an unconfirmed transaction chain, any competing transaction for one of the tranactions in this newly formed chain then presents a cancellation of all child transactions dependent on this parent transaction with a conflict. +When there are competing transactions (double spends) being propagated on the network, only one of the conflicting transactions can be included, the other transactions will in effect be cancelled. In the case of an unconfirmed transaction chain, any competing transaction for one of the transactions in this newly formed chain then presents a cancellation of all child transactions dependent on this parent transaction with a conflict. :::note Unlike on Ethereum, on Bitcoin Cash you can never have a transaction which has to pay fees but does not get included in the blockchain. Either it gets included and the fee is paid, or it's like it never happened. @@ -44,10 +44,10 @@ Unlike on Ethereum, on Bitcoin Cash you can never have a transaction which has t In open contract systems competing transactions can happen organically and by accident, when 2 different users who might be on different sides of the world, interact with your on-chain system at roughly the same time. This situation can be called "UTXO contention" because 2 users simultaneously try to spend the same anyone-can-spend covenant. -However, it is also possible double-spends are created intentioanlly. For example in the case of a DEX naively updating its price state, a rational economic actors might be incentivized to ignore the latest unconfirmed transaction chain and to **intentially** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. +However, it is also possible double-spends are created intentionally. For example in the case of a DEX naively updating its price state, a rational economic actors might be incentivized to ignore the latest unconfirmed transaction chain and to **intentionally** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. :::caution -Smart contract developers developing applications at scale should consider the game-theorethic interaction of advanced, rational economic actors who might benefit from competing against intead of cooparating on building a transaction chain. +Smart contract developers developing applications at scale should consider the game-theoretic interaction of advanced, rational economic actors who might benefit from competing against intead of cooparating on building a transaction chain. ::: ## First-Seen Rule @@ -58,27 +58,27 @@ The "first-seen rule" is a a default mempool inclusion and relay rule for full n In case of normal a P2PKH trasnaction this time window for race conditions is the risk window where it's beneficial to listen for double spends with [double-spend-proofs (DSPs)](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/). ::: -Importantly, the "first-seen rule" is just a default and a network relay rule, advanced actors might send double-spend transactions with a sigificantly higher fee (bribe) to miners directly. Custom configured miners who actively maximize transaction fee revenue would accept the bribe transaction and switch off the "first-seen rule" altogether. However the majority of the Bitcoin Cash network will not relay such late double spend attempts in accordance with the first-seen rule. +Importantly, the "first-seen rule" is just a default and a network relay rule, advanced actors might send double-spend transactions with a significantly higher fee (bribe) to miners directly. Custom configured miners who actively maximize transaction fee revenue would accept the bribe transaction and switch off the "first-seen rule" altogether. However the majority of the Bitcoin Cash network will not relay such late double spend attempts in accordance with the first-seen rule. :::caution -On BTC the node default got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with oridinals. +On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with oridinals. ::: ## Miner-Extractable-Value (MEV) Miner-Extractable-Value (MEV) refers to the value (either in dollars or in BCH) which miners can "extract" by having the ability to decide transaction inclusion and the ability to prioritize or insert their own transactions in their new block. -MEV works quite differently on a UTXO-model blockchain than on an account-based chain. So even if you are very familiar with the MEV meechanisms on Ethereum it will still be helpful to consider how they do - or do not - apply to Bitcoin Cash. +MEV works quite differently on a UTXO-model blockchain than on an account-based chain. So even if you are very familiar with the MEV mechanisms on Ethereum it will still be helpful to consider how they do - or do not - apply to Bitcoin Cash. :::note -On Ethereum they changed the acronym to mean "Maximum-Extractable-Value" because ETH is now a proof-of-stake system and does not have miners. The modified concept still applies to the ETH block producers. +On Ethereum the acronym was changed to mean "Maximum-Extractable-Value" because ETH is now a proof-of-stake system and does not have miners. The modified concept still applies to the ETH block producers. ::: The reason why block producers are better positioned than other economic actors such as on-chain traders or arbitrageurs is that they can priorize their own transactions even if conflicting transactions exist in the mempool. ### Abandoning First-Seen -As should be clear from the explenation higher up, the "first-seen rule" is just a convention and a way to play nice, however it is not per se economically maximizing. If we see more "bribe" double spends then we can expect over times that some miners will deflect from the covention and use custom transaction selection software to extract MEV from bribe transactions. +As should be clear from the explanation higher up, the "first-seen rule" is just a convention and a way to play nice, however it is not per se economically maximizing. If we see more "bribe" double spends then we can expect over times that some miners will deflect from the covention and use custom transaction selection software to extract MEV from bribe transactions. ### Bounty for Transaction Building @@ -86,7 +86,7 @@ A 1st source of potential MEV on Bitcoin Cash comes from smart contract systems ### Profitable DEX trades -If DEXes don't cleverly aggregate their prices, then miners may be incentived to strategically create a competing transaction chain which takes advange of an older price state/ratio which has not yet been confirmed in the blockchain. +If DEXes don't cleverly aggregate their prices, then miners may be incentivized to strategically create a competing transaction chain which takes advange of an older price state/ratio which has not yet been confirmed in the blockchain. ### Not possible on UTXO From dcde821c53785af2352cd7e9ded1b03e74827a73 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Wed, 3 Sep 2025 16:12:28 +0200 Subject: [PATCH 04/17] add 'Transaction lifecycle' guide --- website/docs/guides/adversarial.md | 31 +------------- website/docs/guides/lifecycle.md | 65 ++++++++++++++++++++++++++++++ website/sidebars.js | 1 + 3 files changed, 67 insertions(+), 30 deletions(-) create mode 100644 website/docs/guides/lifecycle.md diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index fba87b3f..23d51474 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -5,35 +5,6 @@ sidebar_label: Adversarial Analysis In this guide we'll focus on "adversarial analysis" of your smart contract system. Adversarial analysis means to analyze your system from the point of a potential malicious 3rd party which might want to hamper or attack your system. -## Mempool and Block-Inclusion - -Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. Before transactions are included in a block they are waiting for inclusion in the mempool of the full nodes. - -Miners can choose which transactions to include in their block. Some miners might set a higher minimum fee or mine empty blocks so transactions can remain pending in the mempool even though a new block was mined. - -:::note -In Bitcoin Cash it is standard for transactions to be included in very next mined block. Because there is no network congestion, -the mempool can get cleared with the arrivial of a new block. -::: - -Because transactions in the mempool are "seen" but not included in the blockchain yet, the latest state of the blockchain of who owns what is somewhat fuzzy. In some sense only the transaction with 6 confirmations are truly finalized but on the other hand in the normal scenario it's only a matter of time before transactions in the mempool get included in blocks and are 6 blocks deep in the blockchain. - -Where things get more complex however is if there are **competing unconfirmed transactions**. In this scenario it is **not** necessarily the case that a transaction is destined to be included in the blockchain. In other words, the latest state of the blockchain is still undecided. - -:::tip -This is why many BCH indexers will allow you to query UTXOs with the option to include or exclude unconfirmed transactions. By default indexers will include unconfirmed UTXOs/unconfirmed transactions in the query result. -::: - -## Unconfirmed Transaction Chains - -Unconfirmed transactions can be chained after one another meaning that even an output of an unconfirmed transaction can already be spent in a new transaction. This means you can have competing unconfirmed transaction **chains** where child transactions are chained to an unconfirmed parent. Any competing transaction for one of the parent transactions then presents a cancellation of the whole chain of dependent child transactions. - -There is no maximum to the length of an unconfirmed transaction chain on BCH, software of full nodes has been upgraded to allow for arbitrary length unconfirmed tx chains. This is very important for public covenants which might have many users interacting and transacting with the same smart contract UTXO. - -:::tip -On Bitcoin Cash it is possible to design smart contract systems which utilize long unconfirmed transaction chain, avoiding the need for blockchain confirmations. However contract developers should be mindful of the possibility of competing transaction chains. -::: - ## Competing Transactions When there are competing transactions (double spends) being propagated on the network, only one of the conflicting transactions can be included, the other transactions will in effect be cancelled. In the case of an unconfirmed transaction chain, any competing transaction for one of the transactions in this newly formed chain then presents a cancellation of all child transactions dependent on this parent transaction with a conflict. @@ -55,7 +26,7 @@ Smart contract developers developing applications at scale should consider the g The "first-seen rule" is a a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. Because the first-seen rule is subjective based on time, different part of the network might enforce this rule for conflicting transactions in case of a race condition. :::note -In case of normal a P2PKH trasnaction this time window for race conditions is the risk window where it's beneficial to listen for double spends with [double-spend-proofs (DSPs)](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/). +In case of normal a P2PKH transaction this time window for race conditions is the risk window where it's beneficial to listen for double spends with [double-spend-proofs (DSPs)](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/). ::: Importantly, the "first-seen rule" is just a default and a network relay rule, advanced actors might send double-spend transactions with a significantly higher fee (bribe) to miners directly. Custom configured miners who actively maximize transaction fee revenue would accept the bribe transaction and switch off the "first-seen rule" altogether. However the majority of the Bitcoin Cash network will not relay such late double spend attempts in accordance with the first-seen rule. diff --git a/website/docs/guides/lifecycle.md b/website/docs/guides/lifecycle.md new file mode 100644 index 00000000..d7f03c9b --- /dev/null +++ b/website/docs/guides/lifecycle.md @@ -0,0 +1,65 @@ +--- +title: Transaction Lifecycle +sidebar_label: Transaction Lifecycle +--- + +This guide will explain the "transaction lifecycle" of a Bitcoin Cash transaction. We'll talk about what the mempool is and how block inclusion works. Further we'll dicuss the possibility of unconfirmed transaction chains and conflicting transactions to cover all the possibilities of the transaction lifecycle! + +## Mempool and Block-Inclusion + +Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. Before transactions are included in a block they are waiting for inclusion in the mempool of the full nodes. + +Miners can choose which transactions to include in their block. Some miners might set a higher minimum fee or mine empty blocks so transactions can remain pending in the mempool even though a new block was mined. + +:::note +In Bitcoin Cash it is standard for transactions to be included in very next mined block. Because there is no network congestion, +the mempool can get cleared with the arrivial of a new block. +::: + +Because transactions in the mempool are "seen" but not included in the blockchain yet, the latest state of the blockchain of who owns what is somewhat fuzzy. In some sense only the transaction with 6 confirmations are truly finalized but on the other hand in the normal scenario it's only a matter of time before transactions in the mempool get included in blocks and are 6 blocks deep in the blockchain. + +Where things get more complex however is if there are **competing unconfirmed transactions**. In this scenario it is **not** necessarily the case that a transaction is destined to be included in the blockchain. In other words, the latest state of the blockchain is still undecided. + +:::tip +This is why many BCH indexers will allow you to query UTXOs with the option to include or exclude unconfirmed transactions. By default indexers will include unconfirmed UTXOs/unconfirmed transactions in the query result. +::: + +## Unconfirmed Transaction Chains + +Unconfirmed transactions can be chained after one another meaning that even an output of an unconfirmed transaction can already be spent in a new transaction. This means you can have competing unconfirmed transaction **chains** where child transactions are chained to an unconfirmed parent. Any competing transaction for one of the parent transactions then presents a cancellation of the whole chain of dependent child transactions. + +There is no maximum to the length of an unconfirmed transaction chain on BCH, software of full nodes has been upgraded to allow for arbitrary length unconfirmed tx chains. This is very important for public covenants which might have many users interacting and transacting with the same smart contract UTXO. + +:::tip +On Bitcoin Cash it is possible to design smart contract systems which utilize long unconfirmed transaction chain, avoiding the need for blockchain confirmations. However contract developers should be mindful of the possibility of competing transaction chains. +::: + +## Competing Transactions + +When there are competing transactions (double spends) being propagated on the network, only one of the conflicting transactions can be included, the other transactions will in effect be cancelled. In the case of an unconfirmed transaction chain, any competing transaction for one of the transactions in this newly formed chain then presents a cancellation of all child transactions dependent on this parent transaction with a conflict. + +:::note +Unlike on Ethereum, on Bitcoin Cash you can never have a transaction which has to pay fees but does not get included in the blockchain. Either it gets included and the fee is paid, or it's like it never happened. +::: + +In open contract systems competing transactions can happen organically and by accident, when 2 different users who might be on different sides of the world, interact with your on-chain system at roughly the same time. This situation can be called "UTXO contention" because 2 users simultaneously try to spend the same anyone-can-spend covenant. + +However, it is also possible double-spends are created intentionally. For example in the case of a DEX naively updating its price state, a rational economic actors might be incentivized to ignore the latest unconfirmed transaction chain and to **intentionally** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. + +:::caution +Smart contract developers developing applications at scale should consider the game-theoretic interaction of advanced, rational economic actors who might benefit from competing against intead of cooparating on building a transaction chain. +::: + +## First-Seen Rule + +The "first-seen rule" is a a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. Because the first-seen rule is subjective based on time, different part of the network might enforce this rule for conflicting transactions in case of a race condition. + +:::note +In case of normal a P2PKH transaction this time window for race conditions is the risk window where it's beneficial to listen for double spends with [double-spend-proofs (DSPs)](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/). +::: + +Importantly, the "first-seen rule" is just a default and a network relay rule, advanced actors might send double-spend transactions with a significantly higher fee (bribe) to miners directly. Custom configured miners who actively maximize transaction fee revenue would accept the bribe transaction and switch off the "first-seen rule" altogether. However the majority of the Bitcoin Cash network will not relay such late double spend attempts in accordance with the first-seen rule. + +:::caution +On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with oridinals. +::: diff --git a/website/sidebars.js b/website/sidebars.js index f29522e2..d1c4b295 100755 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -56,6 +56,7 @@ module.exports = { label: 'Guides', items: [ 'guides/covenants', + 'guides/lifecycle', 'guides/cashtokens', 'guides/infrastructure', 'guides/walletconnect', From d4551923d3561394cc9717d2164729110dca9bf8 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Thu, 4 Sep 2025 08:06:08 +0200 Subject: [PATCH 05/17] spelling fixes --- website/docs/guides/adversarial.md | 16 ++++++++-------- website/docs/guides/lifecycle.md | 12 ++++++------ 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index 23d51474..ad7a07c3 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -15,15 +15,15 @@ Unlike on Ethereum, on Bitcoin Cash you can never have a transaction which has t In open contract systems competing transactions can happen organically and by accident, when 2 different users who might be on different sides of the world, interact with your on-chain system at roughly the same time. This situation can be called "UTXO contention" because 2 users simultaneously try to spend the same anyone-can-spend covenant. -However, it is also possible double-spends are created intentionally. For example in the case of a DEX naively updating its price state, a rational economic actors might be incentivized to ignore the latest unconfirmed transaction chain and to **intentionally** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. +However, it is also possible double-spends are created intentionally. For example in the case of a DEX naively updating its price state, a rational economic actor might be incentivized to ignore the latest unconfirmed transaction chain and to **intentionally** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. :::caution -Smart contract developers developing applications at scale should consider the game-theoretic interaction of advanced, rational economic actors who might benefit from competing against intead of cooparating on building a transaction chain. +Smart contract developers developing applications at scale should consider the game-theoretic interaction of advanced, rational economic actors who might benefit from competing against instead of cooperating on building a transaction chain. ::: ## First-Seen Rule -The "first-seen rule" is a a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. Because the first-seen rule is subjective based on time, different part of the network might enforce this rule for conflicting transactions in case of a race condition. +The "first-seen rule" is a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. Because the first-seen rule is subjective based on time, different part of the network might enforce this rule for conflicting transactions in case of a race condition. :::note In case of normal a P2PKH transaction this time window for race conditions is the risk window where it's beneficial to listen for double spends with [double-spend-proofs (DSPs)](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/). @@ -32,7 +32,7 @@ In case of normal a P2PKH transaction this time window for race conditions is th Importantly, the "first-seen rule" is just a default and a network relay rule, advanced actors might send double-spend transactions with a significantly higher fee (bribe) to miners directly. Custom configured miners who actively maximize transaction fee revenue would accept the bribe transaction and switch off the "first-seen rule" altogether. However the majority of the Bitcoin Cash network will not relay such late double spend attempts in accordance with the first-seen rule. :::caution -On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with oridinals. +On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with ordinals. ::: ## Miner-Extractable-Value (MEV) @@ -45,19 +45,19 @@ MEV works quite differently on a UTXO-model blockchain than on an account-based On Ethereum the acronym was changed to mean "Maximum-Extractable-Value" because ETH is now a proof-of-stake system and does not have miners. The modified concept still applies to the ETH block producers. ::: -The reason why block producers are better positioned than other economic actors such as on-chain traders or arbitrageurs is that they can priorize their own transactions even if conflicting transactions exist in the mempool. +The reason why block producers are better positioned than other economic actors such as on-chain traders or arbitrageurs is that they can prioritize their own transactions even if conflicting transactions exist in the mempool. ### Abandoning First-Seen -As should be clear from the explanation higher up, the "first-seen rule" is just a convention and a way to play nice, however it is not per se economically maximizing. If we see more "bribe" double spends then we can expect over times that some miners will deflect from the covention and use custom transaction selection software to extract MEV from bribe transactions. +As should be clear from the explanation higher up, the "first-seen rule" is just a convention and a way to play nice, however it is not per se economically maximizing. If we see more "bribe" double spends then we can expect over times that some miners will deflect from the convention and use custom transaction selection software to extract MEV from bribe transactions. ### Bounty for Transaction Building -A 1st source of potential MEV on Bitcoin Cash comes from smart contract systems which have a "bounty for transaction building" mechanism. Miners can automate the transaction building or possibly even modify an existing tansaction to claim the bounties for such a system. +A 1st source of potential MEV on Bitcoin Cash comes from smart contract systems which have a "bounty for transaction building" mechanism. Miners can automate the transaction building or possibly even modify an existing transaction to claim the bounties for such a system. ### Profitable DEX trades -If DEXes don't cleverly aggregate their prices, then miners may be incentivized to strategically create a competing transaction chain which takes advange of an older price state/ratio which has not yet been confirmed in the blockchain. +If DEXes don't cleverly aggregate their prices, then miners may be incentivized to strategically create a competing transaction chain which takes advantage of an older price state/ratio which has not yet been confirmed in the blockchain. ### Not possible on UTXO diff --git a/website/docs/guides/lifecycle.md b/website/docs/guides/lifecycle.md index d7f03c9b..3dbf64ec 100644 --- a/website/docs/guides/lifecycle.md +++ b/website/docs/guides/lifecycle.md @@ -3,7 +3,7 @@ title: Transaction Lifecycle sidebar_label: Transaction Lifecycle --- -This guide will explain the "transaction lifecycle" of a Bitcoin Cash transaction. We'll talk about what the mempool is and how block inclusion works. Further we'll dicuss the possibility of unconfirmed transaction chains and conflicting transactions to cover all the possibilities of the transaction lifecycle! +This guide will explain the "transaction lifecycle" of a Bitcoin Cash transaction. We'll talk about what the mempool is and how block inclusion works. Further we'll discuss the possibility of unconfirmed transaction chains and conflicting transactions to cover all the possibilities of the transaction lifecycle! ## Mempool and Block-Inclusion @@ -13,7 +13,7 @@ Miners can choose which transactions to include in their block. Some miners migh :::note In Bitcoin Cash it is standard for transactions to be included in very next mined block. Because there is no network congestion, -the mempool can get cleared with the arrivial of a new block. +the mempool can get cleared with the arrival of a new block. ::: Because transactions in the mempool are "seen" but not included in the blockchain yet, the latest state of the blockchain of who owns what is somewhat fuzzy. In some sense only the transaction with 6 confirmations are truly finalized but on the other hand in the normal scenario it's only a matter of time before transactions in the mempool get included in blocks and are 6 blocks deep in the blockchain. @@ -44,15 +44,15 @@ Unlike on Ethereum, on Bitcoin Cash you can never have a transaction which has t In open contract systems competing transactions can happen organically and by accident, when 2 different users who might be on different sides of the world, interact with your on-chain system at roughly the same time. This situation can be called "UTXO contention" because 2 users simultaneously try to spend the same anyone-can-spend covenant. -However, it is also possible double-spends are created intentionally. For example in the case of a DEX naively updating its price state, a rational economic actors might be incentivized to ignore the latest unconfirmed transaction chain and to **intentionally** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. +However, it is also possible double-spends are created intentionally. For example in the case of a DEX naively updating its price state, a rational economic actor might be incentivized to ignore the latest unconfirmed transaction chain and to **intentionally** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. :::caution -Smart contract developers developing applications at scale should consider the game-theoretic interaction of advanced, rational economic actors who might benefit from competing against intead of cooparating on building a transaction chain. +Smart contract developers developing applications at scale should consider the game-theoretic interaction of advanced, rational economic actors who might benefit from competing against instead of cooperating on building a transaction chain. ::: ## First-Seen Rule -The "first-seen rule" is a a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. Because the first-seen rule is subjective based on time, different part of the network might enforce this rule for conflicting transactions in case of a race condition. +The "first-seen rule" is a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. Because the first-seen rule is subjective based on time, different part of the network might enforce this rule for conflicting transactions in case of a race condition. :::note In case of normal a P2PKH transaction this time window for race conditions is the risk window where it's beneficial to listen for double spends with [double-spend-proofs (DSPs)](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/). @@ -61,5 +61,5 @@ In case of normal a P2PKH transaction this time window for race conditions is th Importantly, the "first-seen rule" is just a default and a network relay rule, advanced actors might send double-spend transactions with a significantly higher fee (bribe) to miners directly. Custom configured miners who actively maximize transaction fee revenue would accept the bribe transaction and switch off the "first-seen rule" altogether. However the majority of the Bitcoin Cash network will not relay such late double spend attempts in accordance with the first-seen rule. :::caution -On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with oridinals. +On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with ordinals. ::: From ece59cae181daef9d7d50112449677d033819923 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Thu, 4 Sep 2025 08:52:57 +0200 Subject: [PATCH 06/17] improve 'Transaction Lifecycle' docs --- website/docs/guides/lifecycle.md | 45 ++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/website/docs/guides/lifecycle.md b/website/docs/guides/lifecycle.md index 3dbf64ec..538cb2ab 100644 --- a/website/docs/guides/lifecycle.md +++ b/website/docs/guides/lifecycle.md @@ -5,18 +5,21 @@ sidebar_label: Transaction Lifecycle This guide will explain the "transaction lifecycle" of a Bitcoin Cash transaction. We'll talk about what the mempool is and how block inclusion works. Further we'll discuss the possibility of unconfirmed transaction chains and conflicting transactions to cover all the possibilities of the transaction lifecycle! -## Mempool and Block-Inclusion +## Block Inclusion -Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. Before transactions are included in a block they are waiting for inclusion in the mempool of the full nodes. +Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. On Bitcoin Cash it is standard for transactions to be included in the very next mined block. -Miners can choose which transactions to include in their block. Some miners might set a higher minimum fee or mine empty blocks so transactions can remain pending in the mempool even though a new block was mined. - -:::note -In Bitcoin Cash it is standard for transactions to be included in very next mined block. Because there is no network congestion, -the mempool can get cleared with the arrival of a new block. +:::tip +The minimum relay-fee for Bitcoin Cash transactions in 1 sat/byte, meaning a transaction with size 500 bytes has to pay at least 500 satoshis mining fee. ::: -Because transactions in the mempool are "seen" but not included in the blockchain yet, the latest state of the blockchain of who owns what is somewhat fuzzy. In some sense only the transaction with 6 confirmations are truly finalized but on the other hand in the normal scenario it's only a matter of time before transactions in the mempool get included in blocks and are 6 blocks deep in the blockchain. +Miners choose which transactions to include in their block. Some miners might set a higher minimum fee or mine empty blocks so transactions can remain pending in the mempool even though a new block was mined. Under normal circumstances, a 1 sat/byte fee rate will be included in the next block but this is not guaranteed. + +## Mempool + +Before transactions are included in a block they are waiting for block inclusion in the mempool of the full nodes. Because transactions in the mempool are "seen" but not included in the blockchain yet, the latest state of the blockchain of who owns what is somewhat fuzzy. + +In some sense only the transactions with 6 confirmations are truly finalized but on the other hand in the normal scenario it's only a matter of time before transactions in the mempool get included in blocks and are 6 blocks deep in the blockchain. Where things get more complex however is if there are **competing unconfirmed transactions**. In this scenario it is **not** necessarily the case that a transaction is destined to be included in the blockchain. In other words, the latest state of the blockchain is still undecided. @@ -24,6 +27,16 @@ Where things get more complex however is if there are **competing unconfirmed tr This is why many BCH indexers will allow you to query UTXOs with the option to include or exclude unconfirmed transactions. By default indexers will include unconfirmed UTXOs/unconfirmed transactions in the query result. ::: +## First-Seen Rule + +The "first-seen rule" is a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. The default relay policies on Bitcoin Cash have been designed in such a way to maximally enable "0-conf" transactions meaning transactions with zero confirmations but which can still be considered reasonably secure. + +:::note +On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become commonplace with ordinals. +::: + +The first-seen rule is subjective based on time, because of this different parts of the network might enforce this rule for conflicting transactions in case of a race condition. For P2PKH transactions a trustless notification system was developed called [double-spend-proofs](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/) (DSPs). However DSPs unfortunately do not work for smart contract transactions. + ## Unconfirmed Transaction Chains Unconfirmed transactions can be chained after one another meaning that even an output of an unconfirmed transaction can already be spent in a new transaction. This means you can have competing unconfirmed transaction **chains** where child transactions are chained to an unconfirmed parent. Any competing transaction for one of the parent transactions then presents a cancellation of the whole chain of dependent child transactions. @@ -31,7 +44,7 @@ Unconfirmed transactions can be chained after one another meaning that even an o There is no maximum to the length of an unconfirmed transaction chain on BCH, software of full nodes has been upgraded to allow for arbitrary length unconfirmed tx chains. This is very important for public covenants which might have many users interacting and transacting with the same smart contract UTXO. :::tip -On Bitcoin Cash it is possible to design smart contract systems which utilize long unconfirmed transaction chain, avoiding the need for blockchain confirmations. However contract developers should be mindful of the possibility of competing transaction chains. +On BCH it's possible to design smart contracts which use long unconfirmed transaction chains, avoiding the need to wait for blockchain confirmations. ::: ## Competing Transactions @@ -50,16 +63,8 @@ However, it is also possible double-spends are created intentionally. For exampl Smart contract developers developing applications at scale should consider the game-theoretic interaction of advanced, rational economic actors who might benefit from competing against instead of cooperating on building a transaction chain. ::: -## First-Seen Rule - -The "first-seen rule" is a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. Because the first-seen rule is subjective based on time, different part of the network might enforce this rule for conflicting transactions in case of a race condition. +## Adversarial Scenarios -:::note -In case of normal a P2PKH transaction this time window for race conditions is the risk window where it's beneficial to listen for double spends with [double-spend-proofs (DSPs)](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/). -::: - -Importantly, the "first-seen rule" is just a default and a network relay rule, advanced actors might send double-spend transactions with a significantly higher fee (bribe) to miners directly. Custom configured miners who actively maximize transaction fee revenue would accept the bribe transaction and switch off the "first-seen rule" altogether. However the majority of the Bitcoin Cash network will not relay such late double spend attempts in accordance with the first-seen rule. +This guide laid out the "transaction lifecycle" of a Bitcoin Cash transaction in general cases but it can be beneficial to specifically analyze how your smart contract system would hold up in adversarial scenarios. For an in depth guide on this more advanced topic, see [the adversarial analysis guide](/docs/guides/adversarial). -:::caution -On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with ordinals. -::: +Some examples are of adversarial scenarios include: what if the minimum relay fee increase? what if the "first-seen-rule" starts to break down? What if we start to see MEV on Bitcoin Cash? From 6ee8518fc353ca2f5a0e19a81641b39ac578b1d2 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Thu, 11 Sep 2025 10:02:40 +0200 Subject: [PATCH 07/17] add to vscode highlighting --- website/docs/language/syntax-highlighting.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/website/docs/language/syntax-highlighting.md b/website/docs/language/syntax-highlighting.md index 463eac55..810880b7 100644 --- a/website/docs/language/syntax-highlighting.md +++ b/website/docs/language/syntax-highlighting.md @@ -5,9 +5,17 @@ title: Syntax Highlighting When developing smart contracts for CashScript it is useful to have the proper syntax highlighting in your code editor / IDE. If you use Visual Studio Code, there is a dedicated CashScript extension. For other editors it is recommended to install a Solidity highlighting plugin and associate it with `.cash` files in your editor, since the syntaxes of the two languages are very similar. ## Visual Studio Code (Recommended) -For Visual Studio Code (and derived editors like Cursor) we have an official [CashScript extension](https://marketplace.visualstudio.com/items?itemName=CashScript.cashscript-vscode). This extension works with `.cash` files and supports syntax highlighting, autocompletion, snippets and linting. +For Visual Studio Code (and derived editors like Cursor) we have an official [CashScript extension](https://marketplace.visualstudio.com/items?itemName=CashScript.cashscript-vscode). This extension works with `.cash` files and supports syntax highlighting, autocompletion, snippets and linting. Because of the first-class CashScript support, Visual Studio Code with this CashScript extension is the recommended way to develop CashScript contracts. -Because of the first-class CashScript support, Visual Studio Code with this CashScript extension is the recommended way to develop CashScript contracts. +To have the extension automatically suggested for any developer looking at your CashScript contract in VScode, add the following configuration in a `.vscode/extensions.json` file: + +```json title="~/.vscode/extensions.json" +{ + "recommendations": [ + "cashscript.cashscript-vscode", + ] +} +``` ## Cursor From 71f9d4fba941b856b14f93b3010df2303cfee55f Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Thu, 11 Sep 2025 10:39:29 +0200 Subject: [PATCH 08/17] add section on 'Minimum Relay Fee' --- website/docs/compiler/script-limits.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/website/docs/compiler/script-limits.md b/website/docs/compiler/script-limits.md index d4548c95..3f0f747d 100644 --- a/website/docs/compiler/script-limits.md +++ b/website/docs/compiler/script-limits.md @@ -65,7 +65,7 @@ Bitcoin Cash allows multiple OP_RETURN outputs, but the total size of all data o Bitcoin Cash defines a "dust" threshold for output value. Outputs below this threshold are considered dust and will not be relayed by standard nodes. Provably unspendable outputs (OP_RETURN outputs) are exempt from this rule. -The dust threshold is calculated as: +The dust threshold for output value is calculated as: ```ts function calculateDust(outputSize: number): number { @@ -92,6 +92,10 @@ There's 4 types of standard output types: `P2PKH`, `P2SH` (which includes `P2SH2 The `lockingBytecode` standardness rules can be important for smart contract developers, and is why CashScript has helpers like `LockingBytecodeP2PKH`, `LockingBytecodeP2SH32` and `LockingBytecodeNullData`. ::: +### Minimum Relay Fee + +The Bitcoin Cash protocol does not strictly enforce minimum fees for transactions, minimum transaction fees are enforced as a standardness rule on the relay level. The minimum relay fee for BCH transactions is 1sat/byte (1000sats/kb). This is also the standard minimum fee set by most miners on the network. + ## Summary table | Limit type | Constraint | @@ -103,6 +107,7 @@ The `lockingBytecode` standardness rules can be important for smart contract dev | Max transaction size | 100,000 bytes for standardness (1MB for consensus) | | Max OP_RETURN data size | 220 bytes data payload (standardness) | | Dust threshold | based on output size (standardness) - commonly 1,000 sats is used as dust | +| Minimum relay fee | 1sat/byte (standardness) | | Output Standardness | `P2PKH`, `P2SH` (incl. `P2SH20` & `P2SH32`), `P2MS` and `OP_RETURN` data-outputs| For further details on transaction validation and standardness rules, see the [documentation on BCH transaction validation][standardness-docs]. From b7a05e81685cf80162d99c03bdf87ead0cf1f48e Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Thu, 11 Sep 2025 12:55:14 +0200 Subject: [PATCH 09/17] improve 'tx lifecylce' guide --- website/docs/guides/lifecycle.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/website/docs/guides/lifecycle.md b/website/docs/guides/lifecycle.md index 538cb2ab..0a3c4add 100644 --- a/website/docs/guides/lifecycle.md +++ b/website/docs/guides/lifecycle.md @@ -10,11 +10,15 @@ This guide will explain the "transaction lifecycle" of a Bitcoin Cash transactio Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. On Bitcoin Cash it is standard for transactions to be included in the very next mined block. :::tip -The minimum relay-fee for Bitcoin Cash transactions in 1 sat/byte, meaning a transaction with size 500 bytes has to pay at least 500 satoshis mining fee. +Commonly BCH miners are configured to accept transactions paying a minimum of 1 sat/byte, meaning a transaction of 500 bytes has to pay at least 500 satoshis in mining fee. ::: Miners choose which transactions to include in their block. Some miners might set a higher minimum fee or mine empty blocks so transactions can remain pending in the mempool even though a new block was mined. Under normal circumstances, a 1 sat/byte fee rate will be included in the next block but this is not guaranteed. +:::note +Even if a miner sets a higher minimum fee for inclusion in his own blocks, 1 sat/byte is the standard minimum fee for nodes to relay your transaction around the network. This way it will get into the mempool of nodes across the BCH network. +::: + ## Mempool Before transactions are included in a block they are waiting for block inclusion in the mempool of the full nodes. Because transactions in the mempool are "seen" but not included in the blockchain yet, the latest state of the blockchain of who owns what is somewhat fuzzy. @@ -55,16 +59,20 @@ When there are competing transactions (double spends) being propagated on the ne Unlike on Ethereum, on Bitcoin Cash you can never have a transaction which has to pay fees but does not get included in the blockchain. Either it gets included and the fee is paid, or it's like it never happened. ::: +### Accidental Race-Conditions + In open contract systems competing transactions can happen organically and by accident, when 2 different users who might be on different sides of the world, interact with your on-chain system at roughly the same time. This situation can be called "UTXO contention" because 2 users simultaneously try to spend the same anyone-can-spend covenant. +:::tip +To design around UTXO-contention it is smart to always create multiple duplicate UTXOs for public covenants. This way each of the UTXOs represents a distinct "thread" in a multi-threaded system enabling simultaneous interactions. +::: + +### Intentional Double-Spends + However, it is also possible double-spends are created intentionally. For example in the case of a DEX naively updating its price state, a rational economic actor might be incentivized to ignore the latest unconfirmed transaction chain and to **intentionally** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. :::caution Smart contract developers developing applications at scale should consider the game-theoretic interaction of advanced, rational economic actors who might benefit from competing against instead of cooperating on building a transaction chain. ::: -## Adversarial Scenarios - -This guide laid out the "transaction lifecycle" of a Bitcoin Cash transaction in general cases but it can be beneficial to specifically analyze how your smart contract system would hold up in adversarial scenarios. For an in depth guide on this more advanced topic, see [the adversarial analysis guide](/docs/guides/adversarial). - -Some examples are of adversarial scenarios include: what if the minimum relay fee increase? what if the "first-seen-rule" starts to break down? What if we start to see MEV on Bitcoin Cash? +Refer to [the adversarial analysis guide](/docs/guides/adversarial) for a more in-depth guide covering the adversarial cases of intentional double spends and miner bribes. From f11fd31c349d5eef2076aa03f500e89ea2507c34 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Thu, 11 Sep 2025 14:55:34 +0200 Subject: [PATCH 10/17] improve 'adversial' guide --- website/docs/guides/adversarial.md | 37 +++++++++++++++++++----------- website/docs/guides/lifecycle.md | 2 +- 2 files changed, 24 insertions(+), 15 deletions(-) diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index ad7a07c3..8ec46a8d 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -3,36 +3,45 @@ title: Adversarial Analysis sidebar_label: Adversarial Analysis --- -In this guide we'll focus on "adversarial analysis" of your smart contract system. Adversarial analysis means to analyze your system from the point of a potential malicious 3rd party which might want to hamper or attack your system. +In this guide we'll focus on "adversarial analysis" of your smart contract system. Adversarial analysis means to analyze your system from the point of a potential malicious 3rd party which might want to hamper or attack your system. This guide will build further on knowledge from the [the transaction lifecylce guide](/docs/guides/lifecylce). -## Competing Transactions +## The Happy Case -When there are competing transactions (double spends) being propagated on the network, only one of the conflicting transactions can be included, the other transactions will in effect be cancelled. In the case of an unconfirmed transaction chain, any competing transaction for one of the transactions in this newly formed chain then presents a cancellation of all child transactions dependent on this parent transaction with a conflict. +As long as all miners follow the first-seen rule then you can count on the idea that competing transaction chains can only occur due to accidental race conditions caused by simultaneous users. In the case of an attempted double spend, full nodes on the BCH network won't relay the transaction, and even if the transaction reaches the mempool of a miner, they would discard the transaction because of the first seen rule. -:::note -Unlike on Ethereum, on Bitcoin Cash you can never have a transaction which has to pay fees but does not get included in the blockchain. Either it gets included and the fee is paid, or it's like it never happened. +:::tip +The "happy case" scenario is currently the standard lifecylce for transactions on the Bitcoin Cash network, also for DeFi transactions interacting with on-chain DEXes. ::: -In open contract systems competing transactions can happen organically and by accident, when 2 different users who might be on different sides of the world, interact with your on-chain system at roughly the same time. This situation can be called "UTXO contention" because 2 users simultaneously try to spend the same anyone-can-spend covenant. +## Miner Bribes -However, it is also possible double-spends are created intentionally. For example in the case of a DEX naively updating its price state, a rational economic actor might be incentivized to ignore the latest unconfirmed transaction chain and to **intentionally** create a competing unconfirmed transaction chain. This way they can interact with the smart contract at an earlier (more advantageous) price. +Besides accidental race condition caused by simultaneous users, there can also be intentional double spends by adversarial actors. +In this case the adversarial attacker needs to convince the miners to abandon their first seen rule and to instead include the intentional double spend in their block. -:::caution -Smart contract developers developing applications at scale should consider the game-theoretic interaction of advanced, rational economic actors who might benefit from competing against instead of cooperating on building a transaction chain. +To convince the miners to include the double spend transaction instead of the original, the malicious attacker will include a signigicantly higher mining fee than the original transaction. This can be seen as a 'miner bribe' being paid to discard the first-seen rule and to accept the double spend instead of the original. + +:::note +Intentional double spends don't require a race condition, instead they only require that the original transaction is still in the mempool and that the double spend transaction reaches the mempool of miners/mining pools. ::: -## First-Seen Rule +We will now consider what motive the adversarial actor might have to perform these bribes. The two classes of motives are either the profit motive for an economically motivated actor or causing on-chain disruption for a maliciouly motivated actor. -The "first-seen rule" is a default mempool inclusion and relay rule for full nodes which says that for any UTXO the first seen spending transaction is the one that gets included in the node's mempool and relayed. Because the first-seen rule is subjective based on time, different part of the network might enforce this rule for conflicting transactions in case of a race condition. +### Extracting value from old state + +If DEXes don't cleverly aggregate their prices across blocks, then it can be economical for adversarial actors to instead of building on the latest transaction in the uncofirmed transaction chain of a smart contract, to instead create a competing transaction chain building on an older state. By strategically creating a competing transaction chain they might be able to take advantage of an older price state/ratio which has not yet been confirmed in the blockchain. + +Because having a more advantegous (older) price state or ratio might be very profitable, it is worth it for the adversarial actor to pay the high fee "miner bribe" to attempt this double spend transaction. :::note -In case of normal a P2PKH transaction this time window for race conditions is the risk window where it's beneficial to listen for double spends with [double-spend-proofs (DSPs)](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/). +Attempting a double spend in this way does not incur risk to the adversarial party, either their transaction is not included and they don't pay any fee, or they succesfully perform the double spend and they pay the high fee "miner bribe". ::: -Importantly, the "first-seen rule" is just a default and a network relay rule, advanced actors might send double-spend transactions with a significantly higher fee (bribe) to miners directly. Custom configured miners who actively maximize transaction fee revenue would accept the bribe transaction and switch off the "first-seen rule" altogether. However the majority of the Bitcoin Cash network will not relay such late double spend attempts in accordance with the first-seen rule. +### Griefing users + +When a late double-spend does make it into a block instead of the first seen relayed transaction, the original transactions will in effect be cancelled. In the case of an unconfirmed transaction chain, any competing transaction for one of the the chained unconfirmed transactions then presents a cancellation of the whole chain of dependent child transactions. :::caution -On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become common place with ordinals. +This means that in adverserial environments user created transactions on public covenants are not certain to be confirmed so waiting for block confirmations is required to be sure the transaction isn't cancelled in this way. ::: ## Miner-Extractable-Value (MEV) diff --git a/website/docs/guides/lifecycle.md b/website/docs/guides/lifecycle.md index 0a3c4add..c39ed8a3 100644 --- a/website/docs/guides/lifecycle.md +++ b/website/docs/guides/lifecycle.md @@ -43,7 +43,7 @@ The first-seen rule is subjective based on time, because of this different parts ## Unconfirmed Transaction Chains -Unconfirmed transactions can be chained after one another meaning that even an output of an unconfirmed transaction can already be spent in a new transaction. This means you can have competing unconfirmed transaction **chains** where child transactions are chained to an unconfirmed parent. Any competing transaction for one of the parent transactions then presents a cancellation of the whole chain of dependent child transactions. +Unconfirmed transactions can be chained after one another meaning that even an output of an unconfirmed transaction can already be spent in a new transaction. This means you can have competing unconfirmed transaction **chains** where child transactions are chained to an unconfirmed parent. A competing transaction for any of the chained unconfirmed transactions then presents a cancellation of the whole chain of dependent child transactions. There is no maximum to the length of an unconfirmed transaction chain on BCH, software of full nodes has been upgraded to allow for arbitrary length unconfirmed tx chains. This is very important for public covenants which might have many users interacting and transacting with the same smart contract UTXO. From 318682ae60ac5d80e613a9d8065ce02bba307114 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Thu, 11 Sep 2025 14:59:51 +0200 Subject: [PATCH 11/17] spelling fixes to the adversial guide --- website/docs/guides/adversarial.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index 8ec46a8d..ffa595d5 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -3,14 +3,14 @@ title: Adversarial Analysis sidebar_label: Adversarial Analysis --- -In this guide we'll focus on "adversarial analysis" of your smart contract system. Adversarial analysis means to analyze your system from the point of a potential malicious 3rd party which might want to hamper or attack your system. This guide will build further on knowledge from the [the transaction lifecylce guide](/docs/guides/lifecylce). +In this guide we'll dive into "adversarial analysis" for smart contract systems. Adversarial analysis means to analyze your system from the point of a potential malicious 3rd party which might want to hamper or attack your system. This guide will build further on knowledge from the [the transaction lifecycle guide](/docs/guides/lifecycle). ## The Happy Case -As long as all miners follow the first-seen rule then you can count on the idea that competing transaction chains can only occur due to accidental race conditions caused by simultaneous users. In the case of an attempted double spend, full nodes on the BCH network won't relay the transaction, and even if the transaction reaches the mempool of a miner, they would discard the transaction because of the first seen rule. +As long as all Bitcoin Cash miners follow the first-seen rule then you can count on the idea that competing transaction chains can only occur due to accidental race conditions caused by simultaneous users. In the case of an attempted double spend, full nodes on the BCH network won't relay the transaction, and even if the transaction reaches the mempool of a miner, they would discard the transaction because of the first seen rule. :::tip -The "happy case" scenario is currently the standard lifecylce for transactions on the Bitcoin Cash network, also for DeFi transactions interacting with on-chain DEXes. +The "happy case" scenario is currently the standard lifecycle for transactions on the Bitcoin Cash network, also for DeFi transactions interacting with on-chain DEXes. ::: ## Miner Bribes @@ -18,22 +18,22 @@ The "happy case" scenario is currently the standard lifecylce for transactions o Besides accidental race condition caused by simultaneous users, there can also be intentional double spends by adversarial actors. In this case the adversarial attacker needs to convince the miners to abandon their first seen rule and to instead include the intentional double spend in their block. -To convince the miners to include the double spend transaction instead of the original, the malicious attacker will include a signigicantly higher mining fee than the original transaction. This can be seen as a 'miner bribe' being paid to discard the first-seen rule and to accept the double spend instead of the original. +To convince the miners to include the double spend transaction instead of the original, the malicious attacker will include a significantly higher mining fee than the original transaction. This can be seen as a 'miner bribe' being paid to discard the first-seen rule and to accept the double spend instead of the original. :::note Intentional double spends don't require a race condition, instead they only require that the original transaction is still in the mempool and that the double spend transaction reaches the mempool of miners/mining pools. ::: -We will now consider what motive the adversarial actor might have to perform these bribes. The two classes of motives are either the profit motive for an economically motivated actor or causing on-chain disruption for a maliciouly motivated actor. +We will now consider what motive the adversarial actor might have to perform these bribes. The two classes of motives are either the profit motive for an economically motivated actor or causing on-chain disruption for a maliciously motivated actor. ### Extracting value from old state -If DEXes don't cleverly aggregate their prices across blocks, then it can be economical for adversarial actors to instead of building on the latest transaction in the uncofirmed transaction chain of a smart contract, to instead create a competing transaction chain building on an older state. By strategically creating a competing transaction chain they might be able to take advantage of an older price state/ratio which has not yet been confirmed in the blockchain. +If DEXes don't cleverly aggregate their prices across blocks, then it can be economical for adversarial actors to instead of building on the latest transaction in the unconfirmed transaction chain of a smart contract, to instead create a competing transaction chain building on an older state. By strategically creating a competing transaction chain they might be able to take advantage of an older price state/ratio which has not yet been confirmed in the blockchain. -Because having a more advantegous (older) price state or ratio might be very profitable, it is worth it for the adversarial actor to pay the high fee "miner bribe" to attempt this double spend transaction. +Because having a more advantageous (older) price state or ratio might be very profitable, it is worth it for the adversarial actor to pay the high fee "miner bribe" to attempt this double spend transaction. :::note -Attempting a double spend in this way does not incur risk to the adversarial party, either their transaction is not included and they don't pay any fee, or they succesfully perform the double spend and they pay the high fee "miner bribe". +Attempting a double spend in this way does not incur risk to the adversarial party, either their transaction is not included and they don't pay any fee, or they successfully perform the double spend and they pay the high fee "miner bribe". ::: ### Griefing users @@ -41,7 +41,7 @@ Attempting a double spend in this way does not incur risk to the adversarial par When a late double-spend does make it into a block instead of the first seen relayed transaction, the original transactions will in effect be cancelled. In the case of an unconfirmed transaction chain, any competing transaction for one of the the chained unconfirmed transactions then presents a cancellation of the whole chain of dependent child transactions. :::caution -This means that in adverserial environments user created transactions on public covenants are not certain to be confirmed so waiting for block confirmations is required to be sure the transaction isn't cancelled in this way. +This means that in adversarial environments user created transactions on public covenants are not certain to be confirmed so waiting for block confirmations is required to be sure the transaction isn't cancelled in this way. ::: ## Miner-Extractable-Value (MEV) From 0724c2b7e42682009d4054173a330a8d55d11e75 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Thu, 11 Sep 2025 15:30:39 +0200 Subject: [PATCH 12/17] add to adversial guide --- website/docs/guides/adversarial.md | 32 ++++++++++++++++++++++-------- website/docs/guides/lifecycle.md | 2 +- 2 files changed, 25 insertions(+), 9 deletions(-) diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index ffa595d5..439862a4 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -48,26 +48,42 @@ This means that in adversarial environments user created transactions on public Miner-Extractable-Value (MEV) refers to the value (either in dollars or in BCH) which miners can "extract" by having the ability to decide transaction inclusion and the ability to prioritize or insert their own transactions in their new block. -MEV works quite differently on a UTXO-model blockchain than on an account-based chain. So even if you are very familiar with the MEV mechanisms on Ethereum it will still be helpful to consider how they do - or do not - apply to Bitcoin Cash. - :::note On Ethereum the acronym was changed to mean "Maximum-Extractable-Value" because ETH is now a proof-of-stake system and does not have miners. The modified concept still applies to the ETH block producers. ::: +### MEV Differences from ETH + +MEV works quite differently on a UTXO-model blockchain than on an account-based chain. So even if you are very familiar with the MEV mechanisms on Ethereum it will still be helpful to consider how they do - or do not - apply to Bitcoin Cash. + +What is not possible to do on UTXO chains is a "sandwich" strategy where a miner would insert a transaction in the middle of a valid transaction chain. In UTXO each transaction explicitly consumes inputs of a previous transaction and creates outputs. Because of this it is not possible to "insert" a transaction in the middle of an unconfirmed chain and thus sandwich strategies are not possible. + +### The Power of Block Construction + The reason why block producers are better positioned than other economic actors such as on-chain traders or arbitrageurs is that they can prioritize their own transactions even if conflicting transactions exist in the mempool. +Other actors can construct double spend transactions will face great difficulty in getting their transaction to propagate and they have to pay high mining fees to bribe miners to accept the double spend over the original transaction. + +## Expected Evolution of MEV + +Below we will extend the adversarial analysis by extrapolating the evolution of MEV on Bitcoin cash based on the example of more mature DeFi ecosystems like Ethereum. + +:::tip +As mentioned at the start, the "happy case" scenario is currently the standard lifecycle for transactions on BCH. The analysis below is speculatively extrapolating how this could evolve in a mature DeFi ecosystem. +::: + ### Abandoning First-Seen As should be clear from the explanation higher up, the "first-seen rule" is just a convention and a way to play nice, however it is not per se economically maximizing. If we see more "bribe" double spends then we can expect over times that some miners will deflect from the convention and use custom transaction selection software to extract MEV from bribe transactions. -### Bounty for Transaction Building +Over time we can expect miners not just to prefer bribes when available but to actively build transactions to extract from or create value for DeFi protocols. -A 1st source of potential MEV on Bitcoin Cash comes from smart contract systems which have a "bounty for transaction building" mechanism. Miners can automate the transaction building or possibly even modify an existing transaction to claim the bounties for such a system. +### Miners Extracting Value -### Profitable DEX trades +As we mentioned before, if DEXes don't cleverly aggregate their prices, then miners may be incentivized to strategically create a competing transaction chain which takes advantage of an older price state/ratio which has not yet been confirmed in the blockchain. -If DEXes don't cleverly aggregate their prices, then miners may be incentivized to strategically create a competing transaction chain which takes advantage of an older price state/ratio which has not yet been confirmed in the blockchain. +Although miners are not specialists in the optimal construction of DeFi transactions in a block, miner would over time be likely to team up with teams/companies creating this type of software for them. We've already seen the emergence of a specialized 'block constructor' class for Ethereum. -### Not possible on UTXO +### Miners Providing Value -What is not possible to do on UTXO chains is a "sandwich" strategy where a miner would insert a transaction in the middle of a valid transaction chain. In UTXO each transaction explicitly consumes inputs of a previous transaction and creates outputs. Because of this it is not possible to "insert" a transaction in the middle of an unconfirmed chain and thus sandwich strategies are not possible. +A potential way in which miner transaction building can be seen as providing value is in the case of covenants using a 'Bounty for Transaction Building'. Here the value comes not from "extraction" but from smart contract with a mechanism paying a bounty for creating the transactions necessary for the operation of the contract system. diff --git a/website/docs/guides/lifecycle.md b/website/docs/guides/lifecycle.md index c39ed8a3..4d828279 100644 --- a/website/docs/guides/lifecycle.md +++ b/website/docs/guides/lifecycle.md @@ -7,7 +7,7 @@ This guide will explain the "transaction lifecycle" of a Bitcoin Cash transactio ## Block Inclusion -Bitcoin Cash has a blocktime of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. On Bitcoin Cash it is standard for transactions to be included in the very next mined block. +Bitcoin Cash has a block-time of 10 minutes, meaning that on average every 10 minutes a new block is found which adds a collection of transactions to the ledger. On Bitcoin Cash it is standard for transactions to be included in the very next mined block. :::tip Commonly BCH miners are configured to accept transactions paying a minimum of 1 sat/byte, meaning a transaction of 500 bytes has to pay at least 500 satoshis in mining fee. From 7292bdba06406b8bb73f294164999a96702fb3b2 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Sat, 13 Sep 2025 14:57:04 +0200 Subject: [PATCH 13/17] add info on Chain Reorgs --- website/docs/guides/lifecycle.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/website/docs/guides/lifecycle.md b/website/docs/guides/lifecycle.md index 4d828279..f50706ce 100644 --- a/website/docs/guides/lifecycle.md +++ b/website/docs/guides/lifecycle.md @@ -21,11 +21,9 @@ Even if a miner sets a higher minimum fee for inclusion in his own blocks, 1 sat ## Mempool -Before transactions are included in a block they are waiting for block inclusion in the mempool of the full nodes. Because transactions in the mempool are "seen" but not included in the blockchain yet, the latest state of the blockchain of who owns what is somewhat fuzzy. +Before transactions are included in a block they are waiting for block inclusion in the mempool of the full nodes. Because transactions in the mempool are "seen" but not included in the blockchain yet, the latest state of the blockchain of who owns what is somewhat fuzzy. -In some sense only the transactions with 6 confirmations are truly finalized but on the other hand in the normal scenario it's only a matter of time before transactions in the mempool get included in blocks and are 6 blocks deep in the blockchain. - -Where things get more complex however is if there are **competing unconfirmed transactions**. In this scenario it is **not** necessarily the case that a transaction is destined to be included in the blockchain. In other words, the latest state of the blockchain is still undecided. +In a normal scenario it's only a matter of time before a BCH transaction in the mempool gets included in a block. Where things get more complex however is if there are **competing unconfirmed transactions**. In this scenario it is **not** necessarily the clear that a transaction is destined to be included in the blockchain. In other words, the latest state of the blockchain is still undecided. :::tip This is why many BCH indexers will allow you to query UTXOs with the option to include or exclude unconfirmed transactions. By default indexers will include unconfirmed UTXOs/unconfirmed transactions in the query result. @@ -76,3 +74,19 @@ Smart contract developers developing applications at scale should consider the g ::: Refer to [the adversarial analysis guide](/docs/guides/adversarial) for a more in-depth guide covering the adversarial cases of intentional double spends and miner bribes. + +## Chain Reorgs + +A "Chain Reorganization" or reorg for short is when the full nodes discard the current chain tip of the blockchain and adopt a new longest chain. Because a chain reorg causes different blocks to be part of the canonical blockchain, it might be that different transactions got included than what was initially expected. + + +:::tip +A great resource to learn more details about reorgs is the ['Chain Reorganization'](https://learnmeabitcoin.com/technical/blockchain/chain-reorganization/) page on the info website learn-me-a-bitcoin. +::: + +:::note +2-block reorganisations are already super rare occurrences, so having 2+ confirmations is often enough for all practical purposes. +Many exchanges however use a 6-block confirmation policy for Bitcoin Cash deposits. +::: + +Chain reorgs don't always include all the same transactions, so some transactions can get un-included from the blockchain with a reorg. In this scenario, if no competing transaction was mined then the un-included transaction will just return to the mempool waiting for inclusion in a next block. From fc7e57be23aee1308f3e5a84ff9cf24a3cdeddbf Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Sat, 13 Sep 2025 16:18:04 +0200 Subject: [PATCH 14/17] add to adversarial guid --- website/docs/guides/adversarial.md | 47 ++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index 439862a4..ac6f49aa 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -13,20 +13,44 @@ As long as all Bitcoin Cash miners follow the first-seen rule then you can count The "happy case" scenario is currently the standard lifecycle for transactions on the Bitcoin Cash network, also for DeFi transactions interacting with on-chain DEXes. ::: -## Miner Bribes +## The Adversarial Case -Besides accidental race condition caused by simultaneous users, there can also be intentional double spends by adversarial actors. -In this case the adversarial attacker needs to convince the miners to abandon their first seen rule and to instead include the intentional double spend in their block. +The adversarial case is where 3rd parties intentionally double spend unconfirmed transactions in the contract system with the goal to extract value or to disrupt the experience for normal users. -To convince the miners to include the double spend transaction instead of the original, the malicious attacker will include a significantly higher mining fee than the original transaction. This can be seen as a 'miner bribe' being paid to discard the first-seen rule and to accept the double spend instead of the original. +:::caution +In an adversarial environment where double spends occur, user-created transactions interacting with public are not certain to be confirmed. This means waiting for block confirmations is required to be sure the transaction isn't cancelled. +::: + +There is 2 categories to consider for adversarial double spends: + +1) Race-condition double spends (no miner help required) + +2) Late double spends (miner help required) + +### Race-condition Double Spends + +The first scenario of race-condition double spends do not benefit the adversarial 3rd party, instead the goal would just be griefing: to disrupt the flow for normal users. The double spend can cause the user-transaction to be cancelled even though from the user point-of-view it already looked like the transaction went through and achieved its goal. + +:::note +For an adversarial attack to pull off this time-sensitive attack, he would require extensive monitoring on the p2p network and quickly be able to generate and broadcast competing double spend transactions. +::: + +### Late Double Spends + +In the case of an late double spend (which does not try to exploit a race condition) the adversarial actor need help from a miner. +Either the adversarial actor needs to convince the miners to abandon their first seen rule or he needs to be mining himself to be able to construct his own block. + +To convince existing miners to include the double spend transaction instead of the original, the malicious attacker will include a significantly higher mining fee than the original transaction. This can be seen as a 'miner bribe' being paid to discard the first-seen rule and to accept the double spend instead of the original. :::note -Intentional double spends don't require a race condition, instead they only require that the original transaction is still in the mempool and that the double spend transaction reaches the mempool of miners/mining pools. +Both race-condition and late double spends can both be used to grief the experience for normal users, however only late double spends can be used to extract economic value. ::: +## Economic Value Extraction + We will now consider what motive the adversarial actor might have to perform these bribes. The two classes of motives are either the profit motive for an economically motivated actor or causing on-chain disruption for a maliciously motivated actor. -### Extracting value from old state +### Stale-state arbitrage If DEXes don't cleverly aggregate their prices across blocks, then it can be economical for adversarial actors to instead of building on the latest transaction in the unconfirmed transaction chain of a smart contract, to instead create a competing transaction chain building on an older state. By strategically creating a competing transaction chain they might be able to take advantage of an older price state/ratio which has not yet been confirmed in the blockchain. @@ -36,13 +60,6 @@ Because having a more advantageous (older) price state or ratio might be very pr Attempting a double spend in this way does not incur risk to the adversarial party, either their transaction is not included and they don't pay any fee, or they successfully perform the double spend and they pay the high fee "miner bribe". ::: -### Griefing users - -When a late double-spend does make it into a block instead of the first seen relayed transaction, the original transactions will in effect be cancelled. In the case of an unconfirmed transaction chain, any competing transaction for one of the the chained unconfirmed transactions then presents a cancellation of the whole chain of dependent child transactions. - -:::caution -This means that in adversarial environments user created transactions on public covenants are not certain to be confirmed so waiting for block confirmations is required to be sure the transaction isn't cancelled in this way. -::: ## Miner-Extractable-Value (MEV) @@ -58,11 +75,11 @@ MEV works quite differently on a UTXO-model blockchain than on an account-based What is not possible to do on UTXO chains is a "sandwich" strategy where a miner would insert a transaction in the middle of a valid transaction chain. In UTXO each transaction explicitly consumes inputs of a previous transaction and creates outputs. Because of this it is not possible to "insert" a transaction in the middle of an unconfirmed chain and thus sandwich strategies are not possible. -### The Power of Block Construction +### Controlling Block-Construction The reason why block producers are better positioned than other economic actors such as on-chain traders or arbitrageurs is that they can prioritize their own transactions even if conflicting transactions exist in the mempool. -Other actors can construct double spend transactions will face great difficulty in getting their transaction to propagate and they have to pay high mining fees to bribe miners to accept the double spend over the original transaction. +Other actors who construct double spend transactions will face great difficulty in getting their transaction to propagate and in having to pay high mining fees to bribe miners to accept their double spend over the original transaction. ## Expected Evolution of MEV From b211b2c4e1ca2267f20358c21ce64b22dbb0f78e Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Sat, 13 Sep 2025 17:20:09 +0200 Subject: [PATCH 15/17] add to adversarial guide --- website/docs/guides/adversarial.md | 38 +++++++++++++++++++----------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index ac6f49aa..c94c3bd7 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -40,10 +40,14 @@ For an adversarial attack to pull off this time-sensitive attack, he would requi In the case of an late double spend (which does not try to exploit a race condition) the adversarial actor need help from a miner. Either the adversarial actor needs to convince the miners to abandon their first seen rule or he needs to be mining himself to be able to construct his own block. +:::caution +Both race-condition and late double spends can both be used to grief the experience for normal users, however only late double spends can be used to extract economic value. +::: + To convince existing miners to include the double spend transaction instead of the original, the malicious attacker will include a significantly higher mining fee than the original transaction. This can be seen as a 'miner bribe' being paid to discard the first-seen rule and to accept the double spend instead of the original. :::note -Both race-condition and late double spends can both be used to grief the experience for normal users, however only late double spends can be used to extract economic value. +Attempting a double spend in this way does not incur risk to the adversarial party, either their transaction is not included and they don't pay any fee, or they successfully perform the double spend and they pay the high fee "miner bribe". ::: ## Economic Value Extraction @@ -56,8 +60,8 @@ If DEXes don't cleverly aggregate their prices across blocks, then it can be eco Because having a more advantageous (older) price state or ratio might be very profitable, it is worth it for the adversarial actor to pay the high fee "miner bribe" to attempt this double spend transaction. -:::note -Attempting a double spend in this way does not incur risk to the adversarial party, either their transaction is not included and they don't pay any fee, or they successfully perform the double spend and they pay the high fee "miner bribe". +:::tip +We list some possible mitigations which smart contract systems can implement in the section on ['Avoiding MEV'](#avoiding-mev) ::: @@ -66,7 +70,7 @@ Attempting a double spend in this way does not incur risk to the adversarial par Miner-Extractable-Value (MEV) refers to the value (either in dollars or in BCH) which miners can "extract" by having the ability to decide transaction inclusion and the ability to prioritize or insert their own transactions in their new block. :::note -On Ethereum the acronym was changed to mean "Maximum-Extractable-Value" because ETH is now a proof-of-stake system and does not have miners. The modified concept still applies to the ETH block producers. +On Ethereum the acronym was changed to mean "Maximum-Extractable-Value" because ETH is now a proof-of-stake system and does not have miners. The modified concept still applies to the ETH block proposers (validators). ::: ### MEV Differences from ETH @@ -83,24 +87,30 @@ Other actors who construct double spend transactions will face great difficulty ## Expected Evolution of MEV -Below we will extend the adversarial analysis by extrapolating the evolution of MEV on Bitcoin cash based on the example of more mature DeFi ecosystems like Ethereum. +Below we will extend the adversarial analysis by extrapolating the evolution of MEV on Bitcoin cash based on the example of more mature DeFi ecosystems like Ethereum. As mentioned at the start, the "happy case" scenario is currently the standard lifecycle for transactions on BCH. The analysis below is speculatively extrapolating how this could evolve in a mature DeFi ecosystem. + +### Abandoning First-Seen + +If over time "bribe" double spends start happening on BCH then we can expect over time that some miners will deflect from the convention and use custom transaction selection software to extract MEV from bribe transactions. Over time we can expect miners not just to prefer bribes when available but to actively build transactions to extract from or create value for DeFi protocols. :::tip -As mentioned at the start, the "happy case" scenario is currently the standard lifecycle for transactions on BCH. The analysis below is speculatively extrapolating how this could evolve in a mature DeFi ecosystem. +Adversarial analysis should take into account that "first-seen rule" is just a convention and a way to play nice, however it is not economically maximizing when double spends include miner bribes. ::: -### Abandoning First-Seen +### Specialized Block-Builders + -As should be clear from the explanation higher up, the "first-seen rule" is just a convention and a way to play nice, however it is not per se economically maximizing. If we see more "bribe" double spends then we can expect over times that some miners will deflect from the convention and use custom transaction selection software to extract MEV from bribe transactions. +As described in the section on "stale-state arbitrage" economic actors ay be incentivized to strategically create a competing transaction chain which takes advantage of an older price state/ratio which has not yet been confirmed in the blockchain. Although miners are not specialized in the optimal construction of DeFi transactions in a block, miner would over time be likely to team up with teams/companies creating this type of software for them. -Over time we can expect miners not just to prefer bribes when available but to actively build transactions to extract from or create value for DeFi protocols. +:::note +Ethereum with its large amount of MEV has already seen the emergence of specialized 'block builder' as a new class of relevant economic actors separate from the block proposer (who signs the block). +::: -### Miners Extracting Value +## MEV Avoidance Strategies -As we mentioned before, if DEXes don't cleverly aggregate their prices, then miners may be incentivized to strategically create a competing transaction chain which takes advantage of an older price state/ratio which has not yet been confirmed in the blockchain. +### Batching Same-Block Trades -Although miners are not specialists in the optimal construction of DeFi transactions in a block, miner would over time be likely to team up with teams/companies creating this type of software for them. We've already seen the emergence of a specialized 'block constructor' class for Ethereum. +### Centralized Co-signing -### Miners Providing Value +### Avoid Bounty Transactions -A potential way in which miner transaction building can be seen as providing value is in the case of covenants using a 'Bounty for Transaction Building'. Here the value comes not from "extraction" but from smart contract with a mechanism paying a bounty for creating the transactions necessary for the operation of the contract system. From 20b6693a71873ca80f917cbd2e6be4241ae74eca Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Sun, 14 Sep 2025 16:48:55 +0200 Subject: [PATCH 16/17] add MEV Avoidance Strategies --- website/docs/guides/adversarial.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index c94c3bd7..8d70cd4c 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -108,9 +108,27 @@ Ethereum with its large amount of MEV has already seen the emergence of speciali ## MEV Avoidance Strategies +There's a few strategies which dapps can employ to avoid introducing unwanted MEV: + ### Batching Same-Block Trades +For DEXes the solution to the 'stale-state arbitrage' problem is introducing a batching mechanism for same-block trades so they all execute at the same price. The drawback is that this mechanism requires extra contract complexity and careful design. The benefit of including such a MEV avoidance mechanism is that even at scale with many adversarial actors, economic extraction with double spends is not possible. + +:::tip +This strategy of batching same-block trades (or "joint-execution") is the key concept demonstrated by the [Jedex contract prototype](https://github.com/bitjson/jedex#demonstrated-concepts). +::: + ### Centralized Co-signing +For contract systems relying on a continuously update on-chain oracle price feed, the problem of 'stale-state arbitrage' reappears. +However in this context the only known solution to adversarial actors exploiting stale state with a late double spend is to require centralized co-signing in the contract system. + +The drawback of this approach is that it introduces a central party to enforce honest, sequential actions to prevent late double spends. The approach introduces the need for interactivity and assumes that the central signing service does not collude or cannot be bribed, additionally it also introduces new possible security concerns. + ### Avoid Bounty Transactions +Having anyone-can-claim bounty transactions in a smart contract system directly encourages the development of double spending technology, whether it is race-condition double spends, miner bribe double spends or miner-involved double spends. + +:::tip +To not incentivize the development of double-spending technologies, it is best to avoid anyone-can-claim bounty transactions in your smart contract system. +::: From a8f1b59fbdc7ca1e17164c8665ae78903c401149 Mon Sep 17 00:00:00 2001 From: Rosco Kalis Date: Thu, 25 Sep 2025 10:49:50 +0200 Subject: [PATCH 17/17] Small updates to adversarial analysis guides --- website/docs/basics/about-bch.md | 2 +- website/docs/guides/adversarial.md | 6 +++--- website/docs/guides/lifecycle.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/docs/basics/about-bch.md b/website/docs/basics/about-bch.md index 23434ff1..0d03f39a 100644 --- a/website/docs/basics/about-bch.md +++ b/website/docs/basics/about-bch.md @@ -8,7 +8,7 @@ Bitcoin Cash (ticker BCH) is one of the biggest cryptocurrencies. Bitcoin Cash i Bitcoin Cash shares many of the same fundamentals as Bitcoin (BTC) like the *Proof-of-Work* consensus algorithm and the *UTXO data-model*. However regarding smart contract programmability, Bitcoin Cash has significantly diverged from Bitcoin (BTC). We will go over the main differences between BCH and BTC, and then delve into the smart contract capabilities of Bitcoin Cash! :::info -To learn more about the Bitcoin Basics refer to the book ['Mastering Bitcoin'](https://github.com/bitcoinbook/bitcoinbook). The core of Bitcoin's design is still very much the same in Bitcoin Cash. +To learn more about the Bitcoin Basics refer to the book ['Mastering Bitcoin'](https://github.com/bitcoinbook/bitcoinbook). The core of Bitcoin's design is still very much the same in Bitcoin Cash. To learn more about BCH's transaction lifecycle, see the dedicated guide ['Transaction Lifecycle'](/docs/guides/lifecycle). ::: ## How BCH differs from BTC diff --git a/website/docs/guides/adversarial.md b/website/docs/guides/adversarial.md index 8d70cd4c..607a5694 100644 --- a/website/docs/guides/adversarial.md +++ b/website/docs/guides/adversarial.md @@ -41,7 +41,7 @@ In the case of an late double spend (which does not try to exploit a race condit Either the adversarial actor needs to convince the miners to abandon their first seen rule or he needs to be mining himself to be able to construct his own block. :::caution -Both race-condition and late double spends can both be used to grief the experience for normal users, however only late double spends can be used to extract economic value. +Both race-condition and late double spends can be used to grief the experience for normal users, however only late double spends can be used to extract economic value. ::: To convince existing miners to include the double spend transaction instead of the original, the malicious attacker will include a significantly higher mining fee than the original transaction. This can be seen as a 'miner bribe' being paid to discard the first-seen rule and to accept the double spend instead of the original. @@ -50,7 +50,7 @@ To convince existing miners to include the double spend transaction instead of t Attempting a double spend in this way does not incur risk to the adversarial party, either their transaction is not included and they don't pay any fee, or they successfully perform the double spend and they pay the high fee "miner bribe". ::: -## Economic Value Extraction +## Economic Value Extraction We will now consider what motive the adversarial actor might have to perform these bribes. The two classes of motives are either the profit motive for an economically motivated actor or causing on-chain disruption for a maliciously motivated actor. @@ -127,7 +127,7 @@ The drawback of this approach is that it introduces a central party to enforce h ### Avoid Bounty Transactions -Having anyone-can-claim bounty transactions in a smart contract system directly encourages the development of double spending technology, whether it is race-condition double spends, miner bribe double spends or miner-involved double spends. +Having anyone-can-claim bounty transactions in a smart contract system directly encourages the development of double spending technology, whether it is race-condition double spends, miner bribe double spends or miner-involved double spends. :::tip To not incentivize the development of double-spending technologies, it is best to avoid anyone-can-claim bounty transactions in your smart contract system. diff --git a/website/docs/guides/lifecycle.md b/website/docs/guides/lifecycle.md index f50706ce..aa4cf8c7 100644 --- a/website/docs/guides/lifecycle.md +++ b/website/docs/guides/lifecycle.md @@ -3,7 +3,7 @@ title: Transaction Lifecycle sidebar_label: Transaction Lifecycle --- -This guide will explain the "transaction lifecycle" of a Bitcoin Cash transaction. We'll talk about what the mempool is and how block inclusion works. Further we'll discuss the possibility of unconfirmed transaction chains and conflicting transactions to cover all the possibilities of the transaction lifecycle! +This guide will explain the "transaction lifecycle" of a Bitcoin Cash transaction. We'll talk about what the mempool is and how block inclusion works. Further we'll discuss the possibility of unconfirmed transaction chains and conflicting transactions to cover the full transaction lifecycle! ## Block Inclusion