Nostr.Event.ZapReceipt (Nostr Lib v0.2.1) (event) (nip57)

Zap Receipt events (Kind 9735).

Implements NIP-57: https://github.com/nostr-protocol/nips/blob/master/57.md

A zap receipt is published by the recipient's lightning wallet after a zap request invoice has been paid. It serves as proof that a Lightning payment was made.

Required Tags

p - zap recipient pubkey
bolt11 - the paid Lightning invoice
description - JSON-encoded zap request event

Optional Tags

P - zap sender pubkey (uppercase P)
e - event that was zapped
a - addressable event coordinate
k - kind of the zapped event
preimage - payment preimage

Validation

Per NIP-57 Appendix F, clients should validate:

Receipt's pubkey matches the recipient's LNURL nostrPubkey
Invoice amount matches the zap request's amount tag
Receipt's lnurl tag (if present) matches recipient's lnurl

Examples

# Parse a zap receipt
{:ok, receipt} = ZapReceipt.parse(event)

# Get the zap amount
sats = ZapReceipt.get_amount_sats(receipt)

# Get the embedded zap request
{:ok, request} = ZapReceipt.get_zap_request(receipt)

Summary

Types

t()

Functions

create(opts)

Creates a zap receipt event.

get_amount_msats(zap_receipt)

Returns the zap amount in millisatoshis from the parsed invoice.

get_amount_sats(zap_receipt)

Returns the zap amount in satoshis from the parsed invoice.

get_zap_request(zap_receipt)

Returns the parsed zap request from the description tag.

parse(event)

Parses a kind 9735 event into a ZapReceipt struct.

serialize_event_to_json(event)

Serializes an event to JSON object format for use in the description tag.

validate(zap_receipt, wallet_pubkey)

Validates the zap receipt according to NIP-57 Appendix F.

Types

t()

@type t() :: %Nostr.Event.ZapReceipt{
  address: binary() | nil,
  bolt11: binary(),
  description: binary(),
  event: Nostr.Event.t(),
  event_id: binary() | nil,
  invoice: Nostr.Bolt11.t() | nil,
  kind: non_neg_integer() | nil,
  preimage: binary() | nil,
  recipient: binary(),
  sender: binary() | nil,
  zap_request: Nostr.Event.ZapRequest.t() | nil
}

Functions

create(opts)

@spec create(keyword()) :: t() | {:error, String.t()}

Creates a zap receipt event.

Required Options

:recipient - recipient pubkey (p tag)
:bolt11 - the paid Lightning invoice
:description - JSON-encoded zap request event

Optional Options

:sender - sender pubkey (P tag)
:event_id - event that was zapped (e tag)
:address - addressable event coordinate (a tag)
:kind - kind of the zapped event (k tag)
:preimage - payment preimage

Examples

ZapReceipt.create(
  recipient: "recipient_pubkey",
  bolt11: "lnbc...",
  description: ~s({"kind":9734,...}),
  sender: "sender_pubkey",
  event_id: "zapped_event_id"
)

get_amount_msats(zap_receipt)

@spec get_amount_msats(t()) :: non_neg_integer() | nil

Returns the zap amount in millisatoshis from the parsed invoice.

get_amount_sats(zap_receipt)

@spec get_amount_sats(t()) :: non_neg_integer() | nil

Returns the zap amount in satoshis from the parsed invoice.

Returns nil if the invoice couldn't be parsed or has no amount.

get_zap_request(zap_receipt)

@spec get_zap_request(t()) :: {:ok, Nostr.Event.ZapRequest.t()} | {:error, String.t()}

Returns the parsed zap request from the description tag.

Returns {:ok, zap_request} if successfully parsed, {:error, reason} otherwise.

parse(event)

@spec parse(Nostr.Event.t()) :: t() | {:error, String.t(), Nostr.Event.t()}

Parses a kind 9735 event into a ZapReceipt struct.

Automatically parses the embedded bolt11 invoice and zap request.

serialize_event_to_json(event)

@spec serialize_event_to_json(Nostr.Event.t()) :: binary()

Serializes an event to JSON object format for use in the description tag.

This is different from Event.serialize/1 which returns array format for ID computation.

validate(zap_receipt, wallet_pubkey)

@spec validate(t(), binary()) :: :ok | {:error, String.t()}

Validates the zap receipt according to NIP-57 Appendix F.

Validation Steps

Receipt's pubkey must match the wallet's nostrPubkey
Invoice amount must match the zap request's amount tag (if present)
Zap request's lnurl tag (if present) should match recipient's lnurl

Returns :ok if valid, {:error, reason} otherwise.