NIP-DB: Browser Nostr Event Database Interface

NIP-DB: Browser Nostr Event Database Interface

Abstract

This NIP defines a standard interface for browser extensions that provide local Nostr event storage capabilities to web applications. The interface allows web applications to interact with Nostr events stored locally in the browser through a standardized window.nostrdb API.

Motivation

Browser extensions can provide valuable local storage and caching capabilities for Nostr events, improving performance and enabling offline functionality.

This NIP establishes a common interface that browser extensions can implement to provide Nostr event storage services to web applications.

Specification

Interface Definition

Browser extensions implementing this NIP MUST inject a window.nostrdb object that implements the following interface:

interface IWindowNostrDB {
  /** Add an event to the database */
  add(event: NostrEvent): Promise<boolean>;

  /** Get a single event by ID */
  event(id: string): Promise<NostrEvent | undefined>;

  /** Get the latest version of a replaceable event */
  replaceable(
    kind: number,
    author: string,
    identifier?: string,
  ): Promise<NostrEvent | undefined>;

  /** Count the number of events matching filters */
  count(filters: Filter | Filter[]): Promise<number>;

  /** Check if the database backend supports features */
  supports(): Promise<string[]>;

  /** Get events by filters */
  query(filters: Filter | Filter[]): Promise<NostrEvent[]>;

  /** Subscribe to events in the database based on filters */
  subscribe(filters: Filter | Filter[]): AsyncGenerator<NostrEvent>;
}

Feature Detection

The supports() method allows web applications to check for optional features:

• "search" - NIP-50 full-text search capabilities

Implementation Requirements

1. Injection: The interface MUST be injected into every web page via content scripts
2. Availability: The interface MUST be available as window.nostrdb after DOM content is loaded
3. Error Handling: All methods MUST handle errors gracefully and return appropriate error states
4. Thread Safety: The interface MUST be safe to use from multiple contexts

Usage Examples

Basic Event Operations

// Add an event
const success = await window.nostrdb.add(nostrEvent);

// Get a specific event
const event = await window.nostrdb.event(eventId);

// Get latest replaceable event
const profile = await window.nostrdb.replaceable(0, pubkey);

// Count events
const count = await window.nostrdb.count({ kinds: [1] });

Getting Events

// Get events matching filters
const events = await window.nostrdb.query([{ kinds: [1] }]);
console.log("Found events:", events);

Subscribing to Events

// Subscribe to events using an async iterator
for await (const event of window.nostrdb.subscribe([{ kinds: [1] }])) {
  console.log("New event:", event);
}

Feature Detection

// Get all supported features
const supportedFeatures = await window.nostrdb.supports();

// Check for search support
if (supportedFeatures.includes("search")) {
  // Use search functionality
  const notes = await window.nostrdb.query({ kinds: [1], search: "nostr" });
}

Reference Implementation

A reference implementation is available at: nostr-bucket