go-nostr

When using relay.Subscribe, you must manage the lifecycle of the subscription to prevent goroutine leaks. If you stop listening to the sub.Events channel without properly closing the subscription, the library will continue to spawn goroutines for every new event that arrives.

To prevent this:

1. Ensure the context.Context passed to Subscribe is eventually canceled.
2. Or, explicitly call .Unsub() on the subscription object.

To run tests targeting WebAssembly, install wasmbrowsertest and execute:

GOOS=js GOARCH=wasm go test -short ./...

For significantly faster signing and verification, you can use the libsecp256k1 shared library. This requires the host to have libsecp256k1 installed and CGO support enabled.

To use it, include the tag during compilation:

go build -tags=libsecp256k1 .

To add go-nostr to your Go project, use the following command:

go get github.com/nbd-wtf/go-nostr

Note: This repository is in maintenance mode. For new projects, the maintainers recommend using fiatjaf.com/nostr@master instead.

Enable Debug Logs

To see detailed interaction logs with relays in STDOUT, compile or run your program with the -tags debug flag.

Disable Info Logs

To suppress all info logs, replace the global nostr.InfoLogger with a logger that discards output:

nostr.InfoLogger = log.New(io.Discard, "", 0)

A MultiStore is a collection of RelayStore implementations (a slice of RelayStore). It allows you to treat multiple relays as a single unified store. When you call methods on a MultiStore, it broadcasts the operation to all underlying stores and aggregates the results or errors.

• Publish: Sends an event to all relays in the store. Returns a joined error if any individual publish fails.
• QueryEvents: Starts a streaming query across all relays. It spawns goroutines to pipe events from each individual relay channel into a single unified channel. Returns an error only if all underlying stores fail to provide a channel.
• QuerySync: Performs a synchronous fetch from all relays. It aggregates all returned events into a single slice and sorts them by CreatedAt in descending order (newest first).

type MultiStore []RelayStore

The Envelope interface is the common type for all Nostr message types. Any object implementing this interface can be used to handle incoming or outgoing relay messages. It provides methods for identifying the message type, parsing from JSON, and serializing back to JSON.

type Envelope interface {
	Label() string
	FromJSON(string) error
	MarshalJSON() ([]byte, error)
	String() string
}

The Pointer interface provides a unified way to handle references to Nostr entities (profiles, events, or addressable entities). It allows you to convert a reference into a Tag for inclusion in new events, a Filter for querying relays, or a simple string reference.

Supported implementations include:

• ProfilePointer: References a user profile (typically via p tags).
• EventPointer: References a specific event (typically via e tags).
• EntityPointer: References an addressable entity (typically via a tags).

To melt (exchange) Cashu tokens for a Lightning Network (Bolt11) payment, follow the quote-then-melt pattern:

1. Request a Melt Quote: Use PostMeltQuoteBolt11 with a nut05.PostMeltQuoteBolt11Request.
2. Check Status: Use GetMeltQuoteState with the quoteId to poll for the status.
3. Complete Melting: Use PostMeltBolt11 with a nut05.PostMeltBolt11Request to finalize the transaction.

// 1. Request melt quote
meltQuoteReq := nut05.PostMeltQuoteBolt11Request{...}
meltQuoteResp, err := client.PostMeltQuoteBolt11(ctx, mintURL, meltQuoteReq)

// 2. Check state
state, err := client.GetMeltQuoteState(ctx, mintURL, meltQuoteResp.QuoteID)

// 3. Post melt
meltReq := nut05.PostMeltBolt11Request{...}
meltResp, err := client.PostMeltBolt11(ctx, mintURL, meltReq)

Use NewSimplePool to create a manager for multiple relay connections. The pool handles connection lifecycle, reconnection logic, and prevents duplicate connections to the same relay. You can pass several PoolOptions to configure behavior like authentication, middleware, or a penalty box for failing relays.

import "github.com/nbd-wtf/go-nostr"

// Create a new pool with a context
pool := nostr.NewSimplePool(ctx, 
    nostr.WithRelayOptions(nostr.WithRequestHeader(myHeaders)),
    nostr.WithAuthHandler(myAuthFunc),
    nostr.WithPenaltyBox(),
)