Define Peer and Swarm in Docs

[walkerlj0]

In searching Docs, I didn't find a clear definition of what a peer is (what defines it and what behaviors/ features can a peer have)

I also think it would be helpful to have a clear definition of w swarms - how the peers in a swarm are determined, how the communication and searching is done (and different from DHT) they cryptographic keys used, when & how peers in a swarm are determined and maintained.

[welcome]

Thank you for submitting your first issue to this repository! A maintainer will be here shortly to triage and review.
In the meantime, please double-check that you have provided all the necessary information to make this process easy! Any information that can help save additiona round trips is useful! We currently aim to give initial feedback within two business days. If this does not happen, feel free to leave a comment.
Please keep an eye on how this issue will be labeled, as labels give an overview of priorities, assignments and additional actions requested by the maintainers:

• "Priority" labels will show how urgent this is for the team.
• "Status" labels will show if this is ready to be worked on, blocked, or in progress.
• "Need" labels will indicate if additional input or analysis is required.

Finally, remember to use https://discuss.ipfs.io if you just need general support.

[walkerlj0]

Note- in talking with Tyler we found that it was in fact in the glossary, however when you search for it, the glossary terms do not show up

[TMoMoreau]

Taylor*, very common mistake so don't worry about it :) Feel free to refer to me as T Mo, that's what most people do lol.

As for this issue, I will work in a link to the glossary from the "Beginners guide" doc I wrote, that seems like a good start. I also feel the glossary should be more pronounced and visible from anywhere on the docs.

[Annamarie2019]

Hi @walkerlj0 and @TMoMoreau I'm triaging this issue. I've been wanting to understand more about swarms too, so I agree this would be great to address. There are definitions in the glossary, but they're very light, as they should be in a glossary, and there is also recently a little more information on peers added to the nodes page, which even has links to its behavior/features: Nodes, but it doesn't address how peers behave in swarms.

Issue #294 addresses a solution to being able to see glossary terms in search. (We should get to this soon.)

However, I don't think that Swarms are addressed in the doc, and Lindsay has some great suggestions as to what a page on Swarms could answer. So here's how I see this going:

Create a page on Swarms and Peers to answer Lindsay's suggestions:

• a clear definition of Swarms and Peers (as members of swarms)
• how the peers in a swarm are determined,
• how the communication and searching is done (and different from DHT)
• the cryptographic keys used,
• when & how peers in a swarm are determined and maintained.
• add a link to the peers bullet point on Nodes, saying something like: "To learn more about how peers behave in swarms, see....[The new page].
• add a link to peer and swarm in the glossary to [The new page].

How's that summary?

[schomatis]

I think much of this could be leveraged form the libp2p docs to avoid duplication. On the unfortunate "swarm" term (very ingrained in the stack), it has now been rebranded as "switch", which is basically the transport layer.

[TMoMoreau]

Hey @Annamarie2019 and @walkerlj0. I'm working on this issue now, just have a couple questions that I'm hoping either of you can clear up for me.

• "How the communication and searching is done (and different from the DHT)"

I'm assuming this is in reference to how the nodes in a swarm communicate and search for content? In which case, it is my understanding that nodes do their communicating and searching entirely within the DHT.

• "The cryptographic keys used"

Not sure which cryptographic keys are being referenced here, is it referring to each nodes peerID? If that is the case, is this point looking to explain how nodes use peerIDs to identify, communicate, and search for content?

Any clarifications or opinions are greatly appreciated, thanks in advance!

[Annamarie2019]

@TMoMoreau I defer to @walkerlj0 on this. I would have the same questions. (I just spoke with Lindsay and she's pretty swamped with presentations for the next week.)

[walkerlj0]

@TMoMoreau Hmm, lets see

• I think you are accurate when you say nodes are done in the DHT is correct
• By the cryptographic keys used, I think this was early on and I was having trouble understanding that difference between IPFS and Filecoin. Now that I understand things better, I know there is not cryptography in IPFS

This was an early question written by me, so I was just spitballing questions, thanks for answering!

[TMoMoreau]

Closing this issue as while I was working on it I realized that most of this info is already in the docs, or is irrelevant to IPFS. I think the only thing that isn't explained in the docs already is how peers in a swarm are determined.