Preface

This is not a bug per se, but an issue that arises in specific circumstances.

TL;DR:

• To start hole punching you need to determine your public IP, which generally requires other peers if you're behind NAT
• We determine our own observed address by running the identify protocol against peers
• We "activate" an observed address once 4 peers return tell us they've observed an address. This reduces the trust assumptions on any particular peer and provides some level of security
  

  go-libp2p/p2p/protocol/identify/obsaddr.go

  Lines 17 to 22 in 3deee92

  	// ActivationThresh sets how many times an address must be seen as "activated"
  	// and therefore advertised to other peers as an address that the local peer
  	// can be contacted on. The "seen" events expire by default after 40 minutes
  	// (OwnObservedAddressTTL * ActivationThreshold). The are cleaned up during
  	// the GC rounds set by GCInterval.
  	var ActivationThresh = 4

• The activation of an observed address is transport and IP specific. That means that with QUIC and TCP enabled with both IPv4 and IPv6 addrs, you will need 16 connections for the 4 addresses to be activated. By corollary, as the number of transports and IPs increases, more connections are necessary to activate a given addr. (Can you confirm this @sukunrt)
• When you are behind NAT, don't start a DHT client, and create a new host with the default configuration, there's a good chance that you won't be able to hole punch into other peers behind NAT, because you don't have any activated public addresses.
• Even if you connect to the 4 libp2p bootstrap nodes (without starting a DHT client), depending on the transports over it connects, none of your public addrs will activate.

Background

ipfs-check, is a retrievability diagnostics tool. You provide it with a CID and a multiaddr and it checks —amongst other things— whether the peer is dialable and whether it has the block of the CID. This is especially useful to determine whether a peer behind NAT is actually "hole-punchable", which you can only know by trying to connect to.

The tool creates a short-lived libp2p test host for each check, which connects to one or two peers (two if it needs circuit relay reservation if the other peer is behind NAT), however hole punching will never kick off and it will hang on the following line:

2024-08-29T13:40:04.468+0200	DEBUG	p2p-holepunch	holepunch/svc.go:98	waiting until we have at least one public addresspeer12D....`

I was able to work around this by adding a DHT client to the test host, however, it's not clear whether this is ideal. There are some situations (like resource constrained environments) where you don't want the overhead of increased connections and bandwidth associated with a DHT clients.

Ideas

• Return a more specific error from NewStream indicating that it couldn't hole punch because of no observed public addrs.