Skip to content

Add signedPeerRecord and discussion of message sizes to identify #709

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
achingbrain wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add signedPeerRecord and discussion of message sizes to identify #709

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
03c6dc6
docs: add signedPeerRecord and discussion of message sizes to identify
achingbrain Apr 8, 2026
339487f
docs: apply suggestions from code review
achingbrain Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 73 additions & 22 deletions identify/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

| Lifecycle Stage | Maturity Level | Status | Latest Revision |
|-----------------|----------------|--------|-----------------|
| 3A | Recommendation | Active | r1, 2021-08-09 |
| 3A | Recommendation | Active | r2, 2026-04-08 |

Authors: [@vyzo]

Expand All @@ -17,6 +17,7 @@ Interest Group: [@yusefnapora], [@tomaka], [@richardschneider], [@Stebalien], [@
[@richardschneider]: https://github.com/richardschneider
[@Stebalien]: https://github.com/Stebalien
[@bigs]: https://github.com/bigs
[@achingbrain]: https://github.com/achingbrain

See the [lifecycle document][lifecycle-spec] for context about the maturity level
and spec status.
Expand All @@ -26,17 +27,21 @@ and spec status.
## Table of Contents

- [Identify v1.0.0](#identify-v100)
- [Table of Contents](#table-of-contents)
- [Overview](#overview)
- [`identify`](#identify)
- [`identify/push`](#identifypush)
- [The Identify Message](#the-identify-message)
- [protocolVersion](#protocolversion)
- [agentVersion](#agentversion)
- [publicKey](#publickey)
- [listenAddrs](#listenaddrs)
- [observedAddr](#observedaddr)
- [protocols](#protocols)
- [Table of Contents](#table-of-contents)
- [Overview](#overview)
- [`identify`](#identify)
- [`identify/push`](#identifypush)
- [The Identify Message](#the-identify-message)
- [protocolVersion](#protocolversion)
- [agentVersion](#agentversion)
- [publicKey](#publickey)
- [listenAddrs](#listenaddrs)
- [observedAddr](#observedaddr)
- [protocols](#protocols)
- [signedPeerRecord](#signedpeerrecord)
- [Implementation notes](#implementation-notes)
- [Message sizes and message splitting](#message-sizes-and-message-splitting)
- [Receiving multiple messages](#receiving-multiple-messages)


## Overview
Expand All @@ -48,9 +53,9 @@ 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 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 one or more `Identify` messages and closes the stream.

### `identify/push`

Expand All @@ -61,14 +66,15 @@ When a peer's basic information changes, for example, because they've obtained a
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.
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 one or more `Identify`
messages 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.
Upon receiving the pushed `Identify` message(s), 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.

## The Identify Message

Expand All @@ -81,6 +87,7 @@ message Identify {
repeated bytes listenAddrs = 2;
optional bytes observedAddr = 4;
repeated string protocols = 3;
optional bytes signedPeerRecord = 8;
}
```

Expand Down Expand Up @@ -133,3 +140,47 @@ 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.

### signedPeerRecord

This field contains a serialized [SignedEnvelope](../RFC/0002-signed-envelopes.md)
containing a [PeerRecord](../RFC/0003-routing-records.md) signed by the sending
node.

It normally contains the same addresses as the `listenAddrs` field, but in a
form that lets us share authenticated addresses with other peers.

When present the fields from a `PeerRecord` MUST be preferred over those in the
main body of the `Identify` message.

## Implementation notes

### Message sizes and message splitting

Early implementations of the Identify protocol limited the incoming message size
to 2KB and would reject any messages larger than this. Others have since
increased this limit to 4KB or 8KB.

With the addition of signed peer records, Circuit Relay addresses, multiaddrs
that contain certificate hashes, etc, it is now much more likely that this
threshold will be exceeded.

If an a modern implementation's Identify message would exceed this limit, it
Comment thread
achingbrain marked this conversation as resolved.
Outdated
should break it up into smaller chunks.

For optimum backwards compatibility the first message SHOULD NOT exceed 2KB.
Subsequent messages SHOULD NOT exceed 4KB.

@wjmelements wjmelements Apr 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can signed peer records be subdivided? I suspect they can themselves exceed 4 KB.

@dozyio dozyio Apr 18, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One possible issue is signature size of signed peer records if/when libp2p supports post quantum signatures - 4KB would be too small for ML-DSA-44 and ML-DSA-65, 8KB would be too small for ML-DSA-87

| Variant | Public key (bytes) | Signature (bytes) |
| --- | ---: | ---: | ---: |
| ML-DSA-44 | 1312 | 2420 |
| ML-DSA-65 | 1952 | 3309 |
| ML-DSA-87 | 2592 | 4627 |


Listen addresses SHOULD be ordered such that addresses that have a higher
likelihood of being dialed successfully (e.g. public, non-NAT or Circuit Relay)
are sent in the first Identify message and the `signedPeerRecord`, if used.

### Receiving multiple messages

When multiple messages are received, all fields SHOULD be respected, with later
updates for fields with a cardinality of one taking priority.

Where repeated fields encountered in subsequent messages, they SHOULD be
appended to the earlier occurrences of the field and deduplicated as necessary.

A maximum of 10 Identify messages SHOULD be accepted.