commit-reveal

Cryptographic commit-reveal schemes with zero-knowledge proofs. Pure Python. Zero dependencies.

---

Highlights

• Multi-algorithm commitments — SHA-256, SHA-512, SHA-3, BLAKE2b/2s
• Schnorr zero-knowledge proofs on secp256k1 (same curve as Bitcoin)
• Tamper-evident audit trail with cryptographic integrity verification
• Secure CLI that never stores plaintext values on disk
• Zero external dependencies — stdlib only
• 90%+ test coverage, mypy strict, property-based testing with Hypothesis

Installation

pip install commit-reveal

Or with Poetry:

poetry add commit-reveal

Quick Start

Basic commit-reveal

from commit_reveal import CommitRevealScheme

scheme = CommitRevealScheme()

# Commit phase — share the commitment, keep the salt secret
commitment, salt = scheme.commit("my secret value")

# Reveal phase — prove you committed to this value
assert scheme.reveal("my secret value", salt, commitment)  # True
assert not scheme.reveal("wrong value", salt, commitment)   # False

With zero-knowledge proofs

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
)

CLI

# Commit to a value (prompts securely, no echo)
commit-reveal-secure commit my-secret

# Verify the value later
commit-reveal-secure reveal my-secret

# List stored commitments
commit-reveal-secure list

Supported Hash Algorithms

Algorithm	Output	Notes
sha256	32 bytes	Default, widely compatible
sha384	48 bytes
sha512	64 bytes	Higher security margin
sha3_256	32 bytes	NIST post-quantum family
sha3_384	48 bytes
sha3_512	64 bytes
blake2b	64 bytes	Fast on 64-bit platforms
blake2s	32 bytes	Fast on 32-bit platforms

API at a Glance

class CommitRevealScheme:
    def __init__(self, hash_algorithm='sha256', use_zkp=False, enable_audit=True): ...

    def commit(value, salt=None) -> tuple[bytes, bytes]: ...
    def reveal(value, salt, commitment) -> bool: ...
    def verify(value, salt, commitment) -> bool: ...  # alias for reveal

    # Zero-knowledge proofs (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: ...

Exceptions: ValidationError for invalid input, SecurityError for insecure operations (e.g., MD5/SHA-1).

Full API reference: documentation

CLI Tools

Command	Description
commit-reveal-secure	Production CLI — never stores plaintext
commit-reveal-migrate	Migrate from legacy to secure format
commit-reveal	Legacy CLI (deprecated)

Enable ZKP for any command with --zkp:

commit-reveal-secure --zkp commit my-secret
commit-reveal-secure --zkp verify-proof my-secret

Documentation

Full documentation available at cryptuon.github.io/commit-reveal.

• Getting Started
• API Reference
• Use Cases (auctions, voting, gaming, blockchain)
• Security Guide

Development

# Install with dev dependencies
poetry install --with dev

# Run tests
poetry run pytest

# Type checking
poetry run mypy commit_reveal/ --strict

# Formatting
poetry run black commit_reveal/ tests/

# Security scan
poetry run bandit -r commit_reveal/

Security

See SECURITY.md for the full security policy, threat model, and vulnerability reporting process.

License

MIT © 2025 Dipankar Sarkar