doc.go raw
1 // Package directory_client provides a high-level client API for the
2 // Distributed Directory Consensus Protocol (NIP-XX).
3 //
4 // # Overview
5 //
6 // This package builds on top of the lower-level directory protocol package
7 // to provide convenient utilities for:
8 //
9 // - Identity resolution and key delegation tracking
10 // - Trust score calculation and aggregation
11 // - Replication filtering based on trust relationships
12 // - Event collection and filtering
13 // - Trust graph construction and analysis
14 //
15 // # Architecture
16 //
17 // The client library consists of several main components:
18 //
19 // **IdentityResolver**: Tracks mappings between delegate keys and primary
20 // identities, enabling resolution of the actual identity behind any signing
21 // key. It processes Identity Tags (I tags) from events and maintains a cache
22 // of delegation relationships.
23 //
24 // **TrustCalculator**: Computes aggregate trust scores from multiple trust
25 // acts using a weighted average approach. Trust levels (high/medium/low) are
26 // mapped to numeric weights and non-expired acts are combined to produce
27 // an overall trust score.
28 //
29 // **ReplicationFilter**: Uses trust scores to determine which relays should
30 // be trusted for event replication. It maintains a set of trusted relays
31 // based on a configurable minimum trust score threshold.
32 //
33 // **EventCollector**: Provides convenient methods to extract and parse
34 // specific types of directory events from a collection.
35 //
36 // **TrustGraph**: Represents trust relationships as a directed graph,
37 // enabling analysis of trust networks and transitive trust paths.
38 //
39 // # Thread Safety
40 //
41 // All components are thread-safe and can be used concurrently from multiple
42 // goroutines. Internal state is protected by read-write mutexes.
43 //
44 // # Example: Identity Resolution
45 //
46 // resolver := directory_client.NewIdentityResolver()
47 //
48 // // Process events to build identity mappings
49 // for _, event := range events {
50 // resolver.ProcessEvent(event)
51 // }
52 //
53 // // Resolve identity behind a delegate key
54 // actualIdentity := resolver.ResolveIdentity(delegateKey)
55 //
56 // // Check delegation status
57 // if resolver.IsDelegateKey(pubkey) {
58 // tag, _ := resolver.GetIdentityTag(pubkey)
59 // fmt.Printf("Delegate %s belongs to identity %s\n",
60 // pubkey, tag.Identity)
61 // }
62 //
63 // # Example: Trust Management
64 //
65 // calculator := directory_client.NewTrustCalculator()
66 //
67 // // Add trust acts
68 // for _, event := range trustEvents {
69 // if act, err := directory.ParseTrustAct(event); err == nil {
70 // calculator.AddAct(act)
71 // }
72 // }
73 //
74 // // Calculate trust score
75 // score := calculator.CalculateTrust(targetPubkey)
76 // fmt.Printf("Trust score: %.1f\n", score)
77 //
78 // # Example: Replication Filtering
79 //
80 // // Create filter with minimum trust score of 50
81 // filter := directory_client.NewReplicationFilter(50)
82 //
83 // // Add trust acts to influence decisions
84 // for _, act := range trustActs {
85 // filter.AddTrustAct(act)
86 // }
87 //
88 // // Check if should replicate from a relay
89 // if filter.ShouldReplicate(relayPubkey) {
90 // // Proceed with replication
91 // events := fetchEventsFromRelay(relayPubkey)
92 // // ...
93 // }
94 //
95 // # Example: Event Collection
96 //
97 // collector := directory_client.NewEventCollector(events)
98 //
99 // // Extract specific event types
100 // identities := collector.RelayIdentities()
101 // trustActs := collector.TrustActs()
102 // keyAds := collector.PublicKeyAdvertisements()
103 //
104 // // Find specific events
105 // if identity, found := directory_client.FindRelayIdentity(
106 // events, "wss://relay.example.com/"); found {
107 // fmt.Printf("Found relay identity: %s\n", identity.RelayURL)
108 // }
109 //
110 // # Example: Trust Graph Analysis
111 //
112 // graph := directory_client.BuildTrustGraph(events)
113 //
114 // // Find who trusts a specific relay
115 // trustedBy := graph.GetTrustedBy(targetPubkey)
116 // fmt.Printf("Trusted by %d relays\n", len(trustedBy))
117 //
118 // // Find who a relay trusts
119 // targets := graph.GetTrustTargets(sourcePubkey)
120 // fmt.Printf("Trusts %d relays\n", len(targets))
121 //
122 // # Integration with Directory Protocol
123 //
124 // This package is designed to work seamlessly with the lower-level
125 // directory protocol package (next.orly.dev/pkg/protocol/directory).
126 // Use the protocol package for:
127 //
128 // - Parsing individual directory events
129 // - Creating new directory events
130 // - Validating event structure
131 // - Working with event content and tags
132 //
133 // Use the client package for:
134 //
135 // - Managing collections of events
136 // - Tracking identity relationships
137 // - Computing trust metrics
138 // - Filtering events for replication
139 // - Analyzing trust networks
140 //
141 // # Performance Considerations
142 //
143 // The IdentityResolver maintains in-memory caches of identity mappings.
144 // For large numbers of identities and delegates, memory usage will grow
145 // proportionally. Use ClearCache() if you need to free memory.
146 //
147 // The TrustCalculator stores all trust acts in memory. For long-running
148 // applications processing many trust acts, consider periodically clearing
149 // expired acts or implementing a sliding window approach.
150 //
151 // # Related Documentation
152 //
153 // See the NIP-XX specification for details on the protocol:
154 //
155 // docs/NIP-XX-distributed-directory-consensus.md
156 //
157 // See the directory protocol package for low-level event handling:
158 //
159 // pkg/protocol/directory/
160 package directory_client
161