Skip to content

Add Address Manager spec - #738

Open
gmelodie wants to merge 1 commit into
libp2p:masterfrom
vacp2p:feat/addr-manager
Open

Add Address Manager spec#738
gmelodie wants to merge 1 commit into
libp2p:masterfrom
vacp2p:feat/addr-manager

Conversation

@gmelodie

@gmelodie gmelodie commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

A libp2p node learns its own addresses from several sources: the listen addresses that it binds, a port mapping, a relay reservation, an Identify observation, and the configuration of the host operator. No source alone proves that a remote peer can dial the address. Today each source lives in its own component, each one rewrites the announce list, and the answers of AutoNAT per address collapse into one flag.

This spec describes an Address Manager: one component at host level that owns the announce path, separates always-on address discovery from optional reachability confirmation, and delegates confirmation to a replaceable Verifier backed by AutoNAT v2. It defines no message and no wire format, thus a node that adopts it stays compatible with a node that does not.

  • One candidate per multiaddress, with a set of sources and a state (Unverified, Confirmed, Unreachable).
  • Each source is locally trusted or remote-derived. Identify and Autonat both carry an IP that a remote peer chose, and a candidate with only such sources stays unannounced until a verifier confirms it.
  • The observation ring holds one entry per reporting peer, and minCount counts distinct peers. One peer that reconnects thus cannot choose the external address.
  • The verifier trusts neither verdict alone. It accepts OK only when the AutoNAT v2 dial-back nonce arrived on the address under test, and an announced public address needs two peers before it becomes Unreachable.
  • Without a verifier it announces every candidate that it discovers, thus a node that disables AutoNAT keeps the behaviour of today.

@github-project-automation github-project-automation Bot moved this to Triage in libp2p Specs Sep 1, 2026
@gmelodie
gmelodie force-pushed the feat/addr-manager branch 5 times, most recently from 0ea9618 to 05599e4 Compare September 1, 2026 19:04
@gmelodie
gmelodie marked this pull request as ready for review September 1, 2026 19:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Triage

Development

Successfully merging this pull request may close these issues.

1 participant