Skip to content

Latest commit

 

History

History
139 lines (96 loc) · 4.49 KB

README.md

File metadata and controls

139 lines (96 loc) · 4.49 KB
Raw

Copper Multicodec

A Java implementation of Multicodec and Multihash.

Java 8 CI Quality Gate Status Maven Central License

Features

  • static codecs registry
    • no lookups for a codec when encoding
    • direct static access to codecs
    • configurable set of codecs to support when decoding
  • Multihash support
  • Unsigned VarInt support
  • no 3rd party dependencies

Examples

/* encode an input as P-521 public key */
byte[] encoded = KeyCodec.P521_PUBLIC_KEY.encode(input);

/* encode an input as an identity */
byte[] encoded = MultihashCodec.IDENTITY.encode(input);

/* get decoder instance initialized with all supported codecs */
var decoder = MulticodecDecoder.getInstance();

/* get custom decoder initialized with codecs tagged as key and hash */
var decoder = MulticodecDecoder.getInstance(Tag.Key, Tag.Hash);

/* get custom decoder initialized with custom codec set  */
var decoder = MulticodecDecoder.getInstance(codecs...);

/* decode */
byte[] decoded = decoder.decode(encoded);

/* or check if encoding is supported  */
Multicodec codec = decoder.getCodec(encoded).orElseThrow(() -> new IllegalArgumentException("Unsupported codec."));
byte[] decoded = codec.decode(encoded);

/* or directly when only one codec is supported */
byte[] decoded = KeyCodec.P521_PUBLIC_KEY.decode(encoded);

/* check if byte array is encoded with a codec */
if (KeyCodec.P521_PUBLIC_KEY.isEncoded(encoded)) {
  ...
}

/* create a custom codec */
var codec = Multicodec.of(name, tag, code);

/* get registry instance initialized with all supported codecs */
var registry = MulticodecRegistry.getInstance();

/* get custom registry initialized with codecs tagged as key and hash */
var registry = MulticodecRegistry.getInstance(Tag.Key, Tag.Hash);

/* get custom registry initialized with custom codec set  */
var registry = MulticodecRegistry.getInstance(codecs...);

/* get codec */
var codec = registry.getCodec(code).orElseThrow(() -> new IllegalArgumentException("Unsupported codec."));
byte[] encoded = codec.encode(input);

Multihash

/* get multihash decoder initialized with all multihash codecs */
var decoder = MulticodecDecoder.getInstance(Tag.Multihash);

/* decode; digest size is checked and removed */
byte[] decoded = decoder.decode(encoded);

/* or check if supported  */
var codec = decoder.get(encoded).orElseThrow(() -> new IllegalArgumentException("Unsupported multihash."));
byte[] decoded = codec.decode(encoded);

/* or directly */
byte[] decoded = MultihashCodec.SHA2_384.decode(encoded);

/* 

/* check if byte array is encoded with multihash codec */
if (MultihashCodec.SHA2_384.isEncoded(encoded)) {
  ...
}

/* get registry initialized with all multihash codecs */
var registry = MulticodecRegistry.getInstance(Tag.Multihash);

/* encode an input as multihash */
var codec = registry.get(code).orElseThrow(() -> new IllegalArgumentException("Unsupported multihash."));
byte[] encoded = codec.encode(input);

Installation

Maven

<dependency>
    <groupId>com.apicatalog</groupId>
    <artifactId>copper-multicodec</artifactId>
    <version>1.1.0</version>
</dependency>

Documentation

Contributing

All PR's welcome!

Building

Fork and clone the project repository.

> cd copper-multicodec
> mvn clean package

Resources