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:
160
pkg/protocol/directory-client/doc.go
Normal file
160
pkg/protocol/directory-client/doc.go
Normal file
@@ -0,0 +1,160 @@
|
||||
// Package directory_client provides a high-level client API for the
|
||||
// Distributed Directory Consensus Protocol (NIP-XX).
|
||||
//
|
||||
// # Overview
|
||||
//
|
||||
// This package builds on top of the lower-level directory protocol package
|
||||
// to provide convenient utilities for:
|
||||
//
|
||||
// - Identity resolution and key delegation tracking
|
||||
// - Trust score calculation and aggregation
|
||||
// - Replication filtering based on trust relationships
|
||||
// - Event collection and filtering
|
||||
// - Trust graph construction and analysis
|
||||
//
|
||||
// # Architecture
|
||||
//
|
||||
// The client library consists of several main components:
|
||||
//
|
||||
// **IdentityResolver**: Tracks mappings between delegate keys and primary
|
||||
// identities, enabling resolution of the actual identity behind any signing
|
||||
// key. It processes Identity Tags (I tags) from events and maintains a cache
|
||||
// of delegation relationships.
|
||||
//
|
||||
// **TrustCalculator**: Computes aggregate trust scores from multiple trust
|
||||
// acts using a weighted average approach. Trust levels (high/medium/low) are
|
||||
// mapped to numeric weights and non-expired acts are combined to produce
|
||||
// an overall trust score.
|
||||
//
|
||||
// **ReplicationFilter**: Uses trust scores to determine which relays should
|
||||
// be trusted for event replication. It maintains a set of trusted relays
|
||||
// based on a configurable minimum trust score threshold.
|
||||
//
|
||||
// **EventCollector**: Provides convenient methods to extract and parse
|
||||
// specific types of directory events from a collection.
|
||||
//
|
||||
// **TrustGraph**: Represents trust relationships as a directed graph,
|
||||
// enabling analysis of trust networks and transitive trust paths.
|
||||
//
|
||||
// # Thread Safety
|
||||
//
|
||||
// All components are thread-safe and can be used concurrently from multiple
|
||||
// goroutines. Internal state is protected by read-write mutexes.
|
||||
//
|
||||
// # Example: Identity Resolution
|
||||
//
|
||||
// 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 delegation status
|
||||
// if resolver.IsDelegateKey(pubkey) {
|
||||
// tag, _ := resolver.GetIdentityTag(pubkey)
|
||||
// fmt.Printf("Delegate %s belongs to identity %s\n",
|
||||
// pubkey, tag.Identity)
|
||||
// }
|
||||
//
|
||||
// # Example: Trust Management
|
||||
//
|
||||
// calculator := directory_client.NewTrustCalculator()
|
||||
//
|
||||
// // Add trust acts
|
||||
// for _, event := range trustEvents {
|
||||
// if act, err := directory.ParseTrustAct(event); err == nil {
|
||||
// calculator.AddAct(act)
|
||||
// }
|
||||
// }
|
||||
//
|
||||
// // Calculate trust score
|
||||
// score := calculator.CalculateTrust(targetPubkey)
|
||||
// fmt.Printf("Trust score: %.1f\n", score)
|
||||
//
|
||||
// # Example: Replication Filtering
|
||||
//
|
||||
// // Create filter with minimum trust score of 50
|
||||
// filter := directory_client.NewReplicationFilter(50)
|
||||
//
|
||||
// // Add trust acts to influence decisions
|
||||
// for _, act := range trustActs {
|
||||
// filter.AddTrustAct(act)
|
||||
// }
|
||||
//
|
||||
// // Check if should replicate from a relay
|
||||
// if filter.ShouldReplicate(relayPubkey) {
|
||||
// // Proceed with replication
|
||||
// events := fetchEventsFromRelay(relayPubkey)
|
||||
// // ...
|
||||
// }
|
||||
//
|
||||
// # Example: Event Collection
|
||||
//
|
||||
// collector := directory_client.NewEventCollector(events)
|
||||
//
|
||||
// // Extract specific event types
|
||||
// identities := collector.RelayIdentities()
|
||||
// trustActs := collector.TrustActs()
|
||||
// keyAds := collector.PublicKeyAdvertisements()
|
||||
//
|
||||
// // Find specific events
|
||||
// if identity, found := directory_client.FindRelayIdentity(
|
||||
// events, "wss://relay.example.com/"); found {
|
||||
// fmt.Printf("Found relay identity: %s\n", identity.RelayURL)
|
||||
// }
|
||||
//
|
||||
// # Example: Trust Graph Analysis
|
||||
//
|
||||
// graph := directory_client.BuildTrustGraph(events)
|
||||
//
|
||||
// // Find who trusts a specific 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))
|
||||
//
|
||||
// # Integration with Directory Protocol
|
||||
//
|
||||
// This package is designed to work seamlessly with the lower-level
|
||||
// directory protocol package (next.orly.dev/pkg/protocol/directory).
|
||||
// Use the protocol package for:
|
||||
//
|
||||
// - Parsing individual directory events
|
||||
// - Creating new directory events
|
||||
// - Validating event structure
|
||||
// - Working with event content and tags
|
||||
//
|
||||
// Use the client package for:
|
||||
//
|
||||
// - Managing collections of events
|
||||
// - Tracking identity relationships
|
||||
// - Computing trust metrics
|
||||
// - Filtering events for replication
|
||||
// - Analyzing trust networks
|
||||
//
|
||||
// # Performance Considerations
|
||||
//
|
||||
// The IdentityResolver maintains in-memory caches of identity mappings.
|
||||
// For large numbers of identities and delegates, memory usage will grow
|
||||
// proportionally. Use ClearCache() if you need to free memory.
|
||||
//
|
||||
// The TrustCalculator stores all trust acts in memory. For long-running
|
||||
// applications processing many trust acts, consider periodically clearing
|
||||
// expired acts or implementing a sliding window approach.
|
||||
//
|
||||
// # Related Documentation
|
||||
//
|
||||
// See the NIP-XX specification for details on the protocol:
|
||||
//
|
||||
// docs/NIP-XX-distributed-directory-consensus.md
|
||||
//
|
||||
// See the directory protocol package for low-level event handling:
|
||||
//
|
||||
// pkg/protocol/directory/
|
||||
package directory_client
|
||||
Reference in New Issue
Block a user