Nostr.NIP19 (Nostr Lib v0.2.0)

View Source

NIP-19: Bech32-encoded shareable identifiers with metadata.

This module provides encoding and decoding of NIP-19 entities that include TLV (Type-Length-Value) metadata such as relay hints.

Supported Formats

Bare keys and IDs (simple 32-byte data)

  • npub - public key
  • nsec - private key
  • note - event ID

Shareable identifiers with metadata (TLV encoded)

  • nprofile - profile with optional relay hints
  • nevent - event with optional relay hints, author, and kind
  • naddr - addressable event coordinate with identifier, author, kind, and optional relays

Examples

# Encode a profile with relay hints
iex> Nostr.NIP19.encode_nprofile("3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d", ["wss://relay.example.com"])
{:ok, "nprofile1qqsrhuxx8l9ex335q7he0f09aej04zpazpl0ne2cgukyawd24mayt8gpvem8x6"}

# Decode an nprofile to get pubkey and relays
iex> {:ok, profile} = Nostr.NIP19.decode_nprofile("nprofile1qqsrhuxx8l9ex335q7he0f09aej04zpazpl0ne2cgukyawd24mayt8gpvem8x6")
iex> profile.pubkey
"3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"

Summary

Functions

decode(bech32)

Decodes any NIP-19 bech32 string and returns the appropriate struct or hex value.

decode_naddr(bech32)

Decodes an naddr bech32 string to an Address struct.

decode_nevent(bech32)

Decodes an nevent bech32 string to an Event struct.

decode_nprofile(bech32)

Decodes an nprofile bech32 string to a Profile struct.

encode_naddr(identifier, pubkey, kind, relays \\ [])

Encodes an addressable event coordinate as an naddr bech32 string.

encode_nevent(event_id, opts \\ [])

Encodes an event as an nevent bech32 string with optional metadata.

encode_nprofile(pubkey, relays \\ [])

Encodes a profile as an nprofile bech32 string with optional relay hints.

Functions

decode(bech32)

@spec decode(String.t()) ::
  {:ok, :npub | :nsec | :note, String.t()}
  | {:ok, :nprofile, Nostr.NIP19.Profile.t()}
  | {:ok, :nevent, Nostr.NIP19.Event.t()}
  | {:ok, :naddr, Nostr.NIP19.Address.t()}
  | {:error, term()}

Decodes any NIP-19 bech32 string and returns the appropriate struct or hex value.

Returns:

  • {:ok, :npub, hex} for public keys
  • {:ok, :nsec, hex} for secret keys
  • {:ok, :note, hex} for event IDs
  • {:ok, :nprofile, %Profile{}} for profiles
  • {:ok, :nevent, %Event{}} for events
  • {:ok, :naddr, %Address{}} for addressable events
  • {:error, reason} on failure

Examples

iex> Nostr.NIP19.decode("npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6")
{:ok, :npub, "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"}

decode_naddr(bech32)

@spec decode_naddr(String.t()) :: {:ok, Nostr.NIP19.Address.t()} | {:error, term()}

Decodes an naddr bech32 string to an Address struct.

Examples

iex> {:ok, addr} = Nostr.NIP19.decode_naddr(naddr_string)
iex> addr.identifier
"my-article"
iex> addr.kind
30023

decode_nevent(bech32)

@spec decode_nevent(String.t()) :: {:ok, Nostr.NIP19.Event.t()} | {:error, term()}

Decodes an nevent bech32 string to an Event struct.

Examples

iex> {:ok, event} = Nostr.NIP19.decode_nevent(nevent_string)
iex> event.event_id
"b9f5441e45ca39179320e0031cfb18e34078673dcc3d3e3a3b3a981571b14f4e"

decode_nprofile(bech32)

@spec decode_nprofile(String.t()) :: {:ok, Nostr.NIP19.Profile.t()} | {:error, term()}

Decodes an nprofile bech32 string to a Profile struct.

Examples

iex> {:ok, profile} = Nostr.NIP19.decode_nprofile("nprofile1qqsrhuxx8l9ex335q7he0f09aej04zpazpl0ne2cgukyawd24mayt8gpp4mhxue69uhhytnc9e3k7mgpz4mhxue69uhkg6nzv9ejuumpv34kytnrdaksjlyr9p")
iex> profile.pubkey
"3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"
iex> profile.relays
["wss://r.x.com", "wss://djbas.sadkb.com"]

encode_naddr(identifier, pubkey, kind, relays \\ [])

@spec encode_naddr(String.t(), String.t(), non_neg_integer(), [String.t()]) ::
  {:ok, String.t()} | {:error, :invalid_pubkey}

Encodes an addressable event coordinate as an naddr bech32 string.

Parameters

  • identifier - the "d" tag value (use "" for normal replaceable events)
  • pubkey - 32-byte hex-encoded author public key
  • kind - event kind number
  • relays - list of relay URLs (optional)

Examples

iex> Nostr.NIP19.encode_naddr("my-article", "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d", 30023)
{:ok, naddr}

encode_nevent(event_id, opts \\ [])

@spec encode_nevent(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, :invalid_event_id | :invalid_author}

Encodes an event as an nevent bech32 string with optional metadata.

Parameters

  • event_id - 32-byte hex-encoded event ID
  • opts - keyword list with optional :relays, :author, and :kind

Examples

iex> Nostr.NIP19.encode_nevent("b9f5441e45ca39179320e0031cfb18e34078673dcc3d3e3a3b3a981571b14f4e")
{:ok, "nevent1qqsw04gswg4e5wr9uecqrxpelvvwxsupmhd8pa8c6ww6fvz4cmg578gpzemhxue69uhhyetvv9ujuurjd9kkzmpwdejhgxz0p8m"}

iex> Nostr.NIP19.encode_nevent("b9f5441e45ca39179320e0031cfb18e34078673dcc3d3e3a3b3a981571b14f4e", relays: ["wss://relay.example.com"], author: "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d", kind: 1)
{:ok, nevent}

encode_nprofile(pubkey, relays \\ [])

@spec encode_nprofile(String.t(), [String.t()]) ::
  {:ok, String.t()} | {:error, :invalid_pubkey}

Encodes a profile as an nprofile bech32 string with optional relay hints.

Parameters

  • pubkey - 32-byte hex-encoded public key
  • relays - list of relay URLs (optional, defaults to empty)

Examples

iex> Nostr.NIP19.encode_nprofile("3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d")
{:ok, "nprofile1qqsrhuxx8l9ex335q7he0f09aej04zpazpl0ne2cgukyawd24mayt8gxerzmt"}

iex> Nostr.NIP19.encode_nprofile("3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d", ["wss://r.x.com"])
{:ok, "nprofile1qqsrhuxx8l9ex335q7he0f09aej04zpazpl0ne2cgukyawd24mayt8gpz4mhxue69uhkc6t8dph8x3k7d"}