Enhance Directory Client Library for NIP-XX Protocol
- Introduced a TypeScript client library for the Distributed Directory Consensus Protocol (NIP-XX), providing a high-level API for managing directory events, identity resolution, and trust calculations. - Implemented core functionalities including event parsing, trust score aggregation, and replication filtering, mirroring the Go implementation. - Added comprehensive documentation and development guides for ease of use and integration. - Updated the `.gitignore` to include additional dependencies and build artifacts for the TypeScript client. - Enhanced validation mechanisms for group tag names and trust levels, ensuring robust input handling and security. - Created a new `bun.lock` file to manage package dependencies effectively.
This commit is contained in:
248
pkg/protocol/directory-client/README.md
Normal file
248
pkg/protocol/directory-client/README.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# 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
|
||||
|
||||
```go
|
||||
import "next.orly.dev/pkg/protocol/directory-client"
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Identity Resolution
|
||||
|
||||
```go
|
||||
// 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
|
||||
|
||||
```go
|
||||
// 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
|
||||
|
||||
```go
|
||||
// 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
|
||||
|
||||
```go
|
||||
// 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
|
||||
|
||||
```go
|
||||
// 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](../../docs/NIP-XX-distributed-directory-consensus.md)
|
||||
- [Directory Protocol Package](../directory/)
|
||||
|
||||
## License
|
||||
|
||||
See [LICENSE](../../LICENSE) file.
|
||||
Reference in New Issue
Block a user