/ 
Net-Nostr-Core-1.001000
/ Net::Nostr::RelayAccess

NAME

Net::Nostr::RelayAccess - NIP-43 Relay Access Metadata and Requests

SYNOPSIS

use Net::Nostr::RelayAccess;

# Role definition (kind 33534)
my $event = Net::Nostr::RelayAccess->role_definition(
    pubkey      => $hex_pubkey,
    role_id     => '28b7e50f',
    label       => 'king',
    description => 'ruler of the relay',
    color       => 37,
    order       => 1,
);

# Membership list (kind 13534)
my $event = Net::Nostr::RelayAccess->membership_list(
    pubkey  => $hex_pubkey,
    members => [$member_pk1, { pubkey => $member_pk2, roles => ['28b7e50f'] }],
);

# Add member (kind 8000)
my $event = Net::Nostr::RelayAccess->add_member(
    pubkey => $hex_pubkey,
    member => $member_pk,
);

# Remove member (kind 8001)
my $event = Net::Nostr::RelayAccess->remove_member(
    pubkey => $hex_pubkey,
    member => $member_pk,
);

# Join request (kind 28934)
my $event = Net::Nostr::RelayAccess->join_request(
    pubkey => $hex_pubkey,
    claim  => $invite_code,
);

# Invite response (kind 28935)
my $event = Net::Nostr::RelayAccess->invite(
    pubkey => $hex_pubkey,
    claim  => $generated_code,
);

# Leave request (kind 28936)
my $event = Net::Nostr::RelayAccess->leave_request(
    pubkey => $hex_pubkey,
);

# Parse any relay access event
my $parsed = Net::Nostr::RelayAccess->from_event($event);

# Validate
Net::Nostr::RelayAccess->validate($event);

DESCRIPTION

Implements NIP-43 (Relay Access Metadata and Requests). Seven event kinds are used:

  • Membership List (kind 13534) - A replaceable event listing pubkeys that have access to a relay. MUST be signed by the relay's NIP-11 self pubkey. Contains member tags with hex pubkeys and optional role ids.

  • Role Definition (kind 33534) - An addressable event defining a relay role. Contains a d tag with the role id and optional label, description, color, and order tags.

  • Add Member (kind 8000) - Published when a member is added to a relay. Contains a p tag with the member's hex pubkey.

  • Remove Member (kind 8001) - Published when a member is removed from a relay. Contains a p tag with the member's hex pubkey.

  • Join Request (kind 28934) - An ephemeral event sent by a user to request admission to a relay. MUST contain a claim tag with an invite code.

  • Invite (kind 28935) - An ephemeral event returned by a relay with a claim string. Relays generate claims on the fly when requested.

  • Leave Request (kind 28936) - An ephemeral event sent by a user to revoke their own access.

All seven kinds MUST include a NIP-70 ["-"] protected tag.

CONSTRUCTOR

new

Accepts named arguments as either a flat list or a single hash reference.

my $ra = Net::Nostr::RelayAccess->new(
    members => [$member_pk],
);

Creates a new Net::Nostr::RelayAccess object. Croaks on unknown arguments. members defaults to [].

CLASS METHODS

role_definition

my $event = Net::Nostr::RelayAccess->role_definition(
    pubkey      => $hex_pubkey,      # required
    role_id     => '28b7e50f',       # required, d tag
    label       => 'king',           # optional
    description => 'ruler',          # optional
    color       => 37,               # optional, 0..360
    order       => 1,                # optional integer
);

Creates a kind 33534 role definition Net::Nostr::Event. Automatically includes the NIP-70 ["-"] protected tag.

membership_list

my $event = Net::Nostr::RelayAccess->membership_list(
    pubkey  => $hex_pubkey,          # required
    members => [
        $member_pk,
        { pubkey => $other_pk, roles => ['28b7e50f'] },
    ],                               # optional, defaults to []
);

Creates a kind 13534 membership list Net::Nostr::Event. Automatically includes the NIP-70 ["-"] protected tag. A plain member pubkey becomes ["member", $pubkey]. A hashref member adds role ids after the pubkey. members and hashref roles values must be arrayrefs.

add_member

my $event = Net::Nostr::RelayAccess->add_member(
    pubkey => $hex_pubkey,           # required
    member => $member_pk,            # required (p tag)
);

Creates a kind 8000 add-member Net::Nostr::Event. Automatically includes the NIP-70 ["-"] protected tag.

remove_member

my $event = Net::Nostr::RelayAccess->remove_member(
    pubkey => $hex_pubkey,           # required
    member => $member_pk,            # required (p tag)
);

Creates a kind 8001 remove-member Net::Nostr::Event. Automatically includes the NIP-70 ["-"] protected tag.

join_request

my $event = Net::Nostr::RelayAccess->join_request(
    pubkey => $hex_pubkey,           # required
    claim  => $invite_code,          # required (claim tag)
);

Creates a kind 28934 join request Net::Nostr::Event. Automatically includes the NIP-70 ["-"] protected tag. The claim tag contains the invite code.

invite

my $event = Net::Nostr::RelayAccess->invite(
    pubkey => $hex_pubkey,           # required
    claim  => $generated_code,       # required (claim tag)
);

Creates a kind 28935 invite Net::Nostr::Event. Automatically includes the NIP-70 ["-"] protected tag. The claim tag contains the generated invite code.

leave_request

my $event = Net::Nostr::RelayAccess->leave_request(
    pubkey => $hex_pubkey,           # required
);

Creates a kind 28936 leave request Net::Nostr::Event. Automatically includes the NIP-70 ["-"] protected tag. No other tags are required.

from_event

my $ra = Net::Nostr::RelayAccess->from_event($event);

Parses a kind 13534, 33534, 8000, 8001, 28934, 28935, or 28936 event into a Net::Nostr::RelayAccess object. Returns undef for unrecognized kinds.

validate

Net::Nostr::RelayAccess->validate($event);

Validates a NIP-43 event. Croaks if:

  • Kind is not 13534, 33534, 8000, 8001, 28934, 28935, or 28936

  • Missing NIP-70 ["-"] protected tag

  • Kind 8000/8001 missing p tag

  • Kind 28934/28935 missing claim tag

  • Kind 33534 missing d tag

Returns 1 on success.

ACCESSORS

members

Arrayref of member entries from member tags (membership list only). Entries without roles are hex pubkey strings. Entries with roles are hashrefs with pubkey and roles. Defaults to [].

member

Hex pubkey from p tag (add/remove member only).

claim

Invite code string from claim tag (join request/invite only).

role_id

Role id from the d tag (role definition only).

label

Optional role label.

description

Optional role description.

color

Optional role color value, 0 through 360.

order

Optional role sort order.

SEE ALSO

NIP-43, NIP-70, Net::Nostr, Net::Nostr::Event