The identify protocol is used to exchange basic information with other peers in the network, including addresses, public keys, and capabilities.
| Lifecycle Stage | Maturity Level | Status | Latest Revision |
|---|---|---|---|
| 3A | Recommendation | Active | r1, 2021-08-09 |
Authors: @vyzo
Interest Group: @yusefnapora, @tomaka, @richardschneider, @Stebalien, @bigs
See the lifecycle document for context about the maturity level and spec status.
There are two variations of the identify protocol, identify and identify/push.
The identify protocol has the protocol id /ipfs/id/1.0.0, and it is used
to query remote peers for their information.
The protocol works by opening a stream to the remote peer you want to query, using
/ipfs/id/1.0.0 as the protocol id string. The peer being identified responds by returning
an Identify message and closes the stream.
The identify/push protocol has the protocol id /ipfs/id/push/1.0.0, and it is used
to inform known peers about changes that occur at runtime.
When a peer's basic information changes, for example, because they've obtained a new
public listen address, they can use identify/push to inform others about the new
information.
The push variant works by opening a stream to each remote peer you want to update, using
/ipfs/id/push/1.0.0 as the protocol id string. When the remote peer accepts the stream,
the local peer will send an Identify message and close the stream.
Upon receiving the pushed Identify message, the remote peer should update their local
metadata repository with the information from the message. Note that missing fields
should be ignored, as peers may choose to send partial updates containing only the fields
whose values have changed.
syntax = "proto2";
message Identify {
optional string protocolVersion = 5;
optional string agentVersion = 6;
optional bytes publicKey = 1;
repeated bytes listenAddrs = 2;
optional bytes observedAddr = 4;
repeated string protocols = 3;
}The protocol version identifies the family of protocols used by the peer. The field is optional but recommended for debugging and statistic purposes.
Previous versions of this specification required connections to be closed on version mismatch. This requirement is revoked to allow interoperability between protocol families / networks.
Example value: /my-network/0.1.0.
This is a free-form string, identifying the implementation of the peer.
The usual format is agent-name/version, where agent-name is
the name of the program or library and version is its semantic version.
This is the public key of the peer, marshalled in binary form as specicfied in peer-ids.
These are the addresses on which the peer is listening as multi-addresses.
This is the connection source address of the stream-initiating peer as observed by the peer being identified; it is a multi-address. The initiator can use this address to infer the existence of a NAT and its public address.
For example, in the case of a TCP/IP transport the observed addresses will be of the form
/ip4/x.x.x.x/tcp/xx. In the case of a circuit relay connection, the observed address will
be of the form /p2p/QmRelay/p2p-circuit. In the case of onion transport, there is no
observable source address.
This is a list of protocols supported by the peer.
A node should only advertise a protocol if it's willing to receive inbound
streams on that protocol. This is relevant for asymmetrical protocols. For
example assume an asymmetrical request-response style protocol foo where some
clients only support initiating requests while some servers (only) support
responding to requests. To prevent clients from initiating requests to other
clients, which given them being clients they fail to respond, clients should not
advertise foo in their protocols list.