Write reference level documentation for the network code

[pmnoxx]

To make network code easier to understand we should write a reference level documentation. That will make it easier for new developers to understand different parts of the networking code.

• [x] https://github.com/near/nearcore/pull/5580
• [x] https://github.com/near/nearcore/pull/5621
• [x] https://github.com/near/nearcore/pull/5622
• [x] https://github.com/near/nearcore/pull/5623
• [x] https://github.com/near/nearcore/pull/5625
• [x] https://github.com/near/nearcore/pull/5626
• [x] https://github.com/near/nearcore/pull/5627

Add in-code documentation

• [x] - Graph - https://github.com/near/nearcore/pull/5162
• [x] Add comments to utils.rs (https://github.com/near/nearcore/pull/5216)
• [x] Add comments to test_utils.rs (https://github.com/near/nearcore/pull/5217)
• [x] Add comments/refactor rate_counter.rs (https://github.com/near/nearcore/pull/5218)

Dead code

• [x] remove dead code (https://github.com/near/nearcore/pull/5207)

Improve code quality:

• [x] Remove not needed clones - https://github.com/near/nearcore/pull/5209
• [x] Remove 'pub' modifier from Edge - https://github.com/near/nearcore/pull/5223
• [x] Use constants for time in db.rs https://github.com/near/nearcore/pull/5215
• [x] Refactor Arc to a new struct https://github.com/near/nearcore/pull/5228/files

[pmnoxx]

@bowenwang1996 @mm-near @matklad

[matklad]

Great idea! I've just spend five minutes reading the doc in the wip PR, and I feel I've already learned more about near networking more than I knew before.

I have one high-level comment here: we might want to ensure strict separation between protocol specification and code-level documentation. Ideally, I'd love to see two documents: "NEAR P2P protocol" and "Implementation of networking in nearcore". The first documents abstract protocol without references to a particular implementation. It doesn't mention Rust, tokio, nearcore or actors, but it does mention TCP, borsh format, persistent nonces etc. So if you want to implement a nearcore node in Go, you can use that document as a spec. The second document describes how we implement protocol in nearcore (eg, "to maintain persistent nonces, we store removed edges into the database using this column").

Don't think that we should immediately create that, but it might make sense to keep the separation between proper protocol and specific implementation in mind while writing the docs.

[matklad]

The first documents abstract protocol without references to a particular implementation

I guess the right home for that doc is https://nomicon.io/ChainSpec/NetworkSpec.html (and network spec should probably be lifted one level up and become a sibling of ChanSpec)