# Multihash

An Elixir implementation of the [multihash](https://github.com/multiformats/multihash) specification — a self-describing hash digest format.

A multihash wraps a raw hash digest with a varint-encoded codec identifier and digest length, making the hash algorithm unambiguously identifiable from the binary data alone. This library handles hashing content, encoding the result as a multihash, and decoding multihash binaries back into their components.

## Supported Hash Algorithms

| Algorithm | Multicodec Name |
|-----------|----------------|
| SHA-1 | `"sha1"` |
| SHA-256 | `"sha2-256"` |
| SHA-384 | `"sha2-384"` |
| SHA-512 | `"sha2-512"` |
| SHA3-224 | `"sha3-224"` |
| SHA3-256 | `"sha3-256"` |
| SHA3-384 | `"sha3-384"` |
| SHA3-512 | `"sha3-512"` |
| BLAKE2b-512 | `"blake2b-512"` |
| BLAKE2s-256 | `"blake2s-256"` |
| MD4 | `"md4"` |
| MD5 | `"md5"` |
| Identity (no-op) | `"identity"` |
| SHA-256 truncated (Filecoin) | `"sha2-256-trunc254-padded"` |

## Usage

### Encoding

Hash content and wrap the digest in multihash format:

```elixir
multihash = Multihash.encode!("hello world", "sha2-256")
# => <<18, 32, 185, 77, 39, ...>>
#    ^codec ^size ^--- digest ---
```

The `encode/2` variant returns `{:ok, binary}` or `:error`:

```elixir
{:ok, multihash} = Multihash.encode("hello world", "sha2-256")
```

### Decoding

Extract the algorithm name, digest size, and raw digest from a multihash binary:

```elixir
{algorithm, size, digest} = Multihash.decode(multihash)
# => {"sha2-256", 32, <<185, 77, 39, ...>>}
```

## Custom hash algorithms

The `Multihash.Algorithm` behaviour defines the contract for hash algorithm modules:

```elixir
defmodule MyApp.Blake3 do
  @behaviour Multihash.Algorithm

  @impl true
  def hash(data) when is_binary(data) do
    # ... your hashing logic, returns raw digest bytes ...
  end
end
```

The built-in `Multihash.Identity` and `Multihash.SHA256Trunc254Padded` modules implement this behaviour.

## Dependencies

This library depends on [multicodec](https://github.com/tyler-eon/multicodec) for codec prefix encoding.

## Part of the multiformats ecosystem

This library is one component of a family of Elixir multiformats libraries. For runtime codec registration and cross-component composition, see the [multicodec](https://github.com/tyler-eon/multicodec) project.