This is a master issue to track docs improvements we need on libp2p. tl;dr We have many friends and fans at Web3 and DevCon4, and the number one request we hear is to create more docs, diagrams, architectural overviews, videos, etc. Let's fix that!

• Video and/or diagrammatic explanation of @raulk "story of a node" from DevCon4
• libp2p/libp2p#53 (diagrams explaining pubsub protocol)
• libp2p/libp2p#54 (libp2p conceptual overview diagrams)
• Diagram showing the ping-pong sequence of events that occurs when two peers connect, negotiate a protocol, and open stream(s)
• Literature bibliography - Kad paper, Coral paper, some Leslie Lamport classics, etc
• Switch/Swarm diagram
• Life of a libp2p connection
• Single entry point to conceptual level documentation - something we can point people to that links out to all videos, diagrammatic overviews, etc.
• Deeper dives into libp2p modules like:
  • DHT
  • PubSub architectures (flood, gossip, epi)
  • Peer Discovery mechanisms
• Spec 2.0 - define what implementors MAY, SHOULD, MUST do
• What to do about libp2p/interface-* repos and the interface standardization issue?
  • Do we actually want this? (lowest common denominator problem
  • Interfaces vs conceptual architecture
  • How to test conformance in arbitrary new language implementations
• Hackmd.io pad @stuckinaboot and @zixuanzh - maybe we can use this content somehow?
• Ideas in libp2p/libp2p#58

cc @raulk @Mikerah

We should have a "Getting Started" style tutorial for the main libp2p language implementations. This issue tracks the need for the javascript tutorial.

This should be a "conversational" step-by-step tutorial that covers just enough to get a minimal p2p example running. Ideally this will serve as "chapter one" in a series of tutorials, so we don't need to cover everything under the sun.

• installing prerequisites (e.g. node)
• importing libp2p dependencies & making a libp2p bundle
• instantiating a node on some transport (maybe TCP for simplicity)
• simple p2p communication, e.g. having one node ping another

Related concepts:

• transport
• protocol dispatching (multistream)
• stream muxing
• (maybe) encryption / connection upgrading
  • not strictly necessary for first tutorial, could save for next round

In the handler functions portion of the Protocol docs under Concepts, the following sentence has a broken link:

To accept connections, a libp2p application will register handler functions for protocols using their protocol id with the switch (aka “swarm”), or a higher level interface such as go’s Host interface.

The go host interface link goes to: https://github.com/libp2p/go-libp2p-host/blob/master/host.go

Which returns a 404 error from Github.

Looks like the cert we're using for docs.libp2p.io isn't valid for the domain:

Not urgent, but at some point other people are going to start contributing to this documentation. If we have a set of writing conventions we want them to follow, it's much easier to lay down some ground rules in advance and then politely say in review "Can you revise this per our style guidelines [link]."

I would backlog this until we start getting a few outside contributions. That'll give a sense of what kind of weird (to us, but normal in the contributor's mind) types of writing we get.

NAT traversal is a pain point for every real-world p2p system, so we should highlight how libp2p addresses it "out of the box".

Should start with overview of the problem (what is NAT & why it sucks for p2p) and cover:

• automatic port forwarding via UPnP
• overview of STUN & description of identify protocol
  • link to spec when merged
• overview of TURN & description of libp2p relay protocol
  • link to spec

AutoRelay might deserve its own article, but could fit in here if we can link to #13 for details on how the DHT fits in.

This covers the go part of #29

The idea is to pull the examples from https://github.com/libp2p/go-libp2p-examples into the docs site, ideally using an automated process to pull in the narrative and code samples from the example READMEs. May take some rewriting / tweaking of the readmes

• The libp2p 'host'
• Building an http proxy with libp2p
• An echo host
• Multicodecs with protobufs
• P2P chat application
• P2P chat application w/ rendezvous peer discovery
• P2P chat application with peer discovery using mdns

See https://github.com/ipfs/docs/issues/97 - this seems like it belongs at the libp2p level rather than IPFS. Once written, IPFS docs can link here.

See ipfs-inactive/docs#96 - this feels like it belongs at the libp2p level, rather than IPFS.

I think we could stand to clarify what we mean specifically by "connection", and it would help to have an overview of the connection upgrading process.

The upgrading section should link to the secure comms and stream multiplexing docs, since those are both examples of upgraded connections. We should also link to the protocol negotiation (multistream-select) docs, since that's used in the upgrade process.

Could potentially also address content routing and cover ipfs-inactive/docs#111

We should have a high-level into that defines what peer routing is and builds to an overview of how the kad DHT works in practice.

Found a small typo in the Transport docs in the Concepts section.

In the section explaining multiaddresses, shouldn't the TCP ending of the multiaddress: /ip4/7.7.7.7/tcp/6543 match the more familiar construction 7.7.7.7:6542?

7.7.7.7:6542 =? /ip4/7.7.7.7/tcp/6543

Here’s an example of a multiaddr for a TCP/IP transport:

/ip4/7.7.7.7/tcp/6543
This is equivalent to the more familiar 7.7.7.7:6542 construction, but it has the advantage of being explicit about the protocols that are being described. With the multiaddr, you can see at a glance that the 7.7.7.7 address belongs to the IPv4 protocol, and the 6543 belongs to TCP.

This is a meta issue to keep track of the completion of our concept articles.

Write & publish:

• Transport
• #14 NAT traversal
• #11 Addressing / multiaddr
• #12 Peer Ids
• #13 Peer Routing
• #39 Stream Multiplexing
• #18 Protocol negotiation (multistream)
• #19 Encrypted comms / secio
• #23 Content Routing / DHT / record store
• #32 Connections & connection upgrading
• #33 Switch / Swarm
• #34 Pubsub

Improve:

• #17 improve Transport doc

This is part of #29, specific to the js examples

The overall goal is to pull each of these into the docs site, ideally by automatically extracting the narrative text directly from the README files (with edits so things make sense).

• Transports
• Protocol and Stream Muxing
• Encrypted Communications
• Discovery Mechanisms
• Peer and Content Routing
• PubSub
• NAT Traversal
• Running libp2p in the Browser
• The standard echo net example with libp2p
• A simple chat app with libp2p

Note: if you click into any of these links they are much easier to read. However, the images are much larger than they render on my screen, the inline Github images are a bit smaller but are closer to how they appear on my screen.

Given that documentation is a text heavy website, I think we should consider increasing the font-weight to help improve the contrast. I'm not sure what this looks like on OSX (probably, amazing), but at least on Linux the font rendering it's quite there and it's a tad bit hard to read.

Current

400 font-weight

When I copied this repo over from ipfs/docs, I blanked out the README.md file to reduce confusion over what this repo was for. However, there is some content in the original README.md that we actually probably want to bring back:

• Building the docs site locally - this could come over verbatim
• Explain that merged PRs kick off a rebuild+redeploy of docs.libp2p.io
• Something about how to contribute to docs - this could be a pointer to an article on docs.libp2p.io itself, rather than repeating information in the readme. But people will expect to find something about how to contribute.

Not urgent, but just wanted to log this somewhere.

On this page: https://docs.libp2p.io/introduction/what-is-libp2p/ in the What problems can libp2p solve section, the many projects and reach out to let us know links both point towards a TODO link ( https://docs.libp2p.io/TODO ), which, when clicked, produces this output:

ipfs resolve -r /ipns/docs.libp2p.io/TODO: no link named "TODO" under QmeNJdQTHY55sEanTBsG9SS5c7v7fjgNPBkT6QXt489eiK

In initial setup of P2PNode, there module.exports code to export the module. For experienced node devs, this may not be an issue and the code may be implied. However, for those with less experience, they may be thrown off by the nebulous error message of "TypeError: P2PNode is not a constructor".

const Libp2p = require('libp2p')
const TCP = require('libp2p-tcp')

const defaultsDeep = require('@nodeutils/defaults-deep')

const DEFAULT_OPTS = {
  modules: {
    transport: [
      TCP
    ]
  }
}

class P2PNode extends Libp2p {
  constructor (opts) {
    super(defaultsDeep(opts, DEFAULT_OPTS))
  }
}
// currently, no module.exports code here
/*
needs this addition
module.exports = { 
  P2PNode
};

*/

We should have an overview of the interface & descriptions of floodsub, gossipsub & epidemicsub.

https://docs.libp2p.io/reference/glossary/#swarm

See the discussion about the name change for context.

Just a thought: Would placing the Protocol docs first make the Concepts section flow better? That way developers are introduced to the concept of networking protocols which is the foundation of the entire stack.

Thoughts?

I tried to follow the toturial here https://docs.libp2p.io/tutorials/getting-started/go/ but the program failed to compile with the following errors

# github.com/libp2p/go-libp2p/p2p/host/basic
../../go/pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/basic_host.go:131:32: cannot use h (type *BasicHost) as type host.Host in argument to identify.NewIDService:
        *BasicHost does not implement host.Host (missing EventBus method)
../../go/pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/basic_host.go:158:32: cannot use h (type *BasicHost) as type host.Host in argument to ping.NewPingService:
        *BasicHost does not implement host.Host (missing EventBus method)
../../go/pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/basic_host.go:512:28: h.natmgr.NAT().ExternalAddrs undefined (type *"github.com/libp2p/go-libp2p-nat".NAT has no field or method ExternalAddrs)
../../go/pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:94:8: assignment mismatch: 1 variable but "github.com/libp2p/go-libp2p-nat".DiscoverNAT returns 2 values
../../go/pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:94:26: not enough arguments in call to "github.com/libp2p/go-libp2p-nat".DiscoverNAT
        have ()
        want (context.Context)
../../go/pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:154:13: mapping.InternalAddr undefined (type "github.com/libp2p/go-libp2p-nat".Mapping has no field or method InternalAddr)
../../go/pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:176:26: not enough arguments in call to nat.NewMapping
        have (multiaddr.Multiaddr)
        want (string, int)
../../go/pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:206:13: mapping.InternalAddr undefined (type "github.com/libp2p/go-libp2p-nat".Mapping has no field or method InternalAddr)

And my go version output is go version go1.13.3 darwin/amd64

Thanks for the great documentation.

https://docs.libp2p.io/tutorials/getting-started/javascript/#configure-libp2p

The links "one for node.js" and "one for the browser" do not link to an existing Github page.

https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/libp2p-nodejs.js

https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/libp2p-browser.js

Guessing their new location is:

https://github.com/ipfs/js-ipfs/blob/10e8682e44ed06fdcad849b7cb7e6a38dbd9ba49/packages/ipfs/src/core/runtime/libp2p-nodejs.js

https://github.com/ipfs/js-ipfs/blob/10e8682e44ed06fdcad849b7cb7e6a38dbd9ba49/packages/ipfs/src/core/runtime/libp2p-browser.js

This is a proposal for a tutorial to follow the current "Getting Started" tutorials based on what I would have found useful as I've been getting to know libp2p in the last week or so.

The tutorial would be called "Implementing a Protocol" and would cover:

• Defining a protocol ID and setting a stream handler
• Reading and writing protocol data
• Defining a set of structured messages that make up the protocol
• Encoding / decoding protocol messages
• Handling different types of messages
• Handling an async request / response flow
• Handling protocol upgrades (i.e. version bumps, semver matching)

Rather than making up a protocol, I suggest using an existing, simple protocol that's easy to understand and doesn't distract from the point of the tutorial, perhaps JSON-RPC over libp2p?

@yusefnapora WDYT? I'd be happy to draft a Go version of this if you think it would be useful? I always like sharing my learning experience to make it easier for others 😄

As people consume libp2p documentation, we should leverage the opportunity to get them to contribute to libp2p.

How to achieve this? By reducing friction between the time that people think “wow, this is interesting” (while reading), and they find a meaningful thing to contribute to.

Concept: a context-sensitive “widget” that integrates with Github in each section of our docs, and pulls a list of issues relevant to the content being viewed, tabbed by language so that people can jump straight into making contributions.

This requires annotating each page with metadata to link it to the relevant repos, and using the Github Search API to pull the data in.

So imagine you’re reading all about relays, and just at the bottom of the page (or elsewhere) there's a wishlist of features pulled from go-libp2p-circuit, js-libp2p-circuit, etc. to get you into hacking mode.

When people select a language tab, we should remember their language preference throughout the navigation.

Consider integrating with SourceCred for a gamified experience.

Inside the getting started JS tutorial, there is a code snippet for pingRemotePeer() which refers to using:PeerId.createFromB58String(). However, there is not mention of importing it prior to its use.

The code snippet needs to mention that we should add peer-id before creating the pingRemotePeer() function.

This can be done in the snippet where the docs say:
"To do so, we’ll need to add a couple things to src/index.js. First, require the process module so we can get the command line arguments:"
const process = require('process')

Then we can add some quick information about installing and adding peer-id, as well as explaining its use.

npm i peer-id
const PeerId = require('peer-id')

It would be nice to have some quick comments or clarification on why the PeerId.createFromB58String() method is used in the code. Also nice would be a quick sentence on why use base58 in general. Is due to the same reason that it was used in Bitcoin?

function pingRemotePeer(localPeer) {
  if (process.argv.length < 3) {
    return console.log('no remote peer address given, skipping ping')
  }
  const remoteAddr = multiaddr(process.argv[2])

  // Convert the multiaddress into a PeerInfo object
  const peerId = PeerId.createFromB58String(remoteAddr.getPeerId()) <<< ?
  const remotePeerInfo = new PeerInfo(peerId)
  remotePeerInfo.multiaddrs.add(remoteAddr)

  console.log('pinging remote peer at ', remoteAddr.toString())
  localPeer.ping(remotePeerInfo, (err, time) => {
    if (err) {
      return console.error('error pinging: ', err)
    }
    console.log(`pinged ${remoteAddr.toString()} in ${time}ms`)
  })
}

I have a habit of linking to things that don't exist yet, which can lead me to merging dead links if I'm not careful.

There are a few tools we could use to lint the source or generated output and check for dead links.

https://github.com/wjdp/htmltest seems promising.

We should add it to circle and fail if internal links are broken.

I can't decide whether broken external links should fail CI - it feels flaky to have the build fail for something outside our control. Maybe it could be a warning? It would be nice to be aware when external links disappear.

For the Feb 2021 Hackathon, one project suggested was to proofread every page on docs.libp2p.io for basic typos/grammar (not a technical accuracy proofread). I volunteered for this among other stuff.

We'll track which pages have been proofread in this Google Sheet.

This issue can be closed when every row in that sheet is marked done. (Or at maintainers' discretion if the project gets abandoned after week of Feb 1, 2021.)

cc @vloe

The current examples section just links to external sources for go, js and rust.

I think there's a big opportunity to take those external examples and rework them a bit, pull them into the site, and use them as teaching tools to walk people through libp2p use cases.

I think that keeping the examples in their own repos will probably work best, since that's the easiest place to keep them up-to-date and integrated with CI.

My tentative plan is to clone the example repos as part of the build process for this site, run them through some formatting, and embed the result into the site.

For this to work well, some work needs to be done on the example repos so that they all have enough narrative & framing around them, and I need to develop the formatting / build process.

I was trying to import the go-libp2p to get started with the tutorial provided in https://docs.libp2p.io/tutorials/getting-started/go/.
But I cant import the package with either "go get github.com/libp2p/go-libp2p" or "GOPRIVATE='github.com/libp2p/*' go get ./..."
I am using go module and go version 1.14

Error Details:
$ go version
go version go1.14.5 darwin/amd64

$ GOPRIVATE='github.com/libp2p/*' go get ./...

github.com/libp2p/go-libp2p-interface-pnet

../../pkg/mod/github.com/libp2p/[email protected]/deprecated.go:18:18: undefined: pnet.Protector

github.com/libp2p/go-libp2p/p2p/host/basic

../../pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/basic_host.go:131:32: cannot use h (type *BasicHost) as type host.Host in argument to identify.NewIDService:
*BasicHost does not implement host.Host (missing EventBus method)
../../pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/basic_host.go:158:32: cannot use h (type *BasicHost) as type host.Host in argument to ping.NewPingService:
*BasicHost does not implement host.Host (missing EventBus method)
../../pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/basic_host.go:512:28: h.natmgr.NAT().ExternalAddrs undefined (type *"github.com/libp2p/go-libp2p-nat".NAT has no field or method ExternalAddrs)
../../pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:94:8: assignment mismatch: 1 variable but "github.com/libp2p/go-libp2p-nat".DiscoverNAT returns 2 values
../../pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:94:26: not enough arguments in call to "github.com/libp2p/go-libp2p-nat".DiscoverNAT
have ()
want (context.Context)
../../pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:154:13: mapping.InternalAddr undefined (type "github.com/libp2p/go-libp2p-nat".Mapping has no field or method InternalAddr)
../../pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:176:26: not enough arguments in call to nat.NewMapping
have (multiaddr.Multiaddr)
want (string, int)
../../pkg/mod/github.com/libp2p/[email protected]+incompatible/p2p/host/basic/natmgr.go:206:13: mapping.InternalAddr undefined (type "github.com/libp2p/go-libp2p-nat".Mapping has no field or method InternalAddr)

We should cover how libp2p's support for encrypted communication works, from the negotiation process (link to multistream concept article) to the specific implementations (secio, tls, etc).

Done Criteria

• Enhance secure comm overview
• Populate Noise doc
• Populate TLS doc

Why Important

No explicit material on the supported secure channels in libp2p.

I mentioned the switch / swarm in the transport doc, but a more in-depth look at the public API surface and its responsibilities would help clarify things for users.

Could include:

• discussion of peer store / peer book
• dialing / listening API methods (examples in go, js, rust)
• short example of dial / listen interaction flow
  • can link to related concept docs

related concept docs:

• connection upgrade
• protocol negotiation
• transport
• secure comms
• nat traversal

The second note section within the getting started JS tutorial has a broken link. The link on async/waterfall which leads to https://caolan.github.io/async/docs.html#waterfall results in 404 error from Github.

Link to tutorial: (https://docs.libp2p.io/tutorials/getting-started/javascript/)

The note is:
Because generating the key pair requires some computation, PeerInfo.create is an asynchronous operation. libp2p uses node-style callbacks for most asynchronous operations, and real-world code and more complex examples will often use helpers like async/waterfall to compose chains of async operations. Since this is a fairly simple example, we’re just going to use the callbacks as-is and chain them together the “old fashioned way”.

In definition of Switch, the word transport is incorrect. It is spelled tranport and its corresponding link is broken.

Shouldn't it be spelled: transport and the link to the transport definition in the glossary.

See:
https://docs.libp2p.io/reference/glossary/#switch

While JS & Go are the immediate priority, we should also add rust and python examples as part of #29

As with JS and go, the ideal outcome is one where the example code live in its own repo (or the main libp2p repo for the language), and is covered by CI, etc. We should pull the narrative / explanation and format it for inclusion in the docs site, and also link to the source and build / run instructions.

The rust and python examples are currently light on framing / explanation, so adding some will be part of the work.

Here's the current examples (may need to revisit when we actually pick this up):

Rust:

• chat
• kad dht
• mDNS passive discovery

Python:

• chat

Inside the Transport docs in Concepts section, the following sentence has a broken link:

“When dialing a remote peer, the multiaddress should include the PeerId of the peer you’re trying to reach”

The PeerId link goes to: https://docs.libp2p.io/concepts/peer-identity/
Which returns the message:
ipfs resolve -r /ipns/docs.libp2p.io/concepts/peer-identity/: no link named "peer-identity" under QmcuoK1NLYx6n438xBvxqH1nfnj7LTdSQxKcKCX2wM9x6n

Done Criteria

Transports to add:

• QUIC
• WebTransport

Additional improvements:

• Interaction diagrams for dial / listen flow
• Details about switch / swarm & how the dialer works in practice
• Examples of different multiaddrs for various transports

Context

We have a basic concept doc for transports, but there's opportunity to improve on the content and fill in the gap of missing transport documentation.

Notes

See note from recent docs triage.

We should have a "Getting Started" style tutorial for the main libp2p language implementations. This issue tracks the need for the golang tutorial.

This should be a "conversational" step-by-step tutorial that covers just enough to get a minimal p2p example running. Ideally this will serve as "chapter one" in a series of tutorials, so we don't need to cover everything under the sun.

• installing prerequisites (e.g. install go)
• importing libp2p dependencies
  • should use gomod
  • is it worth discussing gx?
• instantiating a node on some transport (maybe TCP for simplicity)
• simple p2p communication, e.g. having one node ping another

Related concepts:

• transport
• protocol dispatching (multistream)
• stream muxing
• (maybe) encryption / connection upgrading
  • not strictly necessary for first tutorial, could save for next round

Problem

While going through the Getting Started docs for NodeJs, I realized that the current version of [email protected] is causing some problems. Below is the stack trace:

Solution

I replaced the newer version of libp2p-tcp with libp2p-tcp@"^0.13.2, and it worked fine. So either we can freeze the version(add the working version in from of the installation script provided) or fix the current version.

Cover the basics (what is muxing, why do we need it, etc)

Describe how muxing fits into connection upgrade process. Describe & link to interface & implementations.

Related:

• connection upgrade
• protocol negotiation

Once we have a clearly written out security/threat model, we should document it. Not sure if this should live here or in libp2p/libp2p, but it should live somewhere and be pointed to in the docs as an advanced topic. Some users care a lot about this topic and it can't just be self-documenting in the code. Self-assigning.

Inside the Transport docs in Concepts section, the following sentence has a broken link:

The libp2p component responsible for managing the transports is called the switch, which also coordinates protocol negotiation, stream multiplexing, establishing secure communication and other forms of “connection upgrading”.

The protocol negotiation link goes to: https://docs.libp2p.io/concepts/protocol-negotiation

Which returns the message:
ipfs resolve -r /ipns/docs.libp2p.io/concepts/protocol-negotiation: no link named "protocol-negotiation" under QmcuoK1NLYx6n438xBvxqH1nfnj7LTdSQxKcKCX2wM9x6n

Should cover the basics of the content routing interface and how it's used by other parts of libp2p (e.g. rendezvous for AutoRelay). Should mention that the primary implementation is via kad-dht, but others implementations are possible.

This should be complementary to #13, which covers Peer Routing. Since the content routing interface is distinct from peer routing (even if both are often backed by the same DHT implementation), we should discuss it separately and link between the docs where it makes sense.

We should update https://libp2p.io/ to have a Documentation link (pointing to docs.libp2p.io) to the right of Specifications. Or wherever in that top nav bar makes the most sense.

I'll let you figure this one out, @yusefnapora . Not too urgent.

I just realized that this site doesn't really mention the libp2p daemon.

We should add a section that describes what the daemon is capable of and why you'd want to use it; e.g. because you're using a language without a native libp2p implementation.

We should address this topic somewhere in the docs, probably as part of a larger discussion of NATed hosts. Points to cover:

1. What are Relay nodes? (Servers operated by PL that NAT'd hosts can connect to directly to discover peers. Explain that all traffic from nodes using a relay will pass through the relay, which is expensive and expected to be slower than direct connections. We should also explain to folks that if you use this, you're relying on a piece of centralized infrastructure and all the limitations that come with that...)

2. How do I use relay nodes in my code? How can a user tell whether his traffic is going through a relay node? (I believe the answer to the first one is that it's just a flag in the go-libp2p Host constructor. We should show a code example, including how to catch errors if relay nodes are unavailable for some reason. Also, I believe only go-libp2p supports this right now; should make that clear. On the second one, I don't know. If there's not a way, we should log an issue with whoever is working on diagnostic tooling for libp2p.)

3. Other NAT hole punching. The whole reason for relay nodes is to help developers whose users have NAT'd hosts, like PCs on a home router. We should roll this in to a larger discussion of NAT'd hosts, e.g., current status of uPnP to open ports on the router, current status of STUN/ICE (not available afaik), etc.

Problem: Documentation, by definition, creates a separate source of truth independent of the code. While we can autogenerate certain documentation like method signatures (e.g., godoc), there's no realistic automated system for documentation that broad areas like:

• key concepts
• system architecture (including diagrams, which are both expensive to maintain and highly valuable to readers)
• how and why to use certain {classes|methods|subsystems}
• how various pieces fit together

This issue is to collect ideas for what process(es) libp2p should put in place to stay up to date. I don't know what the best practice here is, but we should think about this early before it becomes an unmanageable nightmare.

The snazzy looking pubsub concept documentation describes Gossipsub's gossip as emitting to 6 peers every 1 second. https://github.com/libp2p/docs/pull/64/files#diff-c5421c96c419b40b9ccba140bf7376c4R211-R214

However, in the Go implementation that's not the case. Instead it emits to 0-6 peers every 1 second, depending on if the randomly selected peers are ones that are already in the mesh. https://github.com/libp2p/go-libp2p-pubsub/blob/master/gossipsub.go#L513-L520

I'm not sure which one of these is the bug, but I recall @vyzo mentioning that this was done intentionally in the Go gossipsub implementation to cause less messages to be propagated from smaller degree nodes.

@raulk @vyzo thoughts?

We should have a concept doc about protocol negotiation that describes the high-level need, with details about how multistream is used throughout the libp2p stack.

We should emphasize that multistream is not directly related to multiplexing, but note that multiplexed streams do use multistream to identify the protocol used by each "inner stream".

Related concepts:

• transport
• stream multiplexing

transports is misspelled as translports

A libp2p component responsible for composing multiple translports into a single interface, allowing application code to dial peers without having to specify what transport to use.