Module inbox_relays 

NIP-17 Kind 10050 (DM Relay List) support.

Fetches, caches, and publishes kind 10050 events so that DM gift wraps are delivered to the recipient’s preferred inbox relays.

Structs

BuiltGiftWrap

A gift wrap built once and re-publishable verbatim.

EventPublishTracker

Per-relay publish tracker. One per outbound event whose dependents (deletions, edits, reactions, replies, …) need to fire only after the parent has actually landed at each individual relay.

GiftWrapSendOutcome

Outcome of a retained-key gift-wrap send. Caller is expected to persist wrap_event_id, wrap_secret, and targeted_relays for future deletion.

GiftWrapTargets

Resolved publish targets for a gift wrap. Reusable across retry attempts so transient inbox-relay connections survive the whole retry window instead of reconnecting per attempt. Callers must teardown_gift_wrap_targets when done — transient inbox relays belong to the recipient, not our pool.

InboundReconcile

Local actions needed to make the in-app relay list mirror a newer remote 10050 (the Relays tab IS the DM Relay List, synced across devices/apps).

Functions

build_gift_wrap_retained

Seal + wrap a rumor with a retained ephemeral key, without publishing.

clear_inbox_relay_cache

Drop every cached recipient relay list — called by reset_session(). The cache is recipient-keyed (so technically account-agnostic) but grows unboundedly across sessions; the 1-hour TTL only reclaims re-queried entries. Clear on swap to free memory and avoid stale-data revivals.

fetch_own_inbox_list

Fetch our OWN current 10050 from read + Discovery relays, with its created_at. Ok(None) means the network answered and no list exists; Err means we could not get a trustworthy answer (offline, nothing connected) — callers must NOT publish on Err, that is exactly the blind overwrite this module exists to stop.

get_publish_tracker

Look up the tracker for an event currently being published. Returns None if the publish has fully settled (all relays done) or if the tracker never existed (e.g. the event was sent in a previous app session, or via a non-tracked send path). Dependent senders fall back to a best-effort broadcast in that case.

normalize_relay_url

Canonical string form for relay-url comparison. nostr-sdk canonicalises differently between published-10050 strings and pool keys (trailing slashes, default ports, case), so equality checks must go through this.

note_contributed

Union urls into the contributed set. Adopted/revived relays must count as OUR contribution immediately: retire only fires for contributed entries, and a merge would otherwise re-add (“resurrect”) a relay that a newer remote list deliberately dropped.

note_list_seen

Advance the list-freshness anchor (monotonic).

plan_inbound_reconcile

Plan the inbound half of the sync. ours = locally enabled relay urls, declined = locally known but disabled urls. Reads the contributed set and freshness anchor from the account KV.

publish_gift_wrap_to_targets

Publish an already-built wrap to resolved targets, racing for the first relay OK. Safe to call repeatedly with the same event — relays that already stored it acknowledge the duplicate.

publish_inbox_relays

Sync our kind 10050 from the network, merge our readable relays into it, and publish ONLY if that changes the list. Lists curated in other clients are preserved: foreign entries are re-signed verbatim, never dropped. Publishes to our write relays AND the Discovery Relays so the result is findable by clients with no relay overlap.

publish_inbox_relays_synced

Publish with an already-synced remote list (avoids a second network fetch when the caller just ran the inbound reconcile). ours_override supplies the caller’s store-derived relay list: the live pool momentarily contains relays that are not ours (a recipient’s transient inbox relays mid-DM) and can be missing ours (an adopted relay whose connect failed) — publishing pool state would leak the former fleet-wide and oscillate the latter.

reconnect_gift_wrap_targets

Nudge any non-connected target relay back up before a retry attempt. Transient inbox relays are added with reconnect(false), so a drop mid-retry-window would otherwise leave them dead for every remaining attempt.

republish_inbox_relays_debounced

Republish kind 10050 in the background (debounced). Called after relay config changes (add/remove/toggle/mode update). Rapid successive calls coalesce into a single publish.

resolve_gift_wrap_targets

Resolve where a gift wrap for recipient should be published: their kind-10050 inbox relays when advertised (on-demand connecting any that are not already pooled, as transient members), otherwise our pool’s write-relays.

send_event_first_ok

Send an event to specific relays, returning as soon as the first relay acknowledges success. Remaining relays continue sending in the background.

send_event_pool_first_ok

Send an event to all write-relays in the pool, returning as soon as the first relay acknowledges success.

send_gift_wrap

Send a gift-wrapped rumor to a recipient, routing to their inbox relays (kind 10050) when available. Falls back to pool broadcast if no inbox relays are found or if targeted delivery fails entirely.

send_gift_wrap_retained

Send a gift-wrapped rumor to a recipient using a retained ephemeral key. Routes to the recipient’s inbox relays (kind 10050) when available, falling back to pool write-relays otherwise.

spawn_tracked_publish

Spawn one publish task per resolved relay and register a tracker keyed by the event id. Returns the join handles so the caller can race them for first-ok or wait for all to settle as needed. The spawned tasks continue updating the tracker after the caller stops waiting on the handles.

teardown_gift_wrap_targets

Tear down transiently-added inbox relays — they belong to the recipient, not us. Delivery has already raced to first-ok; one confirmed inbox relay satisfies NIP-17, so cutting any still-in-flight background publishes to the others is acceptable.

trusted_relay_urls

Get the cached parsed trusted relay URLs.

wrap_with_retained_key

Build a NIP-59 kind-1059 gift wrap from a sealed event, returning both the signed wrap event and the ephemeral secp256k1 secret used to sign it.