You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
160 lines
5.2 KiB
160 lines
5.2 KiB
// 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
|
|
|