nostr-replaceable-event-mutation-overwrite

Nostr Replaceable Event Mutation Overwrite

Problem

Nostr replaceable events (Kind 0, 3, 10002, etc.) use a full-replace model: publishing a new event completely replaces the previous one. If a client publishes a mutation based on stale, incomplete, or null cached state, it silently overwrites the canonical version on relays, causing data loss. The most common case is follow list (Kind 3) wipes when a user follows someone before the client has loaded their existing contact list.

Context / Trigger Conditions

• User reports "I followed someone and lost all my other follows"
• Follow/unfollow action on a fresh browser session or mobile login
• Profile update loses existing metadata fields
• Relay list update drops existing relays
• Any mutation on a replaceable event where the UI passes cached state to the mutation function
• React Query / TanStack Query data is undefined when mutation fires (query still loading)
• The mutation function accepts the current event as a parameter from the UI layer

Solution

1. Always Fetch Fresh State Inside the Mutation

Never rely solely on the UI's cached/query state. Fetch the latest version of the replaceable event directly from the relay inside the mutation function, before publishing:

// BAD: Relies on UI cache which may be null/stale
mutationFn: async ({ targetPubkey, currentContactList }) => {
  const currentTags = currentContactList?.tags || []; // null -> [] -> data loss!
  // ... publish with only the new follow
}

// GOOD: Fetches fresh from relay before mutating
mutationFn: async ({ targetPubkey, currentContactList }) => {
  let bestContactList = currentContactList;

  try {
    const relayEvents = await nostr.query([
      { kinds: [3], authors: [userPubkey], limit: 1 },
    ], { signal: AbortSignal.timeout(5000) });

    const relayContactList = relayEvents
      .sort((a, b) => b.created_at - a.created_at)[0] || null;

    if (relayContactList) {
      // NIP-01 already fixes which copy of a replaceable event wins:
      // the higher created_at, and on an exact tie the lower event id.
      // Never compare tag counts — a shorter list is what a legitimate
      // unfollow produces.
      const passed = currentContactList;
      const isNewer =
        !passed ||
        relayContactList.created_at > passed.created_at ||
        (relayContactList.created_at === passed.created_at &&
          relayContactList.id < passed.id);
      if (isNewer) {
        bestContactList = relayContactList;
      }
    }
  } catch {
    // The read failed. It cannot be told apart from "the relay holds
    // nothing", so refuse to publish rather than replacing from a guess.
    throw new Error('Could not confirm the current list. Please try again.');
  }

  if (!bestContactList) {
    throw new Error('Could not load existing data. Please try again.');
  }

  // Now mutate bestContactList...
}