Add Dandelion docs (#740)

* Add scenario
* Update dandelion aggregation explanation

doc/dandelion/dandelion.md

@@ -22,7 +22,7 @@ Illustration:
                                                    └-> I ...
 </pre>
 
-TODO Add transaction aggregation in stem mode
+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
 
@@ -49,7 +49,27 @@ Nodes that receives stem transactions are called stem relays. This relay is chos
 
 ## Aggregation
 
-TODO Transaction 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 reachs 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
 

doc/dandelion/simulation.md

@@ -0,0 +1,93 @@
+Dandelion Simulation
+==================
+This document describes a network of node with Dandelion.
+
+In this scenario, we simulate a successfull aggregation but a failed transaction cut-through forcing a node to revert its stempool state.
+
+This document also helps visualizing all the timers in a simple way.
+
+## Initial Situation
+
+![Initial situation](images/ti.png)
+
+## T = 0
+
+A sends grins to B, adds the transaction to its stempool and starts its patience timer.
+
+![t = 0](images/ti.png)
+
+## T = 10
+
+B waits until he runs out of patience.
+
+![t = 10](images/t10.png)
+
+## T = 30
+
+B runs out of patience, flips a coin, broadcasts the transaction to its stem relay and starts the embargo timer for this transaction.
+
+![t = 30](images/t30.png)
+
+## T = 35
+
+B and H wait.
+
+![t = 35](images/t35.png)
+
+## T = 40
+
+G sends grins to E.
+E adds the transaction to its stempool and starts its patience timer.
+
+![t = 40](images/t40.png)
+
+## T = 50
+
+B, H and E wait.
+
+![t = 50](images/t50.png)
+
+## T = 55
+
+B spends B1 to D.
+D adds the transaction to its stempool and starts its patience timer.
+
+![t = 55](images/t55.png)
+
+## T = 60
+
+H runs out of patience, flips a coin, broadcasts the transaction to its stem relay and starts the embargo timer for this transaction.
+
+![t = 60](images/t60.png)
+
+## T = 65
+
+Waiting.
+
+![t = 65](images/t65.png)
+
+## T = 70
+
+E runs out of patience, flips a coin, broadcasts the aggregated transaction to its stem relay and starts the embargo timer for this transaction.
+
+![t = 70](images/t70.png)
+
+## T = 75
+
+Waiting.
+
+![t = 75](images/t75.png)
+
+## T = 85
+
+D runs out of patience, flips a coin, broadcasts the aggregated transaction to its stem relay and starts the embargo timer for this transaction.
+E receives the stem transaction, aggregates its (thus removing duplicate input/output pair B1) and starts it s patience timer.
+
+![t = 85](images/t85.png)
+
+## T = 100
+
+F runs out of patience, flips a coin, broadcasts the aggregated transaction to all its peers (fluff in the mempool).
+E receives the transaction in its mempool and reverts the state of its stempool to avoid conflicting transactions.
+
+![t = 100](images/t100.png)