NDK is a nostr development kit that makes the experience of building Nostr-related applications, whether they are relays, clients, or anything in between, better, more reliable and overall nicer to work with than existing solutions.
- The core goal of NDK is to improve the decentralization of Nostr via intelligent conventions and data discovery features without depending on any one central point of coordination (such as large relays or centralized search providers).
- NDK team aims to have new to nostr devs get set up, and reading a NIP-01 event within 10 minutes.
- NDK's objective is to serve prospective, and current nostr devs as clients. If you have friction with the NDK developer experience, please open issues, and ask for help from the NDK team! Devs are encouraged to search through existing, and/or create new github issues when experiencing friction with NDK.
npm add @nostr-dev-kit/ndk
NDK uses the debug
package to assist in understanding what's happening behind the hood. If you are building a package
that runs on the server define the DEBUG
envionment variable like
export DEBUG='ndk:*'
or in the browser enable it by writing in the DevTools console
localStorage.debug = 'ndk:*'
- NIP-01
- Caching adapters
- [~] NIP-04: Encryption support
- NIP-18: Repost
-
NIP-26Won't add / NIP-26 is dead - NIP-42: Relay authentication
- NIP-57: Zaps
- LUD06
- LUD16
- NIP-65: Contacts' Relay list
- NIP-89: Application Handlers
- NIP-90: Data Vending Machines
- Subscription Management
- Auto-grouping queries
- Auto-closing subscriptions
- Signing Adapters
- Private key
- NIP-07
- [!]
NIP-26Won't add / NIP-26 is dead - NIP-46
- Permission tokens
- OAuth flow
- Relay discovery
- Outbox-model (NIP-65)
- Implicit relays discovery following pubkey usage
- Implicit relays discovery following
t
tag usage - Explicit relays blacklist
- nostr-tools/SimplePool drop-in replacement interface
- NIP-47: Nostr Wallet Connect
- NIP-96: Media Uploads
- XMLHttpRequest (for progress reporting)
- Fetch API
See REFERENCES.md for a list of projects using NDK to see how others are using it.
You can pass an object with several options to a newly created instance of NDK.
explicitRelayUrls
βΒ an array of relay URLs.signer
- an instance of a signer.cacheAdapter
- an instance of a Cache Adapterdebug
- Debug instance to use for logging. Defaults todebug("ndk")
.
// Import the package
import NDK from "@nostr-dev-kit/ndk";
// Create a new NDK instance with explicit relays
const ndk = new NDK({
explicitRelayUrls: ["wss://a.relay", "wss://another.relay"],
});
If the signer implements the getRelays()
method, NDK will use the relays returned by that method as the explicit relays.
// Import the package
import NDK, { NDKNip07Signer } from "@nostr-dev-kit/ndk";
// Create a new NDK instance with just a signer (provided the signer implements the getRelays() method)
const nip07signer = new NDKNip07Signer();
const ndk = new NDK({ signer: nip07signer });
Note: In normal client use, it's best practice to instantiate NDK as a singleton class. See more below.
After you've instatiated NDK, you need to tell it to connect before you'll be able to interact with any relays.
// Import the package
import NDK from "@nostr-dev-kit/ndk";
// Create a new NDK instance with explicit relays
const ndk = new NDK({
explicitRelayUrls: ["wss://a.relay", "wss://another.relay"],
});
// Now connect to specified relays
await ndk.connect();
NDK uses signers optionally passed in to sign events. Note that it is possible to use NDK without signing events (e.g. to get someone's profile).
Signing adapters can be passed in when NDK is instantiated or later during runtime.
Instatiate NDK with a NIP-07 signer
// Import the package, NIP-07 signer and NDK event
import NDK, { NDKEvent, NDKNip07Signer } from "@nostr-dev-kit/ndk";
const nip07signer = new NDKNip07Signer();
const ndk = new NDK({ signer: nip07signer });
NDK can now ask for permission, via their NIP-07 extension, to...
Read the user's public key
nip07signer.user().then(async (user) => {
if (!!user.npub) {
console.log("Permission granted to read their public key:", user.npub);
}
});
Sign & publish events
const ndkEvent = new NDKEvent(ndk);
ndkEvent.kind = 1;
ndkEvent.content = "Hello, world!";
ndkEvent.publish(); // This will trigger the extension to ask the user to confirm signing.
NDK provides database-agnostic caching functionality out-of-the-box to improve the performance of your application and reduce load on relays.
NDK will eventually allow you to use multiple caches simultaneously and allow for selective storage of data in the cache store that makes the most sense for your application.
The most important data to cache is where a user or note might be found. UX suffers profoundly when this type of data cannot be found. By design, the Nostr protocol leaves breadcrumbs of where a user or note might be found and NDK does it's best to store this data automatically and use it when you query for events.
const redisAdapter = new RedisAdapter(redisUrl);
const ndk = new NDK({ cacheAdapter: redisAdapter });
Clients often need to load data (e.g. profile data) from individual components at once (e.g. initial page render). This typically causes multiple subscriptions to be submitted fetching the same information and causing poor performance or getting rate-limited/maxed out by relays.
NDK implements a convenient subscription model, buffered queries, where a named subscription will be created after a customizable amount of time, so that multiple components can append queries.
// Component 1
ndk.subscribe({ kinds: [0], authors: ["pubkey-1"] });
// Component 2
ndk.subscribe({ kinds: [0], authors: ["pubkey-2"] });
In this example, NDK will wait 100ms (default groupableDelay
) before creating a subscription with the filter:
{kinds: [0], authors: ['pubkey-1', 'pubkey-2'] }
When a client submits a request through NDK, NDK will calculate which relays are most likely able to satisfy this request.
Queries submitted by the client might be broken into different queries if NDK computes different relays.
For example, say npub-A follows npub-B and npub-C. If the NDK client uses:
const ndk = new NDK({ explicitRelayUrls: ["wss://nos.lol"] });
const npubA = ndk.getUser("npub-A");
const feedEvents = await npubA.feed();
This would result in the following request:
{ "kinds": [1], "authors": ["npub-B", "npub-C"] }
But if NDK has observed that npub-B
tends to write to wss://userb.xyz
and
npub-C
tends to write to wss://userc.io
, NDK will instead send the following queries.
// to npub-A's explicit relay wss://nos.lol *if* npub-B and npub-C have been seen on that relay
{ "kinds": [1], "authors": [ "npub-B", "npub-C" ] }
// to wss://userb.xyz
{ "kinds": [1], "authors": [ "npub-B" ] }
// to wss://userc.io
{ "kinds": [1], "authors": [ "npub-C" ] }
Often, clients need to fetch data but don't need to maintain an open connection to the relay. This is true of profile metadata requests especially.
NDK defaults to having the closeOnEose
flag set to false
; if you want your subscription to close after EOSE
, you should set it to true
.
- The
closeOnEose
flag will make the connection close immediately after EOSE is seen.
ndk.subscribe({ kinds: [0], authors: ["..."] }, { closeOnEose: false });
NDK implements several conveience methods for common queries.
This is a handy method for instantiating a new NDKUser
and associating the current NDK instance with that user for future calls.
const pablo = ndk.getUser({
npub: "npub1l2vyh47mk2p0qlsku7hg0vn29faehy9hy34ygaclpn66ukqp3afqutajft",
});
const jeff = ndk.getUser({
pubkey: "1739d937dc8c0c7370aa27585938c119e25c41f6c441a5d34c6d38503e3136ef",
});
You can easily fetch a user's profile data from kind:0
events on relays. Calling .fetchProfile()
will update the profile
attribute on the user object instead of returning the profile directly. NDK then makes it trivial to update values and publish those updates back to relays.
const pablo = ndk.getUser({
npub: "npub1l2vyh47mk2p0qlsku7hg0vn29faehy9hy34ygaclpn66ukqp3afqutajft",
});
await pablo.fetchProfile();
const pabloFullProfile = pablo.profile;
pablo.profile.name = "Pablo";
await pablo.publish(); // Triggers signing via signer
You can fetch the first event or all events that match a given set of filters.
// Create a filter
const filter: NDKFilter = { kinds: [1], authors: [hexpubkey1, hexpubkey2] };
// Will return only the first event
event = await ndk.fetchEvent(filter);
// Will return all found events
events = await ndk.fetchEvents(filter);
const ndk = new NDK({ explicitRelayUrls, signer });
const event = new NDKEvent(ndk);
event.kind = 1;
event.content = "PV Nostr! π€πΌ";
await ndk.publish(event);
// Find the first event from @jack, and react/like it.
const jack = await ndk.getUserFromNip05("jack@cashapp.com");
const event = await ndk.fetchEvent({ authors: [jack.pubkey] })[0];
await event.react("π€");
// Find the first event from @jack, and zap it.
const jack = await ndk.getUserFromNip05("jack@cashapp.com");
const event = await ndk.fetchEvent({ authors: [jack.pubkey] })[0];
await ndk.zap(event, 1337, "Zapping your post!"); // Returns a bolt11 payment request
- Users of NDK should instantiate a single NDK instance.
- That instance tracks state with all relays connected, explicit and otherwise.
- All relays are tracked in a single pool that handles connection errors/reconnection logic.
- RelaySets are assembled ad-hoc as needed depending on the queries set, although some RelaySets might be long-lasting, like the
explicitRelayUrls
specified by the user. - RelaySets are always a subset of the pool of all available relays.