Nostr.NIP45 (Nostr Lib v0.2.1) (nip45)

@type aggregate_result() :: %{
  fallback_sum: non_neg_integer(),
  estimate: non_neg_integer() | nil,
  hll: binary() | nil,
  used_hll_count: non_neg_integer()
}

offset_error()

@type offset_error() :: :no_tag_filter | :multiple_tag_filters | :invalid_tag_values

Functions

add_event(hll, event)

@spec add_event(Nostr.NIP45.HLL.t(), Nostr.Event.t()) ::
  {:ok, Nostr.NIP45.HLL.t()} | {:error, :invalid_pubkey}

Adds an event pubkey into HLL registers.

add_pubkey(hll, pubkey_hex)

@spec add_pubkey(Nostr.NIP45.HLL.t(), binary()) ::
  {:ok, Nostr.NIP45.HLL.t()} | {:error, :invalid_pubkey}

Adds a hex-encoded pubkey to HLL registers.

aggregate_count_payloads(filter, payloads)

@spec aggregate_count_payloads(Nostr.Filter.t() | map(), [
  Nostr.Message.count_payload() | map()
]) ::
  {:ok, aggregate_result()} | {:error, :invalid_payloads}

Aggregates COUNT payloads and merges any valid HLL values.

Returns exact summed counts as :fallback_sum and approximate merged estimate as :estimate when HLL data is usable.

estimate(hll)

@spec estimate(Nostr.NIP45.HLL.t()) :: non_neg_integer()

Returns estimated cardinality from HLL registers.

from_hex(hex, offset)

@spec from_hex(binary(), 8..23) :: {:ok, Nostr.NIP45.HLL.t()} | {:error, :invalid_hll}

Parses a hex-encoded HLL register payload.

hll_eligible?(filter)

@spec hll_eligible?(Nostr.Filter.t() | map()) :: boolean()

Returns true when a filter can derive an HLL offset.

hll_offset(filter)

@spec hll_offset(Nostr.Filter.t() | map()) :: {:ok, 8..23} | {:error, offset_error()}

Derives the deterministic NIP-45 offset for a filter.

Currently only filters with exactly one #<letter> attribute are treated as eligible.

merge(hll1, hll2)

@spec merge(Nostr.NIP45.HLL.t(), Nostr.NIP45.HLL.t()) ::
  {:ok, Nostr.NIP45.HLL.t()} | {:error, :offset_mismatch}

Merges two HLL values by taking max register values.

new(offset)

@spec new(8..23) :: Nostr.NIP45.HLL.t()

Creates a new empty HLL with the given offset.

new_from_filter(filter)

@spec new_from_filter(Nostr.Filter.t() | map()) ::
  {:ok, Nostr.NIP45.HLL.t()} | {:error, offset_error()}

Creates a new empty HLL using offset derived from a filter.

to_hex(hll)

@spec to_hex(Nostr.NIP45.HLL.t()) :: binary()

Encodes HLL registers to a hex string.