A Peer Identity (often written
PeerId) is a unique reference to a specific
peer within the overall peer-to-peer network.
As well as serving as a unique identifier for each peer, a PeerId is a verifiable link between a peer and its public cryptographic key.
Each libp2p peer controls a private key, which it keeps secret from all other peers. Every private key has a corresponding public key, which is shared with other peers.
Together, the public and private key (or “key pair”) allow peers to establish secure communication channels with each other.
Conceptually, a PeerId is a cryptographic hash of a peer’s public key. When peers establish a secure channel, the hash can be used to verify that the public key used to secure the channel is the same one used to identify the peer.
The PeerId spec goes into detail about the byte formats used for libp2p public keys and how to hash the key to produce a valid PeerId.
PeerIds are encoded using the multihash format, which adds a small header to the hash itself that identifies the hash algorithm used to produce it.
PeerIds are multihashes, which are defined as a compact binary format.
Here’s an example of a PeerId represented as a base58-encoded multihash:
While it’s possible to represent multihashes in many textual formats (for example as hexadecimal, base64, etc), PeerIds always use the base58 encoding, with no multibase prefix when encoded into strings.
A PeerId can be encoded into a multiaddr as a
address with the PeerId as a parameter.
If my peer id is
libp2p multiaddress for me would be:
As with other multiaddrs, a
/p2p address can be encapsulated into
another multiaddr to compose into a new multiaddr. For example, I can combine
the above with a transport address
/ip4/18.104.22.168/tcp/4242 to produce this very useful address:
This provides enough information to dial a specific peer over a TCP/IP transport. If some other peer has taken over that IP address or port, it will be immediately obvious, since they will not have control over the key pair used to produce the PeerId embedded in the address.
For more on addresses in libp2p, see Addressing
The multiaddr protocol for libp2p addresses was originally written
and was later renamed to
The two are equivalent and have the same binary
representation in multiaddrs. Which one is rendered in the string format
depends on the version of the multiaddr library in use.
Another common libp2p data structure related to peer identity is the
PeerInfo combines a
PeerId with a set of multiaddrs
that the peer is listening on.
libp2p applications will generally keep a “peer store” or “peer book” that
maintains a collection of
PeerInfo objects for all the peers that they’re
The peer store acts as a sort of “phone book” when dialing out to other peers; if a peer is in the peer store, we probably don’t need to discover their addresses using peer routing.