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 all commits
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.

@gmelodie gmelodie Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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


When present the fields from a `PeerRecord` MUST be preferred over those in the

@richard-ramos richard-ramos Sep 8, 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.

Suggested change
When present the fields from a `PeerRecord` MUST be preferred over those in the
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.
Comment on lines +160 to +166

@gmelodie gmelodie Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think this needs to reason about which is better in which case and why. As it's written rn it just seems like research on current state of implementations


If a modern implementation's Identify message would exceed this limit, it
should break it up into smaller chunks.
Comment on lines +168 to +169

@gmelodie gmelodie Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

i think the past 2 paragraphs and this one could all be replaced by:

An Identify message that exceeds this limit SHOULD be broken up into smaller chunks [of size XYZ].


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
Contributor

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 |

@richard-ramos richard-ramos Sep 8, 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.

If a signed peer record alone exceeds 4kb what should the sender do? it seems that splitting a signed peer record would not work with the merge rules below, because it is a single bytes field, so the later parts would replace the earlier parts instead of joining them.


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)
Comment on lines +174 to +175

@gmelodie gmelodie Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This spec should say which are more likely. This feels a bit too vague

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.
Comment on lines +180 to +181

@gmelodie gmelodie Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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


Where repeated fields encountered in subsequent messages, they SHOULD be
appended to the earlier occurrences of the field and deduplicated as necessary.
Comment on lines +183 to +184

@gmelodie gmelodie Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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


A maximum of 10 Identify messages SHOULD be accepted.

@gmelodie gmelodie Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Would be good to add a note on why 10 is the chosen number