https://github.com/filip26/copper-multicodec
Multicodec & Multihash — encoder/decoder for self-describing data formats
https://github.com/filip26/copper-multicodec
multicodec multiformats multihash self-describing self-descriptive varint
Last synced: 3 months ago
JSON representation
Multicodec & Multihash — encoder/decoder for self-describing data formats
- Host: GitHub
- URL: https://github.com/filip26/copper-multicodec
- Owner: filip26
- License: apache-2.0
- Created: 2023-04-12T23:01:57.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2026-02-23T23:26:06.000Z (3 months ago)
- Last Synced: 2026-02-24T05:49:26.816Z (3 months ago)
- Topics: multicodec, multiformats, multihash, self-describing, self-descriptive, varint
- Language: Java
- Homepage: https://apicatalog.com
- Size: 562 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Copper Multicodec
A multicodec is a **self-describing** format: encoded data always begins
with a varint code that unambiguously identifies its format and intended
purpose.
This design eliminates guesswork, ensures interoperability between systems,
and makes it possible to introduce new formats without breaking existing
implementations.
The multicodec identifier tells applications how the data is meant to be
interpreted and processed.
Each multicodec is tagged to reflect its purpose - for example, hash functions (e.g., `sha2-256`), cryptography keys (e.g., `ed25519-pub`), and other identifiers used across the multiformats ecosystem.
Copper Multicodec is a Java library implementing
[Multicodec](https://github.com/multiformats/multicodec) and
[Multihash](https://github.com/multiformats/multihash), enabling efficient
encoding and decoding of self-describing data formats.
[](https://github.com/filip26/copper-multicodec/actions/workflows/java8-build.yml)
[](https://sonarcloud.io/summary/new_code?id=filip26_copper-multicodec)
[](https://javadoc.io/doc/com.apicatalog/copper-multicodec)
[](https://mvnrepository.com/artifact/com.apicatalog/copper-multicodec)
[](https://opensource.org/licenses/Apache-2.0)
## ✨ Features
- Static codec registry with predefined codecs for efficient access
- Direct static access to codecs without runtime lookups
- Support for custom codecs through extension
- Multihash compatibility
- Unsigned VarInt (UVarInt) encoding and decoding
- Zero third-party dependencies for a lightweight, self-contained implementation
## 💡 Examples
```java
/* 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 */
byte[] decoded = decoder.getCodec(encoded)
.map(codec -> codec.decode(encoded))
.orElseThrow(() -> new IllegalArgumentException("Unsupported codec."));
/* 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 */
byte[] encoded = registry.getCodec(code)
.map(codec -> codec.encode(input))
.orElseThrow(() -> new IllegalArgumentException("Unsupported codec."));
```
### Multihash
```java
/* 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 */
byte[] decoded = decoder.getCodec(encoded)
.map(codec -> codec.decode(encoded))
.orElseThrow(() -> new IllegalArgumentException("Unsupported multihash."));
/* or directly */
byte[] decoded = MultihashCodec.SHA2_384.decode(encoded);
/*
/* check if byte array is encoded with multihash codec */
if (MultihashCodec.SHA2_384.isEncoded(encoded)) {
var digestLength = MultihashCodec.SHA2_384.digestLength(encoded);
...
}
/* determine digest index */
var index = decoder.getCodec(encoded)
.map(Multihash.class::cast)
.mapToInt(codec -> encoded.length - codec.digestLength(encoded))
.orElseThrow(() -> new IllegalArgumentException("Unsupported multihash."));
```
## 📦 Installation
### Maven
To include Copper Multicodec in your project, add the following dependency to your `pom.xml`:
```xml
com.apicatalog
copper-multicodec
2.4.0
```
## 🛠️ LD-CLI
[LD-CLI](https://github.com/filip26/ld-cli) is a command-line utility for
working with multiformats including multibase, multicodec, and multihash,
as well as JSON-LD and related specifications.
It provides encoding, decoding, detection, analysis, and format conversion
features, making it useful for inspecting identifiers, testing content
addressing, and integrating multiformats into development workflows.
### Example
Detect and analyze a multibase + multicodec value
```bash
> ld-cli multicodec --analyze --multibase <<< 'z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu'
Multibase: name=base58btc, prefix=z, length=58 chars
Multicodec: name=ed25519-pub, code=237, varint=[0xED,0x01], tag=Key, status=Draft
Length: 32 bytes
```
## 🤝 Contributing
Contributions are welcome! Please submit a pull request.
### Building
Fork and clone the repository, then build with Maven:
```bash
> cd copper-multicodec
> mvn clean package
```
## 📚 Resources
- [Codecs Registry](https://github.com/multiformats/multicodec/blob/master/table.csv)
- [Multicodec](https://github.com/multiformats/multicodec)
- [Multihash](https://github.com/multiformats/multihash)
- [unsigned-varint](https://github.com/multiformats/unsigned-varint)
- [Copper Multibase](https://github.com/filip26/copper-multibase)
## 💼 Commercial Support
Commercial support and consulting are available.
For inquiries, please contact: filip26@gmail.com