nostr

package module
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Aug 29, 2023 License: MIT Imports: 35 Imported by: 0

README

go-nostr

A set of useful things for Nostr Protocol implementations.

GoDoc
test every commit

Install go-nostr:

go get github.com/studiokaiji/go-nostr
Generating a key
package main

import (
    "fmt"

    "github.com/studiokaiji/go-nostr"
    "github.com/studiokaiji/go-nostr/nip19"
)

func main() {
    sk := nostr.GeneratePrivateKey()
    pk, _ := nostr.GetPublicKey(sk)
    nsec, _ := nip19.EncodePrivateKey(sk)
    npub, _ := nip19.EncodePublicKey(pk)

    fmt.Println("sk:", sk)
    fmt.Println("pk:", pk)
    fmt.Println(nsec)
    fmt.Println(npub)
}
Subscribing to a single relay
ctx := context.Background()
relay, err := nostr.RelayConnect(ctx, "wss://nostr.zebedee.cloud")
if err != nil {
	panic(err)
}

npub := "npub1422a7ws4yul24p0pf7cacn7cghqkutdnm35z075vy68ggqpqjcyswn8ekc"

var filters nostr.Filters
if _, v, err := nip19.Decode(npub); err == nil {
	pub := v.(string)
	filters = []nostr.Filter{{
		Kinds:   []int{nostr.KindTextNote},
		Authors: []string{pub},
		Limit:   1,
	}}
} else {
	panic(err)
}

ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()

sub, err := relay.Subscribe(ctx, filters)
if err != nil {
	panic(err)
}

for ev := range sub.Events {
	// handle returned event.
	// channel will stay open until the ctx is cancelled (in this case, context timeout)
	fmt.Println(ev.ID)
}
Publishing to two relays
sk := nostr.GeneratePrivateKey()
pub, _ := nostr.GetPublicKey(sk)

ev := nostr.Event{
	PubKey:    pub,
	CreatedAt: nostr.Now(),
	Kind:      nostr.KindTextNote,
	Tags:      nil,
	Content:   "Hello World!",
}

// calling Sign sets the event ID field and the event Sig field
ev.Sign(sk)

// publish the event to two relays
ctx := context.Background()
for _, url := range []string{"wss://nostr.zebedee.cloud", "wss://nostr-pub.wellorder.net"} {
	relay, err := nostr.RelayConnect(ctx, url)
	if err != nil {
		fmt.Println(err)
		continue
	}
	_, err = relay.Publish(ctx, ev)
	if err != nil {
		fmt.Println(err)
		continue
	}

	fmt.Printf("published to %s\n", url)
}
Authenticating with NIP-42

For this section, the user needs access to a relay implementing NIP-42. E.g., https://github.com/fiatjaf/relayer with a relay implementing the relayer.Auther interface.

func main() {
	url := "ws://localhost:7447"

	sk := nostr.GeneratePrivateKey()

	relay, err := nostr.RelayConnect(context.Background(), url,
        nostr.WithAuthHandler(func(ctx context.Context, authEvent *Event) (ok bool) {
            authEvent.Sign(sk)
        }),
    )
	if err != nil {
		panic(err)
	}
}
Example script
go run example/example.go

Documentation

Index

Examples

Constants

View Source 
const (
	KindSetMetadata              int = 0
	KindTextNote                 int = 1
	KindRecommendServer          int = 2
	KindContactList              int = 3
	KindEncryptedDirectMessage   int = 4
	KindDeletion                 int = 5
	KindRepost                   int = 6
	KindReaction                 int = 7
	KindChannelCreation          int = 40
	KindChannelMetadata          int = 41
	KindChannelMessage           int = 42
	KindChannelHideMessage       int = 43
	KindChannelMuteUser          int = 44
	KindFileMetadata             int = 1063
	KindZapRequest               int = 9734
	KindZap                      int = 9735
	KindMuteList                 int = 10000
	KindPinList                  int = 10001
	KindRelayListMetadata        int = 10002
	KindNWCWalletInfo            int = 13194
	KindClientAuthentication     int = 22242
	KindNWCWalletRequest         int = 23194
	KindNWCWalletResponse        int = 23195
	KindNostrConnect             int = 24133
	KindCategorizedPeopleList    int = 30000
	KindCategorizedBookmarksList int = 30001
	KindProfileBadges            int = 30008
	KindBadgeDefinition          int = 30009
	KindStallDefinition          int = 30017
	KindProductDefinition        int = 30018
	KindArticle                  int = 30023
	KindApplicationSpecificData  int = 30078
)
View Source 
const MAX_LOCKS = 50

Variables

View Source 
var (
	// call SetOutput on InfoLogger to enable info logging
	InfoLogger = log.New(os.Stderr, "[go-nostr][info] ", log.LstdFlags)

	// call SetOutput on DebugLogger to enable debug logging
	DebugLogger = log.New(os.Stderr, "[go-nostr][debug] ", log.LstdFlags)
)

Functions

func FilterEqual 

func FilterEqual(a Filter, b Filter) bool

func GeneratePrivateKey 

func GeneratePrivateKey() string

func GetPublicKey 

func GetPublicKey(sk string) (string, error)

func IsValidPublicKeyHex 

func IsValidPublicKeyHex(pk string) bool

func IsValidRelayURL 

func IsValidRelayURL(u string) bool

func NormalizeURL 

func NormalizeURL(u string) string

NormalizeURL normalizes the url and replaces http://, https:// schemes by ws://, wss://.

Example 
fmt.Println(NormalizeURL(""))
fmt.Println(NormalizeURL("wss://x.com/y"))
fmt.Println(NormalizeURL("wss://x.com/y/"))
fmt.Println(NormalizeURL("http://x.com/y"))
fmt.Println(NormalizeURL(NormalizeURL("http://x.com/y")))
fmt.Println(NormalizeURL("wss://x.com"))
fmt.Println(NormalizeURL("wss://x.com/"))
fmt.Println(NormalizeURL(NormalizeURL(NormalizeURL("wss://x.com/"))))
fmt.Println(NormalizeURL("x.com"))
fmt.Println(NormalizeURL("x.com/"))
fmt.Println(NormalizeURL("x.com////"))
fmt.Println(NormalizeURL("x.com/?x=23"))

Output:


wss://x.com/y
wss://x.com/y
ws://x.com/y
ws://x.com/y
wss://x.com
wss://x.com
wss://x.com
wss://x.com
wss://x.com
wss://x.com
wss://x.com?x=23

Types

type AuthEnvelope 

type AuthEnvelope struct {
	Challenge *string
	Event     Event
}

func (AuthEnvelope) Label 

func (_ AuthEnvelope) Label() string

func (AuthEnvelope) MarshalJSON 

func (v AuthEnvelope) MarshalJSON() ([]byte, error)

func (*AuthEnvelope) UnmarshalJSON 

func (v *AuthEnvelope) UnmarshalJSON(data []byte) error

type CloseEnvelope 

type CloseEnvelope string

func (CloseEnvelope) Label 

func (_ CloseEnvelope) Label() string

func (CloseEnvelope) MarshalJSON 

func (v CloseEnvelope) MarshalJSON() ([]byte, error)

func (*CloseEnvelope) UnmarshalJSON 

func (v *CloseEnvelope) UnmarshalJSON(data []byte) error

type Connection 

type Connection struct {
	// contains filtered or unexported fields
}

func NewConnection 

func NewConnection(ctx context.Context, url string, requestHeader http.Header) (*Connection, error)

func (*Connection) Close 

func (c *Connection) Close() error

func (*Connection) ReadMessage 

func (c *Connection) ReadMessage(ctx context.Context, buf io.Writer) error

func (*Connection) WriteMessage 

func (c *Connection) WriteMessage(data []byte) error

type CountEnvelope 

type CountEnvelope struct {
	SubscriptionID string
	Filters
	Count *int64
}

func (CountEnvelope) Label 

func (_ CountEnvelope) Label() string

func (CountEnvelope) MarshalJSON 

func (v CountEnvelope) MarshalJSON() ([]byte, error)

func (*CountEnvelope) UnmarshalJSON 

func (v *CountEnvelope) UnmarshalJSON(data []byte) error

type EOSEEnvelope 

type EOSEEnvelope string

func (EOSEEnvelope) Label 

func (_ EOSEEnvelope) Label() string

func (EOSEEnvelope) MarshalJSON 

func (v EOSEEnvelope) MarshalJSON() ([]byte, error)

func (*EOSEEnvelope) UnmarshalJSON 

func (v *EOSEEnvelope) UnmarshalJSON(data []byte) error

type EntityPointer 

type EntityPointer struct {
	PublicKey  string   `json:"pubkey"`
	Kind       int      `json:"kind,omitempty"`
	Identifier string   `json:"identifier,omitempty"`
	Relays     []string `json:"relays,omitempty"`
}

type Envelope 

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

func ParseMessage 

func ParseMessage(message []byte) Envelope

type Event 

type Event struct {
	ID        string    `json:"id"`
	PubKey    string    `json:"pubkey"`
	CreatedAt Timestamp `json:"created_at"`
	Kind      int       `json:"kind"`
	Tags      Tags      `json:"tags"`
	Content   string    `json:"content"`
	Sig       string    `json:"sig"`
	// contains filtered or unexported fields
}

func (Event) CheckSignature 

func (evt Event) CheckSignature() (bool, error)

CheckSignature checks if the signature is valid for the id (which is a hash of the serialized event content). returns an error if the signature itself is invalid.

func (Event) GetExtra 

func (evt Event) GetExtra(key string) any

GetExtra tries to get a value under the given key that may be present in the event object but is hidden in the basic type since it is out of the spec.

func (Event) GetExtraBoolean 

func (evt Event) GetExtraBoolean(key string) bool

GetExtraBoolean is like Event.GetExtra, but only works if the value is a boolean, otherwise returns the zero-value.

func (Event) GetExtraNumber 

func (evt Event) GetExtraNumber(key string) float64

GetExtraNumber is like Event.GetExtra, but only works if the value is a float64, otherwise returns the zero-value.

func (Event) GetExtraString 

func (evt Event) GetExtraString(key string) string

GetExtraString is like Event.GetExtra, but only works if the value is a string, otherwise returns the zero-value.

func (*Event) GetID 

func (evt *Event) GetID() string

GetID serializes and returns the event ID as a string.

func (Event) MarshalEasyJSON 

func (v Event) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Event) MarshalJSON 

func (v Event) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Event) Serialize 

func (evt *Event) Serialize() []byte

Serialize outputs a byte array that can be hashed/signed to identify/authenticate. JSON encoding as defined in RFC4627.

func (*Event) SetExtra 

func (evt *Event) SetExtra(key string, value any)

SetExtra sets an out-of-the-spec value under the given key into the event object.

func (*Event) Sign 

func (evt *Event) Sign(privateKey string) error

Sign signs an event with a given privateKey.

func (Event) String 

func (evt Event) String() string

Event Stringer interface, just returns the raw JSON as a string.

func (*Event) UnmarshalEasyJSON 

func (v *Event) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Event) UnmarshalJSON 

func (v *Event) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type EventEnvelope 

type EventEnvelope struct {
	SubscriptionID *string
	Event
}

func (EventEnvelope) Label 

func (_ EventEnvelope) Label() string

func (EventEnvelope) MarshalJSON 

func (v EventEnvelope) MarshalJSON() ([]byte, error)

func (*EventEnvelope) UnmarshalJSON 

func (v *EventEnvelope) UnmarshalJSON(data []byte) error

type EventMessage 

type EventMessage struct {
	Event Event
	Relay string
}

type EventPointer 

type EventPointer struct {
	ID     string   `json:"id"`
	Relays []string `json:"relays,omitempty"`
	Author string   `json:"author,omitempty"`
	Kind   int      `json:"kind,omitempty"`
}

type Filter 

type Filter struct {
	IDs     []string   `json:"ids,omitempty"`
	Kinds   []int      `json:"kinds,omitempty"`
	Authors []string   `json:"authors,omitempty"`
	Tags    TagMap     `json:"-,omitempty"`
	Since   *Timestamp `json:"since,omitempty"`
	Until   *Timestamp `json:"until,omitempty"`
	Limit   int        `json:"limit,omitempty"`
	Search  string     `json:"search,omitempty"`
}

func (Filter) MarshalEasyJSON 

func (v Filter) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Filter) MarshalJSON 

func (v Filter) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (Filter) Matches 

func (ef Filter) Matches(event *Event) bool

func (Filter) String 

func (ef Filter) String() string

func (*Filter) UnmarshalEasyJSON 

func (v *Filter) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Filter) UnmarshalJSON 

func (v *Filter) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Filters 

type Filters []Filter

func (Filters) Match 

func (eff Filters) Match(event *Event) bool

func (Filters) String 

func (eff Filters) String() string

type NoticeEnvelope 

type NoticeEnvelope string

func (NoticeEnvelope) Label 

func (_ NoticeEnvelope) Label() string

func (NoticeEnvelope) MarshalJSON 

func (v NoticeEnvelope) MarshalJSON() ([]byte, error)

func (*NoticeEnvelope) UnmarshalJSON 

func (v *NoticeEnvelope) UnmarshalJSON(data []byte) error

type OKEnvelope 

type OKEnvelope struct {
	EventID string
	OK      bool
	Reason  *string
}

func (OKEnvelope) Label 

func (_ OKEnvelope) Label() string

func (OKEnvelope) MarshalJSON 

func (v OKEnvelope) MarshalJSON() ([]byte, error)

func (*OKEnvelope) UnmarshalJSON 

func (v *OKEnvelope) UnmarshalJSON(data []byte) error

type ProfileMetadata 

type ProfileMetadata struct {
	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"`
}

func ParseMetadata 

func ParseMetadata(event Event) (*ProfileMetadata, error)

type ProfilePointer 

type ProfilePointer struct {
	PublicKey string   `json:"pubkey"`
	Relays    []string `json:"relays,omitempty"`
}

type Relay 

type Relay struct {
	URL           string
	RequestHeader http.Header // e.g. for origin header

	Connection    *Connection
	Subscriptions *xsync.MapOf[string, *Subscription]

	ConnectionError error

	// custom things that aren't often used
	//
	AssumeValid bool // this will skip verifying signatures for events received from this relay
	// contains filtered or unexported fields
}

func NewRelay 

func NewRelay(ctx context.Context, url string, opts ...RelayOption) *Relay

NewRelay returns a new relay. The relay connection will be closed when the context is canceled.

func RelayConnect 

func RelayConnect(ctx context.Context, url string, opts ...RelayOption) (*Relay, error)

RelayConnect returns a relay object connected to url. Once successfully connected, cancelling ctx has no effect. To close the connection, call r.Close().

func (*Relay) Auth 

func (r *Relay) Auth(ctx context.Context, event Event) (Status, error)

Auth sends an "AUTH" command client -> relay as in NIP-42. Status can be: success, failed, or sent (no response from relay before ctx times out).

func (*Relay) Close 

func (r *Relay) Close() error

func (*Relay) Connect 

func (r *Relay) Connect(ctx context.Context) error

Connect tries to establish a websocket connection to r.URL. If the context expires before the connection is complete, an error is returned. Once successfully connected, context expiration has no effect: call r.Close to close the connection.

The underlying relay connection will use a background context. If you want to pass a custom context to the underlying relay connection, use NewRelay() and then Relay.Connect().

func (*Relay) Context 

func (r *Relay) Context() context.Context

Context retrieves the context that is associated with this relay connection.

func (*Relay) Count 

func (r *Relay) Count(ctx context.Context, filters Filters, opts ...SubscriptionOption) (int64, error)

func (*Relay) IsConnected 

func (r *Relay) IsConnected() bool

IsConnected returns true if the connection to this relay seems to be active.

func (*Relay) PrepareSubscription 

func (r *Relay) PrepareSubscription(ctx context.Context, filters Filters, opts ...SubscriptionOption) *Subscription

PrepareSubscription creates a subscription, but doesn't fire it.

func (*Relay) Publish 

func (r *Relay) Publish(ctx context.Context, event Event) (Status, error)

Publish sends an "EVENT" command to the relay r as in NIP-01. Status can be: success, failed, or sent (no response from relay before ctx times out).

func (*Relay) QuerySync 

func (r *Relay) QuerySync(ctx context.Context, filter Filter, opts ...SubscriptionOption) ([]*Event, error)

func (*Relay) String 

func (r *Relay) String() string

String just returns the relay URL.

func (*Relay) Subscribe 

func (r *Relay) Subscribe(ctx context.Context, filters Filters, opts ...SubscriptionOption) (*Subscription, error)

Subscribe sends a "REQ" command to the relay r as in NIP-01. Events are returned through the channel sub.Events. The subscription is closed when context ctx is cancelled ("CLOSE" in NIP-01).

func (*Relay) Write 

func (r *Relay) Write(msg []byte) <-chan error

Write queues a message to be sent to the relay.

type RelayOption 

type RelayOption interface {
	IsRelayOption()
}

When instantiating relay connections, some options may be passed. RelayOption is the type of the argument passed for that. Some examples of this are WithNoticeHandler and WithAuthHandler.

type ReqEnvelope 

type ReqEnvelope struct {
	SubscriptionID string
	Filters
}

func (ReqEnvelope) Label 

func (_ ReqEnvelope) Label() string

func (ReqEnvelope) MarshalJSON 

func (v ReqEnvelope) MarshalJSON() ([]byte, error)

func (*ReqEnvelope) UnmarshalJSON 

func (v *ReqEnvelope) UnmarshalJSON(data []byte) error

type SimplePool added in v0.0.2 

type SimplePool struct {
	Relays  map[string]*Relay
	Context context.Context
	// contains filtered or unexported fields
}

func NewSimplePool added in v0.0.2 

func NewSimplePool(ctx context.Context) *SimplePool

func (*SimplePool) EnsureRelay added in v0.0.2 

func (pool *SimplePool) EnsureRelay(url string) (*Relay, error)

func (*SimplePool) QuerySingle added in v0.0.2 

func (pool *SimplePool) QuerySingle(ctx context.Context, urls []string, filter Filter) *Event

QuerySingle returns the first event returned by the first relay, cancels everything else.

func (*SimplePool) SubMany added in v0.0.2 

func (pool *SimplePool) SubMany(ctx context.Context, urls []string, filters Filters) chan *Event

SubMany opens a subscription with the given filters to multiple relays the subscriptions only end when the context is canceled

func (*SimplePool) SubManyEose added in v0.0.2 

func (pool *SimplePool) SubManyEose(ctx context.Context, urls []string, filters Filters) chan *Event

SubManyEose is like SubMany, but it stops subscriptions and closes the channel when gets a EOSE

type Status 

type Status int
const (
	PublishStatusSent      Status = 0
	PublishStatusFailed    Status = -1
	PublishStatusSucceeded Status = 1
)

func (Status) String 

func (s Status) String() string

type Subscription 

type Subscription struct {
	Relay   *Relay
	Filters Filters

	// the Events channel emits all EVENTs that come in a Subscription
	// will be closed when the subscription ends
	Events chan *Event

	// the EndOfStoredEvents channel gets closed when an EOSE comes for that subscription
	EndOfStoredEvents chan struct{}

	// Context will be .Done() when the subscription ends
	Context context.Context
	// contains filtered or unexported fields
}

func (*Subscription) Close 

func (sub *Subscription) Close()

Close just sends a CLOSE message. You probably want Unsub() instead.

func (*Subscription) Fire 

func (sub *Subscription) Fire() error

Fire sends the "REQ" command to the relay.

func (*Subscription) GetID 

func (sub *Subscription) GetID() string

GetID return the Nostr subscription ID as given to the Relay it is a concatenation of the label and a serial number.

func (*Subscription) Sub 

func (sub *Subscription) Sub(_ context.Context, filters Filters)

Sub sets sub.Filters and then calls sub.Fire(ctx). The subscription will be closed if the context expires.

func (*Subscription) Unsub 

func (sub *Subscription) Unsub()

Unsub closes the subscription, sending "CLOSE" to relay as in NIP-01. Unsub() also closes the channel sub.Events and makes a new one.

type SubscriptionOption 

type SubscriptionOption interface {
	IsSubscriptionOption()
}

When instantiating relay connections, some options may be passed. SubscriptionOption is the type of the argument passed for that. Some examples are WithLabel.

type Tag 

type Tag []string

func (Tag) Key 

func (tag Tag) Key() string

func (Tag) Relay 

func (tag Tag) Relay() string

func (Tag) StartsWith 

func (tag Tag) StartsWith(prefix []string) bool

StartsWith checks if a tag contains a prefix. for example, 

["p", "abcdef...", "wss://relay.com"]

would match against 

["p", "abcdef..."]

or even 

["p", "abcdef...", "wss://"]

func (Tag) Value 

func (tag Tag) Value() string

type TagMap 

type TagMap map[string][]string

type Tags 

type Tags []Tag

func (Tags) AppendUnique 

func (tags Tags) AppendUnique(tag Tag) Tags

AppendUnique appends a tag if it doesn't exist yet, otherwise does nothing. the uniqueness comparison is done based only on the first 2 elements of the tag.

func (Tags) ContainsAny 

func (tags Tags) ContainsAny(tagName string, values []string) bool

func (Tags) FilterOut 

func (tags Tags) FilterOut(tagPrefix []string) Tags

FilterOut removes all tags that match the prefix, see Tag.StartsWith

func (Tags) GetAll 

func (tags Tags) GetAll(tagPrefix []string) Tags

GetAll gets all the tags that match the prefix, see Tag.StartsWith

func (Tags) GetFirst 

func (tags Tags) GetFirst(tagPrefix []string) *Tag

GetFirst gets the first tag in tags that matches the prefix, see Tag.StartsWith

func (Tags) GetLast 

func (tags Tags) GetLast(tagPrefix []string) *Tag

GetLast gets the last tag in tags that matches the prefix, see Tag.StartsWith

func (*Tags) Scan 

func (t *Tags) Scan(src any) error

type Timestamp 

type Timestamp int64

func Now 

func Now() Timestamp

func (Timestamp) Time 

func (t Timestamp) Time() time.Time

type WithAuthHandler 

type WithAuthHandler func(ctx context.Context, authEvent *Event) (ok bool)

WithAuthHandler takes an auth event and expects it to be signed. when not given, AUTH messages from relays are ignored.

func (WithAuthHandler) IsRelayOption 

func (_ WithAuthHandler) IsRelayOption()

type WithLabel 

type WithLabel string

WithLabel puts a label on the subscription (it is prepended to the automatic id) that is sent to relays.

func (WithLabel) IsSubscriptionOption 

func (_ WithLabel) IsSubscriptionOption()

type WithNoticeHandler 

type WithNoticeHandler func(notice string)

WithNoticeHandler just takes notices and is expected to do something with them. when not given, defaults to logging the notices.

func (WithNoticeHandler) IsRelayOption 

func (_ WithNoticeHandler) IsRelayOption()

Source Files

View all Source files

Directories

Path Synopsis
Package nip13 implements NIP-13 See https://github.com/nostr-protocol/nips/blob/master/13.md for details.
 Package nip13 implements NIP-13 See https://github.com/nostr-protocol/nips/blob/master/13.md for details.

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.