diff --git a/README.md b/README.md index dea9ccb1f..87fafa69a 100644 --- a/README.md +++ b/README.md @@ -1,89 +1,87 @@ -# IPFS Specs +Specifications +============== [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io) [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs) -This repository contains the specs for the IPFS Protocol and associated -subsystems. Some day we will hopefully transform these specs into RFCs. -For now, they assume a high level of familiarity with the concepts. +![](media-artifacts/ipfs-splash.png) - -![](ipfs-splash.png) +> This repository contains the specs for the IPFS Protocol and associated subsystems. Some day we will hopefully transform these specs into RFCs. For now, they assume a high level of familiarity with the concepts. ## Work In Progress -Warning: this is a work in progress. IPFS is a young system and we want to -get it right. We will continue to evaluate and re-think pieces. At this point, -the IPFS protocol is solid enough to write this spec and produce interoperable -implementations in different languages. +Warning: this is a work in progress. IPFS is a young system and we want to get it right. We will continue to evaluate and re-think pieces. At this point, the IPFS protocol is solid enough to write this spec and produce interoperable implementations in different languages. -**(This is not done yet, but.)** -I will tag different specs with their stability: +**Specs are not finished yet. We use the following tag system to identify their state:** -- `wip` this spec is a work-in-progress, it is likely not even complete. -- `draft` this spec is a rough draft and will likely change substantially. -- `stable` this spec is likely to improve, but not change fundamentally. -- `reliable` this spec is believed to be close to final. Minor changes only. -- `permanent` this spec will not change. +- ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) - this spec is a work-in-progress, it is likely not even complete. +- ![](https://img.shields.io/badge/status-draft-yellow.svg?style=flat-square) - this spec is a rough draft and will likely change substantially. +- ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) - this spec is believed to be close to final. Minor changes only. +- ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square) - this spec is likely to improve, but not change fundamentally. +- ![](https://img.shields.io/badge/status-permanent-blue.svg?style=flat-square) - this spec will not change. -Nothing in this spec repository is `permanent` yet. The most important -pieces of IPFS are now `reliable` or `stable`. Many subsystems remain as -`draft`. +Nothing in this spec repository is `permanent` yet. The most important pieces of IPFS are now `reliable` or `stable`. Many subsystems remain as `draft`. -Note that, as in many IPFS repositories, most of the work is happening in -[the issues](https://github.com/ipfs/specs/issues/) or in [active pull requests](https://github.com/ipfs/specs/pulls/). -Go take a look! +Note that, as in many IPFS repositories, most of the work is happening in [the issues](https://github.com/ipfs/specs/issues/) or in [active pull requests](https://github.com/ipfs/specs/pulls/). Go take a look! ## Specs The specs contained in this repository are: -Protocol: -- [protocol](protocol) - the top-level spec and the stack - -Stack: -- network - the network layer spec -- routing - the routing layer spec -- exchange - the exchange layer spec -- merkledag - the Merkle DAG layer spec -- ipns - the naming layer spec -- app - the application layer spec - -Routing Systems: -- kademlia - Kademlia DHT -- dnssd - mDNS for local area networks -- snr - supernode delegated routing -- multirouter - combines multiple others - -Exchanges: -- bitswap - BitTorrent-inspired exchange - -Service: -- service - the spec IPFS libraries and servers should implement -- service-http-api - the HTTP API version of ipfs-service -- service-cli - the CLI version of ipfs-service - -Repository: -- [repo](repo) - IPFS node local repository spec -- config - IPFS node configuration -- fs-repo - the spec of the fs-repo implementation - -Other protocols: -- id - node identification -- relay - the relay protocol - -Formats: +**IPFS Protocol:** +- [protocol](/architecture) - the top-level spec and the stack +- [overviews](/overviews) - quick overviews of the various parts of IPFS + +**Networking layer:** +- [libp2p](/libp2p) - libp2p is a modular and extensible network stack, built and use by IPFS, but that it can be reused as a standalone project. Covers: + - network - the network layer spec + - routing - the routing layer spec + - kademlia - Kademlia DHT + - relay - the relay protocol + - dnssd - mDNS for local area networks + - snr - supernode delegated routing + - multirouter - combines multiple others + +**Data Structures and formats:** +- [MerkleDAG](/merkledag) - The MerkleDAG layer (pre IPLD) +- [IPLD](/ipld) - InterPlanetary Linked Data +- [unixfs](/unixfs) - [multihash](https://github.com/jbenet/multihash) - self-describing hash digest format - [multiaddr](https://github.com/jbenet/multiaddr) - self-describing addressing format +**Block Exchanges:** +- [bitswap](/bitswap) - BitTorrent-inspired exchange + +**Specific Internal Components:** +- Blocks and Block Service +- DAG and DAG Service +- Data Importing +- [Repo](/repo) - IPFS node local repository spec + - config - IPFS node configuration + - fs-repo - the spec of the fs-repo implementation + +**Files / Mutable File System:** +- [Files Impl and API](/files) - Virtual File System interface, unix like, on top of the MerkleDAG + +**Public APIs:** +- [Core API](/public-api/core) - IPFS programmatic interface +- [HTTP API](https://github.com/ipfs/http-api-spec) - IPFS HTTP API specification +- [CLI](/public-api/cli) - Command Line Interface + +**Records and Record Systems:** +- [IPRS](/iprs-interplanetary-record-system) - InterPlanetary Record System +- [IPNS](ipns-interplanetary-naming-system) - InterPlanetary Naming System + +**Key Management:** +- [KeyStore](/keystore) - Key management on IPFS +- [KeyChain](/keychain) - Distribution of cryptographic Artificats + +**Other/related/included:** +- [PDD](/pdd-protocol-driven-developement) - Protocol Driven Development + ## Collaborating -Suggestions, contributions, criticisms are welcome. Though please make sure to -familiarize yourself deeply with IPFS, the models it adopts, and the principles -it follows. +Suggestions, contributions, criticisms are welcome. Though please make sure to familiarize yourself deeply with IPFS, the models it adopts, and the principles it follows. -Please be aware that specs are really hard to design by committee. -Treat this space like you would the workshop of an artist. Please suggest -improvements, but please don't be disappointed if we say no to something. -What we leave out is often more important than what we add in. +Please be aware that specs are really hard to design by committee. Treat this space like you would the workshop of an artist. Please suggest improvements, but please don't be disappointed if we say no to something. What we leave out is often more important than what we add in. diff --git a/api/cli/README.md b/api/cli/README.md deleted file mode 100644 index 56cb85b75..000000000 --- a/api/cli/README.md +++ /dev/null @@ -1,192 +0,0 @@ -# CLI Interface - -ipfs - -ipfs add - -ipfs bitswap - -ipfs bitswap stat - -ipfs bitswap unwant - -ipfs bitswap wantlist - -ipfs block - -ipfs block get - -ipfs block put - -ipfs block stat - -ipfs bootstrap - -ipfs bootstrap add - -ipfs bootstrap list - -ipfs bootstrap rm - -ipfs cat - -ipfs commands - -ipfs config - -ipfs config edit - -ipfs config replace - -ipfs config show - -ipfs daemon - -ipfs dht - -ipfs dht findpeer - -ipfs dht findprovs - -ipfs dht get - -ipfs dht put - -ipfs dht query - -ipfs diag - -ipfs diag net - -ipfs diag sys - -ipfs dns - -ipfs file - -ipfs file ls - -ipfs files - -ipfs files cp - -ipfs files ls - -ipfs files mkdir - -ipfs files mv - -ipfs files read - -ipfs files rm - - -ipfs files stat - -ipfs files write - -ipfs get - -ipfs id - -ipfs init - -ipfs log - -ipfs log level - -ipfs log tail - -ipfs ls - -ipfs mount - -ipfs name - -ipfs name publish - -ipfs name resolve - -ipfs object - -ipfs object data - -ipfs object get - -ipfs object links - -ipfs object new - -ipfs object patch - -ipfs object patch add-link - -ipfs object patch append-data - -ipfs object patch rm-link - -ipfs object patch set-data - -ipfs object put - -ipfs object stat - -ipfs pin - -ipfs pin add - -ipfs pin ls - -ipfs pin rm - -ipfs ping - -ipfs refs - -ipfs refs local - -ipfs repo - -ipfs repo gc - -ipfs resolve - -ipfs stats - -ipfs stats bw - -ipfs swarm - -ipfs swarm addrs - -ipfs swarm addrs local - -ipfs swarm connect - -ipfs swarm disconnect - -ipfs swarm filters - -ipfs swarm filters add - -ipfs swarm filters rm - -ipfs swarm peers - -ipfs tar - -ipfs tar add - -ipfs tar cat - -ipfs tour - -ipfs tour list - -ipfs tour next - -ipfs tour restart - -ipfs update - -ipfs version diff --git a/protocol/README.md b/architecture/README.md similarity index 55% rename from protocol/README.md rename to architecture/README.md index 089b299aa..9903c2552 100644 --- a/protocol/README.md +++ b/architecture/README.md @@ -1,7 +1,7 @@ -IPFS Protocol Spec -================== +IPFS Architecture Overview +========================== -> **This spec is an Work In Progress (WIP)** +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Authors: @@ -12,24 +12,22 @@ Reviewers: * * * -This spec document defines the IPFS protocol stack, the subsystems, the -interfaces, and how it all fits together. It delegates non-interface details -to other specs as much as possible. This is meant as a top-level view of the -protocol and how the system fits together. +This spec document defines the IPFS protocol stack, the subsystems, the interfaces, and how it all fits together. It delegates non-interface details to other specs as much as possible. This is meant as a top-level view of the protocol and how the system fits together. -Note, this document is not meant to be an introduction of the concepts in IPFS -and is not recommended as a first pass to understanding how IPFS works. For -that, please refer to the [IPFS paper](https://github.com/ipfs/specs/tree/master/papers/ipfs.pdf). +Note, this document is not meant to be an introduction of the concepts in IPFS and is not recommended as a first pass to understanding how IPFS works. For that, please refer to the [IPFS paper](https://github.com/ipfs/specs/tree/master/papers/ipfs.pdf). -# Index +# Table of Contents -- []() -- []() +- 1. IPFS and the Merkle DAG +- 2. Nodes and Network Model +- 3. The Stack +- 4. Applications and Datastructures -- on top of IPFS +- 5. Lifetime of fetching an object +- 6. IPFS User Interfaces -## 1. IPFS and the Merkle DAG +# 1. IPFS and the Merkle DAG -At the heart of IPFS is the MerkleDAG, a directed acyclic graph whose links -are hashes. This gives all objects in IPFS useful properties: +At the heart of IPFS is the MerkleDAG, a directed acyclic graph whose links are hashes. This gives all objects in IPFS useful properties: - authenticated: content can be hashed and verified against the link - permanent: once fetched, objects can be cached forever @@ -46,16 +44,12 @@ In turn, these yield properties for the system as a whole: - any datastructure can be modelled and distributed - (todo: list more) -IPFS is a stack of network protocols that organize agent networks to create, -publish, distribute, serve, and download merkledags. It is the authenticated, -decentralized, permanent web. +IPFS is a stack of network protocols that organize agent networks to create, publish, distribute, serve, and download merkledags. It is the authenticated, decentralized, permanent web. -## 2. Nodes and Network Model +# 2. Nodes and Network Model -The IPFS network uses PKI based identity. An "ipfs node" is a program that -can find, publish, and replicate merkledag objects. Its identity is defined -by a private key. Specifically: +The IPFS network uses PKI based identity. An "ipfs node" is a program that can find, publish, and replicate merkledag objects. Its identity is defined by a private key. Specifically: ``` privateKey, publicKey := keygen() @@ -64,17 +58,9 @@ nodeID := multihash(publicKey) TODO: constraints on keygen. -### 2.1 multihash and upgradeable hashing +## 2.1 multihash and upgradeable hashing -All hashes in ipfs are encoded with -[multihash](https://github.com/jbenet/multihash/), a self-describing hash -format. The actual hash function used depends on security requirements. -The cryptosystem of IPFS is upgradeable, meaning that as hash functions are -broken, networks can shift to stronger hashes. There is no free lunch, as -objects may need to be rehashed, or links duplicated. But ensuring that tools -built do not assume a pre-defined length of hash digest means tools that -work with today's hash functions will also work with tomorrows longer hash -functions too. +All hashes in ipfs are encoded with [multihash](https://github.com/jbenet/multihash/), a self-describing hash format. The actual hash function used depends on security requirements. The cryptosystem of IPFS is upgradeable, meaning that as hash functions are broken, networks can shift to stronger hashes. There is no free lunch, as objects may need to be rehashed, or links duplicated. But ensuring that tools built do not assume a pre-defined length of hash digest means tools that work with today's hash functions will also work with tomorrows longer hash functions too. As of this writing, IPFS nodes _must_ support: @@ -85,12 +71,9 @@ sha3 ``` -## 3. The Stack +# 3. The Stack -IPFS has a stack of modular protocols. Each layer may have multiple -implementations, all in different modules. This spec will only address the -interfaces between the layers, and briefly mention possible implementations. -Details are left to the other specs. +IPFS has a stack of modular protocols. Each layer may have multiple implementations, all in different modules. This spec will only address the interfaces between the layers, and briefly mention possible implementations. Details are left to the other specs. IPFS has five layers: @@ -104,10 +87,9 @@ IPFS has five layers: These are briefly described bottom-up. -### [3.1 Network](network) +## [3.1 Network](network) -The **network** provides point-to-point transports (reliable and unreliable) -between any two IPFS nodes in the network. It handles: +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 - supports multiple transports - TCP, SCTP, UTP, ... - supports encryption, signing, or clear communcations @@ -115,44 +97,34 @@ between any two IPFS nodes in the network. It handles: See more in the [network spec](https://github.com/ipfs/specs/tree/master/libp2p). -### [3.2 Routing -- finding peers and data](routing) +## [3.2 Routing -- finding peers and data](routing) The IPFS **Routing** layer serves two important purposes: - **peer routing** -- to find other nodes - **content routing** -- to find data published to ipfs -The Routing Sytem is an interface that is satisfied by various kinds -of implementations. For example: +The Routing Sytem is an interface that is satisfied by various kinds of implementations. For example: -- **DHTs:** perhaps the most common, DHTs can be used to create a semi- - persistent routing record distributed cache in the network. -- **mdns:** used to find services advertised locally. `mdns` (or `dnssd`) - is a local discovery service. We will be using it. -- **snr:** supernode routing is a delegated routing system: it delegates - to one of a set of supernodes. This is roughly like federated routing. +- **DHTs:** perhaps the most common, DHTs can be used to create a semi-persistent routing record distributed cache in the network. +- **mdns:** used to find services advertised locally. `mdns` (or `dnssd`) is a local discovery service. We will be using it. +- **snr:** supernode routing is a delegated routing system: it delegates to one of a set of supernodes. This is roughly like federated routing. - **dns:** ipfs routing could even happen over dns. See more in the [routing spec](https://github.com/ipfs/specs/tree/master/libp2p). -### [3.3 Block Exchange -- transfering content-addressed data](exchange) +## [3.3 Block Exchange -- transfering content-addressed data](exchange) -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. +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. -The Block Exchange is an interface that is satisfied by various kinds -of implementations. For example: +The Block Exchange is an interface that is satisfied by various kinds of implementations. For example: - **Bitswap:** our main protocol for exchanging data. It is a generalization 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](../merkledag) -[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** 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: @@ -169,10 +141,7 @@ message MDagNode { } ``` -The merkledag is the "thin waist" of authenticated datastructures. -It is a minimal set of information needed to represent + transfer arbitrary -authenticated datastructures. More complex datastructures are implemented -on top of the merkledag, such as: +The merkledag is the "thin waist" of authenticated datastructures. It is a minimal set of information needed to represent + transfer arbitrary authenticated datastructures. More complex datastructures are implemented on top of the merkledag, such as: - **git** and other version control systems - **bitcoin** and other blockchains @@ -180,7 +149,7 @@ on top of the merkledag, such as: See more in the merkledag spec (TODO). -### [3.4.1 Merkledag Paths](../merkledag) +## [3.4.1 Merkledag Paths](../merkledag) The merkledag is enough to resolve paths: @@ -196,55 +165,36 @@ See more in the path resolution spec (TODO). ![](../media/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). +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). The IPFS **naming** layer -- or IPNS -- handles the creation of: - mutable pointers to objects - human-readable names -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. +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). +# [4. Applications and Datastructures -- on top of IPFS]() +The stack described so far is enough to represent arbitrary datastructures and replicate them accross the internet. It is also enough to build and deploy decentralized websites. -## [4. Applications and Datastructures -- on top of IPFS]() - -The stack described so far is enough to represent arbitrary datastructures -and replicate them accross 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. +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). +## [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: +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). - ## [5 Lifetime of fetching an object.]() Suppose we ask an IPFS node to retrieve @@ -263,14 +213,9 @@ 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: +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 @@ -279,10 +224,10 @@ design and implementation. Examples: * * * -### WIP Stack Dump: +# WIP Stack Dump: - How the layers fit together - How they call on each other - Mention all the ports - Mention all the interfaces with the user -- Mnetion gateways +- Mention gateways diff --git a/protocol/stack.png b/architecture/stack.png similarity index 100% rename from protocol/stack.png rename to architecture/stack.png diff --git a/bitswap/README.md b/bitswap/README.md new file mode 100644 index 000000000..7054c32ef --- /dev/null +++ b/bitswap/README.md @@ -0,0 +1,26 @@ +unixfs +====== + +Authors: + +Reviewers: + +> tl;dr; + +* * * + +# Abstract + +# Status of this spec + +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) + +# Organization of this document + +This spec is organized by chapters described on the *Table of contents* section. Each of the chapters can be found in its own file. + +# Table of contents + +- [1]() +- [2]() +- [...]() diff --git a/files/README.md b/files/README.md new file mode 100644 index 000000000..7054c32ef --- /dev/null +++ b/files/README.md @@ -0,0 +1,26 @@ +unixfs +====== + +Authors: + +Reviewers: + +> tl;dr; + +* * * + +# Abstract + +# Status of this spec + +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) + +# Organization of this document + +This spec is organized by chapters described on the *Table of contents* section. Each of the chapters can be found in its own file. + +# Table of contents + +- [1]() +- [2]() +- [...]() diff --git a/merkledag/ipld.md b/ipld/README.md similarity index 99% rename from merkledag/ipld.md rename to ipld/README.md index ade9b6429..c620587e5 100644 --- a/merkledag/ipld.md +++ b/ipld/README.md @@ -1,10 +1,13 @@ -# IPLD -- the "thin-waist" merkle dag format. +IPLD -- the "thin-waist" merkle dag format +========================================== + +![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) There are a variety of systems that use merkle-tree and hash-chain inspired datastructures (e.g. git, bittorrent, ipfs, tahoe-lafs, sfsro). IPLD defines: - **_merkle-links_**: the core unit of a merkle-graph - **_merkle-dag_**: any graphs whose edges are _merkle-links_. -- **_merkle-paths_**: unix-style paths for traversing _merkle-dags_ with _named merkle-links** +- **_merkle-paths_**: unix-style paths for traversing _merkle-dags_ with _named merkle-links_ - **IPLD Data Model**: a flexible, JSON-based data model for representing merkle-dags. - **IPLD Serialized Formats**: a set of formats in which IPLD objects can be represented, for example JSON, CBOR, CSON, YAML, Protobuf, XML, RDF, etc. - **IPLD Canonical Format**: a deterministic description on a serialized format that ensures the same _logical_ object is always serialized to _the exact same sequence of bits_. This is critical for merkle-linking, and all cryptographic applications. diff --git a/merkledag/ipld-compat-protobuf.md b/ipld/ipld-compat-protobuf.md similarity index 100% rename from merkledag/ipld-compat-protobuf.md rename to ipld/ipld-compat-protobuf.md diff --git a/records/README.md b/iprs-interplanetary-record-system/README.md similarity index 100% rename from records/README.md rename to iprs-interplanetary-record-system/README.md diff --git a/libp2p/README.md b/libp2p/README.md index 24260f81e..f4e50d9d9 100644 --- a/libp2p/README.md +++ b/libp2p/README.md @@ -23,7 +23,7 @@ This document defines the spec implemented in `libp2p`. # Status of this spec -> **This spec is a Work In Progress (WIP).** +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) # Organization of this document diff --git a/modules/components/components.001.jpg b/media-artifacts/components/components.001.jpg similarity index 100% rename from modules/components/components.001.jpg rename to media-artifacts/components/components.001.jpg diff --git a/modules/components/components.002.jpg b/media-artifacts/components/components.002.jpg similarity index 100% rename from modules/components/components.002.jpg rename to media-artifacts/components/components.002.jpg diff --git a/modules/components/components.003.jpg b/media-artifacts/components/components.003.jpg similarity index 100% rename from modules/components/components.003.jpg rename to media-artifacts/components/components.003.jpg diff --git a/modules/components/components.004.jpg b/media-artifacts/components/components.004.jpg similarity index 100% rename from modules/components/components.004.jpg rename to media-artifacts/components/components.004.jpg diff --git a/modules/components/components.005.jpg b/media-artifacts/components/components.005.jpg similarity index 100% rename from modules/components/components.005.jpg rename to media-artifacts/components/components.005.jpg diff --git a/modules/components/components.key b/media-artifacts/components/components.key similarity index 100% rename from modules/components/components.key rename to media-artifacts/components/components.key diff --git a/media/ipfs-resolve/ipfs-resolve.gif b/media-artifacts/ipfs-resolve/ipfs-resolve.gif similarity index 100% rename from media/ipfs-resolve/ipfs-resolve.gif rename to media-artifacts/ipfs-resolve/ipfs-resolve.gif diff --git a/media/ipfs-resolve/resolve-gif.001.jpg b/media-artifacts/ipfs-resolve/resolve-gif.001.jpg similarity index 100% rename from media/ipfs-resolve/resolve-gif.001.jpg rename to media-artifacts/ipfs-resolve/resolve-gif.001.jpg diff --git a/media/ipfs-resolve/resolve-gif.002.jpg b/media-artifacts/ipfs-resolve/resolve-gif.002.jpg similarity index 100% rename from media/ipfs-resolve/resolve-gif.002.jpg rename to media-artifacts/ipfs-resolve/resolve-gif.002.jpg diff --git a/media/ipfs-resolve/resolve-gif.003.jpg b/media-artifacts/ipfs-resolve/resolve-gif.003.jpg similarity index 100% rename from media/ipfs-resolve/resolve-gif.003.jpg rename to media-artifacts/ipfs-resolve/resolve-gif.003.jpg diff --git a/media/ipfs-resolve/resolve-gif.004.jpg b/media-artifacts/ipfs-resolve/resolve-gif.004.jpg similarity index 100% rename from media/ipfs-resolve/resolve-gif.004.jpg rename to media-artifacts/ipfs-resolve/resolve-gif.004.jpg diff --git a/media/ipfs-resolve/resolve-gif.005.jpg b/media-artifacts/ipfs-resolve/resolve-gif.005.jpg similarity index 100% rename from media/ipfs-resolve/resolve-gif.005.jpg rename to media-artifacts/ipfs-resolve/resolve-gif.005.jpg diff --git a/media/ipfs-resolve/resolve-gif.006.jpg b/media-artifacts/ipfs-resolve/resolve-gif.006.jpg similarity index 100% rename from media/ipfs-resolve/resolve-gif.006.jpg rename to media-artifacts/ipfs-resolve/resolve-gif.006.jpg diff --git a/media/ipfs-resolve/resolve-gif.007.jpg b/media-artifacts/ipfs-resolve/resolve-gif.007.jpg similarity index 100% rename from media/ipfs-resolve/resolve-gif.007.jpg rename to media-artifacts/ipfs-resolve/resolve-gif.007.jpg diff --git a/media/ipfs-resolve/resolve-gif.008.jpg b/media-artifacts/ipfs-resolve/resolve-gif.008.jpg similarity index 100% rename from media/ipfs-resolve/resolve-gif.008.jpg rename to media-artifacts/ipfs-resolve/resolve-gif.008.jpg diff --git a/ipfs-splash.png b/media-artifacts/ipfs-splash-lg.png similarity index 100% rename from ipfs-splash.png rename to media-artifacts/ipfs-splash-lg.png diff --git a/media-artifacts/ipfs-splash.png b/media-artifacts/ipfs-splash.png new file mode 100644 index 000000000..9ca92016f Binary files /dev/null and b/media-artifacts/ipfs-splash.png differ diff --git a/media/spec.key b/media-artifacts/spec.key similarity index 100% rename from media/spec.key rename to media-artifacts/spec.key diff --git a/overviews/README.md b/overviews/README.md index 127a26600..8e62d03a7 100644 --- a/overviews/README.md +++ b/overviews/README.md @@ -1,6 +1,9 @@ -# quick-overview docs +IPFS Overviews +============== These are simple documents meant to be provide quick overviews to various parts of the protocol. +Note that these are not specs, just guides to help understand the underlying systems of IPFS. + - [Implementing HTTP API bindings](implement-api-bindings.md) - [Implementing IPFS itself](implement-ipfs.md) diff --git a/modules/modules.go b/overviews/modules.go similarity index 100% rename from modules/modules.go rename to overviews/modules.go diff --git a/papers/ipfs.pdf b/papers/ipfs.pdf deleted file mode 100644 index eda0b8c15..000000000 Binary files a/papers/ipfs.pdf and /dev/null differ diff --git a/pdd/PDD-multistream.md b/pdd-protocol-driven-development/PDD-multistream.md similarity index 100% rename from pdd/PDD-multistream.md rename to pdd-protocol-driven-development/PDD-multistream.md diff --git a/pdd/README.md b/pdd-protocol-driven-development/README.md similarity index 97% rename from pdd/README.md rename to pdd-protocol-driven-development/README.md index d21cf7d0e..044ac3b89 100644 --- a/pdd/README.md +++ b/pdd-protocol-driven-development/README.md @@ -1,5 +1,7 @@ -RFC {protocol hash} - Protocol Driven Development -================================================= +Protocol Driven Development +=========================== + +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) # Abstract diff --git a/pdd/figs/multistream-1.monopic b/pdd-protocol-driven-development/figs/multistream-1.monopic similarity index 100% rename from pdd/figs/multistream-1.monopic rename to pdd-protocol-driven-development/figs/multistream-1.monopic diff --git a/pdd/figs/multistream-1.txt b/pdd-protocol-driven-development/figs/multistream-1.txt similarity index 100% rename from pdd/figs/multistream-1.txt rename to pdd-protocol-driven-development/figs/multistream-1.txt diff --git a/pdd/figs/multistream-2.monopic b/pdd-protocol-driven-development/figs/multistream-2.monopic similarity index 100% rename from pdd/figs/multistream-2.monopic rename to pdd-protocol-driven-development/figs/multistream-2.monopic diff --git a/pdd/figs/multistream-2.txt b/pdd-protocol-driven-development/figs/multistream-2.txt similarity index 100% rename from pdd/figs/multistream-2.txt rename to pdd-protocol-driven-development/figs/multistream-2.txt diff --git a/pdd/figs/multistream-3.monopic b/pdd-protocol-driven-development/figs/multistream-3.monopic similarity index 100% rename from pdd/figs/multistream-3.monopic rename to pdd-protocol-driven-development/figs/multistream-3.monopic diff --git a/pdd/figs/multistream-3.txt b/pdd-protocol-driven-development/figs/multistream-3.txt similarity index 100% rename from pdd/figs/multistream-3.txt rename to pdd-protocol-driven-development/figs/multistream-3.txt diff --git a/api/README.md b/public-api/README.md similarity index 92% rename from api/README.md rename to public-api/README.md index d3c9bb368..45bbf1d2d 100644 --- a/api/README.md +++ b/public-api/README.md @@ -19,7 +19,7 @@ This describes the [IPFS](https://ipfs.io/) APIs, including 'core', 'http' and ' # Status of this spec -> **This spec is a Work In Progress (WIP).** +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) # Organization of this document diff --git a/public-api/cli/README.md b/public-api/cli/README.md new file mode 100644 index 000000000..14e7c4f51 --- /dev/null +++ b/public-api/cli/README.md @@ -0,0 +1,102 @@ +CLI - Command Line Interface +============================ + +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) + +# Commands + +- ipfs +- ipfs add +- ipfs bitswap +- ipfs bitswap stat +- ipfs bitswap unwant +- ipfs bitswap wantlist +- ipfs block +- ipfs block get +- ipfs block put +- ipfs block stat +- ipfs bootstrap +- ipfs bootstrap add +- ipfs bootstrap list +- ipfs bootstrap rm +- ipfs cat +- ipfs commands +- ipfs config +- ipfs config edit +- ipfs config replace +- ipfs config show +- ipfs daemon +- ipfs dht +- ipfs dht findpeer +- ipfs dht findprovs +- ipfs dht get +- ipfs dht put +- ipfs dht query +- ipfs diag +- ipfs diag net +- ipfs diag sys +- ipfs dns +- ipfs files +- ipfs files ls +- ipfs files +- ipfs files cp +- ipfs files ls +- ipfs files mkdir +- ipfs files mv +- ipfs files read +- ipfs files rm +- ipfs files stat +- ipfs files write +- ipfs get +- ipfs id +- ipfs init +- ipfs log +- ipfs log level +- ipfs log tail +- ipfs ls +- ipfs mount +- ipfs name +- ipfs name publish +- ipfs name resolve +- ipfs object +- ipfs object data +- ipfs object get +- ipfs object links +- ipfs object new +- ipfs object patch +- ipfs object patch add-link +- ipfs object patch append-data +- ipfs object patch rm-link +- ipfs object patch set-data +- ipfs object put +- ipfs object stat +- ipfs pin +- ipfs pin add +- ipfs pin ls +- ipfs pin rm +- ipfs ping +- ipfs refs +- ipfs refs local +- ipfs repo +- ipfs repo gc +- ipfs resolve +- ipfs stats +- ipfs stats bw +- ipfs swarm +- ipfs swarm addrs +- ipfs swarm addrs local +- ipfs swarm connect +- ipfs swarm disconnect +- ipfs swarm filters +- ipfs swarm filters add +- ipfs swarm filters rm +- ipfs swarm peers +- ipfs tar +- ipfs tar add +- ipfs tar cat +- ipfs tour +- ipfs tour list +- ipfs tour next +- ipfs tour restart +- ipfs update +- ipfs version diff --git a/api/core/README.md b/public-api/core/README.md similarity index 88% rename from api/core/README.md rename to public-api/core/README.md index b94234893..a80a7b70e 100644 --- a/api/core/README.md +++ b/public-api/core/README.md @@ -1,6 +1,11 @@ -# Core API +Core API +======== -The `core` API is the programmatic interface for IPFS, it defines the method signatures. +> The `core` API is the programmatic interface for IPFS, it defines the method signatures. + +# Status + +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) ## Required for compliant IPFS implementation diff --git a/api/http/README.md b/public-api/http/README.md similarity index 58% rename from api/http/README.md rename to public-api/http/README.md index 7c3ea2164..74f279246 100644 --- a/api/http/README.md +++ b/public-api/http/README.md @@ -1,12 +1,15 @@ -> note: Currently, the HTTP API is a mix between a RPC and RESTful API - -# HTTP API +HTTP API +======== +# Status +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) # Interactive HTTP API documentation +> note: Currently, the HTTP API is a mix between a RPC and RESTful API + You can find a live version of the HTTP API on Apiary: - Apiary = http://docs.ipfs.apiary.io/# -- Repo - https://github.com/ipfs/api +- Repo - https://github.com/ipfs/http-api-spec diff --git a/api/internals/README.md b/public-api/internals/README.md similarity index 98% rename from api/internals/README.md rename to public-api/internals/README.md index 89679c335..856c11e40 100644 --- a/api/internals/README.md +++ b/public-api/internals/README.md @@ -1,4 +1,7 @@ -# Internals +Internals +========= + +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) In addition to the APIs exposed to developers (cli, http and core), the IPFS spec provides a set of specifications for the IPFS subsystems (AKA modules), providing a clean understanding of the components that have to be constructed for a full IPFS implementation or even a clear knowledge of how to make a partial implementation, without compromissing due to the interdependencies of these subsystems. diff --git a/api/internals/blocks.md b/public-api/internals/blocks.md similarity index 100% rename from api/internals/blocks.md rename to public-api/internals/blocks.md diff --git a/api/internals/merkle-dag.md b/public-api/internals/merkle-dag.md similarity index 100% rename from api/internals/merkle-dag.md rename to public-api/internals/merkle-dag.md diff --git a/unixfs/README.md b/unixfs/README.md new file mode 100644 index 000000000..7054c32ef --- /dev/null +++ b/unixfs/README.md @@ -0,0 +1,26 @@ +unixfs +====== + +Authors: + +Reviewers: + +> tl;dr; + +* * * + +# Abstract + +# Status of this spec + +![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) + +# Organization of this document + +This spec is organized by chapters described on the *Table of contents* section. Each of the chapters can be found in its own file. + +# Table of contents + +- [1]() +- [2]() +- [...]()