highperfocused/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2025-04-02 09:00:23 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: add badge definition event

Browse Source
This commit is contained in:
Ricardo Arturo Cabral Mejía 2023-02-22 00:35:28 -05:00
parent 38d8184cc4
commit 4e0a91f7db
No known key found for this signature in database
GPG Key ID: 5931EBF43A650245
2 changed files with 94 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
58.md
View File

@ -6,102 +6,126 @@ Badges
`draft` `optional` `author:cameri`
A special event meaning "Badge" is defined as an event with kind `8` having a list of `p` tags,
one for each pubkey the author (issuer) wishes to award. A parameterized replaceable event meaning "Profile Badges" is defined as an event with kind `30008` with a `d` tag identifier equal to `profile_badges` and having an ordered list of `e` tags, one for each badge the user wishes to show on their profile. Badges as immutable events are non-transferrable.
Three special events are used to define, award and display badges in
user profiles:
### Badge event
1. A "Badge Definition" event is defined as a parameterized replaceable event
with kind `30009` having a `d` tag with a value that uniquely identifies
the badge (e.g. `bravery`) published by the badge issuer. Badge definitions can
be updated.
A Badge's `content` field is a JSON-stringified object containing the fields `short_desc`, `image`, `thumbs` and optionally `long_desc` and `sha256sums`. In the case where `long_desc` is omitted, it is treated the same equal to `short_desc`.
2. A "Badge Award" event is a kind `8` event with a single `a` tag referencing
a "Define Badge" event and one or more `p` tags, one for each pubkey the
badge issuer wishes to award. The value for the `a` tag MUST follow the format
defined in [NIP-33](33.md). Awarded badges are immutable and non-transferrable.
The `short_desc` and `long_desc` fields are strings that may contain the meaning behind the badge and/or
the reason of it's issuance.
3. A "Profile Badges" event is defined as a parameterized replaceable event
with kind `30008` with a `d` tag with the value `profile_badges`.
Profile badges contain an ordered list of pairs of `a` and `e` tags referencing a `Badge Definition` and a `Badge Award` for each badge to be displayed.
The `image` field is the URL of a high-resolution image representing the badge.
### Badge Definition event
The `thumbs` field is an object containing thumbnail versions of the image referenced in the `image` field. The format of the keys are the dimensions `width`x`height` in pixels and the value is an URL pointing to respective thumbnail image.
The following tags MUST be present:
The `sha256sums` field is an object containing the fields `image` and one for every thumbnail in the `thumbs` object with the same key. The values are the SHA256 digests of each one of image files.
- `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 `width`x`height` 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 it's 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 `width`x`height` in pixels.
### 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 receive is unbounded. The Profile Badge event allows individual users to choose
the badges (and order) to show on their profiles.
The number of badges a pubkey can be awarded is unbounded. The Profile Badge
event allows individual users to accept and choose the display order of awarded badges to show on their profiles.
The content is not used and SHOULD be blank.
The following tags MUST be present:
The `e` tags in the Profile Badge event MUST reference kind `8` events containing a `p` tag that matches that of the Profile Badge. Badges that don't meet this criteria MUST be ignored.
- 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 in recognition, in gratitude, for participation, or in appreciation of a certain goal, task or cause.
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
Badge issuers MAY include some Proof of Work as per [NIP-13](13.md) when minting badges to embed them with an energy cost, arguably making them more special and valuable for users that wish to collect them.
Badge issuers MAY include some Proof of Work as per [NIP-13](13.md) when minting Badge Definitions or Badge Awards to embed them with a combined energy cost, arguably making them more special and valuable for users that wish to collect them.
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 sizes are: 512x512 (xl), 256x256 (l), 64x64 (m), 32x32 (s) and 16x16 (xs).
Badge thumbnail image recommended dimensions are: 512x512 (xl), 256x256 (l), 64x64 (m), 32x32 (s) and 16x16 (xs).
Clients SHOULD render the most appropriate badge thumbnail according to the number of badges chosen by the user and space available. Clients SHOULD render the high-res version on user action (click, tap, hover).
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.
### Example of Badge Event
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
Event:
```json
{
"id": "<charlie's issued badge event id>",
"kind": 8,
"pubkey": "<charlie's (issuer) pubkey>",
"pubkey": "alice",
"kind": 30009,
"tags": [
["p", "<alice's (recipient) pubkey in hex>"]
["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"],
],
"content": "<json stringified object shown below>",
...other fields...
...
}
```
Content:
### Example of Badge Award event
```json
{
"long_desc": "This user joined our relay 2 years ago.",
"short_desc": "Two-Year Club",
"image": "https://relay.nostr/badges/two-year-club.png",
"thumbs": {
"512x512": "https://relay.nostr/badges/two-year-club-512x512.png",
"256x256": "https://relay.nostr/badges/two-year-club-256x256.png",
"128x128": "https://relay.nostr/badges/two-year-club-128x128.png",
"64x64": "https://relay.nostr/badges/two-year-club-64x64.png",
"32x32": "https://relay.nostr/badges/two-year-club-32x32.png",
"16x16": "https://relay.nostr/badges/two-year-club-16x16.png"
},
"sha256sums": {
"image": "8d43b3081c8091147e03e41878604606c8aa53d1337d49a4d5e0e8c29c223798",
"512x512": "af94c2afee5321b6acbca7ba00fcfa4ae2e103dda3a3a038e8b0aec4207ef164",
"256x256": "8c1eaf36d0353e20e30511c473411f1df0b9e58f68daadad972a8a6955824a0e",
"128x128": "86b0ebe1cf924f39a0eb4cfde5cdfe8a271b882284fc4f1c353bf6589eef1870",
"64x64": "a92ec141189c8e0228d8c388b9c0e822ecf1347367b834c43c7e82427569e06d",
"32x32": "6afa09c719f0729253ce8034618743d3a3aadd7aa4215554b7e5aa72b46c41a9",
"16x16": "abacf2675c05b7710cf853800a95e4191c10b2005540a39adb4b7cdda617249b"
}
"id": "<badge award event id>",
"kind": 8,
"pubkey": "alice",
"tags": [
["a", "30009:alice:bravery"],
["p", "bob", "wss://relay"],
["p", "charlie", "wss://relay"],
],
...
}
```
### Example of a Profile Badges Event
### Example of a Profile Badges event
Honorable Bob The Brave:
```json
{
"kind": 30008,
"pubkey": "<alice's pubkey in hex>",
"content": "",
"pubkey": "bob",
"tags": [
["d", "profile_badges"],
["e", "<charlie's issued badge event id>"]
["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...
...
}
```

22
README.md
View File

@ -30,7 +30,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh
- [NIP-36: Sensitive Content](36.md)
- [NIP-40: Expiration Timestamp](40.md)
- [NIP-42: Authentication of clients to relays](42.md)
- [NIP-46: Nostr Connect](46.md)
- [NIP-46: Nostr Connect](46.md)
- [NIP-50: Keywords filter](50.md)
- [NIP-56: Reporting](56.md)
- [NIP-57: Lightning Zaps](57.md)
@ -46,6 +46,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh
| 4 | Encrypted Direct Messages | [4](04.md) |
| 5 | Event Deletion | [9](09.md) |
| 7 | Reaction | [25](25.md) |
| 8 | Badge Award | [58](58.md) |
| 40 | Channel Creation | [28](28.md) |
| 41 | Channel Metadata | [28](28.md) |
| 42 | Channel Message | [28](28.md) |
@ -63,8 +64,8 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh
| 10000-19999 | Replaceable Events | [16](16.md) |
| 20000-29999 | Ephemeral Events | [16](16.md) |
| 30000-39999 | Parameterized Replaceable Events | [33](33.md) |
| 30008 | Profile Badges | [58](58.md) |
| 30009 | Badge Definition | [58](58.md) |
## Message types
@ -91,6 +92,7 @@ When experimenting with kinds, keep in mind the classification introduced by [NI
## Standardized Tags
<<<<<<< HEAD
| name | value | other parameters | NIP |
| ---------- | ----------------------- | ----------------- | ------------------------ |
| e | event id (hex) | relay URL, marker | [1](01.md), [10](10.md) |
@ -103,6 +105,20 @@ When experimenting with kinds, keep in mind the classification introduced by [NI
| subject | subject | | [14](14.md) |
| d | identifier | | [33](33.md) |
| expiration | unix timestamp (string) | | [40](40.md) |
=======
| name | value | other parameters | NIP |
| ---------- | -------------------------- | ----------------- | ------------------------ |
| e | event id (hex) | relay URL, marker | [1](01.md), [10](10.md) |
| p | pubkey (hex) | relay URL | [1](01.md) |
| r | a reference (URL, etc) | | [12](12.md) |
| t | hashtag | | [12](12.md) |
| a | kind, pubkey, d-identifier | | [33](33.md) |
| g | geohash | | [12](12.md) |
| nonce | random | | [13](13.md) |
| subject | subject | | [14](14.md) |
| d | identifier | | [33](33.md) |
| expiration | unix timestamp (string) | | [40](40.md) |
>>>>>>> 8fc286a (docs: add badge definition event)
## Criteria for acceptance of NIPs