Hash-based commitments
A commitment is H(value ‖ salt). The value is bound but never leaked. Reveal proves you bound to that value and no other.
Everything the library actually does.
Two primitives, a strict safety posture, and a small toolchain — the fairness core that anti-MEV ordering, sealed-bid auctions, and verifiable-AI networks are built from. Every line below traces to the source. Nothing here is aspirational.
§ A
The commitment primitive
Eight selectable hash algorithms
SHA-256 (default), SHA-384, SHA-512, SHA3-256/384/512, BLAKE2b, BLAKE2s — configured per scheme instance.
CSPRNG salts by default
Salt defaults to secrets.token_bytes(32) — the OS CSPRNG. The random module is never imported in the runtime path.
Timing-safe reveal
Reveal comparison goes through hmac.compare_digest, not ==. No early-exit byte comparison to leak.
§ B
The zero-knowledge path
Schnorr proof of knowledge
Prove "I know the value behind this commitment" without revealing it. Opt in with CommitRevealScheme(use_zkp=True).
Non-interactive via Fiat–Shamir
The interactive Schnorr protocol is made non-interactive with a SHA-256 challenge. No verifier round-trip needed.
secp256k1 from scratch
The same curve as Bitcoin, hand-rolled in affine arithmetic: canonical parameters p, a=0, b=7, G, n. Point add, scalar multiply, 0x02/0x03 compression.
Consistency checks
verify_commitment_consistency ties the ZKP public key back to the (value, salt, commitment) triple.
§ C
Safety by construction
MD5 and SHA-1 rejected
The constructor raises SecurityError for md5 and sha1. Broken hashes cannot be selected even by accident.
Strict input validation
Anything outside the eight-algorithm allowlist raises ValidationError. Inputs are validated before use.
Audit module
commit_reveal/audit.py records scheme operations for review, separate from the cryptographic core.
Zero external dependencies
pyproject.toml lists only python ^3.8. Nothing transitive to typosquat, pin, or compromise mid-release.
§ D
Tooling
Secure CLI
commit-reveal-secure never writes plaintext to disk. Values are entered via getpass; commitment files are mode 0600.
Filename sanitization
Commitment names are sanitized before use as filenames — no directory traversal through the CLI.
Migration tool
A migration utility upgrades commitment files written by older formats; a deprecated legacy CLI stays for compatibility.
Typed, tested, formatted
mypy strict, Hypothesis property tests, Black formatting, and a clean Bandit scan on the latest release.
Next
See it wired into a protocol.
The use-cases walk through sealed-bid auctions, on-chain randomness, fair-launch ordering, and teaching. Or start from the quickstart.