docs(network): README #2100

danforbes · 2021-12-03T14:49:41Z

Changes

Added README to network package. Rendered docs here.

Tests

N/A

Issues

Closes #2036

Primary Reviewer

@noot

codecov · 2021-12-03T15:30:56Z

Codecov Report

Merging #2100 (e26b4c9) into development (d096d44) will increase coverage by 0.00%.
The diff coverage is n/a.

@@             Coverage Diff              @@
##           development    #2100   +/-   ##
============================================
  Coverage        61.35%   61.36%           
============================================
  Files              202      202           
  Lines            27355    27355           
============================================
+ Hits             16785    16787    +2     
+ Misses            8694     8691    -3     
- Partials          1876     1877    +1

Flag	Coverage Δ
unit-tests	`61.36% <ø> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
lib/runtime/wasmer/imports.go	`48.71% <0.00%> (+0.05%)`	⬆️
dot/network/connmgr.go	`90.41% <0.00%> (+1.36%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d096d44...e26b4c9. Read the comment docs.

dot/network/README.md

jimjbrettj

I think you said this is a WIP, but looks great so far!

dot/network/README.md

noot · 2021-12-09T21:25:40Z

dot/network/README.md

+[key distribution](#identity--key-management) capabilities. The Noise protocol is
+[well documented](http://cryptowiki.net/index.php?title=Noise_Protocol_Framework) and the Go implementation is


it might be nicer to link to the libp2p spec: https://github.com/libp2p/specs/blob/master/noise/README.md afaik the libp2p version of noise and the "official" version have some slight differences

dot/network/README.md

noot · 2021-12-09T21:29:54Z

dot/network/README.md

+unidirectionally "push" information to other peers in the network. Although the peer receiving the information must
+explicitly accept a handshake in order to open a stream for a notification protocol, this stream does not allow the
+receiver to "push" information to the sender.


Suggested change

unidirectionally "push" information to other peers in the network. Although the peer receiving the information must

explicitly accept a handshake in order to open a stream for a notification protocol, this stream does not allow the

receiver to "push" information to the sender.

unidirectionally "push" information to other peers in the network. On stream opening, the outgoing and incoming sides will exchange a handshake. After this handshake is completed, the incoming side is closed for writing; ie. the receiver of the stream can only receive data over the stream, but not write to it. The opposite is true for the outgoing side; the stream is closed for reading after the handshake has completed, and data can only be sent.

I'd also update this to say something like "the stream can be left open indefinitely until one side no longer wishes to communicate"

dot/network/README.md

noot · 2021-12-09T21:31:02Z

dot/network/README.md

+contains a [block header](https://docs.substrate.io/v3/getting-started/glossary/#header) and associated data, such as
+the [BABE pre-runtime digest](https://crates.parity.io/sp_consensus_babe/digests/enum.PreDigest.html).


the BABE digests are part of the header, so I'd just leave this as saying the message is a block header.

dot/network/README.md

noot · 2021-12-09T21:32:02Z

dot/network/README.md

+[Finality](https://wiki.polkadot.network/docs/learn-consensus#finality-gadget-grandpa) protocols ("gadgets") such as
+GRANDPA are often described in terms of "games" that are played by the participants in a network. In GRANDPA, this game
+relates to voting on the blocks that inform the canonical chain. This notification protocol is used by peers to cast
+votes for participation in the GRANDPA game.


Suggested change

votes for participation in the GRANDPA game.

votes for participation in the GRANDPA game, and as well to gossip a `Commit` message when a chain has been finalised.

noot · 2021-12-09T21:33:44Z

dot/network/README.md

+
+[These protocols](https://crates.parity.io/sc_network/index.html#request-response-protocols) allow peers to request
+specific information from one another. The requesting peer sends a protocol-specific message that describes the request
+and the peer to which the request was sent replies with a message.


I'd update this to also say if a node opens a stream with some remote peer, then the outgoing side will only push requests and the incoming side will only expect to receive requests. same for the other way around, the outgoing side expects to only receive responses.

noot

nice work! just a few comments/suggestions. it might also be good to add something about "polite gossip" - ie. don't send the same message to a peer twice and that kinda thing

kishansagathiya · 2021-12-10T05:28:44Z

dot/network/README.md

+peer-to-peer networks use have evolved over time - [Napster](https://en.wikipedia.org/wiki/Napster) relied on a central
+database, [Gnutella](https://en.wikipedia.org/wiki/Gnutella) used a brute-force technique called "flooding",
+[BitTorrent](https://en.wikipedia.org/wiki/BitTorrent) takes a performance-preserving approach that relies on a
+[distributed hash table (DHT)](https://en.wikipedia.org/wiki/Distributed_hash_table). Gossamer uses a `libp2p`-based


BitTorrent also uses Kademlia

dot/network/README.md

Co-authored-by: Quentin McGaw <quentin.mcgaw@gmail.com>

Co-authored-by: Eclésio Junior <eclesiomelo.1@gmail.com>

Co-authored-by: noot <36753753+noot@users.noreply.github.com>

danforbes · 2021-12-13T19:10:25Z

Thank you for your clarifications, @noot - can you please review this commit to make sure I got everything right? 🙏🏻 e26b4c9

noot

looks good to me! do you still plan to add links to the codebase here? oh, and also stuff about polite gossip?

danforbes · 2021-12-15T18:38:38Z

@noot yes I am working on "deeper" links into the codebase/godocs but if you think this is correct and compete enough I say that we go ahead and merge it in and I can continue with iterative improvements on the docs 👍🏻

danforbes added the Type: Documentation label Dec 3, 2021

danforbes assigned noot Dec 3, 2021

danforbes requested review from arijitAD, EclesioMeloJunior, edwardmack, jimjbrettj, kishansagathiya, noot, qdm12 and timwu20 as code owners December 3, 2021 14:49

danforbes force-pushed the dfo/doc/net branch from 1b72fc8 to a1a3cf7 Compare December 3, 2021 15:02

jimjbrettj reviewed Dec 3, 2021

View reviewed changes

dot/network/README.md Show resolved Hide resolved

jimjbrettj reviewed Dec 3, 2021

View reviewed changes

dot/network/README.md Outdated Show resolved Hide resolved

jimjbrettj reviewed Dec 3, 2021

View reviewed changes

dot/network/README.md Show resolved Hide resolved

jimjbrettj reviewed Dec 3, 2021

View reviewed changes

qdm12 reviewed Dec 6, 2021

View reviewed changes

dot/network/README.md Outdated Show resolved Hide resolved

dot/network/README.md Outdated Show resolved Hide resolved

dot/network/README.md Outdated Show resolved Hide resolved

dot/network/README.md Outdated Show resolved Hide resolved

danforbes force-pushed the dfo/doc/net branch 4 times, most recently from f3477da to 7fcabc1 Compare December 7, 2021 22:34

danforbes requested a review from qdm12 December 8, 2021 11:28

danforbes changed the title ~~README for network Package~~ docs(network): README Dec 8, 2021

EclesioMeloJunior approved these changes Dec 8, 2021

View reviewed changes

dot/network/README.md Outdated Show resolved Hide resolved

noot reviewed Dec 9, 2021

View reviewed changes

dot/network/README.md Outdated Show resolved Hide resolved

noot reviewed Dec 9, 2021

View reviewed changes

dot/network/README.md Outdated Show resolved Hide resolved

noot reviewed Dec 9, 2021

View reviewed changes

dot/network/README.md Outdated Show resolved Hide resolved

noot reviewed Dec 9, 2021

View reviewed changes

dot/network/README.md Outdated Show resolved Hide resolved

noot reviewed Dec 9, 2021

View reviewed changes

dot/network/README.md Show resolved Hide resolved

noot reviewed Dec 9, 2021

View reviewed changes

dot/network/README.md Outdated Show resolved Hide resolved

noot reviewed Dec 9, 2021

View reviewed changes

dot/network/README.md Outdated Show resolved Hide resolved

noot reviewed Dec 9, 2021

View reviewed changes

kishansagathiya reviewed Dec 10, 2021

View reviewed changes

danforbes and others added 13 commits December 13, 2021 10:57

README for network Package

f1b4066

Update dot/network/README.md

2b2fbae

Co-authored-by: Quentin McGaw <quentin.mcgaw@gmail.com>

Expand detail on public keys

dc3104b

Misc fixes & enhancements

7e8d18f

Update dot/network/README.md

d46822e

Co-authored-by: Eclésio Junior <eclesiomelo.1@gmail.com>

Prettier

5b7da26

Fix link

fde0609

Clarify purpose of keystore

16f036d

emulates -> implements

10059f6

Apply suggestions from code review

4ce80c4

Co-authored-by: noot <36753753+noot@users.noreply.github.com>

Prettier

f6ee211

Expand top-level network protocol sections

e79c716

Clarify points brought up by @noot

e26b4c9

danforbes force-pushed the dfo/doc/net branch from 9dd1fd5 to e26b4c9 Compare December 13, 2021 19:09

danforbes requested a review from noot December 13, 2021 19:09

noot approved these changes Dec 15, 2021

View reviewed changes

danforbes merged commit 7ce1cd7 into development Dec 15, 2021

danforbes deleted the dfo/doc/net branch December 15, 2021 18:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(network): README #2100

docs(network): README #2100

danforbes commented Dec 3, 2021 •

edited

Loading

codecov bot commented Dec 3, 2021 •

edited

Loading

jimjbrettj left a comment

noot Dec 9, 2021

noot Dec 9, 2021

noot Dec 9, 2021

noot Dec 9, 2021

noot Dec 9, 2021

noot Dec 9, 2021

noot left a comment

kishansagathiya Dec 10, 2021

danforbes commented Dec 13, 2021

noot left a comment •

edited

Loading

danforbes commented Dec 15, 2021

		[key distribution](#identity--key-management) capabilities. The Noise protocol is
		[well documented](http://cryptowiki.net/index.php?title=Noise_Protocol_Framework) and the Go implementation is

		contains a [block header](https://docs.substrate.io/v3/getting-started/glossary/#header) and associated data, such as
		the [BABE pre-runtime digest](https://crates.parity.io/sp_consensus_babe/digests/enum.PreDigest.html).

	votes for participation in the GRANDPA game.
	votes for participation in the GRANDPA game, and as well to gossip a `Commit` message when a chain has been finalised.

docs(network): README #2100

docs(network): README #2100

Conversation

danforbes commented Dec 3, 2021 • edited Loading

Changes

Tests

Issues

Primary Reviewer

codecov bot commented Dec 3, 2021 • edited Loading

Codecov Report

jimjbrettj left a comment

Choose a reason for hiding this comment

noot Dec 9, 2021

Choose a reason for hiding this comment

noot Dec 9, 2021

Choose a reason for hiding this comment

noot Dec 9, 2021

Choose a reason for hiding this comment

noot Dec 9, 2021

Choose a reason for hiding this comment

noot Dec 9, 2021

Choose a reason for hiding this comment

noot Dec 9, 2021

Choose a reason for hiding this comment

noot left a comment

Choose a reason for hiding this comment

kishansagathiya Dec 10, 2021

Choose a reason for hiding this comment

danforbes commented Dec 13, 2021

noot left a comment • edited Loading

Choose a reason for hiding this comment

danforbes commented Dec 15, 2021

danforbes commented Dec 3, 2021 •

edited

Loading

codecov bot commented Dec 3, 2021 •

edited

Loading

noot left a comment •

edited

Loading