Kind 10001: Pinned Notes

Overview

Pinned Notes events (kind 10001) allow users to showcase specific notes on their profile pages. This standard replaceable event kind serves as a list of note references that a user wants to highlight for visitors to their profile, similar to pinned posts on other social platforms. Pinning notes helps users feature their most important, representative, or popular content.

Specification

Property	Value
Kind Number	10001
Event Range	Replaceable
Defined in	NIP-51

Content Format

The content field can contain encrypted private pinned notes using NIP-04 encryption. The encrypted content would follow the same structure as the public tags but is only visible to the creator. Most implementations will likely leave this field empty as pinned notes are typically meant to be publicly displayed.

Schema

For encrypted private pinned notes (rarely used):

"content": "<NIP-04 encrypted JSON array of tags>"

The encrypted content, when decrypted, would reveal a JSON array of tags:

[
  ["e", "<event-id>", "<relay-url>"]
]

Tags

Tag Name	Description	Format	Required
e	Referenced note to pin	["e", "<event-id>", "<relay-url>"]	Yes

Client Behavior

Clients should:

1. Display pinned notes prominently on the user's profile
2. Typically show pinned notes at the top of the profile, before the regular timeline
3. Provide an interface for users to pin and unpin notes from their profile
4. When displaying pinned notes:
   • Load the full content of the referenced notes
   • Include visual indication that a note is pinned
   • Maintain the order of pins as specified in the event
5. Allow users to update their pinned notes by publishing a new kind 10001 event
6. Limit the number of pinned notes to a reasonable amount (e.g., 3-5) in the UI
7. Only allow users to pin kind 1 (text note) events

Relay Behavior

Relays should:

1. Handle kind 10001 events as normal replaceable events
2. Store these events to allow clients to retrieve the user's pinned notes
3. Not attempt to interpret or enforce the pinning behavior (this is client-side functionality)

Use Cases

• Highlighting a personal introduction or bio post
• Featuring important announcements
• Pinning the most popular or representative content
• Showcasing creative work or achievements
• Displaying current projects or interests
• Promoting important links or resources
• Creating a curated introduction to a user's content

Example

{
  "id": "f5d5f20e395549fe356efc5442ef346fd6cc60a28d39bee61b93f4c179eb96c7",
  "pubkey": "854043ae8f1f97430ca8c1f1a090bdde6488bd5115c7a45307a2a212750ae4cb",
  "created_at": 1699597889,
  "kind": 10001,
  "tags": [
    ["e", "04d2c21d3ecc928f1d75e78d6dd1896356dc1120d2b9e09be9494e41607389cf", "wss://relay.nostr.example.com"],
    ["e", "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2", "wss://relay.damus.io"],
    ["e", "b3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4", "wss://relay.primal.net"]
  ],
  "content": "",
  "sig": "a9a4e2192eede77e6c9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad001cb039cb8de91d83ce30e9a94f82ac3c5a2372aa1294a96bd"
}

References

• NIP-51: Lists
• NIP-01: Basic Protocol

Related Kinds

• Kind 1: Short Text Note - The kind of event that can be pinned
• Kind 10000: Mute List - Another standard list for content filtering
• Kind 10003: Bookmarks - Saved content for personal reference

Notes

• Pinned notes are one of several standard list types defined in NIP-51
• Users can only have one pinned notes list (since it's a replaceable event)
• Only kind 1 (text note) events should be pinned
• The order of e tags in the event determines the display order of pinned notes
• Relay hints in the e tags are recommended to help clients locate the referenced notes
• This kind was intended to replace the deprecated parameterized replaceable event with kind 30001 and d tag "pin"