Skip to content

Commit c8362a9

Browse files
committed
fix: clarify IPNS quorum and minor spec improvements
kad-dht spec: - clarify IPNS quorum is application-level recommendation (SHOULD use 16), not DHT default - add link to IPNS record spec in quorum section - fix malformed link to Amino DHT blog post - fix typo: "Thy are" to "They are" - fix formatting: "e.g in" to "e.g., in" - remove redundant paragraph describing client lookup behavior ipns-record spec: - add note referencing kad-dht retrieval strategies including quorum
1 parent b1e4620 commit c8362a9

File tree

2 files changed

+9
-15
lines changed

2 files changed

+9
-15
lines changed

src/ipns/ipns-record.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -477,6 +477,10 @@ Note: Base32 according to the :cite[rfc4648].
477477
The routing record is spread across the network according to the available routing systems.
478478
The two routing systems currently available in IPFS are the :cite[kad-dht] and :cite[ipns-pubsub-router].
479479

480+
When using :cite[kad-dht] for routing, implementations SHOULD follow the retrieval strategies
481+
documented in the IPFS Kademlia DHT specification, including the recommended quorum value
482+
for IPNS record lookups.
483+
480484
**Key format:** `/ipns/BINARY_ID`
481485

482486
- `/ipns/` is the ASCII prefix (bytes in hex: `2f69706e732f`)

src/routing/kad-dht.md

Lines changed: 5 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ identifiers SHOULD be used.
7575

7676
#### Amino DHT
7777

78-
[_Amino DHT_]((https://blog.ipfs.tech/2023-09-amino-refactoring/#why-amino)) is
78+
[_Amino DHT_](https://blog.ipfs.tech/2023-09-amino-refactoring/#why-amino) is
7979
a public instance of the _IPFS Kademlia DHT_ spec mounted under
8080
`/ipfs/kad/1.0.0` libp2p protocol, it is also referred to as the _Public IPFS
8181
DHT_.
@@ -90,7 +90,7 @@ and can be joined by using the [public good Amino DHT Bootstrappers](https://doc
9090
#### IPFS LAN DHTs
9191

9292
_IPFS LAN DHTs_ are DHT swarms operating exclusively within a local network.
93-
Thy are accessible only to nodes within the same network and are identified by
93+
They are accessible only to nodes within the same network and are identified by
9494
the libp2p protocol `/ipfs/lan/kad/1.0.0`.
9595

9696
In a LAN DHT:
@@ -289,7 +289,7 @@ periodically refresh the Routing Table.
289289

290290
When using periodic refresh, DHT Servers SHOULD perform a Routing Table Refresh
291291
every `10` minutes. During this process, the server sends a ping request to all
292-
nodes it hasn't heard from recently (e.g in the last 5 minutes). Any peer that
292+
nodes it hasn't heard from recently (e.g., in the last 5 minutes). Any peer that
293293
fails to respond MUST be removed from the Routing Table.
294294

295295
After removing unresponsive peers, any buckets that are not full MUST be
@@ -360,16 +360,6 @@ Upon receiving a response, the client adds freshly received peers to the list
360360
of closest peers. It sends a request to the closest peer to `kid` that hasn't
361361
been queried yet. The client ignores timeouts and invalid responses.
362362

363-
When a client (or a DHT server acting as a client) initiates a lookup for a
364-
Kademlia Identifier `kid`, it begins by selecting the known nodes closest to
365-
`kid` in terms of XOR distance, and adds them to a candidate list. It then
366-
sends lookup requests to the closest nodes from that list.
367-
368-
As responses are received, any newly discovered peers are added to the
369-
candidate list. The client proceeds by sending a request to the nearest peer to
370-
`kid` that has not yet been queried. Invalid responses and timeouts are simply
371-
discarded.
372-
373363
#### Termination
374364

375365
The resilience parameter (`β`) defines the number of closest reachable peers
@@ -593,10 +583,10 @@ and [IPNS Record Size Limit](https://specs.ipfs.tech/ipns/ipns-record/#record-si
593583

594584
A quorum is the minimum number of distinct responses a client must collect from
595585
DHT Servers to determine a valid result. Since different DHT Servers may store
596-
different versions of an IPNS record, a client fetches the record from multiple
586+
different versions of an [IPNS record](https://specs.ipfs.tech/ipns/ipns-record/), a client fetches the record from multiple
597587
DHT Servers to increase the likelihood of retrieving the most recent version.
598588

599-
For IPNS lookups, the default quorum value is `16`, meaning the client attempts
589+
For IPNS lookups, implementations SHOULD use a quorum value of `16`, meaning the client attempts
600590
to collect responses from at least `16` DHT Servers out of `20` before
601591
determining the best available record.
602592

0 commit comments

Comments
 (0)