docs(routing): align IPIP-476 with someguy v0.11.0 implementation

Final ratification cleanup aligning specs with actual shipped implementation.

Changes to IPIP-0476:
- change path parameter from {peer-id} to {key}
- remove unimplemented query parameters (count, closer-than)
- document query parameters in Alternatives section with rationale
- add peer sorting requirement (XOR distance for Kademlia DHTs)
- update test fixtures to reflect actual API surface
- note about raw codec for arbitrary multihash lookups
- update date to 2025-11-20

Changes to http-routing-v1.md:
- add raw codec documentation for arbitrary multihash lookups
- clarify peer sorting requirement (SHOULD, XOR distance)
- fix streaming description (remove "more results" language)
- add note about streaming being blocked until DHT lookup completes
- reorganize frontmatter: move inactive editors to former_editors
- add contributors to thanks section
- update date to 2025-11-20

Both specs now accurately reflect the API shipped in:
- boxo v0.35.2 (ipfs/boxo#1021)
- someguy v0.11.0 (https://github.com/ipfs/someguy/releases/tag/v0.11.0)

Author: lidel

src/ipips/ipip-0476.md

@@ -1,6 +1,6 @@
 ---
 title: "IPIP-0476: Delegated Routing DHT Closest Peers API"
-date: 2025-08-19
+date: 2025-11-20
 ipip: proposal
 editors:
   - name: Alex Potsides
@@ -42,19 +42,14 @@ This is particularly problematic for:
 
 This IPIP introduces a new "DHT Routing API" section to the Delegated Routing V1 HTTP API specification with the following endpoint:
 
-### `GET /routing/v1/dht/closest/peers/{peer-id}`
+### `GET /routing/v1/dht/closest/peers/{key}`
 
 #### Path Parameters
 
-- `peer-id`: The target peer ID to find closest peers for, represented as a CIDv1 encoded with `libp2p-key` codec
-
-#### Query Parameters
-
-- `closer-than` (optional): A peer ID represented as a CIDv1 encoded with `libp2p-key` codec
-  - Returned peer records must be closer to `peer-id` than `closer-than`
-  - If omitted, the routing implementation should use its own peer ID
-- `count` (optional): Number of peer records to return
-  - Minimum 1, maximum 100, default 20
+- `key` is a [CID](https://github.com/multiformats/cid) or Peer ID to find the closest peers to.
+  - CID SHOULD be a CIDv1 in any encoding.
+  - Peer ID can be represented as a Multihash in Base58btc, or a CIDv1 with `libp2p-key` (`0x72`) codec in Base36 or Base32.
+  - Arbitrary multihash lookups can be performed by wrapping the multihash in a CIDv1 with `raw` (`0x55`) codec.
 
 #### Response
 
@@ -65,7 +60,7 @@ The response follows the same format as the existing peer routing endpoints, ret
 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/{peer-id}` endpoint with its parameters and response format
+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
 
 ## Design rationale
@@ -78,7 +73,7 @@ The endpoint provides the minimum viable functionality needed for the primary us
 
 ### Future-Proofed Path Structure
 
-The path `/routing/v1/dht/closest/peers/{peer-id}` is intentionally structured to allow future expansion:
+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
@@ -131,14 +126,25 @@ Several alternatives were considered:
 
 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.
+
+### 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.
+
 ## Test fixtures
 
 This IPIP does not deal with content-addressed data, so specific test CIDs are not applicable. However, implementations should test:
 
-1. Valid peer ID inputs return appropriate closest peers
-2. The `closerThan` parameter correctly filters results
-3. The `count` parameter limits results as specified
-4. Invalid peer IDs return appropriate error responses
+1. Valid CID and Peer ID inputs return appropriate closest peers
+2. Results are limited to the DHT bucket size
+3. Peers are sorted by closeness (XOR distance for Kademlia DHTs)
+4. Invalid keys return appropriate error responses
+5. Both streaming (NDJSON) and non-streaming (JSON) response formats work correctly
 
 ### Copyright
 

src/routing/http-routing-v1.md

@@ -4,9 +4,28 @@ description: >
   Delegated routing is a mechanism for IPFS implementations to use for offloading
   content routing, peer routing and naming to another process/server. This specification describes
   an HTTP API for delegated routing of content, peers, and IPNS.
-date: 2025-08-19
+date: 2025-11-20
 maturity: reliable
 editors:
+  - name: Marcin Rataj
+    github: lidel
+    url: https://lidel.org/
+    affiliation:
+      name: Shipyard
+      url: https://ipshipyard.com
+former_editors:
+  - name: Henrique Dias
+    url: https://hacdias.com/
+    github: hacdias
+    affiliation:
+      name: Shipyard
+      url: https://ipshipyard.com
+  - name: Daniel Norman
+    github: 2color
+    affiliation:
+      name: Shipyard
+      url: https://ipshipyard.com
+thanks:
   - name: Gus Eggert
     github: guseggert
     affiliation:
@@ -17,20 +36,15 @@ editors:
     affiliation:
       name: Protocol Labs
       url: https://protocol.ai/
-  - name: Henrique Dias
-    url: https://hacdias.com/
-    github: hacdias
+  - name: Alex Potsides
+    github: achingbrain
     affiliation:
       name: Shipyard
       url: https://ipshipyard.com
-  - name: Marcin Rataj
-    github: lidel
-    url: https://lidel.org/
-    affiliation:
-      name: Shipyard
-      url: https://ipshipyard.com
-  - name: Daniel Norman
-    github: 2color
+  - name: Will Scott
+    github: willscott
+  - name: Hector Sanjuan
+    github: hsanjuan
     affiliation:
       name: Shipyard
       url: https://ipshipyard.com
@@ -254,8 +268,9 @@ This optional endpoint allows light clients to lower the cost of DHT walks in br
 #### Path Parameters
 
 - `key` is a [CID] or [Peer ID][peer-id-representation] to find the closest peers to.
-  - [CID] should be a CIDv1 in any encoding.
+  - [CID] SHOULD be a CIDv1 in any encoding.
   - [Peer ID][peer-id-representation] can be represented as a Multihash in Base58btc, or a CIDv1 with `libp2p-key` (`0x72`) codec in Base36 or Base32.
+  - Arbitrary multihash lookups can be performed by wrapping the multihash in a CIDv1 with `raw` (`0x55`) codec.
   - Implementations SHOULD support both CID and Peer ID formats for maximum interoperability.
 
 #### Response Status Codes
@@ -294,7 +309,9 @@ This optional endpoint allows light clients to lower the cost of DHT walks in br
 
 The number of peer records in the response SHOULD be limited to the DHT bucket size (20 for Amino DHT).
 
-The client SHOULD be able to make a request with `Accept: application/x-ndjson` and get a [stream](#streaming) with more results.
+Peers SHOULD be returned 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.
+
+The client SHOULD be able to make a request with `Accept: application/x-ndjson` and get a [stream](#streaming) with results. Note that due to the XOR sorting requirement, the streamed response may be blocked until the DHT lookup completes and peers can be sorted before transmission.
 
 Each object in the `Peers` list is a record conforming to the [Peer Schema](#peer-schema).