multiformats
The main repository for discussing multiformats
Multiformats is a set of self-describing protocol values.
These values are foundational in that they are low-level building blocks for both data and network layers of the composable protocols making up IPFS, IPLD, libp2p, and many other decentralized data systems.
This repository's issues and pull requests are currently the primary venue for the coordination between the various registries making up the group, each of which is separately being hardened as specifications and public, formal registries over time.
See [contributing.md][./contributing.md] for more details on governance and process.
Current Registries
Currently, we have the following formats, each of which corresponds to a specification and a registry. More formats are being discussed and may be added over time, but the following are the mature ones to date:
| Repo | Maintainer | Status | IETF |
|---|---|---|---|
| multiaddr | @lgierth | stable | WIP |
| multibase | @jbenet | stable | W3C CCG |
| multicodec | @jbenet | stable | TBD |
| multihash | @jbenet | stable | W3C CCG |
| multikey | @protocol | WIP | TBD |
See the project directory, below, for implementations and other related repositories.
Table of Contents
Background
Every choice in computing has a tradeoff. This includes formats, algorithms, encodings, and so on. And even with a great deal of planning, decisions may lead to breaking changes down the road, or to solutions which are no longer optimal. Allowing systems to evolve and grow is important.
Multiformats is a collection of protocols which aim to future-proof systems, today. They do this mainly by allowing data to be self-describable. This allows interoperability, protocol agility, and helps us avoid various forms of lock-in. Currently, these interlocking protocols (both works in progress and implemented) cover the following areas:
- multiaddr: network addresses
- multibase: base encodings
- multicodec: serialization codes
- multihash: cryptographic hashes
- multikey: cryptographic keys and artifacts
Several of the multiformats are stable, and work on the others is ongoing. Implementers and refiners of the drafts of any one of these registries or their tooling are welcome to contribute, without needing to understand deeply or track progress on the others. Across these otherwise quite different use-cases and mechanisms, the self-describing aspects of the protocols have a few stipulations in common:
- the "prefixes" use to self-describe a value must be inline with the value (not passed out-of-band, in function calls, implicit choices, or documentation);
- they must be compact and have a binary-packed representation (as opposed to a sparser encoding) or they will hinder performance;
- they must have a human-readable representation.
A note on the word Multiformats
Multiformats is the name for the community (and the "organization" in GitHub's access control model), but multiformats can also be used to refer to protocols; for instance, in the sentence "Use one of the multiformats".
Formats is interchangeable with protocols, here, as each format is designed in tandem with one or more protocols which handle those self-describing values centrally.
We try to capitalize Multiformats when it refers to the organization.
Project Directory
Below, a list of all of the projects in the Multiformats organization is listed.
Maintainers are the active leads for each project, even if the specification is still under construction. Their responsibilities are to make sure that issues and pull requests are attended to in a timely manner, and general upkeep. If you have questions about a repository, or need feedback, please contact them as appropriate. If any of the specifications defining these formats are formalized and finalized in a standards body, these maintainers may continue on as Registrars of the table of entries which can keep growing after stabilizing the syntax and tooling interfaces.
Implementations
As well as specifications, we also have some implementations checked into and maintained through the GitHub organization. Checking in implementation code here is not a requirement of listing here, unless maintainership is being transferred.
Multiaddr Implementations
| Repo | Captain |
|---|---|
| cs-multiaddress | @tabrath |
| go-multiaddr | @whyrusleeping |
| go-multiaddr-net | @whyrusleeping |
| go-multiaddr-dns | @lgierth |
| java-multiaddr | @ianopolous |
| js-multiaddr | @diasdavid |
| rust-multiaddr | @dignifiedquire |
| SwiftMultiaddr | @NeoTeo |
| py-multiaddr |
Multihash Implementations
| Repo | Captain | Note |
|---|---|---|
| c-multihash | @Kubuxu | Only parsing and encoding, and not hashing. |
| c-multihashing | @Kubuxu | |
| cs-multihash | @tabrath | |
| clj-multihash | @greglook | |
| ex_multihash | @zabirauf | |
| go-multihash | @Kubuxu | |
| haskell-multihash | @LukeHoersten | |
| java-multihash | @ianopolous | |
| hash-overlay (Java 9) | @jamespedwards42 | |
| js-multihash | @diasdavid | |
| js-multihashing-async | @dignifiedquire | |
| js-multihashing | @diasdavid | |
| MultiHash.Net (fork) | @MCGPPeters | |
| php-multihash | @Fil | |
| ruby-multihash | @kyledrake | |
| rust-multihash | @dignifiedquire | |
| scala-multihash | @parkan | |
| SwiftMultihash | @NeoTeo |
Multicodec Implementations
| Repo | Captain | Note |
|---|---|---|
| clj-multicodec | @greglook | |
| go-multicodec-packed | @whyrusleeping | |
| go-multicodec | @jbenet | |
| js-multicodec | @diasdavid |
Other Implementations
| Repo | Captain | Note |
|---|---|---|
| cs-multibase | @tabrath | |
| go-multibase | @whyrusleeping | |
| go-multigram | @lgierth | |
| go-multistream | @whyrusleeping | |
| java-multibase | @ianopolous | |
| js-multibase | @diasdavid | |
| js-multistream-select | @diasdavid |
Other Repositories
| Repo | Captain | Note |
|---|---|---|
| clj-varint | @ekroon | |
| ma-pipe | @jbenet | |
| multiformats | @RichardLitt | This repository |
| specs | @nicola | Specification work regarding multihash, multiaddr, and others. WIP. |
| unsigned-varint | @jbenet | unsigned varint in use in multiformat specs. WIP. |
| clj-varint | @ekroon | Simple wrapper around Bazel VarInt code. |
| website | @victorbjelkholm | The multiformats website |
Maintainers
Contribute
Check out our contributing document for more information on how we work, and about contributing in general.
License
This repository is only for documents. All of these are licensed under the CC-BY-SA 3.0 license © 2016 Protocol Labs Inc. Any code is under a MIT © 2016 Protocol Labs Inc.