Part of Stem. This page defines the ListPeers method of the sync RPC specification. It is how a peer learns new addresses without a distributed hash table.

The formal schema is attached as the schemaDefinition of this page: a struct {key, input, output} with key pinned to ListPeers.

Peer-table exchange. Unchanged from HM24 except for the schema; it carries addresses only, never account bindings.

Input

field	type	required	meaning
`page`	rpc/type/page	no	Pagination.
`listHash`	bytes	no	SHA-256 of the caller's own sorted peer table; an identical server answers with an empty page.

Output

field	type	required	meaning
`peers`	list of struct (below)	yes	Known peers seen within the freshness window.
`nextPageToken`	string or null	yes	Token for the next page, or null.

peers is a struct:

field	type	required	meaning
`id`	data/peer-id	yes	Peer id.
`addrs`	list of string	yes	Multiaddrs.
`updatedAt`	timestamp	yes	When the server last saw it.

Rules

The server returns peers it has seen within its freshness window (thirty days), newest first.

If listHash equals the SHA-256 of the server's own sorted table the server answers with an empty page and a null token, so two peers with the same view spend one round trip.

The method reveals nothing about accounts: a peer id is never tied to an account in this exchange.

A server may refuse to share peers at all; it then answers with an empty page.

Stem does not use the result to pick peers for content. Content is pulled from authority and trusted peers; this table only supplies addresses for them.

Today (HM24)

Unchanged in behaviour from HM24's P2P.ListPeers (page size, page token, list hash). What changes is its role: HM24 also samples up to twenty of these peers per tier when discovering content; Stem never does.

Example

{"key": "ListPeers", "input": {"page": {"pageSize": 30}, "listHash": {"/": {"bytes": "9f2a…"}}}}

{"peers": [{"id": "12D3KooW…", "addrs": ["/ip4/203.0.113.7/udp/56001/quic-v1"], "updatedAt": 1759900000000}], "nextPageToken": null}

Input

Output

Rules

Today (HM24)

Example

See also