Nostr.Message (Nostr Lib v0.2.1)

Nostr message is represented as tuple in Elixir. This module provides functions to generate messages, serialize or parse them.

Summary

Types

count_payload()

parse_reason()

t()

Functions

auth(event)

Generate AUTH message (NIP-42).

close(sub_id)

Generate close message

closed(sub_id, message)

Generate CLOSED message (NIP-01)

count(count, sub_id)

Generate count message (NIP-45).

create_event(event)

Generate post new event message

eose(sub_id)

Generate eose message

event(event, sub_id)

Generate event message

neg_close(sub_id)

Generate negentropy close message (NIP-77)

neg_err(sub_id, reason)

Generate negentropy error message (NIP-77)

neg_msg(sub_id, message)

Generate negentropy message frame (NIP-77)

neg_open(sub_id, filter, initial_message)

Generate negentropy open message (NIP-77)

notice(message)

Generate notice message

ok(event_id, success?, message)

Generate OK message

parse(msg)

Parse binary message to Elixir tuple, if message contains event it will be returned as general Nostr.Event.t() struct.

parse_specific(msg)

Parse binary message to Elixir tuple, if message contains event it will be returned as specific Nostr.Event.t() struct dependent of type of Event

parse_with_reason(msg)

Parse binary message to Elixir tuple and return structured parse errors.

request(filter, sub_id)

Generate request message

serialize(message)

Serialize Elixir tuple message to on-the-wire binary

Types

count_payload()

@type count_payload() :: %{
  :count => integer(),
  optional(:approximate) => boolean(),
  optional(:hll) => binary()
}

parse_reason()

@type parse_reason() ::
  :invalid_message_format
  | :unsupported_json_escape
  | :unsupported_json_literals

t()

@type t() ::
  {:event, Nostr.Event.t()}
  | {:event, binary(), Nostr.Event.t()}
  | {:req, binary(), [Nostr.Filter.t()]}
  | {:close, binary()}
  | {:neg_open, binary(), Nostr.Filter.t(), binary()}
  | {:neg_msg, binary(), binary()}
  | {:neg_close, binary()}
  | {:neg_err, binary(), binary()}
  | {:eose, binary()}
  | {:notice, String.t()}
  | {:ok, binary(), boolean(), String.t()}
  | {:auth, Nostr.Event.t() | binary()}
  | {:count, String.t(),
     Nostr.Filter.t() | [Nostr.Filter.t()] | count_payload()}
  | {:closed, String.t(), String.t()}

Functions

auth(event)

@spec auth(Nostr.Event.t() | %{event: Nostr.Event.t()} | binary()) ::
  {:auth, Nostr.Event.t() | binary()}

Generate AUTH message (NIP-42).

Can be used by relay (with challenge string) or by client (with signed event).

close(sub_id)

@spec close(binary()) :: {:close, binary()}

Generate close message

closed(sub_id, message)

@spec closed(String.t(), String.t()) :: {:closed, String.t(), String.t()}

Generate CLOSED message (NIP-01)

count(count, sub_id)

@spec count(pos_integer() | Nostr.Filter.t() | [Nostr.Filter.t()], binary()) ::
  {:count, binary(), count_payload() | Nostr.Filter.t() | [Nostr.Filter.t()]}

Generate count message (NIP-45).

Can be used to request counts from relay (with filters) or respond with counts (with integer).

Parsed COUNT responses preserve optional approximate and hll keys when present.

create_event(event)

@spec create_event(Nostr.Event.t() | %{event: Nostr.Event.t()}) ::
  {:event, Nostr.Event.t()}

Generate post new event message

eose(sub_id)

@spec eose(binary()) :: {:eose, binary()}

Generate eose message

event(event, sub_id)

@spec event(Nostr.Event.t() | %{event: Nostr.Event.t()}, binary()) ::
  {:event, binary(), Nostr.Event.t()}

Generate event message

neg_close(sub_id)

@spec neg_close(binary()) :: {:neg_close, binary()}

Generate negentropy close message (NIP-77)

neg_err(sub_id, reason)

@spec neg_err(binary(), binary()) :: {:neg_err, binary(), binary()}

Generate negentropy error message (NIP-77)

neg_msg(sub_id, message)

@spec neg_msg(binary(), binary()) :: {:neg_msg, binary(), binary()}

Generate negentropy message frame (NIP-77)

neg_open(sub_id, filter, initial_message)

@spec neg_open(binary(), Nostr.Filter.t(), binary()) ::
  {:neg_open, binary(), Nostr.Filter.t(), binary()}

Generate negentropy open message (NIP-77)

notice(message)

@spec notice(String.t()) :: {:notice, String.t()}

Generate notice message

ok(event_id, success?, message)

@spec ok(binary(), boolean(), String.t()) :: {:ok, binary(), boolean(), String.t()}

Generate OK message

parse(msg)

@spec parse(msg :: String.t()) :: t()

Parse binary message to Elixir tuple, if message contains event it will be returned as general Nostr.Event.t() struct.

Returns :error for invalid payloads.

parse_specific(msg)

@spec parse_specific(String.t()) :: t() | struct()

Parse binary message to Elixir tuple, if message contains event it will be returned as specific Nostr.Event.t() struct dependent of type of Event

parse_with_reason(msg)

@spec parse_with_reason(String.t()) :: {:ok, t()} | {:error, parse_reason()}

Parse binary message to Elixir tuple and return structured parse errors.

The protocol-level parser in the relay uses this function to distinguish malformed JSON escape/literal cases from other parse failures.

request(filter, sub_id)

@spec request(Nostr.Filter.t() | [Nostr.Filter.t()], binary()) ::
  {:req, binary(), [Nostr.Filter.t()]}

Generate request message

serialize(message)

@spec serialize(tuple()) :: binary()

Serialize Elixir tuple message to on-the-wire binary