nip-badge

Badge Definition event

The following tags MUST be present:

• d tag with the unique name of the badge.

The following tags MAY be present:

• A name tag with a short name for the badge.
• image tag whose value is the URL of a high-resolution image representing the badge. The second value optionally specifies the dimensions of the image as widthxheight in pixels. Badge recommended dimensions is 1024x1024 pixels.
• A description tag whose value MAY contain a textual representation of the image, the meaning behind the badge, or the reason of its issuance.
• One or more thumb tags whose first value is an URL pointing to a thumbnail version of the image referenced in the image tag. The second value optionally specifies the dimensions of the thumbnail as widthxheight in pixels.
• A form tag referencing a Form Template event kind-30168, see NIP-101, that users must fill out when requesting this badge. Format: ["form", "30168:<pubkey>:<form-id>"]

Requesting a Badge

When a Badge Definition includes a form tag, users can request the badge by submitting a Form Response event kind-1069, see NIP-101. The response MUST include:

• An a tag referencing the Form Template specified in the badge definition
• An a tag referencing the Badge Definition being requested
• response tags with the filled-out form data

Clients SHOULD render the form UI based on the referenced Form Template and submit the response to the badge issuer’s relays. Clients MUST respect the privacy settings of the Form Template — if the form specifies encrypted responses, the Form Response should be encrypted as defined in NIP-101.

Badge Award event

The following tags MUST be present:

• An a tag referencing a kind-30009 Badge Definition event.
• One or more p tags referencing each pubkey awarded.

Profile Badges Event

The number of badges a pubkey can be awarded is unbounded. The Profile Badge event allows individual users to accept or reject awarded badges, as well as choose the display order of badges on their profiles.

The following tags MUST be present:

• A d tag with the unique identifier profile_badges

The following tags MAY be present:

• Zero or more ordered consecutive pairs of a and e tags referencing a kind-30009 Badge Definition and kind-8 Badge Award, respectively. Clients SHOULD ignore a without corresponding e tag and viceversa. Badge Awards referenced by the e tags should contain the same a tag.

Motivation

Users MAY be awarded badges (but not limited to) in recognition, in gratitude, for participation, or in appreciation of a certain goal, task or cause.

Users MAY choose to decorate their profiles with badges for fame, notoriety, recognition, support, etc., from badge issuers they deem reputable.

Recommendations

Clients MAY whitelist badge issuers (pubkeys) for the purpose of ensuring they retain a valuable/special factor for their users.

Badge image recommended aspect ratio is 1:1 with a high-res size of 1024x1024 pixels.

Badge thumbnail image recommended dimensions are: 512x512 (xl), 256x256 (l), 64x64 (m), 32x32 (s) and 16x16 (xs).

Clients MAY choose to render less badges than those specified by users in the Profile Badges event or replace the badge image and thumbnails with ones that fits the theme of the client.

Clients SHOULD attempt to render the most appropriate badge thumbnail according to the number of badges chosen by the user and space available. Clients SHOULD attempt render the high-res version on user action (click, tap, hover).

Example of a Badge Definition event

{
  "pubkey": "alice",
  "kind": 30009,
  "tags": [
    ["d", "bravery"],
    ["name", "Medal of Bravery"],
    ["description", "Awarded to users demonstrating bravery"],
    ["image", "https://nostr.academy/awards/bravery.png", "1024x1024"],
    ["thumb", "https://nostr.academy/awards/bravery_256x256.png", "256x256"]
  ],
  // other fields...
}

Example of a Badge Definition with request form

First, the badge issuer creates a Form Template kind-30168:

{
  "pubkey": "alice",
  "kind": 30168,
  "tags": [
    ["d", "membership-application"],
    ["name", "Membership Application"],
    ["field", "reason", "text", "Why do you want to join?", "", "{\"required\":true}"],
    ["field", "referral", "text", "Who referred you?", "", "{\"required\":false}"]
  ],
  // other fields...
}

Then the Badge Definition references this form:

{
  "pubkey": "alice",
  "kind": 30009,
  "tags": [
    ["d", "membership"],
    ["name", "Community Member"],
    ["description", "Granted to approved community members"],
    ["image", "https://example.com/member-badge.png", "1024x1024"],
    ["form", "30168:alice:membership-application"]
  ],
  // other fields...
}

When a user wants to request this badge, they submit a Form Response kind-1069:

{
  "pubkey": "bob",
  "kind": 1069,
  "tags": [
    ["a", "30168:alice:membership-application"],
    ["a", "30009:alice:membership"],
    ["response", "reason", "I would like to contribute articles to the community."],
    ["response", "referral", "charlie"]
  ],
  // other fields...
}

Example of Badge Award event

{
  "id": "<badge award event id>",
  "kind": 8,
  "pubkey": "alice",
  "tags": [
    ["a", "30009:alice:bravery"],
    ["p", "bob", "wss://relay"],
    ["p", "charlie", "wss://relay"]
  ],
  // other fields...
}

Example of a Profile Badges event

Honorable Bob The Brave: jsonc { "kind": 30008, "pubkey": "bob", "tags": [ ["d", "profile_badges"], ["a", "30009:alice:bravery"], ["e", "<bravery badge award event id>", "wss://nostr.academy"], ["a", "30009:alice:honor"], ["e", "<honor badge award event id>", "wss://nostr.academy"] ], // other fields... }