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.
What is a PeerId
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.
How are Peer Ids represented as strings?
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.
PeerIds in multiaddrs
A PeerId can be encoded into a multiaddr as a
/p2p address with the PeerId as a parameter.
If my peer id is
QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N, a 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/22.214.171.124/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
/ipfs and was later renamed to
/p2p. 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 aware of.
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.
You can help improve this article! Please refer to this issue to make suggestions and let us know how to help.