mleku
8e15ca7e2f
- 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.
161 lines
5.2 KiB
Go
161 lines
5.2 KiB
Go
// 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
|