IPIP-0476: Delegated Routing DHT Closest Peers API

3.1 GET /routing/v1/dht/closest/peers/{key}

3.2 Specification Changes

The following changes are made to src/routing/http-routing-v1.md:

1. Add a new "## DHT Routing API" section after the "Peer Routing API" section
2. Document the /routing/v1/dht/closest/peers/{key} endpoint with its parameters and response format
3. Update the document date to reflect the modification

4.1 Simple MVP Approach

The endpoint provides the minimum viable functionality needed for the primary use cases. It can be expanded later if more complex routing scenarios emerge.

4.2 Future-Proofed Path Structure

The path /routing/v1/dht/closest/peers/{key} is intentionally structured to allow future expansion:

• The /dht/ segment clearly indicates DHT-specific operations
• The /closest/peers/ structure allows for potential future endpoints like /closest/keys/ for keyspace queries
• This organization keeps the API logical and extensible

4.3 Routing-Agnostic Implementation

While the endpoint is in the DHT namespace, implementations have flexibility in how they determine "closest" peers. This allows for optimization based on the specific routing system being used.

4.4 Consistency with Existing API

The endpoint follows the established patterns of the Delegated Routing API:

• Uses the same response format as other peer routing endpoints
• Follows the same parameter conventions
• Maintains consistency in error handling and status codes

4.5 User benefit

This enhancement provides significant benefits to end users:

1. Browser Compatibility: Browser nodes can discover circuit relay servers without implementing the full DHT protocol
2. Reduced Resource Usage: Light clients save bandwidth and processing power by delegating peer discovery
3. Faster Peer Discovery: Delegated routing servers can provide cached results more quickly than performing DHT walks
4. Simplified Implementation: Application developers can implement peer discovery with simple HTTP requests instead of complex DHT logic

4.6 Compatibility

This change is fully backward compatible:

• It adds a new endpoint without modifying existing ones
• Existing clients continue to work unchanged
• Servers that don't implement the endpoint return 501 (Not Implemented) as per the specification

4.7 Security

The new endpoint introduces no additional security considerations beyond those already present in the Delegated Routing API:

• Standard rate limiting should be applied to prevent abuse
• The endpoint reveals no more information than a DHT query would
• Access controls can be implemented at the HTTP layer if needed
• Response caching helps mitigate potential DoS attacks

4.8 Alternatives

Several alternatives were considered:

1. Full DHT Client Implementation: Rejected due to excessive resource requirements for browser and mobile environments

2. Custom libp2p Protocol: Would require all nodes to implement a new protocol, creating adoption barriers

3. Extension of Existing Peer Routing: The /routing/v1/peers/ endpoint serves a different purpose (finding specific peers rather than closest peers)

4. Amino-Specific Endpoint: Initially considered /routing/v1/amino/ namespace but rejected in favor of the more generic /dht/ approach

5. Query Parameters for Filtering and Limiting: During design discussions, count and closer-than query parameters were considered:

   • count: limit the number of results returned
   • closer-than: filter peers to only return those closer than a reference peer

   These were omitted from the initial implementation (boxo v0.35.2, someguy v0.11.0) for simplicity. The endpoint defaults to returning up to the DHT bucket size (20 for Amino DHT). Future backwards-compatible updates MAY add these parameters if use cases emerge that require more fine-grained control.

4.9 Peer Ordering

Implementations SHOULD return peers sorted by closeness to the key. For Kademlia-based DHT implementations (such as Amino DHT), this means sorting by XOR distance with the closest peers first.

5.1 Copyright

Copyright and related rights waived via CC0.