Skip to content

Commit 2924bb5

Browse files
committed
refine lifecycle and fetching section
1 parent ef64248 commit 2924bb5

File tree

1 file changed

+15
-7
lines changed

1 file changed

+15
-7
lines changed

docs/quickstart/publish.md

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ Let's unpack what just happened, by looking at CIDs, and how they fits into the
5555

5656
In IPFS, every file and directory is identified with a Content Identifier ([CID](../concepts/content-addressing.md)). The CID serves as the **permanent address** of the file and can be used by anyone to find it on the IPFS network.
5757

58-
When a file is published to IPFS (like the image used in this guide), it's first transformed into a content-addressable representation by which the file is split into smaller chunks which linked and hashed to produce the CID.
58+
When a file is published to IPFS (like the image used in this guide), it's first transformed into a content-addressable representation by which the file is split into smaller chunks (if above ~1MB) which are linked, and hashed to produce the CID.
5959

6060
The CID for the uploaded image is:
6161

@@ -72,17 +72,25 @@ You can now share the CID and anyone should be able to fetch it.
7272
To understand what happens when you pin a file, it's helpful to understand the lifecycle of data in IPFS, which can be summarised as follows:
7373

7474
1. **Content-addressable representation**: The file is transformed into a content-addressable representation with a CID. For this guide, the full details are not important. The basic idea is that this representation makes files and directories **content-addressable** via CIDs by chunking files into smaller blocks**, calculating their hashes, and constructing a [Merkle DAG](../concepts/merkle-dag.md).
75-
2. **Pinning:** refers to the stage where the blocks of the CID are saved on an IPFS node (or multiple nodes), in this case web3.storage. Since saving is not enough for the CID to be retrieveable, pinning typically refers to two things:
75+
2. **Pinning:** refers to the stage where the blocks of the CID are saved on an IPFS node (or multiple nodes), in this case, web3.storage. Since saving is not enough for the CID to be retrievable, pinning typically refers to two things:
7676
- **Advertising:** Making it discoverable to the IPFS network by advertising a record linking between the CID and the server's IP address to the network. This advertising stage is a continuous process that repeats.
7777
- **Providing:** The content-addressable representation of the CID is persisted on one of web3.storage's IPFS nodes (servers running an IPFS node) and made publicly available to the IPFS network.
78-
3. **Fetching:** refers to step where another node in the IPFS network fetches the blocks of the CID and constructing the DAG locally essentially replicating the file.
79-
4. **Deleting**
78+
3. **Retrieval:** refers to when an IPFS node fetches the blocks of the CID and constructs the Merkle DAG. This achieves several things:
79+
- **File access:** once the Merkle DAG is constructed, the file is essentially replicated and can be accessed.
80+
- **Verifying** that the blocks received are the correct ones by hashing them. This allows blocks to come from any node in the network. This type of retrieval is *trustless*.
81+
<!-- - **Replication:** when another IPFS node fetches the CID, it increases the replication factor of the CID, thereby increasing its resilience. -->
82+
4. **Deleting:** refers to the deletion of a CID from a node. Deletion is always a local operation. If a CID has been replicated by other nodes, it will continue to be available on the IPFS network.
8083

8184
## Fetching your published file
8285

83-
There are two main ways you can fetch the CID:
84-
- IPFS node that implements the IPFS suite of protocols
85-
- IPFS gateway: an IPFS node that provides an HTTP interface to the IPFS network and bridges between IPFS and HTTP.
86+
Now that the file is published and you have a CID, you will learn how it can be fetched from the IPFS network.
87+
88+
There are two primary ways to fetch files published with IPFS:
89+
90+
- **IPFS node** by installing one of the IPFS implementations, e.g. [Kubo](/concepts/nodes/#kubo)
91+
- [**IPFS Gateway**](/concepts/ipfs-gateway/) HTTP interface to the IPFS network that allows fetching data from IPFS with HTTP.
92+
93+
The first option allows you to speak the native IPFS protocol. The latter serves as a bridge in situations where you might be constrained to using HTTP, such as in web apps where your app users may not be running an IPFS node.
8694

8795
### Using an IPFS Node
8896

0 commit comments

Comments
 (0)