sdk

package
v0.0.0-...-39d91ff Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 14, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func InputToEventPointer 

func InputToEventPointer(input string) *nostr.EventPointer

InputToEventPointer turns any note/nevent/hex input into a EventPointer (or nil).

func InputToProfile 

func InputToProfile(ctx context.Context, input string) *nostr.ProfilePointer

InputToProfile turns any npub/nprofile/hex/nip05 input into a ProfilePointer (or nil).

func IsVirtualRelay 

func IsVirtualRelay(url string) bool

IsVirtualRelay returns true if the given normalized relay URL shouldn't be considered for outbox-model calculations.

func PerQueryLimitInBatch 

func PerQueryLimitInBatch(totalFilterLimit int, numberOfQueries int) int

PerQueryLimitInBatch tries to make an educated guess for the batch size given the total filter limit and the number of abstract queries we'll be conducting at the same time.

func PrepareNoteEvent 

func PrepareNoteEvent(evt *nostr.Event)

PrepareNoteEvent takes an event with content that may include any number of URLs, partial URLs without the scheme, npub references with or without the "nostr:" prefix, tags and whatnot, then edits the content so it contains properly formatted URLs and references and adds the required tags based on these.

This should only be used when dealing with "plaintext" style events such as kind:1 and kind:1111.

func PubKeyToShid 

func PubKeyToShid(pubkey string) uint64

Types

type EventRef 

type EventRef struct{ nostr.Pointer }

func (EventRef) Value 

func (e EventRef) Value() string

type EventResult 

type EventResult dataloader.Result[*nostr.Event]

type FetchSpecificEventParameters 

type FetchSpecificEventParameters struct {
	// WithRelays indicates whether to include relay information in the response
	// (this causes the request to take longer as it will wait for all relays to respond).
	WithRelays bool

	// SkipLocalStore indicates whether to skip checking the local store for the event
	// and storing the result in the local store.
	SkipLocalStore bool
}

FetchSpecificEventParameters contains options for fetching specific events.

type GenericList 

type GenericList[I TagItemWithValue] struct {
	PubKey string       `json:"-"` // must always be set otherwise things will break
	Event  *nostr.Event `json:"-"` // may be empty if a contact list event wasn't found

	Items []I
}

type GenericSets 

type GenericSets[I TagItemWithValue] struct {
	PubKey string         `json:"-"`
	Events []*nostr.Event `json:"-"`

	Sets map[string][]I
}

type ProfileMetadata 

type ProfileMetadata struct {
	PubKey string       `json:"-"` // must always be set otherwise things will break
	Event  *nostr.Event `json:"-"` // may be empty if a profile metadata event wasn't found

	// every one of these may be empty
	Name        string `json:"name,omitempty"`
	DisplayName string `json:"display_name,omitempty"`
	About       string `json:"about,omitempty"`
	Website     string `json:"website,omitempty"`
	Picture     string `json:"picture,omitempty"`
	Banner      string `json:"banner,omitempty"`
	NIP05       string `json:"nip05,omitempty"`
	LUD16       string `json:"lud16,omitempty"`
	// contains filtered or unexported fields
}

ProfileMetadata represents user profile information from kind 0 events. It contains both the raw event and parsed metadata fields.

func ParseMetadata 

func ParseMetadata(event *nostr.Event) (meta ProfileMetadata, err error)

ParseMetadata parses a kind 0 event into a ProfileMetadata struct. Returns an error if the event is not kind 0 or if the content is not valid JSON.

func (*ProfileMetadata) NIP05Valid 

func (p *ProfileMetadata) NIP05Valid(ctx context.Context) bool

NIP05Valid checks if the profile's NIP-05 identifier is valid.

func (ProfileMetadata) Nprofile 

func (p ProfileMetadata) Nprofile(ctx context.Context, sys *System, nrelays int) string

Nprofile returns the NIP-19 nprofile encoding of the profile, including relay hints from the user's outbox.

func (ProfileMetadata) Npub 

func (p ProfileMetadata) Npub() string

Npub returns the NIP-19 npub encoding of the profile's public key.

func (ProfileMetadata) NpubShort 

func (p ProfileMetadata) NpubShort() string

NpubShort returns a shortened version of the NIP-19 npub encoding, showing only the first 7 and last 5 characters.

func (ProfileMetadata) ShortName 

func (p ProfileMetadata) ShortName() string

ShortName returns the best available name for display purposes. It tries Name, then DisplayName, and falls back to a shortened npub.

type ProfileRef 

type ProfileRef struct {
	Pubkey  string
	Relay   string
	Petname string
}

func (ProfileRef) Value 

func (f ProfileRef) Value() string

type Relay 

type Relay struct {
	URL    string
	Inbox  bool
	Outbox bool
}

func (Relay) Value 

func (r Relay) Value() string

type RelayStream 

type RelayStream struct {
	URLs []string
	// contains filtered or unexported fields
}

RelayStream provides a rotating list of relay URLs. It's used to distribute requests across multiple relays.

func NewRelayStream 

func NewRelayStream(urls ...string) *RelayStream

NewRelayStream creates a new RelayStream with the provided URLs.

func (*RelayStream) Next 

func (rs *RelayStream) Next() string

Next returns the next URL in the rotation.

type RelayURL 

type RelayURL string

func (RelayURL) Value 

func (r RelayURL) Value() string

type System 

type System struct {
	KVStore               kvstore.KVStore
	MetadataCache         cache.Cache32[ProfileMetadata]
	RelayListCache        cache.Cache32[GenericList[Relay]]
	FollowListCache       cache.Cache32[GenericList[ProfileRef]]
	MuteListCache         cache.Cache32[GenericList[ProfileRef]]
	BookmarkListCache     cache.Cache32[GenericList[EventRef]]
	PinListCache          cache.Cache32[GenericList[EventRef]]
	BlockedRelayListCache cache.Cache32[GenericList[RelayURL]]
	SearchRelayListCache  cache.Cache32[GenericList[RelayURL]]
	TopicListCache        cache.Cache32[GenericList[Topic]]
	RelaySetsCache        cache.Cache32[GenericSets[RelayURL]]
	FollowSetsCache       cache.Cache32[GenericSets[ProfileRef]]
	TopicSetsCache        cache.Cache32[GenericSets[Topic]]
	Hints                 hints.HintsDB
	Pool                  *nostr.SimplePool
	RelayListRelays       *RelayStream
	FollowListRelays      *RelayStream
	MetadataRelays        *RelayStream
	FallbackRelays        *RelayStream
	JustIDRelays          *RelayStream
	UserSearchRelays      *RelayStream
	NoteSearchRelays      *RelayStream
	Store                 eventstore.Store

	StoreRelay nostr.RelayStore
	// contains filtered or unexported fields
}

System represents the core functionality of the SDK, providing access to various caches, relays, and dataloaders for efficient Nostr operations.

Usually an application should have a single global instance of this and use its internal Pool for all its operations.

Store, KVStore and Hints are databases that should generally be persisted for any application that is intended to be executed more than once. By default they're set to in-memory stores, but ideally persisteable implementations should be given (some alternatives are provided in subpackages).

func NewSystem 

func NewSystem(mods ...SystemModifier) *System

NewSystem creates a new System with default configuration, which can be customized using the provided modifiers.

The list of provided With* modifiers isn't exhaustive and most internal fields of System can be modified after the System creation -- and in many cases one or another of these will have to be modified, so don't be afraid of doing that.

func (*System) Close 

func (sys *System) Close()

Close releases resources held by the System.

func (*System) FetchBlockedRelayList 

func (sys *System) FetchBlockedRelayList(ctx context.Context, pubkey string) GenericList[RelayURL]

func (*System) FetchBookmarkList 

func (sys *System) FetchBookmarkList(ctx context.Context, pubkey string) GenericList[EventRef]

func (*System) FetchFeedPage 

func (sys *System) FetchFeedPage(
	ctx context.Context,
	pubkeys []string,
	kinds []int,
	until nostr.Timestamp,
	totalLimit int,
) ([]*nostr.Event, error)

FetchFeedNextPage fetches historical events from the given pubkeys in descending order starting from the given until timestamp. The limit argument is just a hint of how much content you want for the entire list, it isn't guaranteed that this quantity of events will be returned -- it could be more or less.

It relies on KVStore's latestKey and oldestKey in order to determine if we should go to relays to ask for events or if we should just return what we have stored locally.

func (*System) FetchFollowList 

func (sys *System) FetchFollowList(ctx context.Context, pubkey string) GenericList[ProfileRef]

func (*System) FetchFollowSets 

func (sys *System) FetchFollowSets(ctx context.Context, pubkey string) GenericSets[ProfileRef]

func (*System) FetchInboxRelays 

func (sys *System) FetchInboxRelays(ctx context.Context, pubkey string, n int) []string

FetchWriteRelays just reads relays from a kind:10002, that's the only canonical place where a user reveals the relays they intend to receive notifications from.

func (*System) FetchMuteList 

func (sys *System) FetchMuteList(ctx context.Context, pubkey string) GenericList[ProfileRef]

func (*System) FetchOutboxRelays 

func (sys *System) FetchOutboxRelays(ctx context.Context, pubkey string, n int) []string

FetchOutboxRelays uses a bunch of heuristics and locally stored data about many relays, including hints, tags, NIP-05, past attempts at fetching data from a user from a given relay, including successes and failures, and the "write" relays of kind:10002, in order to determine the best possible list of relays where a user might be currently publishing their events to.

func (*System) FetchPinList 

func (sys *System) FetchPinList(ctx context.Context, pubkey string) GenericList[EventRef]

func (System) FetchProfileFromInput 

func (sys System) FetchProfileFromInput(ctx context.Context, nip19OrNip05Code string) (ProfileMetadata, error)

FetchProfileFromInput takes an nprofile, npub, nip05 or hex pubkey and returns a ProfileMetadata, updating the hintsDB in the process with any eventual relay hints. Returns an error if the profile reference couldn't be decoded.

func (*System) FetchProfileMetadata 

func (sys *System) FetchProfileMetadata(ctx context.Context, pubkey string) (pm ProfileMetadata)

FetchProfileMetadata fetches metadata for a given user from the local cache, or from the local store, or, failing these, from the target user's defined outbox relays -- then caches the result. It always returns a ProfileMetadata, even if no metadata was found (in which case only the PubKey field is set).

func (*System) FetchRelayList 

func (sys *System) FetchRelayList(ctx context.Context, pubkey string) GenericList[Relay]

func (*System) FetchRelaySets 

func (sys *System) FetchRelaySets(ctx context.Context, pubkey string) GenericSets[RelayURL]

func (*System) FetchSearchRelayList 

func (sys *System) FetchSearchRelayList(ctx context.Context, pubkey string) GenericList[RelayURL]

func (*System) FetchSpecificEvent 

func (sys *System) FetchSpecificEvent(
	ctx context.Context,
	pointer nostr.Pointer,
	params FetchSpecificEventParameters,
) (event *nostr.Event, successRelays []string, err error)

FetchSpecificEvent tries to get a specific event using a Pointer (EventPointer or EntityPointer). It first checks the local store, then queries relays associated with the event or author, and finally falls back to general-purpose relays.

func (*System) FetchSpecificEventFromInput 

func (sys *System) FetchSpecificEventFromInput(
	ctx context.Context,
	input string,
	params FetchSpecificEventParameters,
) (event *nostr.Event, successRelays []string, err error)

FetchSpecificEventFromInput tries to get a specific event from a NIP-19 code or event ID. It supports nevent, naddr, and note NIP-19 codes, as well as raw event IDs.

func (*System) FetchTopicList 

func (sys *System) FetchTopicList(ctx context.Context, pubkey string) GenericList[Topic]

func (*System) FetchTopicSets 

func (sys *System) FetchTopicSets(ctx context.Context, pubkey string) GenericSets[Topic]

func (*System) FetchWriteRelays 

func (sys *System) FetchWriteRelays(ctx context.Context, pubkey string) []string

FetchWriteRelays just reads relays from a kind:10002, it's different than FetchOutboxRelays, which relies on other data and heuristics besides kind:10002.

Use FetchWriteRelays when deciding where to publish on behalf of a user, but FetchOutboxRelays when deciding from where to read notes authored by other users.

func (*System) GetEventRelays 

func (sys *System) GetEventRelays(eventID string) ([]string, error)

GetEventRelays returns all known relay URLs an event is known to be available on. It is based on information kept on KVStore.

func (*System) LoadWoTFilter 

func (sys *System) LoadWoTFilter(ctx context.Context, pubkey string) (WotXorFilter, error)

func (*System) SearchUsers 

func (sys *System) SearchUsers(ctx context.Context, query string) []ProfileMetadata

func (*System) StreamLiveFeed 

func (sys *System) StreamLiveFeed(
	ctx context.Context,
	pubkeys []string,
	kinds []int,
) (<-chan *nostr.Event, error)

StreamPubkeysForward starts listening for new events from the given pubkeys, taking into account their outbox relays. It returns a channel that emits events continuously. The events are fetched from the time of the last seen event for each pubkey (stored in KVStore) onwards.

func (*System) TrackEventHints 

func (sys *System) TrackEventHints(ie nostr.RelayEvent)

TrackEventHints is meant to be used standalone as an argument to WithEventMiddleware() when you're not interested in tracking relays associated to event ids.

func (*System) TrackEventHintsAndRelays 

func (sys *System) TrackEventHintsAndRelays(ie nostr.RelayEvent)

TrackEventHintsAndRelays is meant to be as an argument to WithEventMiddleware() when you're interested in tracking relays associated to event ids as well as feeding hints to the HintsDB.

func (*System) TrackEventRelaysD 

func (sys *System) TrackEventRelaysD(relay, id string)

TrackEventRelaysD is a companion to TrackEventRelays meant to be used with WithDuplicateMiddleware()

func (*System) TrackQueryAttempts 

func (sys *System) TrackQueryAttempts(relay string, author string, kind int)

type SystemModifier 

type SystemModifier func(sys *System)

SystemModifier is a function that modifies a System instance. It's used with NewSystem to configure the system during creation.

func WithFallbackRelays 

func WithFallbackRelays(list []string) SystemModifier

WithFallbackRelays returns a SystemModifier that sets the FallbackRelays.

func WithFollowListCache 

func WithFollowListCache(cache cache.Cache32[GenericList[ProfileRef]]) SystemModifier

WithFollowListCache returns a SystemModifier that sets the FollowListCache.

func WithFollowListRelays 

func WithFollowListRelays(list []string) SystemModifier

WithFollowListRelays returns a SystemModifier that sets the FollowListRelays.

func WithHintsDB 

func WithHintsDB(hdb hints.HintsDB) SystemModifier

WithHintsDB returns a SystemModifier that sets the HintsDB.

func WithJustIDRelays 

func WithJustIDRelays(list []string) SystemModifier

WithJustIDRelays returns a SystemModifier that sets the JustIDRelays.

func WithKVStore 

func WithKVStore(store kvstore.KVStore) SystemModifier

WithKVStore returns a SystemModifier that sets the KVStore.

func WithMetadataCache 

func WithMetadataCache(cache cache.Cache32[ProfileMetadata]) SystemModifier

WithMetadataCache returns a SystemModifier that sets the MetadataCache.

func WithMetadataRelays 

func WithMetadataRelays(list []string) SystemModifier

WithMetadataRelays returns a SystemModifier that sets the MetadataRelays.

func WithNoteSearchRelays 

func WithNoteSearchRelays(list []string) SystemModifier

WithNoteSearchRelays returns a SystemModifier that sets the NoteSearchRelays.

func WithRelayListCache 

func WithRelayListCache(cache cache.Cache32[GenericList[Relay]]) SystemModifier

WithRelayListCache returns a SystemModifier that sets the RelayListCache.

func WithRelayListRelays 

func WithRelayListRelays(list []string) SystemModifier

WithRelayListRelays returns a SystemModifier that sets the RelayListRelays.

func WithStore 

func WithStore(store eventstore.Store) SystemModifier

WithStore returns a SystemModifier that sets the Store.

func WithUserSearchRelays 

func WithUserSearchRelays(list []string) SystemModifier

WithUserSearchRelays returns a SystemModifier that sets the UserSearchRelays.

type TagItemWithValue 

type TagItemWithValue interface {
	Value() string
}

type Topic 

type Topic string

func (Topic) Value 

func (r Topic) Value() string

type WotXorFilter 

type WotXorFilter struct {
	Items int
	xorfilter.Xor8
}

func (WotXorFilter) Contains 

func (wxf WotXorFilter) Contains(pubkey string) bool

Source Files

View all Source files

Directories

Path Synopsis
memory
badgerh
lmdbh
memoryh
sqlh
test
badger
lmdb
memory

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.