multi-hash

Rust implementation of the Multihash specification for self-describing cryptographic hash digests.

Multihash is a self-describing format that pairs a hash algorithm identifier (multicodec tag) with the raw digest bytes, enabling systems to switch hash algorithms without breaking compatibility. This crate provides 23 supported hash algorithms, type-safe wrappers, serde integration, and multibase encoding via the multi-util crate stack.

Table of Contents

• Features
• Install
• Supported Algorithms
• Usage
  • Computing a Hash
  • Building from an Existing Digest
  • Encoding and Decoding
  • Base Encoding
  • Converting to EncodedMultihash
  • Serde Integration
  • Error Handling
  • Type-Safe Newtypes
• Testing
• Feature Flags
• Security
• Maintainers
• Contribute
• License

Features

• 23 Hash Algorithms: SHA1, SHA2 family, SHA3 family, Blake2, Blake3, MD5, RIPEMD
• Builder Pattern: Fluent API for creating multihashes from raw data or existing digests
• Multibase Encoding: EncodedMultihash smart pointer for base-encoded string representation via multi-util's BaseEncoded
• Serde Support: JSON (human-readable → codec name string) and binary (varint bytes) serialization (feature-gated)
• Binary Round-Trip: Into<Vec<u8>> and TryFrom<&[u8]> for raw wire format
• Type-Safe Newtypes: HashDigest and AlgorithmId wrappers
• Zero Unsafe Code: #![deny(unsafe_code)] enforced at compile time
• Thread-Safe: All types are Send + Sync

Install

Add this to your Cargo.toml:

[dependencies]
multi-hash = "1.0"

To disable serde support:

[dependencies]
multi-hash = { version = "1.0", default-features = false }

MSRV: Rust 1.85 (Edition 2024)

Supported Algorithms

Secure algorithms (recommended for cryptographic use)

See SAFE_HASH_CODECS for the constant array.

Legacy algorithms (for compatibility)

See HASH_CODECS for the constant array of all 23 supported codecs.

Usage

Computing a Hash

use multi_hash::Builder;
use multi_codec::Codec;

// Compute a SHA2-256 hash
let multihash = Builder::new_from_bytes(Codec::Sha2256, b"hello world")
    .unwrap()
    .try_build()
    .unwrap();

assert_eq!(multihash.codec(), Codec::Sha2256);
assert_eq!(multihash.as_ref().len(), 32); // SHA2-256 outputs 32 bytes

Building from an Existing Digest

If you already have a hash digest (e.g. from an external hashing library):

use multi_hash::Builder;
use multi_codec::Codec;

let digest = vec![0u8; 32]; // pre-computed SHA2-256 digest
let multihash = Builder::new(Codec::Sha2256)
    .with_hash(digest)
    .try_build()
    .unwrap();

Encoding and Decoding

Multihashes encode as codec || length || hash (varint-prefixed):

use multi_hash::{Builder, Multihash};
use multi_codec::Codec;

let mh1 = Builder::new_from_bytes(Codec::Sha2256, b"data")
    .unwrap()
    .try_build()
    .unwrap();

// Encode to binary (varint wire format)
let bytes: Vec<u8> = mh1.clone().into();

// Decode from binary
let mh2 = Multihash::try_from(bytes.as_ref()).unwrap();
assert_eq!(mh1, mh2);

Base Encoding

Use try_build_encoded() with a specific base to get an EncodedMultihash that supports Display and TryFrom<&str>:

use multi_hash::Builder;
use multi_codec::Codec;
use multi_base::Base;

let encoded = Builder::new_from_bytes(Codec::Sha2256, b"data")
    .unwrap()
    .with_base_encoding(Base::Base58Btc)
    .try_build_encoded()
    .unwrap();

// Display as a base58-encoded multihash string
let base58_string = encoded.to_string();
println!("Multihash: {}", base58_string);

// Parse back from string
use multi_hash::EncodedMultihash;
let decoded: EncodedMultihash = EncodedMultihash::try_from(base58_string.as_str()).unwrap();
assert_eq!(encoded, decoded);

Converting to EncodedMultihash

Existing Multihash objects can be converted to EncodedMultihash using .into() (defaults to Base16Lower) or EncodedMultihash::new() with a chosen base:

use multi_hash::{Builder, EncodedMultihash};
use multi_base::Base;
use multi_codec::Codec;

let mh = Builder::new_from_bytes(Codec::Sha3384, b"for great justice, move every zig!")
    .unwrap()
    .try_build()
    .unwrap();

// Uses the preferred encoding for multihash objects: Base16Lower
let encoded_mh1: EncodedMultihash = mh.clone().into();

// Or choose a specific base encoding
let encoded_mh2: EncodedMultihash = EncodedMultihash::new(Base::Base32Upper, mh);

Serde Integration

With the serde feature (enabled by default), Multihash implements Serialize and Deserialize — strings in human-readable formats, varint bytes in binary formats:

use multi_hash::Builder;
use multi_codec::Codec;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug, PartialEq)]
struct DocumentHash {
    hash: multi_hash::Multihash,
    timestamp: u64,
}

let doc = DocumentHash {
    hash: Builder::new_from_bytes(Codec::Sha2256, b"document content")
        .unwrap()
        .try_build()
        .unwrap(),
    timestamp: 1234567890,
};

// Serialize to JSON (human-readable → codec name + hex digest)
let json = serde_json::to_string(&doc).unwrap();
println!("{}", json);

// Deserialize from JSON
let deserialized: DocumentHash = serde_json::from_str(&json).unwrap();
assert_eq!(doc, deserialized);

Error Handling

All conversion and builder errors return Result with a structured Error enum:

use multi_hash::{Builder, Error};
use multi_codec::Codec;

// Handle unsupported algorithms
match Builder::new_from_bytes(Codec::Identity, b"data") {
    Err(Error::UnsupportedHash { codec }) => {
        eprintln!("Algorithm {:?} not supported", codec);
    }
    Err(e) => eprintln!("Other error: {}", e),
    Ok(_) => unreachable!(),
}

// Handle missing hash data
match Builder::new(Codec::Sha2256).try_build() {
    Err(Error::MissingHash) => {
        eprintln!("Must call with_hash() before build()");
    }
    Err(e) => eprintln!("Other error: {}", e),
    Ok(_) => unreachable!(),
}

Type-Safe Newtypes

For additional type safety, use the newtype wrappers:

use multi_hash::types::{HashDigest, AlgorithmId};
use multi_codec::Codec;

// Type-safe hash digest
let digest = HashDigest::new(vec![0u8; 32]);
assert_eq!(digest.len(), 32);
assert_eq!(digest.as_bytes().len(), 32);

// Type-safe algorithm identifier
let algo = AlgorithmId::new(Codec::Sha2256);
assert_eq!(algo.codec(), Codec::Sha2256);
assert_eq!(algo.name(), "sha2-256");
assert_eq!(algo.code(), 0x12);

Testing

The crate has 110 tests across unit, integration, property-based, security, and doc-test suites:

# Run all tests
cargo test --all-features

# Run specific test suites
cargo test --test edge_case_tests
cargo test --test integration_tests
cargo test --test proptest_tests
cargo test --test security_tests

# Run benchmarks
cargo bench

Linting and formatting:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings

Feature Flags

• serde (default): Enables serde serialization/deserialization. When enabled, Multihash implements Serialize and Deserialize — codec name and hex digest in human-readable formats, varint bytes in binary formats.

Disabling Default Features

[dependencies]
multi-hash = { version = "1.0", default-features = false }

Security

• #![deny(unsafe_code)] enforced at compile time
• All errors return Result types — no panics on invalid input
• All types are Send + Sync with no shared mutable state
• Hash computation uses vetted cryptographic libraries from the RustCrypto ecosystem

Maintainers

This repo: @dgrantham.

Contribute

Contributions welcome! Please check out the issues.

Development Guidelines

• Run cargo fmt before committing
• Run cargo clippy -- -D warnings to check for issues
• Add tests for new features
• Update documentation for API changes
• Run the full test suite: cargo test --all-features

License

Apache-2.0 © Cryptid Technologies