fix(kad-dht): reprovide CIDs in Kademlia key order to reduce new dials

Sort CIDs by their Kademlia key before queueing reprovides so that
XOR-adjacent CIDs are processed consecutively. Nearby CIDs in the
keyspace share the same K closest peers, so connections opened for one
CID are likely to be reused for the next, reducing the number of new
dials per reprovide run (Amino DHT SweepingProvider optimisation).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: paschal533

packages/kad-dht/src/reprovider.ts

@@ -2,7 +2,7 @@ import { AdaptiveTimeout, Queue } from '@libp2p/utils'
 import drain from 'it-drain'
 import { TypedEventEmitter, setMaxListeners } from 'main-event'
 import { PROVIDERS_VALIDITY, REPROVIDE_CONCURRENCY, REPROVIDE_INTERVAL, REPROVIDE_MAX_QUEUE_SIZE, REPROVIDE_THRESHOLD, REPROVIDE_TIMEOUT } from './constants.js'
-import { parseProviderKey, readProviderTime, timeOperationMethod } from './utils.js'
+import { convertBuffer, parseProviderKey, readProviderTime, timeOperationMethod } from './utils.js'
 import type { ContentRouting } from './content-routing/index.js'
 import type { OperationMetrics } from './kad-dht.js'
 import type { AbortOptions, ComponentLogger, Logger, Metrics, PeerId } from '@libp2p/interface'
@@ -116,11 +116,20 @@ export class Reprovider extends TypedEventEmitter<ReprovideEvents> {
   /**
    * Check all provider records. Delete them if they have expired, reprovide
    * them if the provider is us and the expiry is within the reprovide window.
+   *
+   * CIDs are queued in Kademlia key order so that XOR-adjacent CIDs are
+   * reprovided consecutively. Since nearby CIDs in the keyspace share the
+   * same K closest peers, connections opened for one CID are likely to be
+   * reused for the next, reducing the number of new dials per reprovide run.
    */
   private async processRecords (options?: AbortOptions): Promise<void> {
     try {
       this.safeDispatchEvent('reprovide:start')
       this.log('starting reprovide/cleanup')
+
+      // collect CIDs that need reproviding so we can sort them before queueing
+      const toReprovide: CID[] = []
+
       // Get all provider entries from the datastore
       for await (const entry of this.datastore.query({
         prefix: this.datastorePrefix
@@ -143,19 +152,45 @@ export class Reprovider extends TypedEventEmitter<ReprovideEvents> {
           }
 
           // if the provider is us and we are within the reprovide threshold,
-          // reprovide the record
+          // collect for reprovision
           if (this.shouldReprovide(isSelf, expires)) {
-            this.log('reproviding %c as it is within the reprovide threshold (%d)', cid, this.reprovideThreshold)
-            this.queueReprovide(cid)
-              .catch(err => {
-                this.log.error('could not reprovide %c - %e', cid, err)
-              })
+            this.log('scheduling reprovide of %c', cid)
+            toReprovide.push(cid)
           }
         } catch (err: any) {
           this.log.error('error processing datastore key %s - %s', entry.key, err.message)
         }
       }
 
+      // sort collected CIDs by their Kademlia key so XOR-adjacent CIDs are
+      // queued consecutively — peers responsible for one CID are likely to
+      // also be responsible for adjacent CIDs, so connections can be reused
+      if (toReprovide.length > 1) {
+        const kadKeys = await Promise.all(
+          toReprovide.map(cid => convertBuffer(cid.multihash.bytes, options))
+        )
+
+        const sortable = toReprovide.map((cid, i) => ({ cid, kadKey: kadKeys[i] }))
+        sortable.sort((a, b) => {
+          for (let i = 0; i < a.kadKey.length; i++) {
+            if (a.kadKey[i] !== b.kadKey[i]) {
+              return a.kadKey[i] - b.kadKey[i]
+            }
+          }
+          return 0
+        })
+
+        toReprovide.splice(0, toReprovide.length, ...sortable.map(({ cid }) => cid))
+      }
+
+      // queue reprovides in Kademlia key order
+      for (const cid of toReprovide) {
+        this.queueReprovide(cid)
+          .catch(err => {
+            this.log.error('could not reprovide %c - %e', cid, err)
+          })
+      }
+
       this.log('reprovide/cleanup successful')
     } finally {
       this.safeDispatchEvent('reprovide:end')

packages/kad-dht/test/reprovider.spec.ts

@@ -8,6 +8,7 @@ import { pEvent } from 'p-event'
 import { stubInterface } from 'sinon-ts'
 import { Providers } from '../src/providers.js'
 import { Reprovider } from '../src/reprovider.js'
+import { convertBuffer } from '../src/utils.js'
 import { createPeerIdWithPrivateKey, createPeerIdsWithPrivateKey } from './utils/create-peer-id.js'
 import type { PeerAndKey } from './utils/create-peer-id.js'
 import type { ContentRouting } from '../src/content-routing/index.js'
@@ -158,6 +159,101 @@ describe('reprovider', () => {
     expect(provsAfter[0].toString()).to.equal(components.peerId.toString())
   })
 
+  it('should reprovide in Kademlia key order', async function () {
+    this.timeout(5000)
+
+    // five well-known IPFS CIDs — their Kademlia keys will be in some order
+    // that is unlikely to match the insertion order below
+    const cids = [
+      CID.parse('QmZ8eiDPqQqWR17EPxiwCDgrKPVhCHLcyn6xSCNpFAdAZb'),
+      CID.parse('QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n'),
+      CID.parse('QmRgutAxd8t7oGkSm4wmeuByG6M51wcTso6cubDdQtuEfL'),
+      CID.parse('QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB'),
+      CID.parse('QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN')
+    ]
+
+    // compute expected Kademlia key order — use multihash bytes as canonical
+    // identity since parseProviderKey always reconstructs CIDs as CIDv1/raw
+    const kadKeys = await Promise.all(cids.map(cid => convertBuffer(cid.multihash.bytes)))
+    const expectedMultihashes = cids
+      .map((cid, i) => ({ multihash: cid.multihash.bytes, kadKey: kadKeys[i] }))
+      .sort((a, b) => {
+        for (let i = 0; i < a.kadKey.length; i++) {
+          if (a.kadKey[i] !== b.kadKey[i]) {
+            return a.kadKey[i] - b.kadKey[i]
+          }
+        }
+        return 0
+      })
+      .map(({ multihash }) => multihash)
+
+    // insert CIDs in REVERSE expected order to prove sorting overrides insertion order
+    for (const { multihash } of [...expectedMultihashes].reverse().map((m, i) => ({ multihash: m, i }))) {
+      const cid = cids.find(c => c.multihash.bytes === multihash) ??
+        cids.find(c => c.multihash.bytes.every((b, j) => b === multihash[j]))
+      if (cid != null) {
+        await providers.addProvider(cid, components.peerId)
+      }
+    }
+
+    // recreate reprovider with concurrency=1 so provides are strictly sequential
+    reprovider = new Reprovider(components, {
+      logPrefix: 'libp2p',
+      datastorePrefix: '/dht',
+      metricsPrefix: '',
+      contentRouting,
+      threshold: 100,
+      validity: 200,
+      interval: 200,
+      concurrency: 1,
+      operationMetrics: {}
+    })
+
+    const provisionMultihashes: Uint8Array[] = []
+
+    // resolve when all CIDs have been provided
+    let resolveWhenDone!: () => void
+    const whenAllDone = new Promise<void>(resolve => { resolveWhenDone = resolve })
+    let provided = 0
+
+    contentRouting.provide.callsFake(async function * (cid: CID) {
+      provisionMultihashes.push(cid.multihash.bytes)
+      provided++
+      if (provided === cids.length) {
+        resolveWhenDone()
+      }
+      yield * []
+    })
+
+    await start(reprovider)
+    await pEvent(reprovider, 'reprovide:start')
+    await pEvent(reprovider, 'reprovide:end')
+
+    // wait for the queue to finish processing all enqueued reprovides
+    await whenAllDone
+
+    // verify CIDs were provided in Kademlia key order by checking each
+    // adjacent pair maintains non-decreasing Kademlia key order
+    expect(provisionMultihashes).to.have.lengthOf(cids.length)
+
+    for (let i = 1; i < provisionMultihashes.length; i++) {
+      const prevKey = await convertBuffer(provisionMultihashes[i - 1])
+      const currKey = await convertBuffer(provisionMultihashes[i])
+
+      let comparison = 0
+      for (let j = 0; j < prevKey.length; j++) {
+        if (prevKey[j] !== currKey[j]) {
+          comparison = prevKey[j] - currKey[j]
+          break
+        }
+      }
+
+      expect(comparison).to.be.lessThanOrEqual(0,
+        `CID at position ${i - 1} should have a smaller or equal Kademlia key than position ${i}`
+      )
+    }
+  })
+
   describe('shouldReprovide', () => {
     it('should return false for non-self providers', () => {
       const expires = Date.now() + 50