From 1aaf377b806dcc936bc1becdd2733b0b68440452 Mon Sep 17 00:00:00 2001 From: ElPaisano <113373882+ElPaisano@users.noreply.github.com> Date: Mon, 18 Sep 2023 17:14:11 -0600 Subject: [PATCH 1/4] Concepts explainer for implementations --- docs/concepts/implentations.md | 30 ++++++++++++++++++++++++++++++ docs/concepts/what-is-ipfs.md | 2 +- 2 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 docs/concepts/implentations.md diff --git a/docs/concepts/implentations.md b/docs/concepts/implentations.md new file mode 100644 index 000000000..7256f501d --- /dev/null +++ b/docs/concepts/implentations.md @@ -0,0 +1,30 @@ +--- +title: IPSF 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 characteritics that 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. + +## Core principles + +IPFS implementations must: + +- Support addressability using Content IDentifiers (CIDs). +- Expose operations such as retrieval, provisioning, and indexing, on resources using CIDs. The operations that an implementation may supportare 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 (eg. 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) \ No newline at end of file diff --git a/docs/concepts/what-is-ipfs.md b/docs/concepts/what-is-ipfs.md index 9643d492b..53452f23e 100644 --- a/docs/concepts/what-is-ipfs.md +++ b/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 implementation of IPFS protocol [specifications](https://github.com/ipfs/specs), such as Kubo. +- An implementation of IPFS protocol [specifications](https://github.com/ipfs/specs), such as Kubo. Learn more about [the principles that define an IPFS implementation](./implentations.md). - A decentralized network composed of IPFS nodes that is open and participatory. - A modular suite of protocols and standards for organizing and transferring content-addressed data. From 0a6a6db9415a3efbe2c510ff677ea9b717d0419f Mon Sep 17 00:00:00 2001 From: ElPaisano <113373882+ElPaisano@users.noreply.github.com> Date: Mon, 18 Sep 2023 17:55:16 -0600 Subject: [PATCH 2/4] Links, typos, mods --- docs/.vuepress/config.js | 10 +++++++++- docs/concepts/{implentations.md => implementations.md} | 2 ++ docs/concepts/ipfs-implementations.md | 2 ++ docs/concepts/what-is-ipfs.md | 2 +- 4 files changed, 14 insertions(+), 2 deletions(-) rename docs/concepts/{implentations.md => implementations.md} (97%) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 918063e73..0cce03005 100644 --- a/docs/.vuepress/config.js +++ b/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/comparisons', '/concepts/usage-ideas-examples', '/concepts/faq', diff --git a/docs/concepts/implentations.md b/docs/concepts/implementations.md similarity index 97% rename from docs/concepts/implentations.md rename to docs/concepts/implementations.md index 7256f501d..9ae169489 100644 --- a/docs/concepts/implentations.md +++ b/docs/concepts/implementations.md @@ -7,6 +7,8 @@ description: Learn about the principles that define what an IPFS implementation 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 characteritics that 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: diff --git a/docs/concepts/ipfs-implementations.md b/docs/concepts/ipfs-implementations.md index 377a7fca0..c397fe2e6 100644 --- a/docs/concepts/ipfs-implementations.md +++ b/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: diff --git a/docs/concepts/what-is-ipfs.md b/docs/concepts/what-is-ipfs.md index 53452f23e..7bf05fe06 100644 --- a/docs/concepts/what-is-ipfs.md +++ b/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 implementation of IPFS protocol [specifications](https://github.com/ipfs/specs), such as Kubo. Learn more about [the principles that define an IPFS implementation](./implentations.md). +- An implementation of IPFS protocol [specifications](https://github.com/ipfs/specs), such as Kubo. Learn more about [the principles that define an IPFS implementation](./implementations.md). - A decentralized network composed of IPFS nodes that is open and participatory. - A modular suite of protocols and standards for organizing and transferring content-addressed data. From 26da58e2abaa39006c7fac184b4bde6151439c6e Mon Sep 17 00:00:00 2001 From: ElPaisano <113373882+ElPaisano@users.noreply.github.com> Date: Mon, 25 Sep 2023 11:56:10 -0600 Subject: [PATCH 3/4] Test build From ec97217d73a1076a8127cb3c28151d6e0e831476 Mon Sep 17 00:00:00 2001 From: ElPaisano <113373882+ElPaisano@users.noreply.github.com> Date: Mon, 25 Sep 2023 15:25:21 -0600 Subject: [PATCH 4/4] typos --- docs/concepts/implementations.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/concepts/implementations.md b/docs/concepts/implementations.md index 9ae169489..7d46b9249 100644 --- a/docs/concepts/implementations.md +++ b/docs/concepts/implementations.md @@ -1,11 +1,11 @@ --- -title: IPSF implementations explained +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 characteritics that 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. +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). @@ -14,7 +14,7 @@ You can see the list of implementations [here](./ipfs-implementations.md). IPFS implementations must: - Support addressability using Content IDentifiers (CIDs). -- Expose operations such as retrieval, provisioning, and indexing, on resources using CIDs. The operations that an implementation may supportare an open-ended, but this requirement covers any operation which the implementation exposes to other IPFS implementations. +- 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 @@ -22,7 +22,7 @@ IPFS implementations must: 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 (eg. a CBOR document, a file or directory, a branch of a B-tree search index) using CIDs. +- 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.