/ 
Net-Nostr-1.003000
/ Net::Nostr::Torrent

NAME

Net::Nostr::Torrent - NIP-35 Torrents

SYNOPSIS

use Net::Nostr::Torrent;

# Create a torrent event (kind 2003)
my $event = Net::Nostr::Torrent->to_event(
    pubkey      => $hex_pubkey,
    info_hash   => 'd4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3',
    title       => 'Example Torrent',
    content     => 'A long description',
    files       => [
        ['video.mkv', '4294967296'],
        ['subs.srt', '2048'],
    ],
    trackers    => ['udp://tracker.example.com:6969'],
    identifiers => ['imdb:tt15239678', 'tmdb:movie:693134'],
    hashtags    => ['movie', '4k'],
);

# Create a torrent comment (kind 2004)
my $comment = Net::Nostr::Torrent->comment(
    pubkey  => $hex_pubkey,
    content => 'Great torrent!',
    tags    => [['e', $torrent_event_id, '', 'root']],
);

# Parse a torrent event
my $torrent = Net::Nostr::Torrent->from_event($event);
say $torrent->title;       # Example Torrent
say $torrent->info_hash;   # d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3

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

DESCRIPTION

Implements NIP-35 (Torrents). Kind 2003 events are a simple torrent index containing enough information to search for content and construct a magnet link. No torrent files exist on nostr.

Kind 2004 events are torrent comments that work exactly like kind 1 text notes and should follow NIP-10 for tagging.

Tags

  • x - V1 BitTorrent Info Hash, as seen in the magnet link magnet:?xt=urn:btih:HASH

  • title - The torrent title

  • file - A file entry including the full path and file size in bytes

  • tracker - (Optional) A tracker URL for this torrent

Tag prefixes

Tag prefixes (i tags) label content with external references:

  • tcat - Comma-separated text category path (e.g. tcat:video,movie,4k)

  • newznab - Category ID from newznab

  • tmdb - The Movie Database ID (e.g. tmdb:movie:693134)

  • ttvdb - TV Database ID (e.g. ttvdb:movie:290272)

  • imdb - IMDB ID (e.g. imdb:tt15239678)

  • mal - MyAnimeList ID (e.g. mal:anime:9253, mal:manga:17517)

  • anilist - AniList ID

A second-level prefix should be included where the database supports multiple media types.

To make torrents searchable by general category, you SHOULD include t tags like movie, tv, HD, UHD, etc.

CONSTRUCTOR

new

my $torrent = Net::Nostr::Torrent->new(
    info_hash => 'abc123',
    title     => 'Example',
);

Creates a new Net::Nostr::Torrent object. Croaks on unknown arguments. Array fields (files, trackers, identifiers, hashtags) default to []. description defaults to ''.

CLASS METHODS

to_event

my $event = Net::Nostr::Torrent->to_event(
    pubkey      => $hex_pubkey,          # required
    info_hash   => $info_hash,           # required (x tag)
    title       => $title,               # required (title tag)
    content     => $description,         # optional, defaults to ''
    files       => [[$path, $size]],     # optional
    trackers    => [$tracker_url],       # optional
    identifiers => [$id_string],         # optional (i tags)
    hashtags    => [$tag],               # optional (t tags)
    created_at  => time(),               # optional
);

Creates a kind 2003 torrent Net::Nostr::Event. info_hash and title are required. The info hash becomes the x tag. Files become file tags with path and size. Trackers become tracker tags. Identifiers become i tags. Hashtags become t tags.

comment

my $event = Net::Nostr::Torrent->comment(
    pubkey  => $hex_pubkey,
    content => 'Great torrent!',
    tags    => [['e', $torrent_id, '', 'root']],
);

Creates a kind 2004 torrent comment Net::Nostr::Event. Works exactly like a kind 1 event and should follow NIP-10 for tagging. All arguments are passed through to "new" in Net::Nostr::Event.

from_event

my $torrent = Net::Nostr::Torrent->from_event($event);

Parses a kind 2003 or 2004 event into a Net::Nostr::Torrent object. Returns undef for unrecognized kinds. For kind 2003, extracts info_hash, title, description, files, trackers, identifiers, and hashtags. For kind 2004, only description (from content) is populated.

validate

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

Validates a NIP-35 event. Croaks if:

  • Kind is not 2003 or 2004

  • Kind 2003 missing x tag (info hash)

  • Kind 2003 missing title tag

Returns 1 on success.

ACCESSORS

info_hash

The V1 BitTorrent Info Hash (x tag value).

title

The torrent title.

description

The long description (event content). Defaults to ''.

files

Arrayref of arrayrefs, each containing a file path and size in bytes. Defaults to [].

trackers

Arrayref of tracker URL strings. Defaults to [].

identifiers

Arrayref of i tag value strings (tag prefixes like imdb:tt1234567). Defaults to [].

hashtags

Arrayref of t tag value strings. Defaults to [].

SEE ALSO

NIP-35, Net::Nostr, Net::Nostr::Event