event

Documentation

Index

• func Hash(in []byte) (out []byte)
• type C
• type E
  • func New() *E
  • func (ev *E) EstimateSize() (size int)
  • func (ev *E) Free()
  • func (ev *E) GetIDBytes() []byte
  • func (ev *E) Marshal(dst []byte) (b []byte)
  • func (ev *E) MarshalBinary(w io.Writer)
  • func (ev *E) MarshalJSON() (b []byte, err error)
  • func (ev *E) Serialize() (b []byte)
  • func (ev *E) Sign(keys signer.I) (err error)
  • func (ev *E) ToCanonical(dst []byte) (b []byte)
  • func (ev *E) Unmarshal(b []byte) (rem []byte, err error)
  • func (ev *E) UnmarshalBinary(r io.Reader) (err error)
  • func (ev *E) UnmarshalJSON(b []byte) (err error)
  • func (ev *E) Verify() (valid bool, err error)
• type S
  • func (ev S) Len() int
  • func (ev S) Less(i, j int) bool
  • func (ev S) Swap(i, j int)

Functions

func Hash

func Hash(in []byte) (out []byte)

Hash is a little helper generate a hash and return a slice instead of an array.

Types

type C

type C chan *E

C is a channel that carries event.E.

type E

type E struct {

	// ID is the SHA256 hash of the canonical encoding of the event in binary
	// format
	ID []byte

	// Pubkey is the public key of the event creator in binary format
	Pubkey []byte

	// CreatedAt is the UNIX timestamp of the event according to the event
	// creator (never trust a timestamp!)
	CreatedAt int64

	// Kind is the nostr protocol code for the type of event. See kind.T
	Kind uint16

	// Tags are a list of tags, which are a list of strings usually structured
	// as a 3-layer scheme indicating specific features of an event.
	Tags *tag.S

	// Content is an arbitrary string that can contain anything, but usually
	// conforming to a specification relating to the Kind and the Tags.
	Content []byte

	// Sig is the signature on the ID hash that validates as coming from the
	// Pubkey in binary format.
	Sig []byte
	// contains filtered or unexported fields
}

E is the primary datatype of nostr. This is the form of the structure that defines its JSON string-based format. Always use New() and Free() to create and free event.E to take advantage of the bufpool which greatly improves memory allocation behaviour when encoding and decoding nostr events.

WARNING: DO NOT use json.Marshal with this type because it will not properly encode <, >, and & characters due to legacy bullcrap in the encoding/json library. Either call MarshalJSON directly or use a json.Encoder with html escaping disabled.

Or import "next.orly.dev/pkg/encoders/json" and use json.Marshal which is the same as go 1.25 json v1 except with this one stupidity removed.

func New

func New() *E

New returns a new event.E. The returned event.E should be freed with Free() to return the unmarshalling buffer to the bufpool.

func (*E) EstimateSize

func (ev *E) EstimateSize() (size int)

EstimateSize returns a size for the event that allows for worst case scenario expansion of the escaped content and tags.

func (*E) Free

func (ev *E) Free()

Free returns the event.E to the pool, as well as nilling all of the fields. This should hint to the GC that the event.E can be freed, and the memory reused. The decode buffer will be returned to the pool for reuse.

func (*E) GetIDBytes

func (ev *E) GetIDBytes() []byte

GetIDBytes returns the raw SHA256 hash of the canonical form of an event.E.

func (*E) Marshal

func (ev *E) Marshal(dst []byte) (b []byte)

func (*E) MarshalBinary

func (ev *E) MarshalBinary(w io.Writer)

MarshalBinary writes a binary encoding of an event.

[ 32 bytes ID ] [ 32 bytes Pubkey ] [ varint CreatedAt ] [ 2 bytes Kind ] [ varint Tags length ]

[ varint tag length ]
  [ varint tag element length ]
  [ tag element data ]
...

[ varint Content length ] [ 64 bytes Sig ]

func (*E) MarshalJSON

func (ev *E) MarshalJSON() (b []byte, err error)

MarshalJSON marshals an event.E into a JSON byte string.

Call bufpool.PutBytes(b) to return the buffer to the bufpool after use.

WARNING: if json.Marshal is called in the hopes of invoking this function on an event, if it has <, > or * in the content or tags they are escaped into unicode escapes and break the event ID. Call this function directly in order to bypass this issue.

func (*E) Serialize

func (ev *E) Serialize() (b []byte)

func (*E) Sign

func (ev *E) Sign(keys signer.I) (err error)

Sign the event using the signer.I. Uses github.com/bitcoin-core/secp256k1 if available for much faster signatures.

Note that this only populates the Pubkey, ID and Sig. The caller must set the CreatedAt timestamp as intended.

func (*E) ToCanonical

func (ev *E) ToCanonical(dst []byte) (b []byte)

ToCanonical converts the event to the canonical encoding used to derive the event ID.

func (*E) Unmarshal

func (ev *E) Unmarshal(b []byte) (rem []byte, err error)

Unmarshal unmarshalls a JSON string into an event.E.

Call ev.Free() to return the provided buffer to the bufpool afterwards.

func (*E) UnmarshalBinary

func (ev *E) UnmarshalBinary(r io.Reader) (err error)

func (*E) UnmarshalJSON

func (ev *E) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON unmarshalls a JSON string into an event.E.

Call ev.Free() to return the provided buffer to the bufpool afterwards.

func (*E) Verify

func (ev *E) Verify() (valid bool, err error)

Verify an event is signed by the pubkey it contains. Uses github.com/bitcoin-core/secp256k1 if available for faster verification.

type S

type S []*E

S is an array of event.E that sorts in reverse chronological order.

func (S) Len

func (ev S) Len() int

Len returns the length of the event.Es.

func (S) Less

func (ev S) Less(i, j int) bool

Less returns whether the first is newer than the second (larger unix timestamp).

func (S) Swap

func (ev S) Swap(i, j int)

Swap two indexes of the event.Es with each other.