/ 
Net-Nostr-0.002000
/ Net::Nostr::Event

NAME

Net::Nostr::Event - Nostr protocol event object

SYNOPSIS

use Net::Nostr::Event;
use Net::Nostr::Key;

# Typical usage: create via Key (sets pubkey and signs automatically)
my $key   = Net::Nostr::Key->new;
my $event = $key->create_event(kind => 1, content => 'hello', tags => []);
say $event->id;   # 64-char hex sha256
say $event->sig;  # 128-char hex signature

# Manual construction (e.g. when parsing from the wire)
my $event = Net::Nostr::Event->new(
    pubkey     => $key->pubkey_hex,
    kind       => 1,
    content    => 'hello world',
    tags       => [['t', 'nostr']],
    created_at => 1700000000,
);

say $event->json_serialize;  # canonical JSON array for hashing
my $hash = $event->to_hash;  # { id, pubkey, created_at, kind, tags, content, sig }

DESCRIPTION

Represents a Nostr event as defined by NIP-01. Handles canonical JSON serialization, automatic ID computation, tag management, kind classification, and signature verification.

CONSTRUCTOR

new

my $event = Net::Nostr::Event->new(
    pubkey     => $hex_pubkey,
    kind       => 1,
    content    => 'hello',
    tags       => [['p', $pubkey]],
    created_at => time(),
    sig        => $hex_sig,
);

Creates a new event. pubkey, kind, and content are required. tags defaults to [], created_at defaults to time(), and id is automatically computed from the canonical serialization. If id is passed explicitly (e.g. when parsing from the wire), it is preserved as-is. Croaks if kind is outside the valid range (0-65535).

METHODS

id

my $id = $event->id;  # '3bf0c63f...' (64-char hex)

Returns the event ID, a SHA-256 hex digest of the canonical serialization.

pubkey

my $pubkey = $event->pubkey;

Returns the author's public key as a 64-character hex string.

created_at

my $ts = $event->created_at;  # Unix timestamp

Returns the event creation timestamp.

kind

my $kind = $event->kind;  # 1

Returns the event kind (integer).

tags

my $tags = $event->tags;  # [['p', 'abc...'], ['e', 'def...']]

Returns the tags arrayref. Each tag is an arrayref of strings.

content

my $content = $event->content;

Returns the event content string.

sig

my $sig = $event->sig;           # get
$event->sig($hex_signature);     # set

Gets or sets the Schnorr signature as a 128-character hex string.

json_serialize

my $json = $event->json_serialize;

Returns the canonical JSON serialization used for ID computation: [0, pubkey, created_at, kind, tags, content]. The output is UTF-8 encoded with no extra whitespace.

to_hash

my $hash = $event->to_hash;
# { id => '...', pubkey => '...', created_at => 1000,
#   kind => 1, tags => [...], content => '...', sig => '...' }

Returns a hashref with all seven event fields. Useful for JSON encoding the full event object.

add_pubkey_ref

$event->add_pubkey_ref('deadbeef' x 8);
# tags now includes ['p', 'deadbeef...']

Appends a p tag referencing the given pubkey hex string.

add_event_ref

$event->add_event_ref('abcd1234' x 8);
# tags now includes ['e', 'abcd1234...']

Appends an e tag referencing the given event ID hex string.

d_tag

my $d = $event->d_tag;  # '' if no d tag

Returns the value of the first d tag, or empty string if none exists. Used for addressable event deduplication (kinds 30000-39999).

my $event = Net::Nostr::Event->new(
    pubkey => 'a' x 64, kind => 30023,
    content => '', tags => [['d', 'my-article']],
);
say $event->d_tag;  # 'my-article'

is_regular

$event->is_regular;  # true for kinds 1, 2, 4-44, 1000-9999

Returns true if the event kind is a regular (non-replaceable, non-ephemeral, non-addressable) kind.

is_replaceable

$event->is_replaceable;  # true for kinds 0, 3, 10000-19999

Returns true if the event kind is replaceable (only latest per pubkey+kind is kept).

is_ephemeral

$event->is_ephemeral;  # true for kinds 20000-29999

Returns true if the event kind is ephemeral (broadcast but never stored).

is_addressable

$event->is_addressable;  # true for kinds 30000-39999

Returns true if the event kind is addressable (only latest per pubkey+kind+d_tag is kept).

verify_sig

my $valid = $event->verify_sig($key);

Verifies the event's Schnorr signature against the given Net::Nostr::Key object. Returns true if the signature is valid.

my $key   = Net::Nostr::Key->new;
my $event = $key->create_event(kind => 1, content => 'signed', tags => []);
say $event->verify_sig($key);  # 1

SEE ALSO

Net::Nostr, Net::Nostr::Key