Update Dandelion Doc and Simulation (#1223)

* Update doc and simulation

doc/dandelion/dandelion.md

@@ -1,13 +1,17 @@
-Dandelion in Grin: Privacy-Preserving Transaction Propagation
+Dandelion in Grin: Privacy-Preserving Transaction Aggregation and Propagation
 ==================
-This document describes the implementation of Dandelion in Grin.
+This document describes the implementation of Dandelion in Grin and its modification to handle transactions aggregation in the P2P protocol.
 ## Introduction
 
 Dandelion is a new transaction broadcasting mechanism that reduces the risk of eavesdroppers linking transactions to the source IP. Moreover, it allows Grin transactions to be aggregated (removing input-output pairs) before being broadcasted to the entire network giving an additional privacy perk.
 
-Dandelion was introduced in [1] by G. Fanti et al. and presented at ACM Sigmetrics 2017. On June 2017 a BIP was proposed introducing a more practical and robust variant of Dandelion called Dandelion++ [2].  This document is an adaptation of this BIP for Grin.
+Dandelion was introduced in [1] by G. Fanti et al. and presented at ACM Sigmetrics 2017. On June 2017, a BIP [2] was proposed introducing a more practical and robust variant of Dandelion called Dandelion++ [3] published later in 2018.  This document is an adaptation of this BIP for Grin.
 
-## Mechanism
+We first define the original Dandelion propagation then the Grin adaptation  of the protocol with transaction aggregation.
+
+## Original Dandelion
+
+### Mechanism
 
 Dandelion transaction propagation proceeds in two phases: first the “stem” phase, and then “fluff” phase. During the stem phase, each node relays the transaction to a *single* peer. After a random number of hops along the stem, the transaction enters the fluff phase, which behaves just like ordinary flooding/diffusion. Even when an attacker can identify the location of the fluff phase, it is much more difficult to identify the source of the stem.
 
@@ -22,9 +26,7 @@ Illustration:
                                                    └-> I ...
 </pre>
 
-This mechanism also allows Grin transactions to be aggregated during the stem phase and then broadcasted to all the nodes on the network. This result in transaction aggregation and possibly cut-through (thus removing spent outputs) giving a significant privacy gain similar to a non-interactive coinjoin with cut-through.
-
-## Specification
+### Specifications
 
 The Dandelion protocol is based on three mechanisms:
 
@@ -48,31 +50,7 @@ After receiving a stem transaction, the node flips a biased coin to determine wh
 
 Nodes that receives stem transactions are called stem relays. This relay is chosen from among the outgoing (or whitelisted) connections, which prevents an adversary from easily inserting itself into the stem graph. Each node periodically randomly choose its stem relay every 10 minutes.
 
-## Aggregation
-
-Two aggregation scenarios have been proposed.
-
-### Scenario 1: aggregating transaction without lock_height
-
-In this scenario, transactions are aggregated during the stem phase and then broadcasted to the mempool only when the fluff phase happens.
-
-Each node maintains a ```patience``` timer along with a ```max_patience``` value. When a node receives a stem transaction, its ```patience``` timer starts, waiting for more stem transactions to aggregate. Once the ```patience``` timer reaches the ```max_patience``` value, the node flips a coin to decide whether to send as stem or fluff.
-In the of a stem transactions, the node starts an embargo timer which is defined in the Considerations part. The node need to track every stem transactions it receives aggregated or not in order to guarantee its propagation and be able to revert to a previous stempool state.
-
-A simulation of this scenario is available [here](simulation.md).
-
-### Scenario 2: aggregating transaction with lock_height
-
-Similar to the previous scenario, except that we aggregate transactions that are locked with ```lock_height```. As of now (7f478d7), transactions with ```lock_height > chain_height``` are rejected by the mempool. In this scenario, such locked transaction would be accepted in the stempool and relayed to other stem relays with the following conditions:
-
-```
-if (lock_height <= chain_tip.height && coin_flip <= stem_probability)
-```
-
-In this scenario, a patience parameter would still exist to know for how long a peer keep the transaction to its stempool before broadcasting it. Also a ```max_lock_height``` parameter must be defined in order to limit the potential denial of service vector.
-
-
-## Considerations
+### Considerations
 
 The main implementation challenges are: (1) identifying a satisfactory tradeoff between Dandelion’s privacy guarantees and its latency/overhead, and (2) ensuring that privacy cannot be degraded through abuse of existing mechanisms. In particular, the implementation should prevent an attacker from identifying stem nodes without interfering too much with the various existing mechanisms for efficient and DoS-resistant propagation.
 
@@ -83,7 +61,23 @@ The main implementation challenges are: (1) identifying a satisfactory tradeoff
 * If a node receives a child transaction that depends on one or more currently-embargoed Dandelion transactions, then the transaction is also relayed in stem mode, and the embargo timer is set to the maximum of the embargo times of its parents. This helps ensure that parent transactions enter fluff mode before child transactions. Later on, this two transaction will be aggregated in one unique transaction removing the need for the timer.
 * Transaction propagation latency should be minimally affected by opting-in to this privacy feature; in particular, a transaction should never be prevented from propagating at all because of Dandelion. The random timer guarantees that the embargo mechanism is temporary, and every transaction is relayed according to the ordinary diffusion mechanism after some maximum (random) delay on the order of 30-60 seconds.
 
+## Dandelion in Grin
+
+Dandelion also allows Grin transactions to be aggregated during the stem phase and then broadcasted to all the nodes on the network. This result in transaction aggregation and possibly cut-through (thus removing spent outputs) giving a significant privacy gain similar to a non-interactive coinjoin with cut-through. This section details this mechanism.
+
+### Aggregation Mechanism
+
+In order to aggregate transactions, Grin implements a modified version of the Dandelion protocol [4].
+
+By default, when a node sends a transaction on the network it will be broadcasted with the Dandelion protocol as a stem transaction to its Dandelion relay. The Dandelion relay will then wait a period of time (the patience timer), in order to get more stem transactions to aggregate. At the end of the timer, the relay does a coin flip for each new stem transaction and determines if it will stem it (send to the next Dandelion relay) or fluff it (broadcast normally). Then the relay will take all the transactions to stem, aggregate them, and broadcast them to the next Dandelion relay. It will do the same for the transactions to fluff, except that it will broadcast the aggregated transactions “normally” (to a random subset of the peers).
+
+This gives us a P2P protocol that can handle transaction merging.
+
+A simulation of this scenario is available [here](simulation.md).
+
 ## References
-1. (Sigmetrics 2017) Dandelion: Redesigning the Bitcoin Network for Anonymity https://arxiv.org/abs/1701.04439
-2. Dandelion++: TBA
-3. Dandelion BIP https://github.com/gfanti/bips/blob/master/bip-dandelion.mediawiki
+
+- [1] (Sigmetrics 2017) Dandelion: Redesigning the Bitcoin Network for Anonymity https://arxiv.org/abs/1701.04439
+- [2] Dandelion BIP https://github.com/dandelion-org/bips/blob/master/bip-dandelion.mediawiki
+- [3] (Sigmetrics 2018) Dandelion++: Lightweight Cryptocurrency Networking with Formal Anonymity Guarantees https://arxiv.org/abs/1805.11060
+- [4] Dandelion Grin Pull Request #1067: https://github.com/mimblewimble/grin/pull/1067

doc/dandelion/simulation.md

@@ -1,8 +1,8 @@
 Dandelion Simulation
 ==================
-This document describes a network of node with Dandelion.
+This document describes a network of node using the Dandelion protocol with transaction aggregation.
 
-In this scenario, we simulate a successful aggregation but a failed transaction cut-through forcing a node to revert its stempool state.
+In this scenario, we simulate a successful aggregation.
 
 This document also helps visualizing all the timers in a simple way.
 
@@ -12,77 +12,66 @@ This document also helps visualizing all the timers in a simple way.
 
 ## T = 5
 
-A sends grins to B. 
-B flips a coin and decides to add it to its stempool and starts the embargo timer for this transaction.
+A sends grins to B. A adds the transaction to its stempool and starts the embargo timer for this transaction.
 
 ![t = 5](images/t5.png)
 
 ## T = 10
 
-B waits until he runs out of patience.
+A waits until he runs out of patience.
 
 ![t = 10](images/t10.png)
 
 ## T = 30
 
-B runs out of patience and broadcasts the aggregated stem transaction to its Dandelion relay H.
-H receives the stem transaction, flips a coin and decides to add it to its stempool and starts the embargo timer for this transaction.
-
+A runs out of patience, flips a coin and broadcasts the stem transaction to its Dandelion relay G.
+G receives the stem transaction, add it to its stempool and starts the embargo timer for this transaction.
+ 
 ![t = 30](images/t30.png)
 
 ## T = 40
 
 G sends grins to E.
-E flips a coin and decides to add it to its stempool and starts the embargo timer for this transaction.
-B and H wait.
+G adds the transaction it to its stempool and starts the embargo timer for this transaction.
 
 ![t = 40](images/t40.png)
 
-## T = 55
+## T = 45
+
+G runs out of patience, flips a coin and broadcasts the stem transaction to its Dandelion relay D.
+
+![t = 45](images/t45.png)
+
+## T = 50
 
 B spends B1 to D.
-D flips a coin and decides to add it to its stempool and starts the embargo timer for this transaction.
-H runs out of patience broadcasts the aggregated stem transaction to its Dandelion relay E.
-E receives the stem transaction, flips a coin and decides to add it to its stempool and starts the embargo timer for this transaction.
+B add it to its stempool and starts the embargo timer for this transaction.
 
 ![t = 55](images/t55.png)
 
-## T = 65
+## T = 55
 
-Nodes are waiting.
+B runs out of patience, flips a coin and broadcasts the stem transaction to its Dandelion relay H.
+D runs out of patience, flips a coin and broadcasts the aggregated stem transaction to its Dandelion relay E.
+E receives the stem transaction, add it to its stempool and starts the embargo timer for this transaction.
 
-![t = 65](images/t65.png)
+![t = 55](images/t55.png)
 
-## T = 70
+## T = 60
 
-E runs out of patience broadcasts the aggregated stem transaction to its Dandelion relay F.
-F receives the stem transaction, flips a coin and decides to add it to its stempool and starts the embargo timer for this transaction.
+H runs out of patience, flips a coin broadcasts the stem transaction to its Dandelion relay E.
+E receives the stem transaction, add it to its stempool and starts the embargo timer for this transaction.
 
-![t = 70](images/t70.png)
+![t = 60](images/t60.png)
 
-## T = 80
+## T = 70 - Step 1
 
-D runs out of patience, broadcasts the aggregated stem transaction to its Dandelion relay.
-E receives the stem transaction, flips a coin and decides to add it to its stempool and starts the embargo timer for this transaction. aggregates them (thus removing duplicate input/output pair B1) and starts its patience timer.
+E runs out of patience, flips a coin and decide to broadcast the transaction to all its peers (fluff in the mempool).
 
-![t = 80](images/t80.png)
+![t = 70_1](images/t70_1.png)
 
-## T = 85
-
-Nodes are waiting.
-
-![t = 85](images/t85.png)
-
-## T = 95 - Step 1
-
-F runs out of patience, broadcasts the aggregated stem transaction to its Dandelion relay H.
-H receives the transaction, flips a coin and decide to broadcast the transaction to all its peers (fluff in the mempool).
-
-![t = 95_1](images/t95_1.png)
-
-## T = 95 - Step 2
+## T = 70 - Step 2
 
 All the nodes add this transaction to their mempool and remove the related transactions from their stempool.
-E receives the transaction in its mempool and reverts the state of its stempool to avoid conflicting transactions.
 
-![t = 95_2](images/t95_2.png)
+![t = 70_2](images/t70_2.png)