NIP-02

Follow List

final optional

A special event with kind 3, meaning “follow list” is defined as having a list of p tags, one for each of the followed/known profiles one is following.

Each tag entry should contain the key for the profile, a relay URL where events from that key can be found (can be set to an empty string if not needed), and a local name (or “petname”) for that profile (can also be set to an empty string or not provided), i.e., ["p", <32-bytes hex key>, <main relay URL>, <petname>].

The .content is not used.

For example:

{
  "kind": 3,
  "tags": [
    ["p", "91cf9..4e5ca", "wss://alicerelay.com/", "alice"],
    ["p", "14aeb..8dad4", "wss://bobrelay.com/nostr", "bob"],
    ["p", "612ae..e610f", "ws://carolrelay.com/ws", "carol"]
  ],
  "content": "",
  // other fields...
}

Every new following list that gets published overwrites the past ones, so it should contain all entries. Relays and clients SHOULD delete past following lists as soon as they receive a new one.

Whenever new follows are added to an existing list, clients SHOULD append them to the end of the list, so they are stored in chronological order.

Uses

Follow list backup

If one believes a relay will store their events for sufficient time, they can use this kind-3 event to backup their following list and recover on a different device.

Profile discovery and context augmentation

A client may rely on the kind-3 event to display a list of followed people by profiles one is browsing; make lists of suggestions on who to follow based on the follow lists of other people one might be following or browsing; or show the data in other contexts.

A client may publish a follow list with good relays for each of their follows so other clients may use these to update their internal relay lists if needed, increasing censorship-resistance.

Petname scheme

Clients can use follow-list petnames as local names for profiles. A petname is stored as the fourth value in a p tag:

["p", "21df6d143fb96c2ec9d63726bf9edc7121df6d143fb96c2ec9d63726bf9edc71", "", "erin"]

Here, the pubkey is known and can be displayed as erin in the current user’s context. Likewise, if Erin has a petname of charlie assigned to one of her contacts, that Charlie can be displayed as ~/erin/charlie in the current user’s context.

Petnames can also work on the other direction and resolve a pubkey from a name path. A path is resolved one component at a time: each component is looked up in the follow list of the profile resolved by the previous component.

For example, if the current user’s follow list gives a profile the petname erin, and Erin’s follow list gives another profile the petname charlie, then ~/erin/charlie resolves to Charlie.

If no user is logged in or the current user context is not relevant, an absolute root can be specified:

~npub1.../erin/charlie
~carol@names.com/erin/charlie

In order to qualify for petname resolution they must have only ASCII letters, numbers or _.