eocarragain/specs

Technical specifications for the IPFS protocol stack

Specifications

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.

Table of Contents

• Work In Progress
• Specs
  • High level Architecture of IPFS
  • IPLD
  • libp2p
    • IPRS
  • bitswap
  • Files API and MFS
  • Public API (CLI, HTTP and Core)
  • DEX - Importers and Exporters
  • keychain
  • keystore
  • Repo
  • Protocol Driven Development
• Contribute
• License

Work In Progress

Specs are not finished yet. We use the following tag system to identify their state:

• - this spec is a work-in-progress, it is likely not even complete.
• - this spec is a rough draft and will likely change substantially.
• - this spec is believed to be close to final. Minor changes only.
• - this spec is likely to improve, but not change fundamentally.
• - 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.

Note that, as in many IPFS repositories, most of the work is happening in the issues or in active pull requests. Go take a look!

Specs

The specs contained in this repository are:

IPFS Protocol:

• protocol - the top-level spec and the stack
• overviews - quick overviews of the various parts of IPFS

Networking layer:

• 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

Records, Naming and Record Systems:

• IPRS - InterPlanetary Record System
• IPNS - InterPlanetary Naming System

Data Structures and formats:

• IPLD - InterPlanetary Linked Data.
• unixfs
• multiformats
  • multihash - self-describing hash digest format.
  • multiaddr - self-describing addressing format.
  • multicodec - self-describing protocol/encoding streams (note: a file is a stream).
  • multistream - multistream is a format -- or simple protocol -- for disambiguating, and layering streams. It is extremely simple.

Files / Mutable File System:

• Files Impl and API - Virtual File System interface, unix like, on top of the MerkleDAG

Block Exchanges:

• bitswap - BitTorrent-inspired exchange

Specific Internal Components:

• Blocks and Block Service
• DAG and DAG Service
• Data Importing
• Repo - IPFS node local repository spec

Public APIs:

• Core API - IPFS programatic interface
• HTTP API - IPFS HTTP API specification
• CLI - Command Line Interface

Key Management:

• KeyStore - Key management on IPFS
• KeyChain - Distribution of cryptographic Artificats

Other/related/included:

• PDD - Protocol Driven Development

Contribute

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.

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

License

TBD. See ipfs#137.