Frequently asked questions.
Short answers, all grounded in the source. For the long form, see how it works and the design notes.
What is a commit-reveal scheme?
A two-phase primitive: first you publish a commitment that binds you to a value without revealing it; later you reveal the value and anyone can check it matches the commitment. It removes the timing advantage that would let later participants peek at earlier ones.
How is the commitment computed?
The commitment is H(value ‖ salt), where the salt defaults to 32 random bytes from the OS CSPRNG (secrets.token_bytes) and the hash is one of eight selectable algorithms (SHA-256 by default).
Does it have any dependencies?
No runtime dependencies. pyproject.toml lists only python ^3.8. It uses hashlib, hmac, and secrets from the standard library — nothing else at runtime.
What are the zero-knowledge proofs for?
The optional Schnorr ZKP lets you prove you know the value behind a commitment without revealing it — useful for hidden-then-verified votes or protocols where a reveal would leak too much. Opt in with CommitRevealScheme(use_zkp=True).
Which curve does the ZKP use?
secp256k1 — the same curve Bitcoin uses — implemented from scratch in affine arithmetic. The Schnorr proof is made non-interactive with the Fiat–Shamir heuristic using a SHA-256 challenge.
Is the reveal comparison timing-safe?
Yes. Reveal uses hmac.compare_digest, a constant-time comparison, rather than ==. It does not leak how much of a guess was correct through timing.
Why are MD5 and SHA-1 not allowed?
They are broken for collision resistance, which a commitment scheme depends on. Selecting either raises SecurityError at construction, so you cannot create a weak commitment by accident.
Can I use it without writing any code?
Yes. The secure CLI (commit-reveal-secure) supports commit, reveal, and list. It prompts via getpass, never echoes the value, and never writes plaintext to disk — commitment files are mode 0600.
How does commit-reveal help with MEV?
Most MEV — front-running, sandwiching, back-running — is a timing attack on information that leaked too early in the mempool. If order intents commit during a sealed window and reveal only after it closes, a searcher cannot react to an order it has not yet seen, and by reveal time the ordering is already fixed. It removes the timing edge extraction depends on, without encrypting the whole mempool.
How is this a building block for verifiable AI?
In agent networks where independent nodes submit answers (DFPN-style inference or forecasting), the risk is that an operator copies a peer instead of computing. Having each agent commit to its output first — and reveal only after the window closes — forces genuine independence, because a commitment leaks nothing to copy. The optional Schnorr ZKP then lets an agent prove its reveal is consistent without re-broadcasting the payload.
Is commit-reveal a network or an on-chain protocol?
No. It is a library, not a network. It computes and verifies commitments and Schnorr proofs in pure Python; it does not run consensus, hold funds, or settle on-chain by itself. You wire it into your own system — who commits, when the window closes, and where reveals are posted are your design choices. If you want on-chain settlement, the project roadmap outlines a minimal reference verifier on an Ethereum L2.
What is it not?
It is not a general-purpose ZKP library, and it is not a sequencer, mempool, or L2. No Pedersen/KZG/Merkle commitments, no pairing-friendly curves (BLS12-381/BN254), no SNARK/STARK circuits, no BLS signatures. For those, see the py_ecc comparison.
Is it production-ready?
It is typed (mypy strict), property-tested (Hypothesis), and Bandit-clean, with an explicit SECURITY.md. It has not had a formal external audit and the secp256k1 code is affine, not constant-time — it is built for protocol prototyping and low-throughput use, not HFT-scale proving.