Compact self-describing codecs. Save space by using predefined multicodec tables.

Go to file

Hector Sanjuan c629b58216 Add codecs for IPFS Cluster It would be useful for Cluster to have our own block codes so that we can identify ownership of blocks from their CIDs.		2019-02-06 12:50:58 +00:00
.travis.yml	ci: add validator script	2019-01-18 13:54:51 +00:00
LICENSE	Standardized Readme	2016-08-23 00:19:24 -04:00
README.md	move multibase prefixes out of this table	2018-12-18 18:25:57 +01:00
table.csv	Add codecs for IPFS Cluster	2019-02-06 12:50:58 +00:00
validate.py	Use '#!/usr/bin/env python3' vs. fixed path '/usr/bin/python3'	2019-01-24 13:02:28 -08:00

README.md

multicodec

Compact self-describing codecs. Save space by using predefined multicodec tables.

Motivation
How does it work? - Protocol Description
Multicodec table
Implementations
FAQ
Maintainers
Contribute
License

Motivation

Multistreams are self-describing protocol/encoding streams. Multicodec uses an agreed-upon "protocol table". It is designed for use in short strings, such as keys or identifiers (i.e CID).

Protocol Description - How does the protocol work?

multicodec is a self-describing multiformat, it wraps other formats with a tiny bit of self-description. A multicodec identifier is a varint.

A chunk of data identified by multicodec will look like this:

<multicodec><encoded-data>
# To reduce the cognitive load, we sometimes might write the same line as:
<mc><data>

Another useful scenario is when using the multicodec as part of the keys to access data, example:

# suppose we have a value and a key to retrieve it
"<key>" -> <value>

# we can use multicodec with the key to know what codec the value is in
"<mc><key>" -> <value>

It is worth noting that multicodec works very well in conjunction with multihash and multiaddr, as you can prefix those values with a multicodec to tell what they are.

MulticodecProtocol Tables

Multicodec uses "protocol tables" to agree upon the mapping from one multicodec code. These tables can be application specific, though -- like with other multiformats -- we will keep a globally agreed upon table with common protocols and formats.

Multicodec table

The full table can be found at table.csv inside this repo.

Adding new multicodecs to the table

The process to add a new multicodec to the table is the following:

1. Fork this repo
1. Update the table with the value you want to add
1. Submit a Pull Request

This "first come, first assign" policy is a way to assign codes as they are most needed, without increasing the size of the table (and therefore the size of the multicodecs) too rapidly.

Implementations

Multicodec Path, also known as `multistream`

Multicodec defines a table for the most common data serialization formats that can be expanded overtime or per application bases, however, in order for two programs to talk with each other, they need to know before hand which table or table extension is being used.

In order to enable self descriptive data formats or streams that can be dynamically described, without the formal set of adding a binary packed code to a table, we have multistream, so that applications can adopt multiple data formats for their streams and with that create different protocols.

FAQ

Q. Why?

Because multistream is too long for identifiers. We needed something shorter.

Q. Why varints?

So that we have no limitation on protocols.

Q. What kind of varints?

An Most Significant Bit unsigned varint, as defined by the multiformats/unsigned-varint.

Q. Don't we have to agree on a table of protocols?

Yes, but we already have to agree on what protocols themselves are, so this is not so hard. The table even leaves some room for custom protocol paths, or you can use your own tables. The standard table is only for common things.

Q. Where did multibase go?

For a period of time, the multibase prefixes lived in this table. However, multibase prefixes are symbols that may map to multiple underlying byte representations (that may overlap with byte sequences used for other multicodecs). Including them in a table for binary/byte identifiers lead to more confusion than it solved.

You can still find the table in multibase.csv.

Contribute

Contributions welcome. Please check out the issues.

Check out our contributing document for more information on how we work, and about contributing in general. Please be aware that all interactions related to multiformats are subject to the IPFS Code of Conduct.

Small note: If editing the README, please conform to the standard-readme specification.