Nostr.NIP13 (Nostr Lib v0.2.1) (nip13)

View Source

NIP-13: Proof of Work helpers.

Provides PoW difficulty calculation, nonce commitment parsing, validation, and mining helpers for Nostr events.

Summary

Types

difficulty_error()
mine_error()
nonce_error()
pow_validation_error()

Functions

difficulty(id)

Returns PoW difficulty as number of leading zero bits in an event id.

meets_difficulty?(event_or_id, required_difficulty)

Returns true when an event id (or event) meets the requested PoW difficulty.

mine(event, target_difficulty, opts \\ [])

Mines an event by updating/adding its nonce tag until the target is met.

mine_and_sign(event, seckey, target_difficulty, opts \\ [])

Mines and signs an event in one call.

nonce_commitment(tags)

Returns the committed target difficulty from a nonce tag.

validate_pow(event, min_difficulty, opts \\ [])

Validates PoW and optional commitment constraints for an event.

Types

difficulty_error()

@type difficulty_error() :: :missing_event_id | :invalid_event_id

mine_error()

@type mine_error() ::
  :max_attempts_exceeded
  | :invalid_created_at
  | :invalid_max_attempts
  | :invalid_commitment
  | :invalid_starting_nonce
  | :pubkey_mismatch

nonce_error()

@type nonce_error() ::
  :missing_nonce_tag | :missing_nonce_commitment | :invalid_nonce_commitment

pow_validation_error()

@type pow_validation_error() ::
  difficulty_error()
  | nonce_error()
  | {:insufficient_difficulty, non_neg_integer(), non_neg_integer()}
  | {:insufficient_commitment, non_neg_integer(), non_neg_integer()}
  | {:commitment_not_met, non_neg_integer(), non_neg_integer()}

Functions

difficulty(id)

@spec difficulty(Nostr.Event.t() | binary()) ::
  {:ok, non_neg_integer()} | {:error, difficulty_error()}

Returns PoW difficulty as number of leading zero bits in an event id.

meets_difficulty?(event_or_id, required_difficulty)

@spec meets_difficulty?(Nostr.Event.t() | binary(), non_neg_integer()) :: boolean()

Returns true when an event id (or event) meets the requested PoW difficulty.

mine(event, target_difficulty, opts \\ [])

@spec mine(Nostr.Event.t(), non_neg_integer(), keyword()) ::
  {:ok, Nostr.Event.t()} | {:error, mine_error()}

Mines an event by updating/adding its nonce tag until the target is met.

Options:

  • :max_attempts - attempt limit (default: 1_000_000)
  • :starting_nonce - nonce counter start (default: 0)
  • :update_created_at - refresh timestamp on each attempt (default: true)
  • :commitment - nonce tag committed target (default: target difficulty)

mine_and_sign(event, seckey, target_difficulty, opts \\ [])

@spec mine_and_sign(Nostr.Event.t(), binary(), non_neg_integer(), keyword()) ::
  {:ok, Nostr.Event.t()} | {:error, mine_error()}

Mines and signs an event in one call.

nonce_commitment(tags)

@spec nonce_commitment(Nostr.Event.t() | [Nostr.Tag.t()]) ::
  {:ok, non_neg_integer()} | {:error, nonce_error()}

Returns the committed target difficulty from a nonce tag.

validate_pow(event, min_difficulty, opts \\ [])

@spec validate_pow(Nostr.Event.t(), non_neg_integer(), keyword()) ::
  :ok | {:error, pow_validation_error()}

Validates PoW and optional commitment constraints for an event.

Options:

  • :require_commitment - require third nonce field (default: false)
  • :enforce_commitment - require actual difficulty >= committed target (default: false)