Merge branch 'ipfs:master' into master

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+ - name: Getting Help on IPFS
+   url: https://ipfs.io/help
+   about: All information about how and where to get help on IPFS.
+ - name: IPFS Official Forum
+   url: https://discuss.ipfs.io
+   about: Please post general questions, support requests, and discussions here.

.github/ISSUE_TEMPLATE/open_an_issue.md

@@ -0,0 +1,19 @@
+---
+name: Open an issue
+about: Only for actionable issues relevant to this repository.
+title: ''
+labels: need/triage
+assignees: ''
+
+---
+<!--
+Hello! To ensure this issue is correctly addressed as soon as possible by the IPFS team, please try to make sure:
+
+- This issue is relevant to this repository's topic or codebase.
+
+- A clear description is provided. It should includes as much relevant information as possible and clear scope for the issue to be actionable.
+
+FOR GENERAL DISCUSSION, HELP OR QUESTIONS, please see the options at https://ipfs.io/help or head directly to https://discuss.ipfs.io.
+
+(you can delete this section after reading)
+-->

API_CORE.md

@@ -12,7 +12,7 @@ The `core` API is the programmatic interface for IPFS, it defines the method sig
 
 # Table of Contents
 
-TODo
+TODO
 
 ## Required for compliant IPFS implementation
 
@@ -83,7 +83,7 @@ TODo
   - tail
 
 
-## Tooling on top of the Core + Extentions
+## Tooling on top of the Core + Extensions
 
 > Everything defined here is optional, and might be specific to the implementation details (like running on the command line).
 

ARCHITECTURE.md

@@ -56,7 +56,7 @@ privateKey, publicKey := keygen()
 nodeID := multihash(publicKey)
 ```
 
-TODO: constraints on keygen.
+See more in the [IPFS keystore spec](https://github.com/ipfs/specs/blob/master/KEYSTORE.md).
 
 ## 2.1 multihash and upgradeable hashing
 
@@ -87,7 +87,7 @@ IPFS has five layers:
 
 These are briefly described bottom-up.
 
-## [3.1 Network](network)
+## 3.1 Network
 
 The **network** provides point-to-point transports (reliable and unreliable) between any two IPFS nodes in the network. It handles:
 - NAT traversal - hole punching, port mapping, and relay
@@ -97,7 +97,7 @@ The **network** provides point-to-point transports (reliable and unreliable) bet
 
 See more in the [libp2p specs](https://github.com/libp2p/specs).
 
-## [3.2 Routing -- finding peers and data](routing)
+## 3.2 Routing -- finding peers and data
 
 The IPFS **Routing** layer serves two important purposes:
 - **peer routing** -- to find other nodes
@@ -112,7 +112,7 @@ The Routing Sytem is an interface that is satisfied by various kinds of implemen
 
 See more in the [libp2p specs](https://github.com/libp2p/specs).
 
-## [3.3 Block Exchange -- transfering content-addressed data](exchange)
+## 3.3 Block Exchange -- transferring content-addressed data
 
 The IPFS **Block Exchange** takes care of negotiating bulk data transfers. Once nodes know each other -- and are connected -- the exchange protocols govern how the transfer of content-addressed blocks occurs.
 
@@ -122,9 +122,9 @@ The Block Exchange is an interface that is satisfied by various kinds of impleme
   of BitTorrent to work with arbitrary (and not known apriori) DAGs.
 - **HTTP:** a simple exchange can be implemented with HTTP clients and servers.
 
-## [3.4. Merkledag -- making sense of data](../merkledag)
+## 3.4. Merkledag -- making sense of data
 
-[As discussed above](#IPFS-and-the-Merkle-DAG), the IPFS **merkledag** is the datastructure at the heart of IPFS. It is an [acyclic directed graph](http://en.wikipedia.org/wiki/Directed_acyclic_graph) whose edges are hashes. Another name for it is the merkleweb.
+[As discussed above](#IPFS-and-the-Merkle-DAG), the IPFS **merkledag** (also known as IPLD - InterPlanetary Linked Data) is the datastructure at the heart of IPFS. It is an [acyclic directed graph](http://en.wikipedia.org/wiki/Directed_acyclic_graph) whose edges are hashes. Another name for it is the merkleweb.
 
 The merkledag data structure is:
 
@@ -147,9 +147,9 @@ The merkledag is the "thin waist" of authenticated datastructures. It is a minim
 - **bitcoin** and other blockchains
 - **unixfs**, a content-addressed unix filesystem
 
-See more in the merkledag spec (TODO).
+See more in the [IPLD spec](https://github.com/ipld/specs/).
 
-## [3.4.1 Merkledag Paths](../merkledag)
+## 3.4.1 Merkledag Paths
 
 The merkledag is enough to resolve paths:
 
@@ -161,11 +161,11 @@ The merkledag is enough to resolve paths:
 - (b) Then look into the links of (a), find the hash for `test`, and resolve it
 - (c) Then look into the links of (b), find the hash for `foo`, and resolve it
 
-See more in the path resolution spec (TODO).
+See more in the [path resolution spec](https://github.com/ipld/specs/blob/master/data-model-layer/paths.md).
 
-![](../media/ipfs-resolve/ipfs-resolve.gif)
+![](img/ipfs-resolve/ipfs-resolve.gif)
 
-## [3.5 Naming -- PKI namespace and mutable pointers]()
+## 3.5 Naming -- PKI namespace and mutable pointers
 
 IPFS is mostly concerned with content-addressed data, which by nature is immutable: changing an object would change its hash -- and thus its address, making it a _different_ object altogether. (Think of it as a copy-on-write filesystem).
 
@@ -175,26 +175,26 @@ The IPFS **naming** layer -- or IPNS -- handles the creation of:
 
 IPNS is based on [SFS](http://en.wikipedia.org/wiki/Self-certifying_File_System). It is a PKI namespace -- a name is simply the hash of a public key. Whoever controls the private key controls the name. Records are signed by the private key and distributed anywhere (in IPFS, via the routing system). This is an egalitarian way to assign mutable names in the internet at large, without any centralization whatsoever, or certificate authorities.
 
-See more in the namin spec (TODO).
+See more in the [IPNS spec](https://github.com/ipfs/specs/blob/master/IPNS.md).
 
-# [4. Applications and Datastructures -- on top of IPFS]()
+# 4. Applications and Datastructures -- on top of IPFS
 
 The stack described so far is enough to represent arbitrary datastructures and replicate them across the internet. It is also enough to build and deploy decentralized websites.
 
 Applications and datastructures on top of IPFS are represented as merkledags. Users can create arbitrary datastructures that extend the merkledag and deploy them to the rest of the world using any of the tools that understand IPFS.
 
-See more in the datastructures and applications specs (TODO).
+See more in the [IPLD datastructures specs](https://github.com/ipld/specs/tree/master/data-structures).
 
-## [4.1 unixfs -- representing traditional files]()
+## 4.1 unixfs -- representing traditional files
 
 The unix filesystem abstractions -- files and directories -- are the main way people conceive of files in the internet. In IPFS, `unixfs` is a datastructure that represents unix files on top of IPFS. We need a separate datastructure to carry over information like:
 
 - whether the object represents a file or directory.
 - total sizes, minus indexing overhead
 
-See more in the unixfs spec (TODO).
+See more in the [unixfs spec](https://github.com/ipfs/specs/blob/master/UNIXFS.md).
 
-## [5 Lifetime of fetching an object.]()
+## 5. Lifetime of fetching an object.
 
 Suppose we ask an IPFS node to retrieve
 
@@ -212,13 +212,13 @@ Then, the IPFS node resolves the components.
 The first component in an `/ipfs/...` path is always a multihash.
 The rest are names of links, to be resolved into multihashes.
 
-# [6 IPFS User Interfaces]()
+# 6. IPFS User Interfaces
 
 IPFS is not just a protocol. It is also a toolset. IPFS implementations include various tools for working with the merkledag, how to publish something, how to name something, etc. These interfaces may be critical to the survival of an implementation, or the project as a whole. These interfaces govern how people use IPFS, thus careful attention must be given to their design and implementation. Examples:
 
-- The [IPFS api](http://ipfs.io/docs/api) - an HTTP service
-- The [IPFS cli](http://ipfs.io/docs/commands/) - a unix cli
-- The [IPFS libs](https://github.com/ipfs/ipfs#api-client-libraries) - implementations in various languages
+- The [IPFS api](https://docs.ipfs.io/reference/api/http/) - an HTTP service
+- The [IPFS cli](https://docs.ipfs.io/reference/api/cli/) - a unix cli
+- The [IPFS libs](https://github.com/ipfs/ipfs#http-client-libraries) - implementations in various languages
 - The IPFS gateways - nodes in the internet that serve HTTP over IPFS
 
 * * *

BITSWAP.md

@@ -113,7 +113,7 @@ Task workers watch the message queues, dequeue a waiting message, and send it to
 
 ## Network
 
-The network is the abstraction representing all Bitswap peers that are connected to us by one or more hops. Bitswap messages flow in and out of the network. This is where a game-theoretical analysis of Bitswap becomes relevant – in an arbitrary network we must assume that all of our peers are rational and self-interested, and we act accordingly. Work along these lines can be found in the [research-bitswap respository](https://github.com/ipfs/research-bitswap), with a preliminary game-theoretical analysis currently in-progress [here](https://github.com/ipfs/research-bitswap/blob/docs/strategy_analysis/analysis/prelim_strategy_analysis.pdf).
+The network is the abstraction representing all Bitswap peers that are connected to us by one or more hops. Bitswap messages flow in and out of the network. This is where a game-theoretical analysis of Bitswap becomes relevant – in an arbitrary network we must assume that all of our peers are rational and self-interested, and we act accordingly. Work along these lines can be found in the [research-bitswap repository](https://github.com/ipfs/research-bitswap), with a preliminary game-theoretical analysis currently in-progress [here](https://github.com/ipfs/research-bitswap/blob/docs/strategy_analysis/analysis/prelim_strategy_analysis.pdf).
 
 # Implementation Details
 

IMPORTERS_EXPORTERS.md

@@ -30,7 +30,7 @@ Lots of discussions around this topic, some of them here:
 
 Importing data into IPFS can be done in a variety of ways. These are use-case specific, produce different datastructures, produce different graph topologies, and so on. These are not strictly needed in an IPFS implementation, but definitely make it more useful.
 
-These data importing primitivies  are really just tools on top of IPLD, meaning that these can be generic and separate from IPFS itself.
+These data importing primitives are really just tools on top of IPLD, meaning that these can be generic and separate from IPFS itself.
 
 Essentially, data importing is divided into two parts:
 
@@ -52,10 +52,10 @@ Essentially, data importing is divided into two parts:
 
 ## Requirements
 
-These are a set of requirements (or guidelines) of the expectations that need to be fullfilled for a layout or a splitter:
+These are a set of requirements (or guidelines) of the expectations that need to be fulfilled for a layout or a splitter:
 
 - a layout should expose an API encoder/decoder like, that is, able to convert data to its format and convert it back to the original format
-- a layout should contain a clear umnambiguous representation of the data that gets converted to its format
+- a layout should contain a clear unambiguous representation of the data that gets converted to its format
 - a layout can leverage one or more splitting strategies, applying the best strategy depending on the data format (dedicated format chunking)
 - a splitter can be:
   - agnostic - chunks any data format in the same way
@@ -77,7 +77,7 @@ These are a set of requirements (or guidelines) of the expectations that need to
                           Importer
 ```
 
-- `chunkers or splitters`  algorithms that read a stream and produce a series of chunks. for our purposes should be deterministic on the stream. divided into:
+- `chunkers or splitters` algorithms that read a stream and produce a series of chunks. for our purposes should be deterministic on the stream. divided into:
   - `universal chunkers` which work on any streams given to them. (eg size, rabin, etc). should work roughly equally well across inputs.
   - `specific chunkers` which work on specific types of files (tar splitter, mp4 splitter, etc). special purpose but super useful for big files and special types of data.
 - `layouts or topologies` graph topologies (eg balanced vs trickledag vs ext4, ... etc)

IPNS.md

@@ -25,7 +25,7 @@ All things considered, the IPFS naming layer is responsible for the creation of:
 
 ## Introduction
 
-Each time a file is modified, its content address changes. As a consequence, the address previously used for getting that file needs to be updated by who is using it. As this is not pratical, IPNS was created to solve the problem.
+Each time a file is modified, its content address changes. As a consequence, the address previously used for getting that file needs to be updated by who is using it. As this is not practical, IPNS was created to solve the problem.
 
 IPNS is based on [SFS](http://en.wikipedia.org/wiki/Self-certifying_File_System). It consists of a PKI namespace, where a name is simply the hash of a public key. As a result, whoever controls the private key has full control over the name. Accordingly, records are signed by the private key and then distributed across the network (in IPFS, via the routing system). This is an egalitarian way to assign mutable names on the Internet at large, without any centralization whatsoever, or certificate authorities.
 
@@ -53,7 +53,7 @@ An IPNS record is a data structure containing the following fields:
 - 7. **ttl** (uint64)
   - A hint for how long the record should be cached before going back to, for instance the DHT, in order to check if it has been updated.
 
-These records are stored locally, as well as spread accross the network, in order to be accessible to everyone. For storing this structured data, we use [Protocol Buffers](https://github.com/google/protobuf), which is a language-neutral, platform neutral extensible mechanism for serializing structured data.
+These records are stored locally, as well as spread across the network, in order to be accessible to everyone. For storing this structured data, we use [Protocol Buffers](https://github.com/google/protobuf), which is a language-neutral, platform neutral extensible mechanism for serializing structured data.
 
 ```
 message IpnsEntry {
@@ -79,13 +79,13 @@ message IpnsEntry {
 
 Taking into consideration a p2p network, each peer should be able to publish IPNS records to the network, as well as to resolve the IPNS records published by other peers.
 
-When a node intends to publish a record to the network, an IPNS record needs to be created first. The node needs to have a previously generated assymetric key pair to create the record according to the datastructure previously specified. It is important pointing out that the record needs to be uniquely identified in the network. As a result, the record identifier should be a hash of the public key used to sign the record.
+When a node intends to publish a record to the network, an IPNS record needs to be created first. The node needs to have a previously generated asymmetric key pair to create the record according to the datastructure previously specified. It is important pointing out that the record needs to be uniquely identified in the network. As a result, the record identifier should be a hash of the public key used to sign the record.
 
 As an IPNS record may be updated during its lifetime, a versioning related logic is needed during the publish process. As a consequence, the record must be stored locally, in order to enable the publisher to understand which is the most recent record published. Accordingly, before creating the record, the node must verify if a previous version of the record exists, and update the sequence value for the new record being created.
 
 Once the record is created, it is ready to be spread through the network. This way, a peer can use whatever routing system it supports to make the record accessible to the remaining peers of the network.
 
-On the other side, each peer must be able to get a record published by another node. It only needs to have the unique identifier used to publish the record to the network. Taking into account the routing system being used, we may obtain a set of occurences of the record from the network. In this case, records can be compared using the sequence number, in order to obtain the most recent one.
+On the other side, each peer must be able to get a record published by another node. It only needs to have the unique identifier used to publish the record to the network. Taking into account the routing system being used, we may obtain a set of occurrences of the record from the network. In this case, records can be compared using the sequence number, in order to obtain the most recent one.
 
 As soon as the node has the most recent record, the signature and the validity must be verified, in order to conclude that the record is still valid and not compromised.
 
@@ -97,12 +97,12 @@ Finally, the network nodes may also republish their records, so that the records
 
 ## API Spec
 
-  - <https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/NAME.md>
+  - [interface-ipfs-core/SPEC/NAME.md](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md)
 
 ## Implementations
 
-  - <https://github.com/ipfs/js-ipfs/tree/master/src/core/ipns>
-  - <https://github.com/ipfs/go-ipfs/tree/master/namesys>
+  - [js-ipfs](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/src/core/ipns)
+  - [go-ipfs](https://github.com/ipfs/go-ipfs/tree/master/namesys)
 
 ## Integration with IPFS
 
@@ -120,4 +120,4 @@ The routing record is spread across the network according to the available routi
 
 **Key format:** `/ipns/BINARY_ID`
 
-The two routing systems currenty available in IPFS are the `DHT` and `pubsub`. As the `pubsub` topics must be `utf-8` for interoperability among different implementations
+The two routing systems currently available in IPFS are the `DHT` and `pubsub`. As the `pubsub` topics must be `utf-8` for interoperability among different implementations