A cryptuon library · v1.0.0 · MIT · Python ≥ 3.8
A commitment binds you to a value without revealing it; the reveal proves you bound to that value and no other. This library implements that primitive with the Python standard library and nothing else — eight hash algorithms, optional Schnorr ZKPs on secp256k1, and a CLI that never writes plaintext to disk.
Runtime deps in pyproject.toml
0
Only python = "^3.8". Nothing transitive.
Modules imported from stdlib
hashlib, hmac, secrets
Plus getpass for the secure CLI.
Curve, implemented from scratch
secp256k1
The same curve as Bitcoin. Hand-rolled affine arithmetic.
§ 1
Any protocol where one party must bind to a choice without yet announcing it. The two-phase structure removes the timing advantage that would otherwise let later participants peek at earlier ones.
Bidders publish a commitment to their bid during the commit phase; nobody, including the auctioneer, can read it. After the deadline, they reveal. The protocol guarantees no late-bidder could have peeked at earlier bids.
— docs/use-cases.md: "Auction Systems"
Multiple parties commit to seeds, then reveal them. The final randomness is a hash of all reveals. As long as one participant is honest, the outcome is uniform and unmanipulable.
— classical commit-reveal RNG
Order intents are committed during a sealed window, then revealed for matching. Front-runners cannot react to orders they have not yet seen, because they have not yet been revealed.
— MEV-resistant DEX design
Each voter commits to a choice, then reveals. With a ZKP, a voter can prove "my reveal matches my commitment" without re-publishing the ballot for everyone to see during verification.
— voting protocol literature
§ 2
Two primitives, both grounded in the source. There are no Pedersen commitments, no KZG, no Merkle commitments, no pairing-friendly curves — if you need those, see the comparison.
Primitive § 2.1
H(value || salt) where the hash is selectable per scheme instance. Salt is 32 random bytes from secrets.token_bytes by default. Reveal comparison uses hmac.compare_digest for constant-time equality.
sha256sha384sha512sha3_256sha3_384sha3_512blake2bblake2s Primitive § 2.2
Non-interactive Schnorr proof of knowledge of the secret derived from (value, salt), made non-interactive via the Fiat-Shamir heuristic with SHA-256 as the challenge hash. Proves "I committed to this value" without revealing it.
secp256k1 § 3
Lifted verbatim from the README.
The library refuses to start with an insecure hash — md5 and
sha1 raise SecurityError at
construction time.
Reveal is timing-safe: comparison goes through hmac.compare_digest,
not ==.
Listing 1 — basic commit and reveal
from commit_reveal import CommitRevealScheme
scheme = CommitRevealScheme()
# commit: share the commitment, keep the salt secret
commitment, salt = scheme.commit("my secret value")
# reveal: prove you committed to this value
assert scheme.reveal("my secret value", salt, commitment) # True
assert not scheme.reveal("wrong value", salt, commitment) # FalseListing 2 — with a Schnorr ZKP on secp256k1
scheme = CommitRevealScheme(use_zkp=True)
commitment, salt = scheme.commit("secret")
public_key, R_compressed, challenge, response = scheme.create_zkp_proof(
"secret", salt, commitment
)
# anyone can verify you know the secret — without learning it
assert scheme.verify_zkp_proof(
commitment, public_key, R_compressed, challenge, response
)Listing 3 — the secure CLI
# prompts via getpass; never echoes; never writes plaintext to disk
commit-reveal-secure commit my-secret
commit-reveal-secure reveal my-secret
commit-reveal-secure listTable 1
Configured per scheme instance through CommitRevealScheme(hash_algorithm=...).
Anything not in this table raises ValidationError;
md5 and sha1 raise
SecurityError.
| Identifier | Output length | Family | Notes |
|---|---|---|---|
| sha256 | 32 bytes | SHA-2 | Default; widely audited. |
| sha384 | 48 bytes | SHA-2 | |
| sha512 | 64 bytes | SHA-2 | Higher security margin. |
| sha3_256 | 32 bytes | SHA-3 / Keccak | NIST post-Merkle–Damgård family. |
| sha3_384 | 48 bytes | SHA-3 / Keccak | |
| sha3_512 | 64 bytes | SHA-3 / Keccak | |
| blake2b | 64 bytes | BLAKE2 | Fast on 64-bit platforms. |
| blake2s | 32 bytes | BLAKE2 | Fast on 32-bit / embedded. |
§ 4
One class, three pure-function methods for the commit-reveal core, three more for the ZKP path.
ZKP methods raise ValueError unless the scheme was
constructed with use_zkp=True.
class CommitRevealScheme:
def __init__(
self,
hash_algorithm: str = "sha256",
use_zkp: bool = False,
enable_audit: bool = True,
): ...
# commit-reveal core
def commit(value, salt=None) -> tuple[bytes, bytes]: ...
def reveal(value, salt, commitment) -> bool: ...
def verify(value, salt, commitment) -> bool: # alias of reveal
...
# Schnorr ZKP on secp256k1 (requires use_zkp=True)
def create_zkp_proof(value, salt, commitment) -> tuple: ...
def verify_zkp_proof(
commitment, public_key, R_compressed, challenge, response
) -> bool: ...
def verify_commitment_consistency(
value, salt, commitment, public_key
) -> bool: ...
# raised exceptions:
# ValidationError — invalid input
# SecurityError — insecure hash (md5, sha1) or unsafe operation¶ Colophon
Eight files under commit_reveal/, the longest of which is the
secp256k1 implementation. mypy strict. Hypothesis property tests. Black formatted. Bandit clean.