next.orly.dev/pkg/protocol/directory-client/README.md

Directory Client Library

High-level Go client library for the Distributed Directory Consensus Protocol (NIP-XX).

Overview

This package provides a convenient API for working with directory events, managing identity resolution, tracking key delegations, and computing trust scores. It builds on the lower-level directory protocol package.

Features

• Identity Resolution: Track and resolve delegate keys to their primary identities
• Trust Management: Calculate aggregate trust scores from multiple trust acts
• Replication Filtering: Determine which relays to trust for event replication
• Event Collection: Convenient utilities for extracting specific event types
• Trust Graph: Build and analyze trust relationship networks
• Thread-Safe: All components support concurrent access

Installation

import "next.orly.dev/pkg/protocol/directory-client"

Quick Start

Identity Resolution

// Create an identity resolver
resolver := directory_client.NewIdentityResolver()

// Process events to build identity mappings
for _, event := range events {
    resolver.ProcessEvent(event)
}

// Resolve identity behind a delegate key
actualIdentity := resolver.ResolveIdentity(delegateKey)

// Check if a key is a delegate
if resolver.IsDelegateKey(pubkey) {
    tag, _ := resolver.GetIdentityTag(pubkey)
    fmt.Printf("Delegate belongs to: %s\n", tag.Identity)
}

// Get all delegates for an identity
delegates := resolver.GetDelegatesForIdentity(identityPubkey)

// Filter events by identity (including delegates)
filteredEvents := resolver.FilterEventsByIdentity(events, identityPubkey)

Trust Management

// Create a trust calculator
calculator := directory_client.NewTrustCalculator()

// Add trust acts
for _, event := range trustEvents {
    if act, err := directory.ParseTrustAct(event); err == nil {
        calculator.AddAct(act)
    }
}

// Calculate aggregate trust score (0-100)
score := calculator.CalculateTrust(targetPubkey)

// Get active (non-expired) trust acts
activeActs := calculator.GetActiveTrustActs(targetPubkey)

Replication Filtering

// Create filter with minimum trust score threshold
filter := directory_client.NewReplicationFilter(50)

// Add trust acts
for _, act := range trustActs {
    filter.AddTrustAct(act)
}

// Check if should replicate from a relay
if filter.ShouldReplicate(relayPubkey) {
    // Proceed with replication
}

// Get all trusted relays
trustedRelays := filter.GetTrustedRelays()

// Filter events to only trusted sources
trustedEvents := filter.FilterEvents(events)

Event Collection

// Create event collector
collector := directory_client.NewEventCollector(events)

// Extract specific event types
identities := collector.RelayIdentities()
trustActs := collector.TrustActs()
groupTagActs := collector.GroupTagActs()
keyAds := collector.PublicKeyAdvertisements()
requests := collector.ReplicationRequests()
responses := collector.ReplicationResponses()

// Find specific events
identity, found := directory_client.FindRelayIdentity(events, "wss://relay.example.com/")
trustActs := directory_client.FindTrustActsForRelay(events, targetPubkey)
groupActs := directory_client.FindGroupTagActsByGroup(events, "premium")

Trust Graph Analysis

// Build trust graph from events
graph := directory_client.BuildTrustGraph(events)

// Find who trusts a relay
trustedBy := graph.GetTrustedBy(targetPubkey)
fmt.Printf("Trusted by %d relays\n", len(trustedBy))

// Find who a relay trusts
targets := graph.GetTrustTargets(sourcePubkey)
fmt.Printf("Trusts %d relays\n", len(targets))

// Get all trust acts from a source
acts := graph.GetTrustActs(sourcePubkey)

API Reference

IdentityResolver

Manages identity resolution and key delegation tracking.

Methods:

• NewIdentityResolver() *IdentityResolver - Create new instance
• ProcessEvent(ev *event.E) - Process event to extract identity info
• ResolveIdentity(pubkey string) string - Resolve delegate to identity
• ResolveEventIdentity(ev *event.E) string - Resolve event's identity
• IsDelegateKey(pubkey string) bool - Check if key is a delegate
• IsIdentityKey(pubkey string) bool - Check if key has delegates
• GetDelegatesForIdentity(identity string) []string - Get all delegates
• GetIdentityTag(delegate string) (*IdentityTag, error) - Get identity tag
• GetPublicKeyAdvertisements(identity string) []*PublicKeyAdvertisement - Get key ads
• FilterEventsByIdentity(events []*event.E, identity string) []*event.E - Filter events
• ClearCache() - Clear all cached mappings
• GetStats() Stats - Get statistics

TrustCalculator

Computes aggregate trust scores from multiple trust acts.

Methods:

• NewTrustCalculator() *TrustCalculator - Create new instance
• AddAct(act *TrustAct) - Add a trust act
• CalculateTrust(pubkey string) float64 - Calculate trust score (0-100)
• GetActs(pubkey string) []*TrustAct - Get all acts for pubkey
• GetActiveTrustActs(pubkey string) []*TrustAct - Get non-expired acts
• Clear() - Remove all acts
• GetAllPubkeys() []string - Get all tracked pubkeys

Trust Score Weights:

• High: 100
• Medium: 50
• Low: 25

ReplicationFilter

Manages replication decisions based on trust scores.

Methods:

• NewReplicationFilter(minTrustScore float64) *ReplicationFilter - Create new instance
• AddTrustAct(act *TrustAct) - Add trust act and update trusted relays
• ShouldReplicate(pubkey string) bool - Check if relay is trusted
• GetTrustedRelays() []string - Get all trusted relay pubkeys
• GetTrustScore(pubkey string) float64 - Get trust score for relay
• SetMinTrustScore(minScore float64) - Update threshold
• GetMinTrustScore() float64 - Get current threshold
• FilterEvents(events []*event.E) []*event.E - Filter to trusted events

EventCollector

Utility for collecting specific types of directory events.

Methods:

• NewEventCollector(events []*event.E) *EventCollector - Create new instance
• RelayIdentities() []*RelayIdentity - Get all relay identities
• TrustActs() []*TrustAct - Get all trust acts
• GroupTagActs() []*GroupTagAct - Get all group tag acts
• PublicKeyAdvertisements() []*PublicKeyAdvertisement - Get all key ads
• ReplicationRequests() []*ReplicationRequest - Get all requests
• ReplicationResponses() []*ReplicationResponse - Get all responses

Helper Functions

Event Filtering:

• IsDirectoryEvent(ev *event.E) bool - Check if event is directory event
• FilterDirectoryEvents(events []*event.E) []*event.E - Filter to directory events
• ParseDirectoryEvent(ev *event.E) (interface{}, error) - Parse any directory event

Event Finding:

• FindRelayIdentity(events, relayURL) (*RelayIdentity, bool) - Find identity by URL
• FindTrustActsForRelay(events, targetPubkey) []*TrustAct - Find trust acts
• FindGroupTagActsForRelay(events, targetPubkey) []*GroupTagAct - Find group acts
• FindGroupTagActsByGroup(events, groupTag) []*GroupTagAct - Find by group

URL Utilities:

• NormalizeRelayURL(url string) string - Ensure trailing slash

Trust Graph:

• NewTrustGraph() *TrustGraph - Create new graph
• BuildTrustGraph(events []*event.E) *TrustGraph - Build from events
• AddTrustAct(act *TrustAct) - Add trust act to graph
• GetTrustActs(source string) []*TrustAct - Get acts from source
• GetTrustedBy(target string) []string - Get who trusts target
• GetTrustTargets(source string) []string - Get who source trusts

Thread Safety

All components are thread-safe and can be used concurrently from multiple goroutines. Internal state is protected by read-write mutexes (sync.RWMutex).

Performance Considerations

• IdentityResolver: Maintains in-memory caches. Use ClearCache() if needed
• TrustCalculator: Stores all trust acts in memory. Consider periodic cleanup of expired acts
• ReplicationFilter: Minimal memory overhead, recalculates trust on each act addition

Integration

This package works with:

• directory protocol package: For parsing and creating events
• event package: For event structures
• EventStore: Can be integrated with any event storage system

Related Documentation

• NIP-XX Specification
• Directory Protocol Package

License

See LICENSE file.