Implementations concepts

docs/.vuepress/config.js

@@ -176,7 +176,15 @@ module.exports = {
                 '/concepts/merkle-dag'
               ]
             },
-            '/concepts/ipfs-implementations',
+            {
+              title: 'Implementations',
+              sidebarDepth: 1,
+              collapsable: true,
+              children: [
+                ['/concepts/implementations', 'Implementations explained'],
+                ['/concepts/ipfs-implementations', 'List of implementations']
+              ]
+            },
             '/concepts/cod',
             '/concepts/comparisons',
             '/concepts/usage-ideas-examples',

docs/concepts/implementations.md

@@ -0,0 +1,32 @@
+---
+title: IPFS implementations explained
+description: Learn about the principles that define what an IPFS implementation is.
+---
+
+# IPFS implementations explained
+
+Software, written in any programming language, is considered to be an _IPFS implementation_ if it adheres to the core principles listed below. However, there are characteristics that an IPFS implementation _may_ have, but are not strictly _required_. IPFS principles are broad by design because, like HTTP, IPFS supports an open-ended set of use cases and is adaptable to a broad array of operating conditions. Some implementations are optimized for specific use cases or devices, or use different subsystems to handle content-addressed data. There are multiple specifications in IPFS for handling content-addressed data, and not all implementations implement them.
+
+You can see the list of implementations [here](./ipfs-implementations.md).
+
+## Core principles
+
+IPFS implementations must:
+
+- Support addressability using <VueCustomTooltip label="An address used to point to data in IPFS, based on the content itself, as opposed to the location." underlined multiline is-medium>Content IDentifiers (CIDs)</VueCustomTooltip>.
+- Expose operations such as retrieval, provisioning, and indexing, on resources using CIDs. The operations that an implementation may support are an open-ended, but this requirement covers any operation which the implementation exposes to other IPFS implementations.
+- Verify that the CIDs it resolves match the resources addressed, at least when the resources' bytes are accessible. Implementations may relax this requirement in controlled environments in which it is possible to ascertain that verification has happened elsewhere in a trusted part of the system.
+
+## Recommended principles
+
+The following principles are not strictly required. However, it is recommended that all IPFS implementations should do the following, for the reasons described:
+
+- Name all the important resources exposed using CIDs. Consider anything that another agent might legitimately wish to access as being in scope, and err on the side of inclusion.
+- Expose the logical units of data that structure a resource (e.g. a CBOR document, a file or directory, a branch of a B-tree search index) using CIDs.
+- Support incremental verifiability, notably so that it may process content of arbitrary sizes.
+- Should not rely on any one transport layer. The transport layer cannot dictate or constrain the way in which CIDs map to content.
+
+## Further resources
+
+- [List of IPFS implementations](./ipfs-implementations.md)
+- [IPFS Standards website: IPFS Principles spec](https://specs.ipfs.tech/architecture/principles/#ipfs-implementation-requirements)

docs/concepts/ipfs-implementations.md

@@ -7,6 +7,8 @@ description: "There isn't just one canonical IPFS implementation. Learn about th
 
 IPFS is an open-source project that encourages the development of multiple implementations of the protocol, each of which seeks to optimize for various use cases. Below is non-exhaustive list of IPFS implementations, grouped by development and maintenance status ([Popular or Actively Maintained](#popular-or-actively-maintained), [Lite or Experimental](#lite-or-experimental) and [Inactive](#inactive)) and ordered alphabetically. To propose additions or edits, [edit this page in GitHub](https://github.com/ipfs/ipfs-docs/edit/main/docs/concepts/ipfs-implementations.md) or [open an issue](https://github.com/ipfs/ipfs-docs/issues/new?assignees=&labels=need%2Ftriage&template=open_an_issue.md&title=IPFS%20Implementations).
 
+You can learn more about the principles that define what an IPFS implementation is [here](./implementations.md).
+
 ::: tip
 Looking for an easy, user-friendly way to get started with IPFS? Try any of the options listed below:
 

docs/concepts/what-is-ipfs.md

@@ -18,7 +18,7 @@ In this conceptual guide, you'll learn what IPFS is and isn't.
 
 The term _IPFS_ can refer to multiple concepts:
 
-- An <VueCustomTooltip label="Software, written in any programming language, with functionality to process and transmit content-addressed data. Some implementations are optimized for specific use cases or devices, or use different subsystems to handle content-addressed data. There are multiple specififactions in IPFS for handling content-addressed data, and not all implementations implement them." underlined multiline is-medium>implementation</VueCustomTooltip> of IPFS protocol [specifications](https://github.com/ipfs/specs), such as <VueCustomTooltip label="The first implementation of IPFS, written in Go." underlined multiline>Kubo</VueCustomTooltip>.
+- An <VueCustomTooltip label="Software, written in any programming language, with functionality to process and transmit content-addressed data. Some implementations are optimized for specific use cases or devices, or use different subsystems to handle content-addressed data. There are multiple specififactions in IPFS for handling content-addressed data, and not all implementations implement them." underlined multiline is-medium>implementation</VueCustomTooltip> of IPFS protocol [specifications](https://github.com/ipfs/specs), such as <VueCustomTooltip label="The first implementation of IPFS, written in Go." underlined multiline>Kubo</VueCustomTooltip>. Learn more about [the principles that define an IPFS implementation](./implementations.md).
 - A 
 <VueCustomTooltip label="A network of computers in which multiple servers act as a single processing point, without having a central server to manage network activity." underlined multiline is-medium>decentralized network</VueCustomTooltip> composed of <VueCustomTooltip label="Computers participating in an IPFS network by running an IPFS implementation. Also referred to as peers" underlined multiline>IPFS nodes</VueCustomTooltip> that is open and participatory.
 - A modular suite of protocols and standards for organizing and transferring content-addressed data.