NIP-02

Contact List and Petnames

final optional author:fiatjaf author:arcbtc

A special event with kind 3, meaning "contact 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 can be anything and should be ignored.

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 contact list that gets published overwrites the past ones, so it should contain all entries. Relays and clients SHOULD delete past contact lists as soon as they receive a new one.

Uses

Contact 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 contact lists of other people one might be following or browsing; or show the data in other contexts.

Relay sharing

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

Petname scheme

The data from these contact lists can be used by clients to construct local "petname" tables derived from other people's contact lists. This alleviates the need for global human-readable names. For example:

A user has an internal contact list that says

[
  ["p", "21df6d143fb96c2ec9d63726bf9edc71", "", "erin"]
]

And receives two contact lists, one from 21df6d143fb96c2ec9d63726bf9edc71 that says

[
  ["p", "a8bb3d884d5d90b413d9891fe4c4e46d", "", "david"]
]

and another from a8bb3d884d5d90b413d9891fe4c4e46d that says

[
  ["p", "f57f54057d2a7af0efecc8b0b66f5708", "", "frank"]
]

When the user sees 21df6d143fb96c2ec9d63726bf9edc71 the client can show erin instead; When the user sees a8bb3d884d5d90b413d9891fe4c4e46d the client can show david.erin instead; When the user sees f57f54057d2a7af0efecc8b0b66f5708 the client can show frank.david.erin instead.