diff --git a/52.md b/52.md index e011c801..5b46b249 100644 --- a/52.md +++ b/52.md @@ -9,7 +9,7 @@ Badges *This NIP is currently in draft, and review / comments are sought.* -This NIP enables an app owner (or community manager) to award of badges to their members. +This NIP enables an app owner (or community manager) to award badges to their members. ## Kind XX: Issue Badge @@ -17,98 +17,83 @@ EVENT sent from client to relay to issue a badge. ```json { - "id": <32-bytes lowercase hex-encoded sha256 of the the serialized event data> + "id": <32-bytes lowercase hex-encoded sha256 of the the serialized event data>, "pubkey": <32-bytes lowercase hex-encoded public key of the app owner issuing the badge>, - "created_at": , + "created_at": , "kind": XX, "tags": [ - ["p", <32-bytes hex pubkey of the member receiving the badge>], - ["badge_type", ] + ["p", <32-bytes hex pubkey of the member receiving the badge> ], + ["badge_type", ] ], - "content": , + "content": , "sig": <64-bytes signature of the sha256 hash of the serialized event data, which is the same as the "id" field> } ``` `p tag` MUST contain exactly one entry, the pubkey of the claim's subject. -`badge_type` identifies badge type. Current accept values are `0 - Achievement Badge` and `1 - Membership Badge` +`badge_type` is used as a reference field to calcuate badge image url. Like Kind 0, badges provide metadata about a pubkey, but the event is sent (and thus signed) by the app owner, not the subject's pubkey. -Two badge types are defined, with the possibility of adding more if required. +### Badge Content Schema -### 0 - Achievement Badge -Awarded to a user for an achievement. - -Achievement Badge Schema ```json { - "issuer_name": , - "name": , + "name": , "message": , - "image": , - "score": + "expiry_date": , + } ```` -Example as content +Examples as stringified JSON object in content + +Badge for an achievement ```json { - "content": "{\"issuer_name\": \"nostr.directory\", \"name\": \"Donation\", \"message\": \"User has sent a sats donation to noster.directory.\", \"image\": \"https://myapp.com/badges/donation.svg\", \"score\": 1000}", - ... + ... + "content": "{\"name\": \"Donation\", \"message\": \"User has sent a sats donation to noster.directory.\"}", + ... } ```` -- issuer_name - name of app or community. e.g. "Nosterplebs", "Continuous Delivery Foundation" -- name - name of the achievement. e.g. "Donation", "Top Bug Crusher" -- message - Text description of the achievement -- image - url link to square badge image (1:1 ratio). Ideally .svg image, but if not SHOULD be 32 x 32 pixels. -- score - optional integer value. Include when you need to rank achievements. e.g. Display "High Score" list in descending order +Badge for a membership +```json +{ + ... + "content": "{\"name\": \"My App Premium Supporter\", \"message\": \"User is a premium supporter of My App.\", \"expiry_date\": 1674818142}", + ... +} +```` + +- name - name of the badge. e.g. "Donation", "Top Bug Crusher" +- message - Text description for the badge +- expiry_date - Optional - Intended use is for when a badge is associated with additional client or relay permissions that expire. For example, issuing a badge for paid subscribers that removes rate limits for their pubkey. Client may include additional key/value pairs in content. -### 1 - Membership Badge -Sent by app owner to confirm that a user is the member of app, community or group. +See for an example of fields for linking other social media accounts to a Nostr pubkey using badges. + +### Using `badge_type` to get badge image + +To support images for their badges, an app owner first sets a NIP-52 template url in their Kind 0: content (similar to how NIP-05 works). -Membership Badge Schema ```json { - "issuer_name": , - "image": , - "role": , - "id": , - "alias": , - "member_since": , - "expiry_date": , - "profile": , - "followers": , - "connections": , - "posts": + "pubkey": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9", + "kind": 0, + "content": "{\"name\": \"My App\", \"nip52\": \"https://myapp.com/[badge_type].svg\"}" + ... } ```` -Example as content -```json -{ - "content": "{\"issuer_name\": \"Nostrplebs\", \"image\": \"https://nostrplebs.com/images/member.svg\", \"role\": \"Premium Member\"}", - ... -} -```` +Clients SHOULD replace the `[badge_type]` place holder in the template URL with the `badge_type` value from the event, to calcuate the badge image url. -- issuer_name - name of app or community. e.g. "Nostrplebs", "Continuous Delivery Foundation" -- image - url link to square badge image (1:1 ratio). Ideally .svg image, but if not SHOULD be 32 x 32 pixels. -- role - role of user within the commnity. e.g. "Moderator", "Administrator", "Reviewer" -- id - unique user ID, usually system generated e.g. Twitter: user.fields.id -- alias - unqiue user ID set by user e.g. Twitter: user.username -- member_since - date user first became a member -- expiry_date - include if membership has expiry date, usually for paid memberships -- profile - url link to user's profile wihin the app -- followers - count of followers, if applicable -- connections - count of connections e.g. On LinkedIn, a user accepts connections for other users, but anyone can become a follower -- posts - total count of tweets, posts, messages, etc. +The `[badge_type]` place holder can be in the URL path, part of a file name, as a query parameter, or omitted all together if an app owner wants to the use the same images for all badges. + +It is recommended that badge images have a square aspect ratio for display compatibility between clients. -Client may include additional key/value pairs in content. Motivation ----------