directory

Overview ¶

Package directory implements the distributed directory consensus protocol as defined in NIP-XX for Nostr relay operators.

Overview ¶

This package provides complete message encoding, validation, and helper functions for implementing the distributed directory consensus protocol. The protocol enables Nostr relay operators to form trusted consortiums that automatically synchronize essential identity-related events while maintaining decentralization and Byzantine fault tolerance.

Event Kinds ¶

The protocol defines six new event kinds:

• 39100: Relay Identity Announcement - Announces relay participation
• 39101: Trust Act - Creates trust relationships between relays
• 39102: Group Tag Act - Attests to arbitrary string values
• 39103: Public Key Advertisement - Advertises HD-derived keys
• 39104: Directory Event Replication Request - Requests event replication
• 39105: Directory Event Replication Response - Responds to replication requests

Directory Events ¶

The following existing event kinds are considered "directory events" and are automatically replicated among consortium members:

• Kind 0: User Metadata
• Kind 3: Follow Lists
• Kind 5: Event Deletion Requests
• Kind 1984: Reporting
• Kind 10002: Relay List Metadata
• Kind 10000: Mute Lists
• Kind 10050: DM Relay Lists

Basic Usage ¶

## Creating a Relay Identity Announcement

pubkey := []byte{...} // 32-byte relay identity key
announcement, err := directory.NewRelayIdentityAnnouncement(
	pubkey,
	"relay.example.com",           // name
	"A community relay",           // description
	"admin@example.com",           // contact
	"wss://relay.example.com",     // relay URL
	"abc123...",                   // signing key (hex)
	"def456...",                   // encryption key (hex)
	"1",                           // version
	"https://relay.example.com/.well-known/nostr.json", // NIP-11 URL
)
if err != nil {
	log.Fatal(err)
}

## Creating a Trust Act

act, err := directory.NewTrustAct(
	pubkey,
	"target_relay_pubkey_hex",     // target relay
	directory.TrustLevelHigh,      // trust level
	"wss://target.relay.com",      // target URL
	nil,                           // no expiry
	directory.TrustReasonManual,   // manual trust
	[]uint16{1, 6, 7},            // additional kinds to replicate
	nil,                           // no identity tag
)

## Creating a Public Key Advertisement

validFrom := time.Now()
validUntil := validFrom.Add(30 * 24 * time.Hour) // 30 days

keyAd, err := directory.NewPublicKeyAdvertisement(
	pubkey,
	"signing-key-001",                    // key ID
	"fedcba9876543210...",               // public key (hex)
	directory.KeyPurposeSigning,         // purpose
	validFrom,                           // valid from
	validUntil,                          // valid until
	"secp256k1",                         // algorithm
	"m/39103'/1237'/0'/0/1",            // derivation path
	1,                                   // key index
	nil,                                 // no identity tag
)

Identity Tags ¶

Identity tags (I tags) provide npub-encoded identities with proof-of-control signatures. They bind an identity to a specific delegate key, preventing unauthorized use.

## Creating Identity Tags

// Create identity tag builder with private key
identityPrivkey := []byte{...} // 32-byte private key
builder, err := directory.NewIdentityTagBuilder(identityPrivkey)
if err != nil {
	log.Fatal(err)
}

// Create signed identity tag for delegate key
delegatePubkey := []byte{...} // 32-byte delegate public key
identityTag, err := builder.CreateIdentityTag(delegatePubkey)
if err != nil {
	log.Fatal(err)
}

// Use in trust act
act, err := directory.NewTrustAct(
	pubkey,
	"target_relay_pubkey_hex",
	directory.TrustLevelHigh,
	"wss://target.relay.com",
	nil,
	directory.TrustReasonManual,
	[]uint16{1, 6, 7},
	identityTag, // Include identity tag
)

Validation ¶

All message types include comprehensive validation:

// Validate a parsed event
if err := announcement.Validate(); err != nil {
	log.Printf("Invalid announcement: %v", err)
	return
}

// Validate any consortium event
if err := directory.ValidateConsortiumEvent(event); err != nil {
	log.Printf("Invalid consortium event: %v", err)
	return
}

// Verify NIP-11 binding
valid, err := directory.ValidateRelayIdentityBinding(
	announcement,
	nip11Pubkey,
	nip11Nonce,
	nip11Sig,
	relayAddress,
)
if err != nil || !valid {
	log.Printf("Invalid relay identity binding")
	return
}

Trust Calculation ¶

The package provides utilities for calculating trust relationships:

// Create trust calculator
calculator := directory.NewTrustCalculator()

// Add trust acts
calculator.AddAct(act1)
calculator.AddAct(act2)

// Get direct trust level
level := calculator.GetTrustLevel("relay_pubkey_hex")

// Calculate inherited trust
inheritedLevel := calculator.CalculateInheritedTrust(
	"from_relay_pubkey",
	"to_relay_pubkey",
)

Replication Filtering ¶

Determine which events should be replicated to which relays:

// Create replication filter
filter := directory.NewReplicationFilter(calculator)
filter.AddTrustAct(act)

// Check if event should be replicated
shouldReplicate := filter.ShouldReplicate(event, "target_relay_pubkey")

// Get all replication targets for an event
targets := filter.GetReplicationTargets(event)

Event Batching ¶

Batch events for efficient replication:

// Create event batcher
batcher := directory.NewEventBatcher(100) // max 100 events per batch

// Add events to batches
batcher.AddEvent("wss://relay1.com", event1)
batcher.AddEvent("wss://relay1.com", event2)
batcher.AddEvent("wss://relay2.com", event3)

// Check if batch is full
if batcher.IsBatchFull("wss://relay1.com") {
	batch := batcher.FlushBatch("wss://relay1.com")
	// Send batch for replication
}

Replication Requests and Responses ¶

## Creating Replication Requests

requestID, err := directory.GenerateRequestID()
if err != nil {
	log.Fatal(err)
}

request, err := directory.NewDirectoryEventReplicationRequest(
	pubkey,
	requestID,
	"wss://target.relay.com",
	[]*event.E{event1, event2, event3},
)

## Creating Replication Responses

// Success response
results := []*directory.EventResult{
	directory.CreateEventResult("event_id_1", true, ""),
	directory.CreateEventResult("event_id_2", false, "duplicate event"),
}

response, err := directory.CreateSuccessResponse(
	pubkey,
	requestID,
	"wss://source.relay.com",
	results,
)

// Error response
errorResponse, err := directory.CreateErrorResponse(
	pubkey,
	requestID,
	"wss://source.relay.com",
	"relay temporarily unavailable",
)

Key Management ¶

The protocol uses BIP32 HD key derivation for deterministic key generation:

// Create key pool manager
masterSeed := []byte{...} // BIP39 seed
manager := directory.NewKeyPoolManager(masterSeed, 0) // identity index 0

// Generate derivation paths
signingPath := manager.GenerateDerivationPath(directory.KeyPurposeSigning, 5)
// Returns: "m/39103'/1237'/0'/0/5"

encryptionPath := manager.GenerateDerivationPath(directory.KeyPurposeEncryption, 3)
// Returns: "m/39103'/1237'/0'/1/3"

// Track key usage
nextIndex := manager.GetNextKeyIndex(directory.KeyPurposeSigning)
manager.SetKeyIndex(directory.KeyPurposeSigning, 10) // Skip to index 10

Error Handling ¶

All functions return detailed errors using the errorf package:

announcement, err := directory.ParseRelayIdentityAnnouncement(event)
if err != nil {
	// Handle specific error types
	switch {
	case strings.Contains(err.Error(), "invalid event kind"):
		log.Printf("Wrong event kind: %v", err)
	case strings.Contains(err.Error(), "missing"):
		log.Printf("Missing required field: %v", err)
	default:
		log.Printf("Parse error: %v", err)
	}
	return
}

Security Considerations ¶

The package implements several security measures:

• All events must have valid signatures
• Identity tags prevent unauthorized identity use
• NIP-11 binding prevents relay impersonation
• Timestamp validation prevents replay attacks
• Content size limits prevent DoS attacks
• Nonce validation ensures cryptographic security

Protocol Constants ¶

Important protocol constants:

• MaxKeyDelegations: 512 unused key delegations per identity
• KeyExpirationDays: 30 days for unused key delegations
• MinNonceSize: 16 bytes minimum for nonces
• MaxContentLength: 65536 bytes maximum for event content

Integration Example ¶

Complete example of implementing consortium membership:

package main

import (
	"log"
	"time"

	"next.orly.dev/pkg/protocol/directory"
)

func main() {
	// Generate relay identity key
	relayPrivkey := []byte{...} // 32 bytes
	relayPubkey := schnorr.PubkeyFromSeckey(relayPrivkey)

	// Create relay identity announcement
	announcement, err := directory.NewRelayIdentityAnnouncement(
		relayPubkey,
		"my-relay.com",
		"My Community Relay",
		"admin@my-relay.com",
		"wss://my-relay.com",
		hex.EncodeToString(signingPubkey),
		hex.EncodeToString(encryptionPubkey),
		"1",
		"https://my-relay.com/.well-known/nostr.json",
	)
	if err != nil {
		log.Fatal(err)
	}

	// Sign and publish announcement
	if err := announcement.Event.Sign(relayPrivkey); err != nil {
		log.Fatal(err)
	}

	// Create trust act for another relay
	act, err := directory.NewTrustAct(
		relayPubkey,
		"trusted_relay_pubkey_hex",
		directory.TrustLevelHigh,
		"wss://trusted-relay.com",
		nil, // no expiry
		directory.TrustReasonManual,
		[]uint16{1, 6, 7}, // replicate text notes, reposts, reactions
		nil, // no identity tag
	)
	if err != nil {
		log.Fatal(err)
	}

	// Sign and publish act
	if err := act.Event.Sign(relayPrivkey); err != nil {
		log.Fatal(err)
	}

	// Set up replication filter
	calculator := directory.NewTrustCalculator()
	calculator.AddAct(act)

	filter := directory.NewReplicationFilter(calculator)
	filter.AddTrustAct(act)

	// When receiving events, check if they should be replicated
	for event := range eventChannel {
		targets := filter.GetReplicationTargets(event)
		for _, target := range targets {
			// Replicate event to target relay
			replicateEvent(event, target)
		}
	}
}

For more detailed examples and advanced usage patterns, see the test files and the reference implementation in the main relay codebase.

Package directory provides data structures and validation for the distributed directory consensus protocol as defined in NIP-XX.

This package implements message encoding and validation for the following event kinds:

• 39100: Relay Identity Announcement - Announces relay participation in consortium
• 39101: Trust Act - Establishes trust relationships with numeric levels (0-100%)
• 39102: Group Tag Act - Creates/manages group tags with ownership specs
• 39103: Public Key Advertisement - Advertises delegate keys with expiration
• 39104: Directory Event Replication Request - Requests event synchronization
• 39105: Directory Event Replication Response - Responds to sync requests
• 39106: Group Tag Transfer - Transfers group tag ownership (planned)
• 39107: Escrow Witness Completion Act - Completes escrow transfers (planned)

Numeric Trust Levels ¶

Trust levels are represented as numeric values from 0-100, indicating the percentage probability that any given event will be replicated. This implements partial replication via cryptographic random selection (dice-throw mechanism):

• 100: Full replication - ALL events replicated (100% probability)
• 75: High partial replication - 75% of events replicated on average
• 50: Medium partial replication - 50% of events replicated on average
• 25: Low partial replication - 25% of events replicated on average
• 10: Minimal sampling - 10% of events replicated on average
• 0: No replication - effectively disables replication

For each event, a cryptographically secure random number (0-100) is generated and compared to the trust level threshold. If the random number ≤ trust level, the event is replicated; otherwise it is discarded. This provides:

• Proportional bandwidth/storage reduction
• Probabilistic network coverage (events propagate via multiple paths)
• Network resilience (different relays replicate different random subsets)
• Tunable trade-offs between resources and completeness

Group Tag Ownership ¶

Group Tag Acts (Kind 39102) establish ownership and control over arbitrary string tags, functioning as a first-come-first-served registration system akin to domain name registration. Features include:

• Single signature or multisig ownership (2-of-3, 3-of-5)
• URL-safe character validation (RFC 3986 compliance)
• Ownership transfer capability (via Kind 39106)
• Escrow-based transfer protocol (via Kind 39107)
• Foundation for permissioned structured groups across multiple relays

Legal Concept of Acts ¶

The term "act" in this protocol draws from legal terminology, where an act represents a formal declaration or testimony that has legal significance. Similar to legal instruments such as:

• Deed Poll: A legal document binding one party to a particular course of action
• Witness Testimony: A formal statement given under oath as evidence
• Affidavit: A written statement confirmed by oath for use as evidence

In the context of this protocol, acts serve as cryptographically signed declarations that establish trust relationships, group memberships, or other formal statements within the relay consortium. Like their legal counterparts, these acts:

• Are formally structured with specific required elements
• Carry the authority and responsibility of the signing party
• Create binding relationships or obligations within the consortium
• Can be verified for authenticity through cryptographic signatures
• May have expiration dates or other temporal constraints

This legal framework provides a conceptual foundation for understanding the formal nature and binding character of consortium declarations.