nostr-tools

The @nostr/tools package provides a comprehensive suite of utilities for working with the Nostr protocol. The main entry point exports core primitives for event manipulation, relay interaction, and NIP (Nostr Implementation Possibility) compliance.

Key functional areas include:

• Pure Utilities: Core functions for signing, verifying, and creating events (exported from ./pure.ts).
• Relay & Pool Management: Classes like Relay and SimplePool for connecting to and interacting with Nostr relays.
• Filtering: Tools for constructing event filters (exported from ./filter.ts).
• Reference Parsing: Utilities for parsing mentions and references (exported from ./references.ts).
• NIP Implementations: Namespaced modules for specific NIPs (e.g., nip01, nip19, nip42).
• Constants & Helpers: Access to event kinds, utils, and fj (fakejson).

import {
  Relay,
  SimplePool,
  nip19,
  kinds,
  // ... other imports
} from '@nostr/tools';

Nostr events are categorized into four main types based on how relays are expected to store and manage them:

• Regular: Expected to be stored by relays (e.g., kind < 10000 excluding 0 and 3).
• Replaceable: For a specific pubkey and kind, only the latest event should be stored; older versions are discarded (e.g., kind === 0, kind === 3, or 10000 <= kind < 20000).
• Ephemeral: Not expected to be stored by relays (e.g., 20000 <= kind < 30000).
• Addressable (Parameterized): For a specific pubkey, kind, and d tag, only the latest event should be stored (e.g., 30000 <= kind < 40000).

You can use classifyKind(kind) to get a KindClassification string: 'regular' | 'replaceable' | 'ephemeral' | 'parameterized' | 'unknown'.

import { classifyKind } from './kinds.ts'

const classification = classifyKind(1)
// returns 'regular'

const ephemeralClassification = classifyKind(25000)
// returns 'ephemeral'

The AbstractRelay class serves as the base class for implementing custom relay connections. To use it, you must provide a verifyEvent function in the constructor options to validate incoming events. It handles WebSocket management, reconnection logic, ping/pong heartbeats, and subscription lifecycles.

Key features include:

• Automatic Reconnection: Configurable via enableReconnect.
• Idle Management: Can automatically close the connection after a period of inactivity using idleTimeout.
• Heartbeats: Uses pingFrequency and pingTimeout to maintain connection health.
• Authentication: Supports NIP-42 via the auth method.

import { AbstractRelay } from './abstract-relay.ts';

// Example of how you might extend it (conceptual)
class MyCustomRelay extends AbstractRelay {
  // Implement custom logic here
}

const relay = await AbstractRelay.connect('wss://relay.example.com', {
  verifyEvent: (event, url) => true, // Always verify events in production!
  enableReconnect: true,
  idleTimeout: 60000 // 1 minute
});

NIP-45 uses HyperLogLog (HLL) to estimate the cardinality of sets (like the number of followers) without storing every individual ID.

To implement the estimation flow:

1. Initialize: Create a new HLL structure using newHll().
2. Determine Offset: Calculate the hash-based offset using computeOffset(filterFirstTagValue) to ensure consistent register mapping.
3. Feed Data: As you receive events or pubkeys, update the HLL using feedEvent(hll, event, offset) or feedPubkey(hll, pubkey, offset).
4. Merge (Optional): If you have multiple HLL structures, combine them using mergeHll(target, source).
5. Estimate: Get the final count using estimateCount(hll).

Encoding/Decoding:

• Use hllEncode(registers) to convert the Uint8Array to a hex string for storage/transmission.
• Use hllDecode(hex) to convert a hex string back into a Uint8Array.

import { 
  newHll, 
  computeOffset, 
  getFilterFirstTagValue, 
  feedEvent, 
  estimateCount 
} from '@nostr/tools/nip45';

const hll = newHll();
const filter = { '#p': ['TARGET_PUBKEY'], kinds: [3] };

// 1. Get the first tag value from the filter to compute offset
const firstTagValue = getFilterFirstTagValue(filter);
if (firstTagValue) {
  const offset = computeOffset(firstTagValue);

  // 2. As events arrive, feed them into the HLL
  // (Assuming 'event' is a valid Nostr Event object)
  feedEvent(hll, event, offset);

  // 3. Estimate the total count
  const count = estimateCount(hll);
  console.log(`Estimated count: ${count}`);
}

NIP-59 provides a mechanism for creating encrypted 'rumors' and 'seals' to facilitate private communication. This module provides high-level functions to create rumors, seal them for a specific recipient using NIP-44 encryption, and wrap them in a GiftWrap (kind GiftWrap) for secure delivery.

Core Workflow

1. Create a Rumor: Use createRumor to generate an unsigned event with a calculated ID.
2. Seal a Rumor: Use createSeal to encrypt the rumor for a specific recipient using NIP-44.
3. Wrap a Seal: Use createWrap to further wrap the seal using a randomly generated secret key, ensuring only the intended recipient can access the content.
4. Unwrap: Use unwrapEvent with the recipient's private key to decrypt the layers and retrieve the original Rumor.

import { createRumor, createSeal, createWrap, wrapEvent, unwrapEvent } from './nip59.ts';

// 1. Setup
const senderPrivateKey = generateSecretKey(); // From pure.ts
const recipientPublicKey = '...';
const eventData = { content: 'Hello, secret world!' };

// 2. Wrap an event (High-level API)
const wrappedEvent = wrapEvent(eventData, senderPrivateKey, recipientPublicKey);

// 3. Unwrap (Recipient side)
const recipientPrivateKey = '...';
const rumor = unwrapEvent(wrappedEvent, recipientPrivateKey);
console.log(rumor.content);