nostr

README

go-nostr

A set of useful things for Nostr Protocol implementations.

Subscribing to a set of relays

pool := nostr.NewRelayPool()

pool.Add("wss://relay.nostr.com/", &nostr.RelayPoolPolicy{
	SimplePolicy: nostr.SimplePolicy{Read: true, Write: true},
})
pool.Add("wss://nostrrelay.example.com/", &nostr.RelayPoolPolicy{
	SimplePolicy: nostr.SimplePolicy{Read: true, Write: true},
})

for notice := range pool.Notices {
	log.Printf("%s has sent a notice: '%s'\n", notice.Relay, notice.Message)
}

Listening for events

sub := pool.Sub(nostr.EventFilters{
	{
		Authors: []string{"0ded86bf80c76847320b16f22b7451c08169434837a51ad5fe3b178af6c35f5d"},
		Kinds:   []string{nostr.KindTextNote}, // or {1}
	},
})

go func() {
	for event := range sub.UniqueEvents {
		log.Print(event)
	}
}()

time.Sleep(5 * time.Second)
sub.Unsub()

Publishing an event

secretKey := "3f06a81e0a0c2ad34ee9df2a30d87a810da9e3c3881f780755ace5e5e64d30a7"

pool.SecretKey = &secretKey

event, statuses, _ := pool.PublishEvent(&nostr.Event{
	CreatedAt: uint32(time.Now().Unix()),
	Kind:      nostr.KindTextNote,
	Tags:      make(nostr.Tags, 0),
	Content:   "hello",
})

log.Print(event.PubKey)
log.Print(event.ID)
log.Print(event.Sig)

for status := range statuses {
	switch status.Status {
	case nostr.PublishStatusSent:
		fmt.Printf("Sent event %s to '%s'.\n", event.ID, status.Relay)
	case nostr.PublishStatusFailed:
		fmt.Printf("Failed to send event %s to '%s'.\n", event.ID, status.Relay)
	case nostr.PublishStatusSucceeded:
		fmt.Printf("Event seen %s on '%s'.\n", event.ID, status.Relay)
	}
}

Generating a key

sk, _ := nostr.GenerateKey()

fmt.Println("sk:", sk)
fmt.Println("pk:", nostr.GetPublicKey(sk))

Documentation

Index

• Constants
• func FilterEqual(a EventFilter, b EventFilter) bool
• func GeneratePrivateKey() string
• func GetPublicKey(sk string) (string, error)
• func NormalizeURL(u string) string
• type Connection
  • func NewConnection(socket *websocket.Conn) *Connection
  • func (c *Connection) Close() error
  • func (c *Connection) WriteJSON(v interface{}) error
  • func (c *Connection) WriteMessage(messageType int, data []byte) error
• type Event
  • func (evt Event) CheckSignature() (bool, error)
  • func (evt *Event) Serialize() []byte
  • func (evt *Event) Sign(privateKey string) error
• type EventFilter
  • func (ef EventFilter) Matches(event *Event) bool
• type EventFilters
  • func (eff EventFilters) Match(event *Event) bool
• type EventMessage
• type IntList
  • func (haystack IntList) Contains(needle int) bool
  • func (as IntList) Equals(bs IntList) bool
• type NoticeMessage
• type PublishStatus
• type RelayPool
  • func NewRelayPool() *RelayPool
  • func (r *RelayPool) Add(url string, policy RelayPoolPolicy) error
  • func (r *RelayPool) PublishEvent(evt *Event) (*Event, chan PublishStatus, error)
  • func (r *RelayPool) Remove(url string)
  • func (r *RelayPool) Sub(filters EventFilters) *Subscription
• type RelayPoolPolicy
• type SimplePolicy
  • func (s SimplePolicy) ShouldRead(_ EventFilters) bool
  • func (s SimplePolicy) ShouldWrite(_ *Event) bool
• type StringList
  • func (haystack StringList) Contains(needle string) bool
  • func (as StringList) Equals(bs StringList) bool
• type Subscription
  • func (subscription Subscription) Sub()
  • func (subscription Subscription) Unsub()
• type Tag
• type Tags
  • func (tags Tags) ContainsAny(tagName string, values StringList) bool
  • func (t *Tags) Scan(src interface{}) error

Constants

const (
	KindSetMetadata            int = 0
	KindTextNote               int = 1
	KindRecommendServer        int = 2
	KindContactList            int = 3
	KindEncryptedDirectMessage int = 4
	KindDeletion               int = 5
)

const (
	PublishStatusSent      = 0
	PublishStatusFailed    = -1
	PublishStatusSucceeded = 1
)

Functions

func FilterEqual

func FilterEqual(a EventFilter, b EventFilter) bool

func GeneratePrivateKey

func GeneratePrivateKey() string

func GetPublicKey

func GetPublicKey(sk string) (string, error)

func NormalizeURL

func NormalizeURL(u string) string

Types

type Connection

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

func NewConnection

func NewConnection(socket *websocket.Conn) *Connection

func (*Connection) Close

func (c *Connection) Close() error

func (*Connection) WriteJSON

func (c *Connection) WriteJSON(v interface{}) error

func (*Connection) WriteMessage

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

type Event

type Event struct {
	ID string `json:"id"` // it's the hash of the serialized event

	PubKey    string `json:"pubkey"`
	CreatedAt uint32 `json:"created_at"`

	Kind int `json:"kind"`

	Tags    Tags   `json:"tags"`
	Content string `json:"content"`
	Sig     string `json:"sig"`
}

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) Serialize

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

Serialize outputs a byte array that can be hashed/signed to identify/authenticate

func (*Event) Sign

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

Sign signs an event with a given privateKey

type EventFilter

type EventFilter struct {
	IDs     StringList `json:"ids,omitempty"`
	Kinds   IntList    `json:"kinds,omitempty"`
	Authors StringList `json:"authors,omitempty"`
	Since   uint32     `json:"since,omitempty"`
	Until   uint32     `json:"until,omitempty"`
	TagE    StringList `json:"#e,omitempty"`
	TagP    StringList `json:"#p,omitempty"`
}

func (EventFilter) Matches

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

type EventFilters

type EventFilters []EventFilter

func (EventFilters) Match

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

type EventMessage

type EventMessage struct {
	Event Event
	Relay string
}

type IntList

type IntList []int

func (IntList) Contains

func (haystack IntList) Contains(needle int) bool

func (IntList) Equals

func (as IntList) Equals(bs IntList) bool

type NoticeMessage

type NoticeMessage struct {
	Message string
	Relay   string
}

type PublishStatus

type PublishStatus struct {
	Relay  string
	Status int
}

type RelayPool

type RelayPool struct {
	SecretKey *string

	Relays map[string]RelayPoolPolicy

	Notices chan *NoticeMessage
	// contains filtered or unexported fields
}

func NewRelayPool

func NewRelayPool() *RelayPool

New creates a new RelayPool with no relays in it

func (*RelayPool) Add

func (r *RelayPool) Add(url string, policy RelayPoolPolicy) error

Add adds a new relay to the pool, if policy is nil, it will be a simple read+write policy.

func (*RelayPool) PublishEvent

func (r *RelayPool) PublishEvent(evt *Event) (*Event, chan PublishStatus, error)

func (*RelayPool) Remove

func (r *RelayPool) Remove(url string)

Remove removes a relay from the pool.

func (*RelayPool) Sub

func (r *RelayPool) Sub(filters EventFilters) *Subscription

type RelayPoolPolicy

type RelayPoolPolicy interface {
	ShouldRead(EventFilters) bool
	ShouldWrite(*Event) bool
}

type SimplePolicy

type SimplePolicy struct {
	Read  bool
	Write bool
}

func (SimplePolicy) ShouldRead

func (s SimplePolicy) ShouldRead(_ EventFilters) bool

func (SimplePolicy) ShouldWrite

func (s SimplePolicy) ShouldWrite(_ *Event) bool

type StringList

type StringList []string

func (StringList) Contains

func (haystack StringList) Contains(needle string) bool

func (StringList) Equals

func (as StringList) Equals(bs StringList) bool

type Subscription

type Subscription struct {
	Events chan EventMessage

	UniqueEvents chan Event
	// contains filtered or unexported fields
}

func (Subscription) Sub

func (subscription Subscription) Sub()

func (Subscription) Unsub

func (subscription Subscription) Unsub()

type Tag

type Tag []interface{}

type Tags

type Tags []Tag

func (Tags) ContainsAny

func (tags Tags) ContainsAny(tagName string, values StringList) bool

func (*Tags) Scan

func (t *Tags) Scan(src interface{}) error