multiformats
![CI](https://img.shields.io/github/workflow/status/multiformats/js-multiformats/test%20&%20maybe%20release/esm-migration?style=flat-square)
Interface for multihash, multicodec, multibase and CID
Table of contents
Install
$ npm i multiformats
Interfaces
This library defines common interfaces and low level building blocks for various interrelated multiformat technologies (multicodec, multihash, multibase, and CID). They can be used to implement custom base encoders / decoders / codecs, codec encoders /decoders and multihash hashers that comply to the interface that layers above assume.
This library provides implementations for most basics and many others can be found in linked repositories.
import { CID } from 'multiformats/cid'
import * as json from 'multiformats/codecs/json'
import { sha256 } from 'multiformats/hashes/sha2'
const bytes = json.encode({ hello: 'world' })
const hash = await sha256.digest(bytes)
const cid = CID.create(1, json.code, hash)
Creating Blocks
import * as Block from 'multiformats/block'
import * as codec from '@ipld/dag-cbor'
import { sha256 as hasher } from 'multiformats/hashes/sha2'
const value = { hello: 'world' }
let block = await Block.encode({ value, codec, hasher })
block.value
block.bytes
block.cid
block = await Block.decode({ bytes: block.bytes, codec, hasher })
block = await Block.create({ bytes: block.bytes, cid: block.cid, codec, hasher })
Multibase Encoders / Decoders / Codecs
CIDs can be serialized to string representation using multibase encoders that implement MultibaseEncoder
interface. This library provides quite a few implementations that can be imported:
import { base64 } from "multiformats/bases/base64"
cid.toString(base64.encoder)
Parsing CID string serialized CIDs requires multibase decoder that implements MultibaseDecoder
interface. This library provides a decoder for every encoder it provides:
CID.parse('mAYAEEiCTojlxqRTl6svwqNJRVM2jCcPBxy+7mRTUfGDzy2gViA', base64.decoder)
Dual of multibase encoder & decoder is defined as multibase codec and it exposes
them as encoder
and decoder
properties. For added convenience codecs also
implement MultibaseEncoder
and MultibaseDecoder
interfaces so they could be
used as either or both:
cid.toString(base64)
CID.parse(cid.toString(base64), base64)
Note: CID implementation comes bundled with base32
and base58btc
multibase codecs so that CIDs can be base serialized to (version specific)
default base encoding and parsed without having to supply base encoders/decoders:
const v1 = CID.parse('bagaaierasords4njcts6vs7qvdjfcvgnume4hqohf65zsfguprqphs3icwea')
v1.toString()
const v0 = CID.parse('QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n')
v0.toString()
v0.toV1().toString()
Multicodec Encoders / Decoders / Codecs
This library defines BlockEncoder
, BlockDecoder
and BlockCodec
interfaces.
Codec implementations should conform to the BlockCodec
interface which implements both BlockEncoder
and BlockDecoder
.
Here is an example implementation of JSON BlockCodec
.
export const { name, code, encode, decode } = {
name: 'json',
code: 0x0200,
encode: json => new TextEncoder().encode(JSON.stringify(json)),
decode: bytes => JSON.parse(new TextDecoder().decode(bytes))
}
Multihash Hashers
This library defines MultihashHasher
and MultihashDigest
interfaces and convinient function for implementing them:
import * as hasher from 'multiformats/hashes/hasher'
const sha256 = hasher.from({
name: 'sha2-256',
code: 0x12,
encode: (input) => new Uint8Array(crypto.createHash('sha256').update(input).digest())
})
const hash = await sha256.digest(json.encode({ hello: 'world' }))
CID.create(1, json.code, hash)
Traversal
This library contains higher-order functions for traversing graphs of data easily.
walk()
walks through the links in each block of a DAG calling a user-supplied loader function for each one, in depth-first order with no duplicate block visits. The loader should return a Block
object and can be used to inspect and collect block ordering for a full DAG walk. The loader should throw
on error, and return null
if a block should be skipped by walk()
.
import { walk } from 'multiformats/traversal'
import * as Block from 'multiformats/block'
import * as codec from 'multiformats/codecs/json'
import { sha256 as hasher } from 'multiformats/hashes/sha2'
const value = { hello: 'world' }
const block = await Block.encode({ value, codec, hasher })
const { cid } = block
console.log(cid)
const load = (cid, blocks) => async (cid) => {
blocks.push(cid)
return block
}
const blocks = []
await walk({ cid, load: load(cid, blocks) })
console.log(blocks)
Legacy interface
blockcodec-to-ipld-format
converts a multiformats BlockCodec
into an
interface-ipld-format
for use with the ipld
package. This can help bridge IPLD codecs implemented using the structure and interfaces defined here to existing code that assumes, or requires interface-ipld-format
. This bridge also includes the relevant TypeScript definitions.
Implementations
By default, no base encodings (other than base32 & base58btc), hash functions,
or codec implementations are exposed by multiformats
, you need to
import the ones you need yourself.
Multibase codecs
Other (less useful) bases implemented in multiformats/js-multiformats include: base2
, base8
, base10
, base36
and base256emoji
.
Multihash hashers
hashes | import | repo |
---|
sha2-256 , sha2-512 | multiformats/hashes/sha2 | multiformats/js-multiformats |
sha3-224 , sha3-256 , sha3-384 ,sha3-512 , shake-128 , shake-256 , keccak-224 , keccak-256 , keccak-384 , keccak-512 | @multiformats/sha3 | multiformats/js-sha3 |
identity | multiformats/hashes/identity | multiformats/js-multiformats |
murmur3-128 , murmur3-32 | @multiformats/murmur3 | multiformats/js-murmur3 |
blake2b-* , blake2s-* | @multiformats/blake2 | multiformats/js-blake2 |
IPLD codecs (multicodec)
License
Licensed under either of
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.