nostr

Documentation

Overview

Package nostr provides signed Nostr events, JSON filters, canonical wire encoding, signature validation, tag helpers and standard kind ranges.

Validate and Parse check the event wire shape, ID and signature. They do not apply kind-specific schemas or decide whether a host should accept an event. Matches evaluates filter constraints and content search without enforcing visibility. Callers must apply authorization and private-content policy.

Canonical encodes a complete wire object; Sign and Validate use the NIP-01 canonical array internally to derive and verify the event ID. Filter search uses case-insensitive content terms and ignores name:value tokens. It is not a ranked search engine.

Index

• func Canonical(e Event) ([]byte, error)
• func CommittedDifficulty(e Event) int
• func Difficulty(id string) int
• func Expiration(e Event) int64
• func GenerateKey() (string, error)
• func IsAddressable(k int) bool
• func IsEphemeral(k int) bool
• func IsReplaceable(k int) bool
• func Matches(f Filter, e Event) bool
• func PublicKey(secretHex string) (string, error)
• func SearchTerms(query string) []string
• func Sign(e *Event, secretHex string) error
• func Tag(e Event, name string) string
• func TagValues(e Event, name string) []string
• func Validate(e Event) error
• type Event
  • func Parse(raw []byte) (Event, error)
• type EventRef
• type Filter
  • func ParseFilter(raw []byte) (Filter, error)
  • func (f Filter) MarshalJSON() ([]byte, error)

Functions

func Canonical

func Canonical(e Event) ([]byte, error)

Canonical encodes e as the JSON representation used on relay boundaries.

func CommittedDifficulty

func CommittedDifficulty(e Event) int

CommittedDifficulty returns the target in a nonce tag's third field.

func Difficulty

func Difficulty(id string) int

Difficulty returns the NIP-13 proof-of-work difficulty encoded by id.

func Expiration

func Expiration(e Event) int64

Expiration returns the positive Unix timestamp in the expiration tag. Malformed, missing and nonpositive values return zero.

func GenerateKey

func GenerateKey() (string, error)

GenerateKey creates a random nonzero 32-byte private key in hexadecimal.

func IsAddressable

func IsAddressable(k int) bool

IsAddressable reports whether k is an addressable event kind.

func IsEphemeral

func IsEphemeral(k int) bool

IsEphemeral reports whether k is in Nostr's ephemeral kind range.

func IsReplaceable

func IsReplaceable(k int) bool

IsReplaceable reports whether k is a replaceable event kind.

func Matches

func Matches(f Filter, e Event) bool

Matches reports whether e satisfies every populated constraint in f. Search terms are matched against content without classifying event kinds. Callers must enforce visibility and authorization before returning matches.

func PublicKey

func PublicKey(secretHex string) (string, error)

PublicKey derives the x-only Schnorr public key for secretHex.

func SearchTerms

func SearchTerms(query string) []string

SearchTerms splits a search query into terms and drops protocol-style name:value tokens.

func Sign

func Sign(e *Event, secretHex string) error

Sign derives the public key, ID and Schnorr signature for e from secretHex. A nil tag slice is encoded as an empty tag list before signing.

func Tag

func Tag(e Event, name string) string

Tag returns the first value for name, or an empty string when the tag is absent or has no value.

func TagValues

func TagValues(e Event, name string) []string

TagValues returns every first value belonging to tags named name.

func Validate

func Validate(e Event) error

Validate checks the wire shape, canonical ID and Schnorr signature of e. Kind-specific checks are applied by the protocol gate that owns the kind.

Types

type Event

type Event struct {
	ID        string     `json:"id"`
	PubKey    string     `json:"pubkey"`
	CreatedAt int64      `json:"created_at"`
	Kind      int        `json:"kind"`
	Tags      [][]string `json:"tags"`
	Content   string     `json:"content"`
	Sig       string     `json:"sig"`
}

func Parse

func Parse(raw []byte) (Event, error)

Parse decodes and validates one complete JSON event object.

type EventRef

type EventRef struct {
	ID        string
	Timestamp int64
}

EventRef identifies an event and its creation time without carrying its content. Relay synchronization uses these pairs to reconcile event sets.

type Filter

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

Filter describes the event fields and tags a subscription or query accepts. Fields combine with AND; values within a list are alternatives. Nil IDs, Authors and Kinds leave that field unrestricted, while an empty non-nil list matches nothing. Tags uses names without the wire prefix #. Since and Until are inclusive Unix timestamps. Limit controls a historical result batch; Matches evaluates each event independently of that limit.

func ParseFilter

func ParseFilter(raw []byte) (Filter, error)

ParseFilter decodes supported Nostr filter fields, including #tag keys, and checks their JSON types.

func (Filter) MarshalJSON

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

MarshalJSON encodes tag constraints with their Nostr #name wire keys.