refactoring, added documentation

event.go

@@ -1,166 +1,63 @@
+// Roots is a purposefully minimal, core Nostr protocol library that provides
+// mathematically invariant primitives that define protocol compliance: event
+// structure, serialization, cryptographic signatures, and subscription
+// filters.
 package roots
 
 import (
-	"crypto/sha256"
-	"encoding/hex"
-	"encoding/json"
 	"errors"
-	"fmt"
 	"regexp"
-
-	"github.com/btcsuite/btcd/btcec/v2"
-	"github.com/btcsuite/btcd/btcec/v2/schnorr"
 )
 
+// Tag represents a single tag within an event as an array of strings.
+// The first element identifies the tag name, the second contains the value,
+// and subsequent elements are optional.
+type Tag []string
+
+// Event represents a Nostr protocol event, with its seven required fields.
+// All fields must be present for a valid event.
 type Event struct {
 	ID        string `json:"id"`
 	PubKey    string `json:"pubkey"`
 	CreatedAt int    `json:"created_at"`
 	Kind      int    `json:"kind"`
-	Tags      [][]string `json:"tags"`
+	Tags      []Tag  `json:"tags"`
 	Content   string `json:"content"`
 	Sig       string `json:"sig"`
 }
 
 var (
+	// Hex64Pattern matches 64-character, lowercase, hexadecimal strings.
+	// Used for validating event IDs and cryptographic keys.
 	Hex64Pattern = regexp.MustCompile("^[a-f0-9]{64}$")
+
+	// Hex128Pattern matches 128-character, lowercase, hexadecimal strings.
+	// Used for validating signatures.
 	Hex128Pattern = regexp.MustCompile("^[a-f0-9]{128}$")
 )
 
 var (
-	ErrMalformedPubKey = errors.New("pubkey must be 64 lowercase hex characters")
+	// ErrMalformedPubKey indicates a public key is not 64 lowercase hex characters.
-	ErrMalformedID     = errors.New("id must be 64 hex characters")
+	ErrMalformedPubKey = errors.New("public key must be 64 lowercase hex characters")
-	ErrMalformedSig    = errors.New("signature must be 128 hex characters")
+
+	// ErrMalformedPrivKey indicates a private key is not 64 lowercase hex characters.
+	ErrMalformedPrivKey = errors.New("private key must be 64 lowercase hex characters")
+
+	// ErrMalformedID indicates an event id is not 64 hex characters.
+	ErrMalformedID = errors.New("event id must be 64 hex characters")
+
+	// ErrMalformedSig indicates an event signature is not 128 hex characters.
+	ErrMalformedSig = errors.New("event signature must be 128 hex characters")
+
+	// ErrMalformedTag indicates an event tag contains fewer than two elements.
 	ErrMalformedTag = errors.New("tags must contain at least two elements")
+
+	// ErrFailedIDComp indicates the event ID could not be computed during validation.
 	ErrFailedIDComp = errors.New("failed to compute event id")
+
+	// ErrNoEventID indicates the event ID field is empty.
 	ErrNoEventID = errors.New("event id is empty")
+
+	// ErrInvalidSig indicates the event signature failed cryptographic validation.
 	ErrInvalidSig = errors.New("event signature is invalid")
 )
-
-func (e *Event) Serialize() ([]byte, error) {
-	serialized := []interface{}{
-		0,
-		e.PubKey,
-		e.CreatedAt,
-		e.Kind,
-		e.Tags,
-		e.Content,
-	}
-
-	bytes, err := json.Marshal(serialized)
-	if err != nil {
-		return []byte{}, err
-	}
-	return bytes, nil
-}
-
-func (e *Event) GetID() (string, error) {
-	bytes, err := e.Serialize()
-	if err != nil {
-		return "", err
-	}
-	hash := sha256.Sum256(bytes)
-	return hex.EncodeToString(hash[:]), nil
-}
-
-func SignEvent(eventID, privateKeyHex string) (string, error) {
-	skBytes, err := hex.DecodeString(privateKeyHex)
-	if err != nil {
-		return "", fmt.Errorf("invalid private key hex: %w", err)
-	}
-
-	idBytes, err := hex.DecodeString(eventID)
-	if err != nil {
-		return "", fmt.Errorf("invalid event id hex: %w", err)
-	}
-
-	// discard public key return value
-	sk, _ := btcec.PrivKeyFromBytes(skBytes)
-	sig, err := schnorr.Sign(sk, idBytes)
-	if err != nil {
-		return "", fmt.Errorf("schnorr signature error: %w", err)
-	}
-
-	return hex.EncodeToString(sig.Serialize()), nil
-}
-
-func (e *Event) Validate() error {
-	if err := e.ValidateStructure(); err != nil {
-		return err
-	}
-
-	if err := e.ValidateID(); err != nil {
-		return err
-	}
-
-	return ValidateSignature(e.ID, e.Sig, e.PubKey)
-}
-
-func (e *Event) ValidateStructure() error {
-	if !Hex64Pattern.MatchString(e.PubKey) {
-		return ErrMalformedPubKey
-	}
-
-	if !Hex64Pattern.MatchString(e.ID) {
-		return ErrMalformedID
-	}
-
-	if !Hex128Pattern.MatchString(e.Sig) {
-		return ErrMalformedSig
-	}
-
-	for _, tag := range e.Tags {
-		if len(tag) < 2 {
-			return ErrMalformedTag
-		}
-	}
-
-	return nil
-}
-
-func (e *Event) ValidateID() error {
-	computedID, err := e.GetID()
-	if err != nil {
-		return ErrFailedIDComp
-	}
-	if e.ID == "" {
-		return ErrNoEventID
-	}
-	if computedID != e.ID {
-		return fmt.Errorf("event id %q does not match computed id %q", e.ID, computedID)
-	}
-	return nil
-}
-
-func ValidateSignature(eventID, eventSig, publicKeyHex string) error {
-	idBytes, err := hex.DecodeString(eventID)
-	if err != nil {
-		return fmt.Errorf("invalid event id hex: %w", err)
-	}
-
-	sigBytes, err := hex.DecodeString(eventSig)
-	if err != nil {
-		return fmt.Errorf("invalid event signature hex: %w", err)
-	}
-
-	pkBytes, err := hex.DecodeString(publicKeyHex)
-	if err != nil {
-		return fmt.Errorf("invalid public key hex: %w", err)
-	}
-
-	signature, err := schnorr.ParseSignature(sigBytes)
-	if err != nil {
-		return fmt.Errorf("malformed signature: %w", err)
-	}
-
-	publicKey, err := schnorr.ParsePubKey(pkBytes)
-	if err != nil {
-		return fmt.Errorf("malformed public key: %w", err)
-	}
-
-	if signature.Verify(idBytes, publicKey) {
-		return nil
-	} else {
-		return ErrInvalidSig
-	}
-}

event_json_test.go

@@ -27,7 +27,7 @@ func TestEventJSONRoundTrip(t *testing.T) {
 		PubKey:    testEvent.PubKey,
 		CreatedAt: testEvent.CreatedAt,
 		Kind:      testEvent.Kind,
-		Tags: [][]string{
+		Tags: []Tag{
 			{"a", "value"},
 			{"b", "value", "optional"},
 			{"name", "value", "optional", "optional"},

event_test.go

@@ -13,7 +13,7 @@ var testEvent = Event{
 	PubKey:    testPK,
 	CreatedAt: 1760740551,
 	Kind:      1,
-	Tags:      [][]string{},
+	Tags:      []Tag{},
 	Content:   "hello world",
 	Sig:       "83b71e15649c9e9da362c175f988c36404cabf357a976d869102a74451cfb8af486f6088b5631033b4927bd46cad7a0d90d7f624aefc0ac260364aa65c36071a",
 }

filter.go

@@ -2,10 +2,19 @@ package roots
 
 import (
 	"encoding/json"
-	// "fmt"
 	"strings"
 )
 
+// TagFilters maps tag names to arrays of values for tag-based filtering
+// Keys correspond to tag names without the "#" prefix.
+type TagFilters map[string][]string
+
+// FilterExtensions holds arbitrary additional filter fields as raw JSON.
+// Allows custom filter extensions without modifying the core Filter type.
+type FilterExtensions map[string]json.RawMessage
+
+// Filter defines subscription criteria for events.
+// All conditions within a filter applied with AND logic.
 type Filter struct {
 	IDs        []string
 	Authors    []string
@@ -13,10 +22,12 @@ type Filter struct {
 	Since      *int
 	Until      *int
 	Limit      *int
-	Tags       map[string][]string
+	Tags       TagFilters
-	Extensions map[string]json.RawMessage
+	Extensions FilterExtensions
 }
 
+// MarshalJSON converts the filter to JSON with standard fields, tag filters
+// (prefixed with "#"), and extensions merged into a single object.
 func (f *Filter) MarshalJSON() ([]byte, error) {
 	outputMap := make(map[string]interface{})
 
@@ -72,9 +83,11 @@ func (f *Filter) MarshalJSON() ([]byte, error) {
 	return json.Marshal(outputMap)
 }
 
+// UnmarshalJSON parses JSON into the filter, separating standard fields,
+// tag filters (keys starting with "#"), and extensions.
 func (f *Filter) UnmarshalJSON(data []byte) error {
 	// Decode into raw map
-	raw := make(map[string]json.RawMessage)
+	raw := make(FilterExtensions)
 	if err := json.Unmarshal(data, &raw); err != nil {
 		return err
 	}
@@ -145,7 +158,7 @@ func (f *Filter) UnmarshalJSON(data []byte) error {
 		if strings.HasPrefix(key, "#") {
 			// Leave Tags as `nil` unless tag fields exist
 			if f.Tags == nil {
-				f.Tags = make(map[string][]string)
+				f.Tags = make(TagFilters)
 			}
 			tagKey := key[1:]
 			var tagValues []string
@@ -165,24 +178,27 @@ func (f *Filter) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// Matches returns true if the event satisfies all filter conditions.
+// Supports prefix matching for IDs and authors, and tag filtering.
+// Does not account for custom extensions.
 func (f *Filter) Matches(event *Event) bool {
 	// Check ID
 	if len(f.IDs) > 0 {
-		if !matchesPrefix(event.ID, &f.IDs) {
+		if !matchesPrefix(event.ID, f.IDs) {
 			return false
 		}
 	}
 
 	// Check Author
 	if len(f.Authors) > 0 {
-		if !matchesPrefix(event.PubKey, &f.Authors) {
+		if !matchesPrefix(event.PubKey, f.Authors) {
 			return false
 		}
 	}
 
 	// Check Kind
 	if len(f.Kinds) > 0 {
-		if !matchesKinds(event.Kind, &f.Kinds) {
+		if !matchesKinds(event.Kind, f.Kinds) {
 			return false
 		}
 	}
@@ -194,7 +210,7 @@ func (f *Filter) Matches(event *Event) bool {
 
 	// Check Tags
 	if len(f.Tags) > 0 {
-		if !matchesTags(&event.Tags, &f.Tags) {
+		if !matchesTags(event.Tags, &f.Tags) {
 			return false
 		}
 	}
@@ -202,8 +218,8 @@ func (f *Filter) Matches(event *Event) bool {
 	return true
 }
 
-func matchesPrefix(candidate string, prefixes *[]string) bool {
+func matchesPrefix(candidate string, prefixes []string) bool {
-	for _, prefix := range *prefixes {
+	for _, prefix := range prefixes {
 		if strings.HasPrefix(candidate, prefix) {
 			return true
 		}
@@ -211,8 +227,8 @@ func matchesPrefix(candidate string, prefixes *[]string) bool {
 	return false
 }
 
-func matchesKinds(candidate int, kinds *[]int) bool {
+func matchesKinds(candidate int, kinds []int) bool {
-	for _, kind := range *kinds {
+	for _, kind := range kinds {
 		if candidate == kind {
 			return true
 		}
@@ -230,23 +246,32 @@ func matchesTimeRange(timestamp int, since *int, until *int) bool {
 	return true
 }
 
-func matchesTags(eventTags *[][]string, filterTags *map[string][]string) bool {
+func matchesTags(eventTags []Tag, tagFilters *TagFilters) bool {
-	for tagName, filterValues := range *filterTags {
+	// Build index of tags and values
+	eventIndex := make(map[string][]string, len(eventTags))
+	for _, tag := range eventTags {
+		if len(tag) < 2 {
+			continue
+		}
+		eventIndex[tag[0]] = append(eventIndex[tag[0]], tag[1])
+	}
+
+	// Check filters against the index
+	for tagName, filterValues := range *tagFilters {
+		// Skip empty tag filters (empty tag filters match all events)
 		if len(filterValues) == 0 {
-			return true
+			continue
+		}
+
+		eventValues, exists := eventIndex[tagName]
+		if !exists {
+			return false
 		}
 
 		found := false
-		for _, eventTag := range *eventTags {
+		for _, filterVal := range filterValues {
-			if len(eventTag) < 2 {
+			for _, eventVal := range eventValues {
-				continue
+				if eventVal == filterVal {
-			}
-			if eventTag[0] != tagName {
-				continue
-			}
-
-			for _, filterValue := range filterValues {
-				if eventTag[1] == filterValue {
 					found = true
 					break
 				}
@@ -261,5 +286,6 @@ func matchesTags(eventTags *[][]string, filterTags *map[string][]string) bool {
 		}
 	}
 
+	// If no filter explicitly fails, then the event is matched
 	return true
 }

filter_match_test.go

@@ -19,6 +19,7 @@ func init() {
 	}
 }
 
+// Test keypairs corresponding to test events, for reference.
 var (
 	nayru_sk  = "1784be782585dfa97712afe12585d13ee608b624cf564116fa143c31a124d31e"
 	nayru_pk  = "d877e187934bd942a71221b50ff2b426bd0777991b41b6c749119805dc40bcbe"
@@ -225,7 +226,7 @@ var filterTestCases = []FilterTestCase{
 	{
 		name: "empty tag filter",
 		filter: Filter{
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"e": {},
 			},
 		},
@@ -245,7 +246,7 @@ var filterTestCases = []FilterTestCase{
 	{
 		name: "single letter tag filter: e",
 		filter: Filter{
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"e": {"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"},
 			},
 		},
@@ -255,7 +256,7 @@ var filterTestCases = []FilterTestCase{
 	{
 		name: "multiple tag matches",
 		filter: Filter{
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"e": {
 					"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36",
 					"ae3f2a91b6c3d8f7e9a1c5b4d8f2e7a9b6c3d8f7e9a1c5b4d8f2e7a9b6c3d8f7",
@@ -268,7 +269,7 @@ var filterTestCases = []FilterTestCase{
 	{
 		name: "multiple tag matches - single event match",
 		filter: Filter{
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"e": {
 					"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36",
 					"cb7787c460a79187d6a13e75a0f19240e05fafca8ea42288f5765773ea69cf2f",
@@ -281,7 +282,7 @@ var filterTestCases = []FilterTestCase{
 	{
 		name: "single letter tag filter: p",
 		filter: Filter{
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"p": {"91cf9b32f3735070f46c0a86a820a47efa08a5be6c9f4f8cf68e5b5b75c92d60"},
 			},
 		},
@@ -291,7 +292,7 @@ var filterTestCases = []FilterTestCase{
 	{
 		name: "multi letter tag filter",
 		filter: Filter{
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"emoji": {"🌊"},
 			},
 		},
@@ -301,7 +302,7 @@ var filterTestCases = []FilterTestCase{
 	{
 		name: "multiple tag filters",
 		filter: Filter{
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"e": {"ae3f2a91b6c3d8f7e9a1c5b4d8f2e7a9b6c3d8f7e9a1c5b4d8f2e7a9b6c3d8f7"},
 				"p": {"3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"},
 			},
@@ -312,7 +313,7 @@ var filterTestCases = []FilterTestCase{
 	{
 		name: "prefix tag filter",
 		filter: Filter{
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"p": {"ae3f2a91"},
 			},
 		},
@@ -322,7 +323,7 @@ var filterTestCases = []FilterTestCase{
 	{
 		name: "unknown tag filter",
 		filter: Filter{
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"z": {"anything"},
 			},
 		},
@@ -358,7 +359,7 @@ var filterTestCases = []FilterTestCase{
 		name: "combined author+tag tag filter",
 		filter: Filter{
 			Authors: []string{"e719e8f8"},
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"power": {"fire"},
 			},
 		},
@@ -374,7 +375,7 @@ var filterTestCases = []FilterTestCase{
 			Kinds:   []int{0},
 			Since:   intPtr(5000),
 			Until:   intPtr(10000),
-			Tags: map[string][]string{
+			Tags: TagFilters{
 				"power": {"fire"},
 			},
 		},
@@ -398,3 +399,21 @@ func TestEventFilterMatching(t *testing.T) {
 		})
 	}
 }
+
+// TestEventFilterMatchingSkipMalformedTags documents that filter.Matches()
+// skips malformed tags during tag matching
+func TestEventFilterMatchingSkipMalformedTags(t *testing.T) {
+	event := Event{
+		Tags: []Tag{
+			{"malformed"},
+			{"valid", "value"},
+		},
+	}
+	filter := Filter{
+		Tags: TagFilters{
+			"valid": {"value"},
+		},
+	}
+
+	assert.True(t, filter.Matches(&event))
+}

id.go

@@ -0,0 +1,37 @@
+package roots
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+)
+
+// Serialize returns the canonical JSON array representation of the event.
+// used for ID computation: [0, pubkey, created_at, kind, tags, content].
+func (e *Event) Serialize() ([]byte, error) {
+	serialized := []interface{}{
+		0,
+		e.PubKey,
+		e.CreatedAt,
+		e.Kind,
+		e.Tags,
+		e.Content,
+	}
+
+	bytes, err := json.Marshal(serialized)
+	if err != nil {
+		return []byte{}, err
+	}
+	return bytes, nil
+}
+
+// GetID computes and returns the event ID as a lowercase, hex-encoded SHA-256 hash
+// of the serialized event.
+func (e *Event) GetID() (string, error) {
+	bytes, err := e.Serialize()
+	if err != nil {
+		return "", err
+	}
+	hash := sha256.Sum256(bytes)
+	return hex.EncodeToString(hash[:]), nil
+}

id_test.go

@@ -18,7 +18,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags:      [][]string{},
+			Tags:      []Tag{},
 			Content:   "",
 		},
 		expected: "13a55672a600398894592f4cb338652d4936caffe5d3718d11597582bb030c39",
@@ -30,7 +30,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags:      [][]string{},
+			Tags:      []Tag{},
 			Content:   "hello world",
 		},
 		expected: "c7a702e6158744ca03508bbb4c90f9dbb0d6e88fefbfaa511d5ab24b4e3c48ad",
@@ -42,7 +42,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags:      [][]string{},
+			Tags:      []Tag{},
 			Content:   "hello world 😀",
 		},
 		expected: "e42083fafbf9a39f97914fd9a27cedb38c429ac3ca8814288414eaad1f472fe8",
@@ -54,7 +54,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags:      [][]string{},
+			Tags:      []Tag{},
 			Content:   "\"You say yes.\"\\n\\t\"I say no.\"",
 		},
 		expected: "343de133996a766bf00561945b6f2b2717d4905275976ca75c1d7096b7d1900c",
@@ -66,7 +66,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags:      [][]string{},
+			Tags:      []Tag{},
 			Content:   "{\"field\": [\"value\",\"value\"],\"numeral\": 123}",
 		},
 		expected: "c6140190453ee947efb790e70541a9d37c41604d1f29e4185da4325621ed5270",
@@ -78,7 +78,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags: [][]string{
+			Tags: []Tag{
 				{"a", ""},
 			},
 			Content: "",
@@ -92,7 +92,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags: [][]string{
+			Tags: []Tag{
 				{"a", "value"},
 			},
 			Content: "",
@@ -106,7 +106,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags: [][]string{
+			Tags: []Tag{
 				{"a", "value", "optional"},
 			},
 			Content: "",
@@ -120,7 +120,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags: [][]string{
+			Tags: []Tag{
 				{"a", "value", "optional"},
 				{"b", "another"},
 				{"c", "data"},
@@ -136,7 +136,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      1,
-			Tags: [][]string{
+			Tags: []Tag{
 				{"a", "😀"},
 			},
 			Content: "",
@@ -150,7 +150,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: 0,
 			Kind:      1,
-			Tags:      [][]string{},
+			Tags:      []Tag{},
 			Content:   "",
 		},
 		expected: "9ca742f2e2eea72ad6e0277a6287e2bb16a3e47d64b8468bc98474e266cf0ec2",
@@ -162,7 +162,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: -1760740551,
 			Kind:      1,
-			Tags:      [][]string{},
+			Tags:      []Tag{},
 			Content:   "",
 		},
 		expected: "4740b027040bb4d0ee8e885f567a80277097da70cddd143d8a6dadf97f6faaa3",
@@ -174,7 +174,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: 9223372036854775807,
 			Kind:      1,
-			Tags:      [][]string{},
+			Tags:      []Tag{},
 			Content:   "",
 		},
 		expected: "b28cdd44496acb49e36c25859f0f819122829a12dc57c07612d5f44cb121d2a7",
@@ -186,7 +186,7 @@ var idTestCases = []IDTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      20021,
-			Tags:      [][]string{},
+			Tags:      []Tag{},
 			Content:   "",
 		},
 		expected: "995c4894c264e6b9558cb94b7b34008768d53801b99960b47298d4e3e23fadd3",

keys.go

@@ -2,10 +2,11 @@ package roots
 
 import (
 	"encoding/hex"
-	"fmt"
 	"github.com/decred/dcrd/dcrec/secp256k1/v4"
 )
 
+// GeneratePrivateKey generates a new, random secp256k1 private key and returns
+// it as a 64-character, lowercase hexadecimal string.
 func GeneratePrivateKey() (string, error) {
 	sk, err := secp256k1.GeneratePrivateKey()
 	if err != nil {
@@ -15,13 +16,15 @@ func GeneratePrivateKey() (string, error) {
 	return hex.EncodeToString(skBytes), nil
 }
 
+// GetPublicKey derives the public key from a private key hex string
+// and returns the x-coordinate as 64 lowercase hex characters.
 func GetPublicKey(privateKeyHex string) (string, error) {
 	if len(privateKeyHex) != 64 {
-		return "", fmt.Errorf("private key must be 64 hex characters")
+		return "", ErrMalformedPrivKey
 	}
 	skBytes, err := hex.DecodeString(privateKeyHex)
 	if err != nil {
-		return "", fmt.Errorf("invalid private key hex: %w", err)
+		return "", ErrMalformedPrivKey
 	}
 
 	pk := secp256k1.PrivKeyFromBytes(skBytes).PubKey()

keys_test.go

@@ -26,5 +26,5 @@ func TestGetPublicKey(t *testing.T) {
 
 func TestGetPublicKeyInvalidPrivateKey(t *testing.T) {
 	_, err := GetPublicKey("abc123")
-	assert.ErrorContains(t, err, "private key must be 64 hex characters")
+	assert.ErrorContains(t, err, "private key must be 64 lowercase hex characters")
 }

sign.go

@@ -0,0 +1,31 @@
+package roots
+
+import (
+	"encoding/hex"
+	"fmt"
+	"github.com/btcsuite/btcd/btcec/v2"
+	"github.com/btcsuite/btcd/btcec/v2/schnorr"
+)
+
+// SignEvent generates a Schnorr signature for the given event ID using the
+// provided private key. Returns the signature as 128 lowercase hex characters.
+func SignEvent(eventID, privateKeyHex string) (string, error) {
+	skBytes, err := hex.DecodeString(privateKeyHex)
+	if err != nil {
+		return "", ErrMalformedPrivKey
+	}
+
+	idBytes, err := hex.DecodeString(eventID)
+	if err != nil {
+		return "", ErrMalformedID
+	}
+
+	// discard public key return value
+	sk, _ := btcec.PrivKeyFromBytes(skBytes)
+	sig, err := schnorr.Sign(sk, idBytes)
+	if err != nil {
+		return "", fmt.Errorf("schnorr signature error: %w", err)
+	}
+
+	return hex.EncodeToString(sig.Serialize()), nil
+}

sign_test.go

@@ -11,12 +11,12 @@ func TestSignEvent(t *testing.T) {
 	actualSig, err := SignEvent(eventID, testSK)
 
 	assert.NoError(t, err)
-	assert.Equal(t, actualSig, expectedSig)
+	assert.Equal(t, expectedSig, actualSig)
 }
 
 func TestSignInvalidEventID(t *testing.T) {
 	badEventID := "thisisabadeventid"
-	expectedError := "invalid event id hex"
+	expectedError := "event id must be 64 hex characters"
 
 	_, err := SignEvent(badEventID, testSK)
 
@@ -26,7 +26,7 @@ func TestSignInvalidEventID(t *testing.T) {
 func TestSignInvalidPrivateKey(t *testing.T) {
 	eventID := testEvent.ID
 	badSK := "thisisabadsecretkey"
-	expectedError := "invalid private key hex"
+	expectedError := "private key must be 64 lowercase hex characters"
 
 	_, err := SignEvent(eventID, badSK)
 

validate.go

@@ -0,0 +1,96 @@
+package roots
+
+import (
+	"encoding/hex"
+	"fmt"
+
+	"github.com/btcsuite/btcd/btcec/v2/schnorr"
+)
+
+// Validate performs a complete event validation: structure, ID computation,
+// and signature verification. Returns the first error encountered.
+func (e *Event) Validate() error {
+	if err := e.ValidateStructure(); err != nil {
+		return err
+	}
+
+	if err := e.ValidateID(); err != nil {
+		return err
+	}
+
+	return e.ValidateSignature()
+}
+
+// ValidateStructure checks that all event fields conform to the protocol
+// specification: hex lengths, tag structure, and field formats.
+func (e *Event) ValidateStructure() error {
+	if !Hex64Pattern.MatchString(e.PubKey) {
+		return ErrMalformedPubKey
+	}
+
+	if !Hex64Pattern.MatchString(e.ID) {
+		return ErrMalformedID
+	}
+
+	if !Hex128Pattern.MatchString(e.Sig) {
+		return ErrMalformedSig
+	}
+
+	for _, tag := range e.Tags {
+		if len(tag) < 2 {
+			return ErrMalformedTag
+		}
+	}
+
+	return nil
+}
+
+// ValidateID recomputes the event ID and verifies it matches the stored ID field.
+func (e *Event) ValidateID() error {
+	computedID, err := e.GetID()
+	if err != nil {
+		return ErrFailedIDComp
+	}
+	if e.ID == "" {
+		return ErrNoEventID
+	}
+	if computedID != e.ID {
+		return fmt.Errorf("event id %q does not match computed id %q", e.ID, computedID)
+	}
+	return nil
+}
+
+// ValidateSignature verifies the event signature is cryptographically valid
+// for the event ID and public key using Schnorr verification.
+func (e *Event) ValidateSignature() error {
+	idBytes, err := hex.DecodeString(e.ID)
+	if err != nil {
+		return fmt.Errorf("invalid event id hex: %w", err)
+	}
+
+	sigBytes, err := hex.DecodeString(e.Sig)
+	if err != nil {
+		return fmt.Errorf("invalid event signature hex: %w", err)
+	}
+
+	pkBytes, err := hex.DecodeString(e.PubKey)
+	if err != nil {
+		return fmt.Errorf("invalid public key hex: %w", err)
+	}
+
+	signature, err := schnorr.ParseSignature(sigBytes)
+	if err != nil {
+		return fmt.Errorf("malformed signature: %w", err)
+	}
+
+	publicKey, err := schnorr.ParsePubKey(pkBytes)
+	if err != nil {
+		return fmt.Errorf("malformed public key: %w", err)
+	}
+
+	if signature.Verify(idBytes, publicKey) {
+		return nil
+	} else {
+		return ErrInvalidSig
+	}
+}

validate_test.go

@@ -23,7 +23,7 @@ var structureTestCases = []ValidateEventTestCase{
 			Content:   testEvent.Content,
 			Sig:       testEvent.Sig,
 		},
-		expectedError: "pubkey must be 64 lowercase hex characters",
+		expectedError: "public key must be 64 lowercase hex characters",
 	},
 
 	{
@@ -37,7 +37,7 @@ var structureTestCases = []ValidateEventTestCase{
 			Content:   testEvent.Content,
 			Sig:       testEvent.Sig,
 		},
-		expectedError: "pubkey must be 64 lowercase hex characters",
+		expectedError: "public key must be 64 lowercase hex characters",
 	},
 
 	{
@@ -51,7 +51,7 @@ var structureTestCases = []ValidateEventTestCase{
 			Content:   testEvent.Content,
 			Sig:       testEvent.Sig,
 		},
-		expectedError: "pubkey must be 64 lowercase hex characters",
+		expectedError: "public key must be 64 lowercase hex characters",
 	},
 
 	{
@@ -65,7 +65,7 @@ var structureTestCases = []ValidateEventTestCase{
 			Content:   testEvent.Content,
 			Sig:       testEvent.Sig,
 		},
-		expectedError: "pubkey must be 64 lowercase hex characters",
+		expectedError: "public key must be 64 lowercase hex characters",
 	},
 
 	{
@@ -79,7 +79,7 @@ var structureTestCases = []ValidateEventTestCase{
 			Content:   testEvent.Content,
 			Sig:       testEvent.Sig,
 		},
-		expectedError: "pubkey must be 64 lowercase hex characters",
+		expectedError: "public key must be 64 lowercase hex characters",
 	},
 
 	{
@@ -145,7 +145,7 @@ var structureTestCases = []ValidateEventTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      testEvent.Kind,
-			Tags:      [][]string{{}},
+			Tags:      []Tag{{}},
 			Content:   testEvent.Content,
 			Sig:       testEvent.Sig,
 		},
@@ -159,7 +159,7 @@ var structureTestCases = []ValidateEventTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      testEvent.Kind,
-			Tags:      [][]string{{"a"}},
+			Tags:      []Tag{{"a"}},
 			Content:   testEvent.Content,
 			Sig:       testEvent.Sig,
 		},
@@ -173,7 +173,7 @@ var structureTestCases = []ValidateEventTestCase{
 			PubKey:    testEvent.PubKey,
 			CreatedAt: testEvent.CreatedAt,
 			Kind:      testEvent.Kind,
-			Tags:      [][]string{{"a", "value"}, {"b"}},
+			Tags:      []Tag{{"a", "value"}, {"b"}},
 			Content:   testEvent.Content,
 			Sig:       testEvent.Sig,
 		},
@@ -206,19 +206,23 @@ func TestValidateEventIDFailure(t *testing.T) {
 }
 
 func TestValidateSignature(t *testing.T) {
-	eventID := testEvent.ID
+	event := Event{
-	eventSig := testEvent.Sig
+		ID:     testEvent.ID,
-	publicKey := testEvent.PubKey
+		PubKey: testEvent.PubKey,
-	err := ValidateSignature(eventID, eventSig, publicKey)
+		Sig:    testEvent.Sig,
+	}
+	err := event.ValidateSignature()
 
 	assert.NoError(t, err)
 }
 
 func TestValidateInvalidSignature(t *testing.T) {
-	eventID := testEvent.ID
+	event := Event{
-	eventSig := "9e43cbcf7e828a21c53fa35371ee79bffbfd7a3063ae46fc05ec623dd3186667c57e3d006488015e19247df35eb41c61013e051aa87860e23fa5ffbd44120482"
+		ID:     testEvent.ID,
-	publicKey := testEvent.PubKey
+		PubKey: testEvent.PubKey,
-	err := ValidateSignature(eventID, eventSig, publicKey)
+		Sig:    "9e43cbcf7e828a21c53fa35371ee79bffbfd7a3063ae46fc05ec623dd3186667c57e3d006488015e19247df35eb41c61013e051aa87860e23fa5ffbd44120482",
+	}
+	err := event.ValidateSignature()
 
 	assert.ErrorContains(t, err, "event signature is invalid")
 }
@@ -276,7 +280,8 @@ var validateSignatureTestCases = []ValidateSignatureTestCase{
 func TestValidateSignatureInvalidEventSignature(t *testing.T) {
 	for _, tc := range validateSignatureTestCases {
 		t.Run(tc.name, func(t *testing.T) {
-			err := ValidateSignature(tc.id, tc.sig, tc.pubkey)
+			event := Event{ID: tc.id, PubKey: tc.pubkey, Sig: tc.sig}
+			err := event.ValidateSignature()
 			assert.ErrorContains(t, err, tc.expectedError)
 		})
 	}
@@ -288,7 +293,7 @@ func TestValidateEvent(t *testing.T) {
 		PubKey:    testEvent.PubKey,
 		CreatedAt: testEvent.CreatedAt,
 		Kind:      testEvent.Kind,
-		Tags: [][]string{
+		Tags: []Tag{
 			{"a", "value"},
 			{"b", "value", "optional"},
 		},