go-roots serves a foundation for other libraries and applications to implement higher level abstractions of the Nostr protocol on top of it, including message transport, semantic event definitions, event storage mechanisms, and user interfaces.

go-roots prioritizes correctness and clarity over optimization and efficiency. For high performance applications, it is recommended to implement optimizations in a separate library or in the application which requires them.

Installation

Add go-roots to your project:

go get git.wisehodl.dev/jay/go-roots

Import it with:

import "git.wisehodl.dev/jay/go-roots"

Access it with the roots namespace.

Usage Examples

Key Management

Generate a new keypair

privateKey, err := roots.GeneratePrivateKey()
if err != nil {
    log.Fatal(err)
}

publicKey, err := roots.GetPublicKey(privateKey)
if err != nil {
    log.Fatal(err)
}

Derive public key from existing private key

privateKey := "f43a0435f69529f310bbd1d6263d2fbf0977f54bfe2310cc37ae5904b83bb167"
publicKey, err := roots.GetPublicKey(privateKey)
// publicKey: "cfa87f35acbde29ba1ab3ee42de527b2cad33ac487e80cf2d6405ea0042c8fef"

Event Creation and Signing

Create and sign a complete event

// 1. Build the event structure
event := roots.Event{
    PubKey:    publicKey,
    CreatedAt: int(time.Now().Unix()),
    Kind:      1,
    Tags: []roots.Tag{
        {"e", "5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"},
        {"p", "91cf9b32f3735070f46c0a86a820a47efa08a5be6c9f4f8cf68e5b5b75c92d60"},
    },
    Content: "Hello, Nostr!",
}

// 2. Compute the event ID
id, err := event.GetID()
if err != nil {
    log.Fatal(err)
}
event.ID = id

// 3. Sign the event
sig, err := roots.SignEvent(id, privateKey)
if err != nil {
    log.Fatal(err)
}
event.Sig = sig

Serialize an event for ID computation

// Returns canonical JSON: [0, pubkey, created_at, kind, tags, content]
serialized, err := event.Serialize()
if err != nil {
    log.Fatal(err)
}

Compute event ID manually

id, err := event.GetID()
if err != nil {
    log.Fatal(err)
}
// Returns lowercase hex SHA-256 hash of serialized form

Event Validation

Validate complete event

// Checks structure, ID computation, and signature
if err := event.Validate(); err != nil {
    log.Printf("Invalid event: %v", err)
}

Validate individual aspects

// Check field formats and lengths
if err := event.ValidateStructure(); err != nil {
    log.Printf("Malformed structure: %v", err)
}

// Verify ID matches computed hash
if err := event.ValidateID(); err != nil {
    log.Printf("ID mismatch: %v", err)
}

// Verify cryptographic signature
if err := event.ValidateSignature(); err != nil {
    log.Printf("Invalid signature: %v", err)
}

Event JSON

Marshal event to JSON

jsonBytes, err := json.Marshal(event)
if err != nil {
    log.Fatal(err)
}
// Standard encoding/json works with Event struct tags

Unmarshal event from JSON

var event roots.Event
err := json.Unmarshal(jsonBytes, &event)
if err != nil {
    log.Fatal(err)
}

// Validate after unmarshaling
if err := event.Validate(); err != nil {
    log.Printf("Received invalid event: %v", err)
}

Filter Creation

Basic filter with standard fields

since := int(time.Now().Add(-24 * time.Hour).Unix())
limit := 50

filter := roots.Filter{
    IDs:     []string{"abc123", "def456"},  // Prefix match
    Authors: []string{"cfa87f35"},          // Prefix match
    Kinds:   []int{1, 6, 7},
    Since:   &since,
    Limit:   &limit,
}

Filter with tag conditions

filter := roots.Filter{
    Kinds: []int{1},
    Tags: roots.TagFilters{
        "e": {"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"},
        "p": {"91cf9b32f3735070f46c0a86a820a47efa08a5be6c9f4f8cf68e5b5b75c92d60"},
    },
}

Filter with extensions (custom fields)

// Extensions allow arbitrary JSON fields beyond the standard filter spec.
// For example, this is how to implement non-standard filters like 'search'.
filter := roots.Filter{
    Kinds: []int{1},
    Extensions: roots.FilterExtensions{
        "search": json.RawMessage(`"bitcoin"`),
    },
}

// Extensions are preserved during marshal/unmarshal but ignored by Matches().
// Storage/transport layers can inspect Extensions to implement custom behavior.

Filter Matching

Match single event

filter := roots.Filter{
    Authors: []string{"cfa87f35"},
    Kinds:   []int{1},
}

if filter.Matches(&event) {
    // Event satisfies all filter conditions
}

Filter event collection

since := int(time.Now().Add(-1 * time.Hour).Unix())
filter := roots.Filter{
    Kinds: []int{1},
    Since: &since,
    Tags: roots.TagFilters{
        "p": {"abc123", "def456"},  // OR within tag values
    },
}

var matches []roots.Event
for _, event := range events {
    if filter.Matches(&event) {
        matches = append(matches, event)
    }
}

Filter JSON

Marshal filter to JSON

filter := roots.Filter{
    IDs:   []string{"abc123"},
    Kinds: []int{1},
    Tags: roots.TagFilters{
        "e": {"event-id"},
    },
    Extensions: roots.FilterExtensions{
        "search": json.RawMessage(`"nostr"`),
    },
}

jsonBytes, err := filter.MarshalJSON()
// Result: {"ids":["abc123"],"kinds":[1],"#e":["event-id"],"search":"nostr"}

Unmarshal filter from JSON

jsonData := `{
    "authors": ["cfa87f35"],
    "kinds": [1],
    "#e": ["abc123"],
    "since": 1234567890,
    "search": "bitcoin"
}`

var filter roots.Filter
err := filter.UnmarshalJSON([]byte(jsonData))
if err != nil {
    log.Fatal(err)
}

// Standard fields populated: Authors, Kinds, Since
// Tag filters populated: Tags["e"] = ["abc123"]
// Unknown fields populated: Extensions["search"] = "bitcoin"

Extensions field behavior

The Extensions field captures any JSON properties not recognized as standard filter fields or tag filters. This design allows the core library to remain frozen while storage and transport layers implement custom filtering behavior.

Standard fields: ids, authors, kinds, since, until, limit

Tag filters: Any key starting with # (e.g., #e, #p, #emoji)

Extensions: Everything else

During marshaling, Extensions merge into the output JSON. During unmarshaling, unrecognized fields populate Extensions. The Matches() method ignores Extensions, and the library expects higher protocol layers to implement their usage.

Example implementing search filter:

filter := roots.Filter{
    Kinds: []int{1},
    Extensions: roots.FilterExtensions{
        "search": json.RawMessage(`"bitcoin"`),
    },
}

// In a storage layer (not this library):
if searchRaw, ok := filter.Extensions["search"]; ok {
    var searchTerm string
    json.Unmarshal(searchRaw, &searchTerm)
    // Apply full-text search using searchTerm
}

Testing

This library contains a comprehensive suite of unit tests. Run them with:

go test