Skip to content

Add IPFS "Mainnet" to the glossary #1910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 19, 2024
Merged

Add IPFS "Mainnet" to the glossary #1910

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4536ff3
feat: add Mainnet to the glossary
2color Jul 25, 2024
f19ff56
feat: add simpler explanation for CAR
2color Jul 25, 2024
3aa828b
chore: refine based on feedback
2color Aug 19, 2024
6c53d78
chore: refine gateway
2color Aug 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/concepts/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ A Bootstrap Node is a trusted peer on the IPFS network through which an IPFS nod

### CAR

The CAR (Content Addressable aRchives) is a format for serialized representation of any [IPLD](#ipld) [DAG](#dag). Typically in a file with a .car filename extension or a byte stream marked as [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) media type. [More about CAR](https://ipld.io/specs/transport/car/)
The CAR (Content Addressable aRchives) is a format for serialized representation of any [IPLD](#ipld) [DAG](#dag). The CAR format is a way of packaging up content-addressed data into archive files that can be easily stored and transferred. Typically in a file with a `.car` filename extension or a byte stream marked as [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) media type. [More about CAR](https://ipld.io/specs/transport/car/)

### CAR v1

Expand Down Expand Up @@ -208,7 +208,7 @@ An experimental data store used when `--nocopy` is passed to `ipfs add`. It stor

### Gateway

An IPFS Gateway acts as a bridge between traditional web browsers and IPFS. Through the gateway, users can browse files and websites stored in IPFS as if they were stored on a traditional web server. [More about Gateway](../concepts/ipfs-gateway.md) and [addressing IPFS on the web](../how-to/address-ipfs-on-web.md)
An IPFS Gateway acts as a bridge between HTTP-based protocols and IPFS. Through the gateway, users can browse files and websites stored in IPFS as if they were stored on a HTTP web server. [More about Gateway](../concepts/ipfs-gateway.md) and [addressing IPFS on the web](../how-to/address-ipfs-on-web.md)

### Garbage Collection

Expand Down Expand Up @@ -298,6 +298,10 @@ In IPFS and [IPLD](#ipld), a _link_ usually means a pointer to some [CID](#cid).

## M

### IPFS Mainnet

IPFS Mainnet is a term used to describe the default or "main" network that many IPFS implementations connect to. Mainnet is a subset of all the [IPFS implementations](https://specs.ipfs.tech/architecture/principles/#ipfs-implementation-requirements) and typically includes implementations that connect to the [Amino DHT](#amino) and support [Bitswap](#bitswap), [UnixFS](#unixfs), and the [IPFS Gateway](#gateway). This has mostly been assumed for the IPFS network and is not emphasized for anyone other than protocol experts. Nonetheless, IPFS Mainnet is a useful distinction in a world of many [IPFS implementations](../concepts/implementations.md) with varying degrees of interoperability.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For me, "mainnet" is less about implementations than configs, i.e. a private-network kubo is not on mainnet, but a default-config kubo puts everything it ipfs adds onto mainnet, if you catch my drift. I could be wrong, tho!

Suggested change
IPFS Mainnet is a term used to describe the default or "main" network that many IPFS implementations connect to. Mainnet is a subset of all the [IPFS implementations](https://specs.ipfs.tech/architecture/principles/#ipfs-implementation-requirements) and typically includes implementations that connect to the [Amino DHT](#amino) and support [Bitswap](#bitswap), [UnixFS](#unixfs), and the [IPFS Gateway](#gateway). This has mostly been assumed for the IPFS network and is not emphasized for anyone other than protocol experts. Nonetheless, IPFS Mainnet is a useful distinction in a world of many [IPFS implementations](../concepts/implementations.md) with varying degrees of interoperability.
IPFS Mainnet is a term used to describe the default or "main" network that most IPFS implementations connect to by default configuration.
Most [IPFS implementations](https://specs.ipfs.tech/architecture/principles/#ipfs-implementation-requirements) were designed to work with mainnet, but many can be configured instead to use private networks (i.e. only sync with manually allowlisted peers) or only serve content generated locally.
Mainnet as a network and data substrate refers to the [Amino DHT](#amino). comprised of nodes that synchronize their contents using the [Bitswap](#bitswap) sync protocol;
as all data is, by default, converted to [UnixFS](#unixfs) at ingress by these implementations, and [IPFS Gateways](#gateway) are configured to assume [UnixFS](#unixfs)-only data, other encodings are sometimes considered incompatible with or problematic for use with bitswap, and as such, not "Mainnet-compatible".
Most IPFS documentation is written assuming all Mainnet-compatible configurations and network topology, because straying from these defaults can break many assumptions of the system and is recommended only for advanced applications.
For this reason, compatibility with IPFS Mainnet is often referred to as "full IPFS compatibility", and many [IPFS implementations](../concepts/implementations.md) require additional care to interoperate at the bitswap-sync, DHT-advertising, or CID-fetching layers.

(totally just winging it, feel free to take or leave any of that, but this would be my "interop maxi"/"roast my docs" take on the full meaning of Mainnet!)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've integrated some of the information from your suggestion. For consistency with other glossary terms, I'm keeping this brief. If you feel it's necessary to add all the additional information, I would create a new page dedicated to this topic. But I'd consider that out of scope for this PR.


### Merkle-DAG

The Merkle-DAG is a computer science data structure used at the core of IPFS files/block storage. Merkle-DAGs create a hash to their content, known as a [Content Identifier](#cid). [More about Merkle-DAG](merkle-dag.md)
Expand Down