Merge pull request #1985 from ipfs/ipns-corrections

correct dht expiration time and improve ipns docs

Author: 2color

.github/styles/Vocab/ipfs-docs-vocab/accept.txt

@@ -64,6 +64,7 @@ Arbol('s)?
 auditable
 Audius
 auspinner
+blockchain
 blockstore
 Browserify
 callouts?
@@ -169,7 +170,8 @@ Qm
 rasterio
 READMEs?
 referenceable
-reprovider
+reprovide
+reprovide(r)
 reproviding
 retrievability
 roadmaps

docs/concepts/ipns.md

@@ -33,6 +33,8 @@ Yet, there are many situations where content-addressed data needs to be regularl
 
 The InterPlanetary Name System (IPNS) is a system for creating such mutable pointers to CIDs known as **names** or **IPNS names**. IPNS names can be thought of as links that can be updated over time, while retaining the verifiability of content addressing.
 
+By analogy, IPNS names are like tags in git, which can be updated over time, and CIDs are like commit hashes in Git, which point to a snapshot of the files in the repository.
+
 ::: callout
 An IPNS name can point to any arbitrary content path (`/ipfs/` or `/ipns/`), *including another IPNS name or DNSLink path*. However, it most commonly points to a fully resolved and immutable path, i.e. `/ipfs/[CID]`.
 :::
@@ -121,7 +123,7 @@ The main implication of this difference is that IPNS operations (publishing and
 
 The DHT is the default transport mechanism for IPNS records in many IPFS implementations.
 
-Due to the ephemeral nature of the DHT, peers forget records after 24 hours. This applies to any record in the DHT, irrespective of the `validity` (also referred to as `lifetime`) field in the IPNS record.
+Due to the ephemeral nature of the DHT, records expire [after 48 hours](https://github.com/libp2p/specs/tree/b5f7fce29b32d4c7d0efe37b019936a11e5db872/kad-dht#content-provider-advertisement-and-discovery). This applies to any record in the DHT, irrespective of the `validity` (also referred to as `lifetime`) field in the IPNS record.
 
 Therefore, IPNS records need to be regularly (re-)published to the DHT. Moreover, publishing to the DHT at regular intervals ensures that the IPNS name can be resolved even when there's high node churn (nodes coming and going.)
 
@@ -173,7 +175,7 @@ Availability means resolving to a valid IPNS record, at the cost of potentially
 
 #### IPNS record validity
 
-When setting the `validity` (referred to as [`lifetime` by Kubo](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsrecordlifetime)) field of an IPNS record, you typically need to choose whether you favor **consistency** (short validity period, e.g. 24 hours) or **availability** (long validity period, e.g. 1 month), due to the inherent trade-off between the two.
+When setting the `validity` (referred to as [`lifetime` by Kubo](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsrecordlifetime)) field of an IPNS record, you typically need to choose whether you favor **consistency** (short validity period, e.g. 48 hours) or **availability** (long validity period, e.g. 1 month), due to the inherent trade-off between the two.
 
 #### Practical considerations
 

docs/how-to/gateway-troubleshooting.md

@@ -106,7 +106,7 @@ If providers were found in the DHT, do the following:
 
 ### No providers returned
 
-If no providers are returned, the issue may lie in the content publishing lifecycle, specifically _reprovider runs_, the continuous process in which a node advertises provider records. _Provider records_ are mappings of CIDs to network addresses, and have an expiration time of 24 hours, which accounts for provider churn. Generally speaking, as more files are added to an IPFS node, the longer reprovide runs take. When a reprovide run takes longer than 24 hours (the expiration time for provider records), CIDs will no longer be discoverable.
+If no providers are returned, the issue may lie in the content publishing lifecycle, specifically _reprovider runs_, the continuous process in which a node advertises provider records. _Provider records_ are mappings of CIDs to network addresses, and have an expiration time of 48 hours, which accounts for provider churn. Generally speaking, as more files are added to an IPFS node, the longer reprovide runs take. When a reprovide run takes longer than 48 hours (the expiration time for provider records), CIDs will no longer be discoverable.
 
 :::
 You can learn more about the content publishing lifecycle in [How IPFS works](../concepts/how-ipfs-works.md).
@@ -129,16 +129,16 @@ With this in mind, if no providers are returned, do the following:
    LastReprovideBatchSize: 1k (1,858)
    ```
 
-1. Note the value for `LastReprovideDuration`. If it is close to 24 hours, select one of the following options, keeping in mind that each has tradeoffs:
+2. Note the value for `LastReprovideDuration`. If it is close to 48 hours, select one of the following options, keeping in mind that each has tradeoffs:
 
    - **Enable the [Accelerated DHT Client](https://github.com/ipfs/go-ipfs/blob/master/docs/experimental-features.md#accelerated-dht-client) in Kubo**. This configuration improves content publishing times significantly by maintaining more connections to peers and a larger routing table and batching advertising of provider records. However, this performance boost comes at the cost of increased resource consumption.
 
    - **Change the reprovider strategy from `all` to either `pinned` or `roots`.** In both cases, only provider records for explicitly pinned content are advertised. Differences and tradeoffs are noted below:
       - The `pinned` strategy will advertise both the root CIDs and child block CIDs (the entire DAG) of explicitly pinned content.
       - The `roots` strategy will only advertise the root CIDs of pinned content, reducing the total number of provides in each run. This strategy is the most efficient, but should be done with caution, as it will limit discoverability only to root CIDs. In other words, if you are adding folders of files to an IPFS node, only the CID for the pinned folder will be advertised. All the blocks will still be retrievable with Bitswap once a connection to the node is established.
 
-1. Manually trigger a reprovide run:
+3. Manually trigger a reprovide run:
 
    ```shell
    ipfs bitswap reprovide
-   ```
+   ```