update Dandelion documentation

[lehnberg]

Fixes #2719.

[lehnberg]

@antiochp @quentinlesceller the first draft is now ready for review, let me know what you think, and please notice the questions I've highlighted throughout the description of the Grin implementation, not sure what we do in some of these cases.

[lehnberg]

@antiochp @quentinlesceller just another nudge on a review on this (happy to make edits in case you'd want this to look different - just say).

Some specific questions I have about the way this is implemented in Grin:

1. How does the node choose their outbound relay? A single one at random? At the beginning of each epoch?
2. Does the node put its own and inbound received transactions into its stempool?
3. Does the node always forward its own transactions alongside its outbound path, even if it's in fluff mode?
4. Is the 10s interval of dandelion_monitor configurable?
5. If a node receives a stem transaction from an inbound node that has already existed in its own stempool that epoch, will it fluff the existing transaction?

[antiochp]

How does the node choose their outbound relay? A single one at random? At the beginning of each epoch?

Yes. One is randomly chosen from the current set of outbound peers at the beginning of each epoch.

Does the node put its own and inbound received transactions into its stempool?

Yes. Any stem txs received will be added to the local stempool.
Any stem txs received via a wallet push will also be added to local stempool.

Does the node always forward its own transactions alongside its outbound path, even if it's in fluff mode?

No. I believe we diverge from the spec here. There may be room for improvement to make the behavior match the spec. Did it this way as the impl was significantly simpler if we did not need to treat "local" txs differently. Still not entirely clear what the benefit is of always stemming local txs.

Is the 10s interval of dandelion_monitor configurable?

Yes. The following is configurable -

• epoch_secs
• embargo_secs
• aggregation_secs
• stem_probability

If a node receives a stem transaction from an inbound node that has already existed in its own stempool that epoch, will it fluff the existing transaction?

I believe so yes. This implies something unexpected happened in terms of routing and we immediately fluff in this situation. We probably want to keep an eye on this and see how often this occurs in practice.

[antiochp]

Apologies for not reviewing this earlier. This looks good.
Responded to your specific questions separately.

[antiochp]

"Always stem local" behavior implemented here - #2876

Turns out the main thing preventing us from doing this was how hard it makes Dandelion testing if we cannot get "local" txs to participate in local stem aggregation.

So made it a configurable option that defaults to following the Dandelion++ paper.

---

The following config will set your local node to aggregate all txs it sees and fluff them periodically -

aggregation_secs = 30
stem_probability = 0
always_stem_local = false

[lehnberg]

@antiochp thanks for the review, the comments, and the improvement! I've updated the docs to reflect your answers I think and this is now ready to be merged.

Just a quick note regarding this one:

Is the 10s interval of dandelion_monitor configurable?

Yes. The following is configurable -

epoch_secs
embargo_secs
aggregation_secs
stem_probability

Actually, I don't think the parameters you list here relate to dandelion_monitor no? I'm referring specifically to what you write in the description of #2628:

Dandelion monitor runs every 10s

Is this every 10s configurable? And if so, what's the parameter?

[antiochp]

Oh I see what you're asking - I misunderstood before.

The 10s is not configurable no, its simply an implementation detail.
Every 10s we check the various (configurable) timers, 30s for aggregation etc.

[lehnberg]

Oki cool - so then this documentation is accurate and is ready for merging unless there is other feedback. ✌️

[sesam]

On which branch should this be merged?

And, reading this

stem_probability = 0
always_stem_local = false

I would have guessed such settings makes stemming not happen.

[lehnberg]

On which branch should this be merged?

Good question, if I understand correctly our current docs are now outdated. Any reason why this shouldn't be merged into master @antiochp?

[antiochp]

We're holding off touching master until after the HF I believe.
But feel free to merge it into the milestone/2.x.x branch for now.

[lehnberg]

@antiochp cool - does that mean that I need to close and reopen the PR?

[jaspervdm]

No, you can change the branch you want to merge in on the top of the page, when you press the "Edit" button

[lehnberg]

Thanks, I've re-opened a cleaned up version as #2942 to be merged against milestone/2.x.x rather than this one. Closing.