# libp2p/specs: implementation-neutral networking reference > libp2p/specs defines the language-independent wire protocols, addresses, peer identities, connection upgrades, discovery, and routing used by libp2p. It is reference material for protocol authors and implementers, not an installable networking library, and the repository states that several specifications remain incomplete. **libp2p/specs** — Technical specifications for the libp2p networking stack - Repository: https://github.com/libp2p/specs - Website: https://libp2p.io - Stars: 1,783 · Forks: 319 - Language: Unknown - License: not declared - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/libp2p-specs ## Why libp2p keeps its protocol reference separate libp2p/specs solves a cross-language compatibility problem. A peer-to-peer application depends on more than an application API: peers must agree on addresses, identities, encrypted connection establishment, stream multiplexing, message encoding, discovery behavior, and routing operations. If each implementation interprets those details independently, clients built with different libp2p stacks may fail to connect or may disagree about the meaning of a protocol message. The repository therefore concentrates on concepts that are independent of language or implementation. Its specification index divides the reference into framework rules, core abstractions and types, and wire protocols. Addressing defines how libp2p addresses work. Peer Ids and Keys defines public-key encodings, peer ID calculation, and message-signature semantics. Connections and Upgrading describes how peers establish secure, multiplexed connections over underlying transports. This makes the repository most relevant to people designing a libp2p implementation, auditing interoperability, implementing a protocol from a normative document, or comparing implementation behavior with a shared reference. It is not a runtime package and does not provide a command-line program. The README directs developers who want user-facing instructions to https://docs.libp2p.io, which is the correct destination for application setup and library usage. ## The specification index follows libp2p's network layers The repository organization mirrors the path from network identity to higher-level routing. Peer identity comes first because a connection must establish which remote peer is being contacted. Addressing then provides the conventions used to locate and describe peers. The connections specification connects those concerns by defining connection establishment and upgrading across transport mechanisms. The protocol set is deliberately broad. `ping` checks peer responsiveness, while `autonat` supports NAT detection. `identify` exchanges keys and addresses. For local discovery, `mdns` uses multicast DNS. The `rendezvous` specification covers generalized peer discovery, and `kademlia` describes the distributed hash table subsystem used for wider routing. Connection behavior is split into separate specifications rather than hidden behind one implementation. `mplex` and `yamux` define stream multiplexers. `noise`, `tls`, `secio`, and `plaintext` describe transport-security or handshake choices. The README explicitly labels `plaintext` as insecure and intended for non-production usage, while `pnet` addresses private networking with pre-shared keys. Relay behavior has its own directory. `relay` describes circuit switching similar to TURN, and `dcutr` specifies direct connection upgrades through a relay. QUIC, WebRTC, and WebTransport each have specifications, showing that transport behavior is treated as part of the compatibility surface rather than an incidental implementation detail. ## Protobuf messages and the libp2p specs lifecycle The listed protocol specifications use Protocol Buffers to define message schemas. This is a concrete interoperability mechanism: a sender and receiver need compatible encodings of protocol IDs, fields, and message values. The README says existing protocols may continue to use `proto2`, while it recommends `proto3` for new protocols. It also points to issue `#465` for context, so implementers should not assume that every message file in the repository uses the same schema version. Specifications are organized as documents rather than generated API documentation. The repository includes `00-framework-01-spec-lifecycle.md` for introducing, revising, and adopting specifications, plus `00-framework-02-document-header.md` for the expected document header. That separation matters because protocol definitions can change independently of any single implementation. The README says the repository is also a coordination point for future work through `ROADMAP.md`. It reports that existing specifications are being revised for correctness and new documents are being written for unspecified parts of libp2p. Contributions are directed first to the specification lifecycle, with an issue used to discuss proposed work. The discussion forum is reserved for topics that are not specific enough for an issue. The key operational warning is the explicit status: the specifications are currently incomplete. A directory in the index identifies work that has been merged into this repository, but it does not guarantee that every protocol or edge case has a settled definition. ## Reading and validating the repository before implementation There is no installation procedure for libp2p/specs, because the repository is a collection of technical documents rather than a library distribution. Nothing in the README or top-level layout provides a package installation command, runtime configuration, executable, or first-use API. The documented way to begin is to use the specification index, select the relevant document, and consult the spec lifecycle before proposing changes. For guidance on operating a libp2p application, the README points to https://docs.libp2p.io. A first useful reading sequence follows the index's structure. Read `addressing/README.md` for address representation, then `peer-ids/peer-ids.md` for key types and peer ID calculation. Continue with `connections/README.md` to understand secure and multiplexed connection establishment. After that, open the protocol directory relevant to the application, such as `identify/README.md`, `kad-dht/README.md`, or `pubsub/README.md`. There is no project-defined smoke test or validation command in the available repository guidance. Consequently, an implementation team cannot claim compatibility merely by reading the index. It must compare its encoded messages and state transitions with the individual specification, then account for the `proto2` or `proto3` schema used by that protocol. The repository provides reference criteria, not a conformance certification result. ## Where the specs replace an earlier RFC The most direct alternative named by the repository is the archived earlier RFC kept under `_archive/`. The README describes that document as containing useful information about libp2p design philosophy, but it says the current specification document replaces it. The distinction is practical. The older RFC offers background on why the system was designed in a particular way, while the indexed specifications organize current wire formats, abstractions, and protocol behavior. For contributors, the current specs also differ from a conventional issue-driven implementation repository. The spec lifecycle defines how a protocol document is introduced, revised, and adopted. That process matters when a proposed network behavior could affect several independent implementations. A change should therefore be evaluated as protocol compatibility work, not merely as an implementation patch. libp2p/specs also differs from user-facing documentation. The README sends operational documentation to https://docs.libp2p.io because this repository is concerned with implementation-independent network behavior. Neither source substitutes for the other: application setup belongs in user documentation, while wire-level compatibility belongs here. ## Maintenance, licensing, and the incomplete specification boundary The repository is not archived. Its last push was on 2026-10-09, so the available history shows recent specification activity rather than an abandoned repository. There are no GitHub releases, which means adoption should be based on the repository's specification lifecycle and commit history rather than release numbers or packaged versions. The `master` branch is the default branch, and the index says it is updated when specification documents move. The repository information does not identify a license. No licensing conclusion can be drawn from the README, and none is needed to understand the technical scope. Users who intend to copy or redistribute specification text or derived schemas should verify the repository's license file directly before reuse. The clearest limitation is also project-specific: the README states that the specifications are incomplete. Some behaviors may still be unspecified, while existing documents may be under revision for correctness. This matters especially for security, framing, handshake failure behavior, and protocol edge cases. The presence of `plaintext` does not imply a production security recommendation, because the index explicitly describes that transport as insecure and for non-production usage. ## Conclusion Protocol authors, compatibility testers, and developers building multiple libp2p implementations should use libp2p/specs as their implementation-neutral reference. Developers looking for setup tutorials or a ready-to-run library should use the user documentation instead. Before adopting a protocol in production, verify its individual specification, stated completeness, wire format, security properties, and support in the intended libp2p implementation; an entry in the specification index is not evidence that every specification is final or complete. ## FAQ ### What is libp2p/specs used for? It provides implementation-independent specifications for libp2p wire protocols, addresses, peer identities, connection upgrades, and other network-level behavior. ### Can I install libp2p/specs as a software package? No installation command is documented because this repository is a specification collection rather than a runtime package. Use the specification index for reference and https://docs.libp2p.io for user-facing libp2p documentation. ### Are all libp2p specifications complete and stable? No. The README explicitly states that the specifications are currently incomplete and that existing documents are being revised while unspecified parts are being documented. ## Sources - [Issues](https://github.com/libp2p/specs/issues) - [libp2p/specs on GitHub](https://github.com/libp2p/specs) - [Project website](https://libp2p.io) - [README](https://github.com/libp2p/specs/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/libp2p-specs