py-multihash ↔ go-multihash Feature Parity Analysis

[sumanjeet0012]

Feature Parity Analysis

Date: 2026-07-05
Python version analyzed: py-multihash v3.0.0
Go version analyzed: go-multihash (latest main branch)
Source: py-multihash · go-multihash

---

Table of Contents

1. Executive Summary
2. Architecture Comparison
3. Feature-by-Feature Gap Analysis
   • 3.1 Core Types & Data Structures
   • 3.2 Encoding & Decoding
   • 3.3 Hash Computation (Sum)
   • 3.4 Stream I/O
   • 3.5 MultihashSet
   • 3.6 Registry System
   • 3.7 Hash Function Coverage
   • 3.8 CLI Tool & Options Package
   • 3.9 Error Handling
   • 3.10 Testing & Benchmarks
4. Feature Matrix Summary
5. Phased Roadmap
   • Phase 1 – Critical Bug Fixes & Core API Gaps
   • Phase 2 – Registry Parity & Variable-Size Hashes
   • Phase 3 – Modular Architecture & Spec Compliance
   • Phase 4 – CLI Tool & Options Package
   • Phase 5 – Testing, Benchmarks & Polish
6. Appendix – Naming Inconsistencies Between Implementations

---

Executive Summary

The Python implementation (py-multihash) has made significant progress in v3.0.0 with rich features like MultihashSet, JSON serialization, stream read/write, SHAKE support, truncation, and an extensive Func enum covering 150+ hash codes. However, several important areas remain incomplete compared to the Go reference implementation:

Area	Status
Core encode/decode/sum	✅ Parity achieved
Stream hashing (sum_stream)	✅ Parity achieved
MultihashSet	⚠️ Missing Visit(), ForEach(), Len()
Registry system	⚠️ Missing RegisterVariableSize(), DefaultLengths map
Modular architecture	❌ Monolithic vs Go's core + register/* packages
CLI tool	❌ Entirely absent
opts package	❌ Entirely absent
Variable-length BLAKE3	❌ Fixed at 32 bytes (Go supports up to 128)
Keccak registration	❌ Defined in enum but NOT registered with hashers
Spec compliance tests	❌ No tests against official multicodec table / test vectors
Benchmarks	❌ None
Cast(), MHFromBytes(), NewReader()/NewWriter()	❌ Missing Go-style convenience APIs

---

Architecture Comparison

Go Architecture (Modular)

go-multihash/
├── core/
│   ├── magic.go          # Constants (IDENTITY, SHA1, SHA2_256, ...)
│   ├── registry.go       # Register(), RegisterVariableSize(), GetHasher(), DefaultLengths
│   └── errata.go         # identityMultihash, doubleSha256 helpers
├── register/
│   ├── all/              # Side-effect import: registers everything
│   ├── blake2/           # blake2b (8–512 bit) + blake2s-256
│   ├── blake3/           # blake3 (variable: 32–128 bytes)
│   ├── sha3/             # sha3-224/256/384/512, shake-128/256, keccak-256/512
│   ├── murmur3/          # murmur3-x64-64
│   ├── sha256/           # std sha256 (go1.21+)
│   └── miniosha256/      # simd sha256 (go <1.21)
├── opts/
│   ├── opts.go           # CLI Options struct, SetupFlags(), Check()
│   └── coding.go         # Encode/Decode for raw/hex/base58/base64
├── multihash/
│   └── main.go           # CLI binary
├── multihash.go          # Multihash type, Encode, Decode, Cast, names/codes maps
├── sum.go                # Sum(), SumStream()
├── io.go                 # Reader/Writer interfaces, NewReader/NewWriter
├── set.go                # Set type (Add, Has, Visit, ForEach, Remove, All)
└── registry.go           # Top-level re-exports of core.Register, core.GetHasher

Key design principle: The core package has zero transitive dependencies. Hash implementations live in separate register/* packages that users import only if needed (via side-effect imports _ "..."). This keeps binary sizes small.

Python Architecture (Monolithic)

py-multihash/
├── multihash/
│   ├── __init__.py       # Public API exports
│   ├── constants.py      # HASH_TABLE, HASH_CODES, CODE_HASHES, HASH_LENGTHS
│   ├── funcs.py          # Func enum, FuncReg, all hash wrapper classes
│   ├── multihash.py      # Multihash namedtuple, MultihashSet, encode/decode/sum/...
│   ├── exceptions.py     # Custom exception hierarchy
│   └── base58.py         # Bundled base58 implementation
├── tests/
│   ├── test_multihash.py
│   ├── test_funcs.py
│   └── test_new_features.py
└── pyproject.toml

Key difference: All hash implementations (blake3, mmh3, hashlib) are loaded eagerly at import time. There is no lazy-loading or opt-in registration.

---

Feature-by-Feature Gap Analysis

3.1 Core Types & Data Structures

Feature	Go	Python	Gap?
Multihash type (byte slice / tuple)	Multihash []byte	Multihash namedtuple	No
DecodedMultihash struct	DecodedMultihash{Code, Name, Length, Digest}	Multihash namedtuple (same fields)	No
HexString() / String()	Methods on Multihash	to_hex_string() standalone + Multihash.encode('hex')	No
B58String()	Method on Multihash	to_b58_string() standalone + Multihash.encode('base58')	No
FromHexString()	FromHexString(s string)	from_hex_string(s)	No
FromB58String()	FromB58String(s string)	from_b58_string(s)	No
Cast(buf []byte)	Validates bytes and returns Multihash type	❌ No equivalent	YES
MHFromBytes(buf []byte)	Returns (bytesRead, Multihash, err) for parsing from a larger buffer	❌ No equivalent	YES
is_valid()	Implicit (use Cast)	is_valid(multihash)	No (Python has extra)
get_prefix()	Implicit (slice [:2])	get_prefix(multihash)	No (Python has extra)
is_app_code()	Not present	is_app_code(code)	No (Python has extra)
coerce_code()	Not present	coerce_code(hash_fn)	No (Python has extra)
to_json() / from_json()	Not present	✅ Present	No (Python has extra)
verify()	Not present	✅ Multihash.verify(data)	No (Python has extra)

3.2 Encoding & Decoding

Feature	Go	Python	Gap?
Encode(buf, code)	✅	✅ encode(digest, code, length)	No
EncodeName(buf, name)	✅	Implicitly via encode(digest, name)	Minor (explicit function)
Decode(buf)	✅ Returns *DecodedMultihash	✅ decode(multihash) returns Multihash	No
Varint encoding	Uses go-varint library	Uses varint library	No
Multi-byte varint codes	Handles codes > 127 correctly (e.g., 0x1012)	⚠️ get_prefix() hardcodes [:2] which breaks for multi-byte varints	YES
Digest length > 127 bytes	Supported via multi-byte varint lengths	⚠️ get_prefix() issue; decode() should handle but get_prefix() won't	YES

3.3 Hash Computation (Sum)

Feature	Go	Python	Gap?
Sum(data, code, length)	✅ length=-1 for default	✅ sum(data, code, length)	No
SumStream(reader, code, length)	✅	✅ sum_stream(stream, code, length)	No
Truncation support	✅ sum[:length]	✅ With TruncationError	No
Identity hash length validation	✅ Requires length == len(data)	❌ No such check	YES
ErrLenTooLarge on oversized request	✅ Returns specific error	⚠️ Raises TruncationError (different semantics)	Minor

3.4 Stream I/O

Feature	Go	Python	Gap?
Multihash.read(stream)	Not present (Go uses ReadMultihash)	✅ Multihash.read(stream)	No (Python has extra)
Multihash.write(stream)	Not present (Go uses WriteMultihash)	✅ Multihash.write(stream)	No (Python has extra)
Reader interface / NewReader()	✅ Wraps io.Reader with ReadMultihash()	❌ No wrapper class	YES
Writer interface / NewWriter()	✅ Wraps io.Writer with WriteMultihash()	❌ No wrapper class	YES
ReadMultihash() on reader	✅ Reads varint code+length+digest from stream	Handled by Multihash.read()	No (different API)
WriteMultihash() on writer	✅ Writes multihash bytes	Handled by Multihash.write()	No (different API)
Evil reader / partial reads handling	✅ Tested with byte-at-a-time reader	❌ Not tested	YES

3.5 MultihashSet

Feature	Go Set	Python MultihashSet	Gap?
NewSet() / constructor	NewSet()	MultihashSet(iterable)	No
Add(m)	✅	✅ Add() + add()	No
Has(m)	✅	✅ Has() + __contains__	No
Remove(m)	✅	✅ Remove() + remove() + discard()	No
All()	✅ Returns []Multihash	✅ Returns list[Multihash]	No
Len()	✅	❌ Only __len__()	YES (Go API)
Visit(m) → bool	✅ Add only if not present, returns True if new	❌ Missing	YES
ForEach(f func(Multihash) error)	✅ Iterate with error-propagating callback	❌ Missing	YES
Set operations (union, intersection, ...)	❌	✅	No (Python has extra)
Type safety (Multihash only)	Implicit (string keys)	✅ Explicit TypeError checks	No (Python is better)

3.6 Registry System

Feature	Go core	Python FuncReg	Gap?
Register(code, factory)	✅	✅ register(code, name, hash_name, hash_new)	No
RegisterVariableSize(code, factory(sizeHint))	✅ Factory receives size hint (-1 for default)	❌ Missing	YES
GetHasher(code)	✅ Returns hash.Hash	✅ hash_from_func(func)	No
GetVariableHasher(code, sizeHint)	✅ Returns hasher with size hint	❌ Missing	YES
DefaultLengths map	✅ map[uint64]int	❌ Missing (has HASH_LENGTHS in constants but not in registry)	YES
Unregister(code)	Not present	✅ unregister(code) for app codes	No (Python has extra)
Reset()	Not present	✅ reset()	No (Python has extra)
func_from_hash(obj)	Not present	✅	No (Python has extra)
Modular registration packages	✅ register/blake2, register/sha3, etc.	❌ All in one funcs.py	YES
Auto-registration of stdlib hashes	✅ In core.init()	✅ In FuncReg.reset()	No

3.7 Hash Function Coverage

Hash functions available in BOTH implementations:

Hash Function	Code	Go	Python	Notes
identity	0x00	✅	✅
sha1	0x11	✅	✅
sha2-256	0x12	✅	✅
sha2-512	0x13	✅	✅
sha3-512	0x14	✅	✅
sha3-384	0x15	✅	✅
sha3-256	0x16	✅	✅
sha3-224	0x17	✅	✅
shake-128	0x18	✅	✅
shake-256	0x19	✅	✅
blake2b-8 to blake2b-512	0xB201–0xB240	✅	✅
blake2s-256	0xB260	✅	✅
md5	0xD5	✅	✅
dbl-sha2-256	0x56	✅	✅
sha2-256-trunc254-padded	0x1012	✅	✅
blake3	0x1E	✅	✅	⚠️ See variable-length gap below

Hash functions in Python but NOT (fully) in Go:

Hash Function	Code	Python	Go	Notes
blake2s-8 to blake2s-248	0xB241–0xB25F	✅ All 32 variants	❌ Only 0xB260 (256-bit)	Python is MORE complete
murmur3-32	0x23	✅	❌
md4	0xD4	✅ (conditional)	❌
ripemd-128/160/256/320	0x1052–0x1055	✅ (conditional)	❌
sha2-224	0x1013	✅	✅	Both have it
sha2-384	0x20	✅	✅	Both have it
sha2-512-224	0x1014	✅	✅	Both have it
sha2-512-256	0x1015	✅	✅	Both have it
keccak-224	0x1A	⚠️ In enum, NOT registered	⚠️ In Names, NOT registered	Both incomplete
keccak-256	0x1B	⚠️ In enum, NOT registered	✅ Registered	Python gap
keccak-384	0x1C	⚠️ In enum, NOT registered	⚠️ In Names, NOT registered	Both incomplete
keccak-512	0x1D	⚠️ In enum, NOT registered	✅ Registered	Python gap

Hash functions in Go but NOT in Python:

Hash Function	Code	Go	Python	Notes
x11	0x1100	⚠️ In Names only (no impl)	❌ Not in constants
poseidon-bls12_381-a2-fc1	0xB401	⚠️ In Names only (no impl)	❌ Not in constants

Variable-length BLAKE3 gap:

Feature	Go	Python
BLAKE3 default (32 bytes)	✅	✅
BLAKE3 64 bytes	✅	❌
BLAKE3 128 bytes	✅	❌
BLAKE3 max size	128 bytes	Fixed at 32
ErrLenTooLarge for > 128	✅	❌

murmur3 naming & behavior inconsistency:

Aspect	Go	Python
Code 0x22 name	"murmur3-x64-64"	"murmur3-128"
Code 0x22 output size	8 bytes (truncated to 64-bit)	16 bytes (full 128-bit)
Code 0x23	Not present	"murmur3-32" (4 bytes)
Underlying library	spaolacci/murmur3	mmh3

⚠️ Critical: The Go implementation at code 0x22 produces an 8-byte digest using murmur3's 64-bit variant, while the multicodec table specifies murmur3-128 (32-byte output). The Python implementation uses mmh3.hash128 producing 16 bytes. Neither matches the multicodec table's stated 0x20 (32-byte) length. This is a known multicodec spec ambiguity.

3.8 CLI Tool & Options Package

Feature	Go	Python	Gap?
CLI binary (multihash)	✅ Full-featured CLI tool	❌ Missing	YES
Hash a file	✅ multihash file.txt	❌	YES
Hash stdin	✅ cat file | multihash	❌	YES
Check checksum	✅ --check <hash>	❌	YES
Algorithm flag	✅ -a sha2-256	❌	YES
Encoding flag	✅ -e hex/base58/base64/raw	❌	YES
Length/truncation flag	✅ -l 256 (bits)	❌	YES
Quiet mode	✅ -q	❌	YES
opts.Options struct	✅	❌	YES
opts.SetupFlags()	✅	❌	YES
opts.Decode(encoding, str)	✅ raw/hex/base58/base64	❌	YES
opts.Encode(encoding, mh)	✅ raw/hex/base58/base64	❌	YES
opts.Check(reader, multihash)	✅	❌	YES

3.9 Error Handling

Go Error	Python Equivalent	Gap?
ErrUnknownCode	UnsupportedCodeError	No
ErrTooShort	ValueError("multihash must be greater than 3 bytes")	Minor (not a dedicated type)
ErrTooLong	Not present	YES
ErrLenNotSupported	Not present	YES
ErrInvalidMultihash	InvalidMultihashError	No
ErrVarintBufferShort	ValueError("Invalid varint provided")	Minor
ErrVarintTooLong	ValueError("Invalid varint provided")	Minor
ErrInconsistentLen (typed struct)	ValueError("Inconsistent multihash length")	Minor (no typed error)
ErrSumNotSupported	HashComputationError	No
ErrLenTooLarge	TruncationError	Minor (different name)
—	MultihashError (base)	Python has extra

3.10 Testing & Benchmarks

Feature	Go	Python	Gap?
Unit tests for encode/decode	✅	✅	No
Sum test vectors	✅ Extensive (40+ cases)	⚠️ Basic	YES (more vectors needed)
Spec compliance: multicodec table CSV	✅ TestSpec	❌	YES
Spec compliance: test_vectors CSV	✅ TestSpecVectors	❌	YES
Set tests	✅	✅	No
IO reader/writer tests	✅ (including evil reader)	✅	⚠️ Missing evil reader test
Allocation tests	✅ mustNotAllocateMore	❌ N/A (Python)	N/A
Benchmark tests	✅ BenchmarkEncode, BenchmarkDecode, BenchmarkCast, BenchmarkSum, BenchmarkBlake2B, BenchmarkSumAllLarge	❌	YES
Varint edge cases	✅ Overflow, underflow, non-minimal	⚠️ Only basic invalid varint	YES
Identity hash length edge cases	✅ TestSmallerLengthHashID	❌	YES

---

Feature Matrix Summary

#	Feature	Priority	Status
1	Cast() function	Medium	❌ Missing
2	MHFromBytes() function	Medium	❌ Missing
3	NewReader() / NewWriter() wrappers	Medium	❌ Missing
4	MultihashSet.Visit()	Low	❌ Missing
5	MultihashSet.ForEach()	Low	❌ Missing
6	MultihashSet.Len()	Low	❌ Missing (has __len__)
7	RegisterVariableSize()	High	❌ Missing
8	GetVariableHasher()	High	❌ Missing
9	DefaultLengths map in registry	High	❌ Missing
10	Variable-length BLAKE3 (32–128 bytes)	High	❌ Fixed at 32
11	Keccak-256 / Keccak-512 registration	High	❌ Not registered
12	Keccak-224 / Keccak-384 registration	Medium	❌ Not registered (Go also missing)
13	Identity hash length validation in Sum	Medium	❌ Missing
14	get_prefix() fix for multi-byte varints	High	⚠️ Broken
15	CLI tool (multihash binary)	Medium	❌ Missing
16	opts package	Medium	❌ Missing
17	Modular registration packages	Medium	❌ Missing
18	Core sub-package (zero transitive deps)	Medium	❌ Missing
19	Spec compliance tests (multicodec table)	High	❌ Missing
20	Spec compliance test vectors	High	❌ Missing
21	Benchmark tests	Low	❌ Missing
22	Varint edge-case tests	Low	❌ Missing
23	murmur3 naming alignment	Low	⚠️ Inconsistent
24	Error type parity	Low	⚠️ Partial

---

Phased Roadmap

Phase 1 – Critical Bug Fixes & Core API Gaps

Goal: Fix bugs that break correctness and add missing Go-style core APIs.

Estimated effort: 1–2 weeks

1.1 Fix get_prefix() for multi-byte varint codes ⚠️ BUG

# Current (broken for codes > 127):
def get_prefix(multihash):
    if is_valid(multihash):
        return multihash[:2]  # Hardcoded 2 bytes!

Fix: Use varint decoding to determine the actual prefix length (code varint + length varint).

def get_prefix(multihash):
    if not is_valid(multihash):
        raise ValueError("invalid multihash")
    buf = BytesIO(multihash)
    code_bytes = len(varint.encode(varint.decode_stream(BytesIO(multihash))))
    buf = BytesIO(multihash[code_bytes:])
    length_bytes = len(varint.encode(varint.decode_stream(buf)))
    return multihash[:code_bytes + length_bytes]

1.2 Add Cast() function

Go-compatible buffer-to-Multihash casting with validation:

def cast(buf: bytes) -> Multihash:
    """Cast a buffer to a Multihash, validating its structure."""
    return decode(buf)

1.3 Add MHFromBytes() function

def from_bytes(buf: bytes) -> tuple[int, Multihash]:
    """Read a multihash from the beginning of buf, returning (bytes_consumed, multihash)."""

1.4 Register Keccak-256 and Keccak-512 hashers

These are defined in the Func enum but have no registered hash implementation. Add wrappers using pysha3 or pycryptodome:

# In funcs.py _optional_func_data:
(Func.keccak_256, "keccak256", Keccak256Hash),  # using pycryptodome or pysha3
(Func.keccak_512, "keccak512", Keccak512Hash),

1.5 Add Identity hash length validation in sum()

Go enforces that identity hash length must equal data length:

if code == Func.identity and length is not None and length != -1:
    if length != len(data):
        raise ValueError(f"identity hash length must equal data length: {length} != {len(data)}")

1.6 Add NewReader() / NewWriter() wrapper classes

class MultihashReader:
    """Wraps a binary stream with ReadMultihash() capability."""
    def __init__(self, stream: BinaryIO): ...
    def read_multihash(self) -> Multihash: ...

class MultihashWriter:
    """Wraps a binary stream with WriteMultihash() capability."""
    def __init__(self, stream: BinaryIO): ...
    def write_multihash(self, mh: Multihash) -> int: ...

---

Phase 2 – Registry Parity & Variable-Size Hashes

Goal: Bring the registry system to full parity with Go's core/registry.go.

Estimated effort: 1–2 weeks

2.1 Add RegisterVariableSize() to FuncReg

@classmethod
def register_variable_size(cls, code: int, name: str, 
                           factory: Callable[[int], tuple[HashObj | None, bool]]) -> None:
    """Register a variable-size hasher factory.
    
    The factory receives a size hint:
    - -1 means "use default length"
    - >= 0 means "try to produce at least this many bytes"
    
    Returns (hasher, success) tuple.
    """

2.2 Add GetVariableHasher() to FuncReg

@classmethod
def hash_from_func_with_size(cls, func: Func | int, size_hint: int = -1):
    """Return a hasher with size hint support."""

2.3 Add DefaultLengths map to FuncReg

class FuncReg:
    default_lengths: ClassVar[dict[int, int]] = {}

Populated automatically when functions are registered.

2.4 Variable-length BLAKE3 support

Update Blake3Hash to accept a length parameter (32–128 bytes) and integrate with the variable-size registry:

class Blake3Hash:
    def __init__(self, length: int = 32):
        self._hasher = blake3.blake3()
        self._length = length
        self.digest_size = length
    
    def digest(self) -> bytes:
        return self._hasher.digest(self._length)

Register with RegisterVariableSize:

FuncReg.register_variable_size(
    Func.blake3, "blake3",
    lambda size: (Blake3Hash(size if size > 0 else 32), size <= 128)
)

2.5 Add Keccak-224 and Keccak-384 registration (if library available)

Using pycryptodome's Crypto.Hash.keccak:

(Func.keccak_224, "keccak224", Keccak224Hash),
(Func.keccak_384, "keccak384", Keccak384Hash),

---

Phase 3 – Modular Architecture & Spec Compliance

Goal: Restructure the package for modularity and add spec compliance verification.

Estimated effort: 2–3 weeks

3.1 Create multihash.core sub-package

Extract constants and registry into a minimal sub-package with zero external dependencies:

multihash/
├── core/
│   ├── __init__.py
│   ├── constants.py    # HASH_TABLE, HASH_CODES, CODE_HASHES
│   ├── magic.py        # Code constants (IDENTITY, SHA1, ...)
│   └── registry.py     # FuncReg, Register, RegisterVariableSize
├── register/
│   ├── __init__.py
│   ├── stdlib.py       # hashlib-based: sha1, sha2-*, md5, identity
│   ├── blake2.py       # blake2b, blake2s variants
│   ├── blake3.py       # blake3 (requires blake3 package)
│   ├── sha3.py         # sha3-*, shake-*, keccak-*
│   ├── murmur3.py      # murmur3-128, murmur3-32 (requires mmh3)
│   └── all.py          # Import everything
├── __init__.py         # Re-export public API
├── multihash.py        # Multihash type, encode/decode/sum
├── exceptions.py
└── base58.py

3.2 Add lazy-loading for optional hash libraries

Currently blake3 and mmh3 are hard dependencies. Move them to optional extras:

[project.optional-dependencies]
blake3 = ["blake3>=0.3.0,<2.0"]
murmur3 = ["mmh3>=3.0.0,<6.0"]
all = ["blake3>=0.3.0,<2.0", "mmh3>=3.0.0,<6.0"]

3.3 Add spec compliance tests

Test 1: Validate HASH_CODES against the official multicodec table.csv:

def test_spec_multicodec_table():
    """Every code in Codes map must exist in the multicodec table with matching name."""

Test 2: Run official test vectors:

def test_spec_vectors():
    """Verify Sum() output matches test_cases.csv for each algorithm/bits/input."""

3.4 Add version.json

{
  "version": "3.0.0"
}

---

Phase 4 – CLI Tool & Options Package

Goal: Provide a CLI tool and options-parsing package matching Go's multihash binary.

Estimated effort: 1–2 weeks

4.1 Create multihash.opts module

# multihash/opts.py
class Options:
    encoding: str = "base58"     # raw, hex, base58, base64
    algorithm: str = "sha2-256"
    algorithm_code: int = 0x12
    length: int = -1

def setup_flags(parser: argparse.ArgumentParser) -> Options: ...
def decode(encoding: str, digest: str) -> bytes: ...
def encode(encoding: str, hash: bytes) -> str: ...
def check(stream: BinaryIO, expected: Multihash, opts: Options) -> bool: ...

4.2 Create CLI entry point

# multihash/cli.py  (or multihash/__main__.py)
def main():
    """CLI: multihash [-a algorithm] [-e encoding] [-l length] [--check hash] [FILE]"""

Register as console script in pyproject.toml:

[project.scripts]
multihash = "multihash.cli:main"

4.3 CLI Features to implement

• Hash a file: multihash file.txt
• Hash stdin: cat file | multihash
• Algorithm selection: -a sha2-256, -a blake3
• Encoding output: -e hex, -e base58, -e base64
• Truncation: -l 128 (in bits)
• Check checksum: --check <multihash>
• Quiet mode: -q
• Help: --help

---

Phase 5 – Testing, Benchmarks & Polish

Goal: Comprehensive test coverage, benchmarks, and API polish.

Estimated effort: 1–2 weeks

5.1 Expand Sum test vectors

Port all 40+ Go test cases from sum_test.go to Python:

SUM_TEST_CASES = [
    (Func.identity, 3, b"foo", "0003666f6f"),
    (Func.sha2_256, -1, b"foo", "12202c26b46b..."),
    (Func.blake3, 64, b"foo", "1e4004e0bb..."),
    (Func.blake3, 128, b"foo", "1e800104e0..."),
    (Func.blake3, 129, b"foo", None, ErrLenTooLarge),  # Expected error
    ...
]

5.2 Add varint edge-case tests

• Overflow (> 64-bit varint)
• Underflow (truncated varint)
• Non-minimal encoding

5.3 Add identity hash edge-case tests

• Identity with length == len(data) → success
• Identity with length < len(data) → error
• Identity with length = -1 → success

5.4 Add evil reader test

Test that Multihash.read() works correctly when the stream returns data one byte at a time.

5.5 Add benchmark suite

# tests/benchmarks/test_benchmarks.py
import pytest

@pytest.mark.benchmark
def test_bench_encode(benchmark): ...

@pytest.mark.benchmark  
def test_bench_decode(benchmark): ...

@pytest.mark.benchmark
def test_bench_sum_sha256(benchmark): ...

@pytest.mark.benchmark
def test_bench_sum_blake2b(benchmark): ...

5.6 Complete MultihashSet Go API parity

class MultihashSet:
    def Len(self) -> int: ...
    def Visit(self, mh: Multihash) -> bool:
        """Add only if not present. Returns True if newly added."""
        if mh in self._set:
            return False
        self._set.add(mh)
        return True
    def ForEach(self, f: Callable[[Multihash], Exception | None]) -> Exception | None:
        """Iterate with callback; stop and return on first error."""
        for mh in self._set:
            err = f(mh)
            if err is not None:
                return err
        return None

5.7 Add error type parity

Add missing specific error types:

class TooShortError(MultihashError): ...
class TooLongError(MultihashError): ...
class InconsistentLengthError(MultihashError):
    def __init__(self, expected, found): ...
class LengthTooLargeError(MultihashError): ...

5.8 Add deprecated aliases (backward compat with older Python multihash libs)

# In __init__.py
ID = Func.identity  # Deprecated: use IDENTITY

---

Appendix – Naming Inconsistencies Between Implementations

These naming differences exist between Go and Python and should be documented (not necessarily "fixed", as changing them would be a breaking change):

Aspect	Go	Python	Multicodec Table
Code 0x22	murmur3-x64-64 (8 bytes)	murmur3-128 (16 bytes)	murmur3-128 (32 bytes!)
Code 0x23	Not present	murmur3-32 (4 bytes)	murmur3-32
Identity alias	IDENTITY + deprecated ID	Func.identity	id
SHA3-512 alias	SHA3 = SHA3_512	No alias	sha3-512
Murmur3 deprecated alias	MURMUR3 = MURMUR3X64_64	No alias	—

Recommendation: Document these differences clearly in the Python README. Consider adding Func.murmur3_x64_64 as an alias for Func.murmur3_128 to improve interoperability, but keep the output at 16 bytes (128-bit) since that's what the multicodec table specifies.

---

Summary Timeline

Phase	Focus	Effort	Key Deliverables
Phase 1	Bug Fixes & Core APIs	1–2 weeks	Fix get_prefix(), add Cast(), MHFromBytes(), Keccak registration, Reader/Writer wrappers
Phase 2	Registry Parity	1–2 weeks	RegisterVariableSize(), DefaultLengths, variable-length BLAKE3, Keccak-224/384
Phase 3	Modular Architecture	2–3 weeks	core sub-package, lazy-loading, spec compliance tests, optional deps
Phase 4	CLI & Options	1–2 weeks	multihash CLI tool, opts module, encoding utilities
Phase 5	Testing & Polish	1–2 weeks	Full test vectors, benchmarks, Visit()/ForEach(), error parity

Total estimated effort: 6–11 weeks

Each phase is independently shippable and provides incremental value. Phase 1 is the highest priority as it fixes correctness bugs. Phase 3 is the most impactful for long-term maintainability.