sdk

package
v0.51.10 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2025 License: MIT Imports: 31 Imported by: 10

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 added in v0.36.0 

func IsVirtualRelay(url string) bool

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

func PerQueryLimitInBatch added in v0.46.0 

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 PubKeyToShid added in v0.51.9 

func PubKeyToShid(pubkey string) uint64

Types

type EventRef added in v0.46.0 

type EventRef struct{ nostr.Pointer }

func (EventRef) Value added in v0.46.0 

func (e EventRef) Value() string

type EventResult added in v0.36.0 

type EventResult dataloader.Result[*nostr.Event]

type FetchSpecificEventParameters added in v0.50.0 

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 added in v0.36.0 

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 added in v0.46.0 

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

	Sets map[string][]I
}

type ProfileMetadata added in v0.36.0 

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 added in v0.36.0 

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 added in v0.42.3 

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

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

func (ProfileMetadata) Nprofile added in v0.36.0 

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 added in v0.36.0 

func (p ProfileMetadata) Npub() string

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

func (ProfileMetadata) NpubShort added in v0.36.0 

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 added in v0.36.0 

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 added in v0.46.0 

type ProfileRef struct {
	Pubkey  string
	Relay   string
	Petname string
}

func (ProfileRef) Value added in v0.46.0 

func (f ProfileRef) Value() string

type Relay added in v0.19.3 

type Relay struct {
	URL    string
	Inbox  bool
	Outbox bool
}

func (Relay) Value added in v0.36.0 

func (r Relay) Value() string

type RelayStream added in v0.38.2 

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 added in v0.38.2 

func NewRelayStream(urls ...string) *RelayStream

NewRelayStream creates a new RelayStream with the provided URLs.

func (*RelayStream) Next added in v0.38.2 

func (rs *RelayStream) Next() string

Next returns the next URL in the rotation.

type RelayURL added in v0.46.0 

type RelayURL string

func (RelayURL) Value added in v0.46.0 

func (r RelayURL) Value() string

type System added in v0.36.0 

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 added in v0.36.0 

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 added in v0.36.0 

func (sys *System) Close()

Close releases resources held by the System.

func (*System) FetchBlockedRelayList added in v0.46.0 

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

func (*System) FetchBookmarkList added in v0.46.0 

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

func (*System) FetchFeedPage added in v0.48.1 

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 added in v0.36.0 

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

func (*System) FetchFollowSets added in v0.46.0 

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

func (*System) FetchInboxRelays added in v0.48.3 

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 added in v0.36.0 

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

func (*System) FetchOutboxRelays added in v0.36.0 

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 added in v0.46.0 

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

func (System) FetchProfileFromInput added in v0.36.0 

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 added in v0.36.0 

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 added in v0.46.0 

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

func (*System) FetchRelaySets added in v0.46.0 

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

func (*System) FetchSearchRelayList added in v0.46.0 

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

func (*System) FetchSpecificEvent added in v0.38.2 

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 added in v0.46.0 

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 added in v0.46.0 

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

func (*System) FetchTopicSets added in v0.46.0 

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

func (*System) FetchWriteRelays added in v0.49.3 

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 added in v0.47.0 

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 added in v0.51.9 

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

func (*System) SearchUsers added in v0.36.0 

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

func (*System) StreamLiveFeed added in v0.48.1 

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 added in v0.37.0 

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 added in v0.47.0 

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 added in v0.47.0 

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

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

func (*System) TrackQueryAttempts added in v0.45.0 

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

type SystemModifier added in v0.36.0 

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 added in v0.36.0 

func WithFallbackRelays(list []string) SystemModifier

WithFallbackRelays returns a SystemModifier that sets the FallbackRelays.

func WithFollowListCache added in v0.36.0 

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

WithFollowListCache returns a SystemModifier that sets the FollowListCache.

func WithFollowListRelays added in v0.36.0 

func WithFollowListRelays(list []string) SystemModifier

WithFollowListRelays returns a SystemModifier that sets the FollowListRelays.

func WithHintsDB added in v0.36.0 

func WithHintsDB(hdb hints.HintsDB) SystemModifier

WithHintsDB returns a SystemModifier that sets the HintsDB.

func WithJustIDRelays added in v0.38.2 

func WithJustIDRelays(list []string) SystemModifier

WithJustIDRelays returns a SystemModifier that sets the JustIDRelays.

func WithKVStore added in v0.47.0 

func WithKVStore(store kvstore.KVStore) SystemModifier

WithKVStore returns a SystemModifier that sets the KVStore.

func WithMetadataCache added in v0.36.0 

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

WithMetadataCache returns a SystemModifier that sets the MetadataCache.

func WithMetadataRelays added in v0.36.0 

func WithMetadataRelays(list []string) SystemModifier

WithMetadataRelays returns a SystemModifier that sets the MetadataRelays.

func WithNoteSearchRelays added in v0.36.0 

func WithNoteSearchRelays(list []string) SystemModifier

WithNoteSearchRelays returns a SystemModifier that sets the NoteSearchRelays.

func WithRelayListCache added in v0.36.0 

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

WithRelayListCache returns a SystemModifier that sets the RelayListCache.

func WithRelayListRelays added in v0.36.0 

func WithRelayListRelays(list []string) SystemModifier

WithRelayListRelays returns a SystemModifier that sets the RelayListRelays.

func WithStore added in v0.36.0 

func WithStore(store eventstore.Store) SystemModifier

WithStore returns a SystemModifier that sets the Store.

func WithUserSearchRelays added in v0.36.0 

func WithUserSearchRelays(list []string) SystemModifier

WithUserSearchRelays returns a SystemModifier that sets the UserSearchRelays.

type TagItemWithValue added in v0.36.0 

type TagItemWithValue interface {
	Value() string
}

type Topic added in v0.46.0 

type Topic string

func (Topic) Value added in v0.46.0 

func (r Topic) Value() string

type WotXorFilter added in v0.51.9 

type WotXorFilter struct {
	Items int
	xorfilter.Xor8
}

func (WotXorFilter) Contains added in v0.51.9 

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.