Developers

Implementing

Guide for writing a compatible ForgeHash-B3 v1 implementation. See the developers hub for the full path. Matching test vectors is not production safety.

Goal

Produce bit-identical outputs for the official v1 vectors in implementers/v1/. If your digests match all four vectors (and parallel/sequential agree when you add lanes), your implementation is v1-compatible.

What you must implement

Follow SPECIFICATION.md exactly. Do not substitute SHA-256, Argon2, or unkeyed BLAKE3 where derive-key / XOF / keyed-hash is required.

Use the checklist in implementers/v1/CHECKLIST.md.

Minimum building blocks:

1. Little-endian helpers (LE32, LE64)
2. BLAKE3: derive-key (ForgeHash/v1/seed), XOF expand, plain hash, keyed hash (pepper), XOF output
3. FastRange = high 64 bits of 128-bit x * n
4. ForgeMix (8 rounds, row/column/diagonal, perm 73x+19 mod 128, feed-forward)
5. Memory fill with 4 slices/pass, pass-0 init blocks 0–1, later-pass XOR overwrite
6. Reference selection + completed-slice cross-lane rules
7. Finalization: lane samples + 64-block groups + group-root + root + output XOF
8. Canonical encoding $forgeh$v=1$m=...,t=...,p=...$salt$hash

Suggested port order

Implementer pack

Machine-readable pack:

implementers/v1/manifest.json
implementers/v1/vectors/*.json

Each vector JSON includes password/salt hex, parameters, seed, group root, hash, encoded string, and sampled intermediates. Load manifest.json, then assert every listed field.

Common pitfalls

• Ordinary BLAKE3 hash instead of derive-key for the seed
• Forgetting domain prefixes (ForgeHash/v1/...)
• Big-endian word IO
• Accepting padded Base64 or reordered m,t,p
• Cross-lane reads from the current incomplete slice
• Finalizing from lane-last-blocks only (must include group digests)
• Unicode-normalizing passwords in the core
• Silently truncating long passwords

Parallelism

p is lane count, not “use p OS threads”. A multithreaded port must barrier after every slice and match the sequential digests exactly.

Compatibility claim

An implementation may claim ForgeHash-B3 v1 compatible only if:

1. All official vectors pass bit-exactly
2. Parser rejects the non-canonical examples in the specification
3. Verification uses constant-time comparison
4. Docs state the algorithm is experimental / not production-ready

ForgeHash-X sandbox

Separate track: custom ForgeX sponge, encoding $forgehx$v=0$. Use SPECIFICATION_X.md, checklist implementers/x0/CHECKLIST.md, and X Vectors. Do not mix B3 and X digests or parsers.