NAME
Net::Nostr::Badge - NIP-58 Badges
SYNOPSIS
use Net::Nostr::Badge;
# Define a badge (kind 30009, addressable)
my $event = Net::Nostr::Badge->definition(
pubkey => $issuer_pubkey,
identifier => 'bravery',
name => 'Medal of Bravery',
description => 'Awarded to users demonstrating bravery',
image => ['https://nostr.academy/awards/bravery.png', '1024x1024'],
thumbs => [
['https://nostr.academy/awards/bravery_256x256.png', '256x256'],
],
);
# Award a badge (kind 8)
my $award = Net::Nostr::Badge->award(
pubkey => $issuer_pubkey,
badge => '30009:issuer_pk:bravery',
awardees => [[$recipient_pk, 'wss://relay']],
);
# Display badges on profile (kind 10008, replaceable)
my $profile = Net::Nostr::Badge->profile_badges(
pubkey => $user_pubkey,
badges => [
{ definition => '30009:issuer:bravery', award => $award_event_id },
],
);
# Categorize badges into a set (kind 30008, addressable)
my $set = Net::Nostr::Badge->badge_set(
pubkey => $user_pubkey,
identifier => 'my-favorites',
badges => [
{ definition => '30009:issuer:bravery', award => $award_event_id },
],
);
# Parse any badge event
my $badge = Net::Nostr::Badge->from_event($event);
# Validate
Net::Nostr::Badge->validate($event);DESCRIPTION
Implements NIP-58 (Badges). Four event kinds are used to define, award, display, and categorize badges:
Badge Definition (kind 30009) - Addressable event defining a badge. Published by the badge issuer. Can be updated.
Badge Award (kind 8) - Awards a badge to one or more pubkeys. Immutable and non-transferable.
Profile Badges (kind 10008) - Replaceable event listing badges a user has accepted, in display order.
Badge Set (kind 30008) - Addressable event categorizing accepted badges into labeled groups.
Badge image recommended aspect ratio is 1:1 with a high-res size of 1024x1024 pixels. Recommended thumbnail dimensions are 512x512 (xl), 256x256 (l), 64x64 (m), 32x32 (s), and 16x16 (xs).
CONSTRUCTOR
new
my $badge = Net::Nostr::Badge->new(%fields);Creates a new Net::Nostr::Badge object. Typically returned by "from_event". Croaks on unknown arguments.
CLASS METHODS
definition
my $event = Net::Nostr::Badge->definition(
pubkey => $hex_pubkey, # required
identifier => 'bravery', # required (d tag)
name => 'Medal of Bravery', # optional (MAY)
description => 'Awarded to brave users', # optional (MAY)
image => ['url', '1024x1024'], # optional (MAY, dims optional)
thumbs => [['url', '256x256']], # optional (MAY, dims optional)
created_at => time(), # optional
);Creates a kind 30009 badge definition Net::Nostr::Event. identifier is required and becomes the d tag. All other fields are optional per the spec.
award
my $event = Net::Nostr::Badge->award(
pubkey => $hex_pubkey, # required
badge => '30009:issuer_pk:bravery', # required (a tag)
awardees => [[$pk, 'wss://relay'], [$pk2]], # required (p tags)
);Creates a kind 8 badge award Net::Nostr::Event. badge is the coordinate of a kind 30009 badge definition. awardees is an arrayref of arrayrefs, each containing a pubkey and optional relay URL. At least one awardee is required.
profile_badges
my $event = Net::Nostr::Badge->profile_badges(
pubkey => $hex_pubkey, # required
badges => [ # required
{ definition => '30009:pk:id', award => $eid, award_relay => 'wss://...' },
],
badge_sets => ['30008:pk:set-name'], # optional
);Creates a kind 10008 profile badges Net::Nostr::Event. badges is an arrayref of hashrefs, each with definition (badge coordinate), award (award event id), and optional award_relay. Tags are emitted as consecutive a/e pairs in order. badge_sets optionally references kind 30008 badge set coordinates.
badge_set
my $event = Net::Nostr::Badge->badge_set(
pubkey => $hex_pubkey, # required
identifier => 'my-favorites', # required (d tag)
badges => [ # required
{ definition => '30009:pk:id', award => $eid },
],
);Creates a kind 30008 badge set Net::Nostr::Event. identifier is required and becomes the d tag. badges uses the same format as "profile_badges".
from_event
my $badge = Net::Nostr::Badge->from_event($event);Parses a badge event into a Net::Nostr::Badge object. Recognizes kinds 30009, 8, 10008, and 30008. Returns undef for unrecognized kinds.
For kind 30009 (definition): identifier, name, description, image, thumbs.
For kind 8 (award): badge, awardees.
For kind 10008 (profile badges): badges.
For kind 30008 (badge set): identifier, badges.
Deprecated kind 30008 events with d=profile_badges are treated as equivalent to kind 10008.
Profile badges and badge sets expect consecutive a/e tag pairs. Unpaired a tags (without a following e) and unpaired e tags (without a preceding a) are ignored, per the spec recommendation.
validate
Net::Nostr::Badge->validate($event);Validates a NIP-58 badge event. Croaks if:
Kind is not 30009, 8, 10008, or 30008
Kind 30009 missing
dtagKind 8 missing
atag referencing a kind 30009 definition, or missingptagKind 30008 missing
dtag
Returns 1 on success.
ACCESSORS
identifier
The d tag value (badge definitions and badge sets).
name
The badge name (from name tag), or undef.
description
The badge description (from description tag), or undef.
image
Arrayref of the image URL and optional dimensions (e.g. ['url', '1024x1024']), or undef.
thumbs
Arrayref of arrayrefs, each containing a thumbnail URL and optional dimensions. Defaults to [].
badge
The badge definition coordinate (from a tag in award events).
awardees
Arrayref of arrayrefs, each containing a pubkey and optional relay URL. Defaults to [].
badges
Arrayref of hashrefs for profile badges and badge sets. Each entry has definition, award, and optional award_relay. Defaults to [].
badge_sets
Arrayref of badge set coordinates (from profile badges events). Defaults to [].