Pedersen commitments
A Pedersen commitment is a sealed envelope for a number. You publish the envelope, a 32-byte curve point, and keep the number and a random blinding value to yourself. Later you can open it to someone you choose, or prove facts about the number while it stays sealed: “at least 500”, “these inputs equal these outputs”, “this total is covered by our reserves”.
ZeroJ implements commitments on the Jubjub curve, whose arithmetic is cheap inside BLS12-381
circuits, so a Groth16 proof about a committed value costs a few thousand constraints. The
profile is pedersen-jubjub-v1,
designed in ADR-0051.
New to commitments? Read Commitments & encryption, explained first. Not sure a commitment is what you need? Choose how to disclose compares it with BBS, predicates, encrypted deliveries and threshold decryption.
Sees only C. Learns nothing about the amount.
1. Seal
Alice picks an amount and a fresh random blinding and publishes one curve point, C = v·G + r·H. Think of a sealed envelope: everyone can see it, nobody can read it. Drag the amount or roll a new blinding and watch C change.
2. Hiding
Commit to the same amount again with a new blinding, and you get a completely different point. Because the blinding is random, C reveals nothing about the amount, not even whether two commitments hide the same one.
3. Open (binding)
Later, Alice can hand the opening (v, r) to someone she chooses. They recompute the point and compare it with C. A second opening for a different amount exists, but she can't feasibly find one, so C locks her in. Type another amount to see it fail.
4. Add
Commitments add up: C + D is the commitment to the sum of the amounts, with the sum of the blindings. A ledger can total balances, or check that inputs equal outputs, without seeing any single amount.
5. Prove without opening
A zero-knowledge proof can show a fact about the hidden amount, such as "at least 1,000 ADA", while C stays sealed. Drag Alice's amount below 1,000 ADA and no valid proof exists.
Status
Section titled “Status”| Area | Status |
|---|---|
In-circuit commitment (ZkPedersen: commit, commitBits, verifyOpening) | Ready on BLS12-381 Groth16, pending external review |
In-circuit homomorphic API (the ZkPedersenCommitment wrapper and its add/subtract, ZkPedersen.assertBalanced, subgroup checks) | Experimental, pending review and external review |
Vector commitments (ZkPedersenVector, PedersenVectorCommitment) | Experimental, pending spec and external review |
Creating commitments off-circuit (PedersenCommitment.commit, randomBlinding) | Offline/isolated only: variable-time arithmetic on secrets |
Verifying a disclosed opening (PedersenCommitment.verify, decode) | Fine anywhere: the opening is no longer secret to that verifier |
“Offline/isolated only” restricts where you run the secret-handling code: on the user’s device or in a separate process, never in a service an attacker can time. It doesn’t weaken the commitment’s hiding or binding.
Add the dependency
Section titled “Add the dependency”Every Pedersen class is in zeroj-circuit-lib. Add it next to the modules from the
quickstart:
dependencies { implementation platform('org.zeroj:zeroj-bom-core:<version>') annotationProcessor platform('org.zeroj:zeroj-bom-core:<version>')
implementation 'org.zeroj:zeroj-circuit-annotation-api' annotationProcessor 'org.zeroj:zeroj-circuit-annotation-processor' implementation 'org.zeroj:zeroj-circuit-dsl' implementation 'org.zeroj:zeroj-circuit-lib' // PedersenCommitment, ZkPedersen, ... implementation 'org.zeroj:zeroj-crypto' implementation 'org.zeroj:zeroj-codec' implementation 'org.zeroj:zeroj-verifier-groth16'}Use 0.1.0-pre13 or later for <version>.
1. Commit and open
Section titled “1. Commit and open”import org.zeroj.circuit.lib.jubjub.JubjubCurve;import org.zeroj.circuit.lib.jubjub.JubjubPoint;import org.zeroj.circuit.lib.jubjub.PedersenCommitment;
import java.math.BigInteger;import java.security.SecureRandom;import java.util.HexFormat;
public class CommitAndOpen {
public static void main(String[] args) { // --- Committer (offline) --- BigInteger value = BigInteger.valueOf(1_000); // the secret BigInteger blinding = PedersenCommitment.randomBlinding(new SecureRandom()); // fresh, never reused
JubjubPoint commitment = PedersenCommitment.commit(value, blinding); byte[] published = commitment.toBytes(); // 32 bytes System.out.println("Commitment (32 bytes): " + HexFormat.of().formatHex(published));
// --- Verifier, later: receives the bytes, then the opening (value, blinding) --- // decode() rejects non-canonical encodings and points outside the prime-order subgroup. JubjubPoint received = PedersenCommitment.decode(published);
System.out.println("Opens to (1000, r)? " + PedersenCommitment.verify(received, value, blinding)); System.out.println("Opens to (1001, r)? " + PedersenCommitment.verify(received, BigInteger.valueOf(1_001), blinding)); System.out.println("Opens to (1000, r+1)? " + PedersenCommitment.verify(received, value, blinding.add(BigInteger.ONE)));
// (0, -1) is on the curve but has order 2: never a valid commitment. BigInteger minusOne = JubjubCurve.BASE_FIELD_PRIME.subtract(BigInteger.ONE); byte[] lowOrder = JubjubPoint.fromAffine(BigInteger.ZERO, minusOne).toBytes(); try { PedersenCommitment.decode(lowOrder); } catch (IllegalArgumentException e) { System.out.println("Low-order point rejected: " + e.getMessage()); } }}Commitment (32 bytes): dd6ad5a52e940bdf5754476f42d1bab89df3391c1282fc26d37ca553d4f21291Opens to (1000, r)? trueOpens to (1001, r)? falseOpens to (1000, r+1)? falseLow-order point rejected: Pedersen commitment is not in the prime-order subgroupThe commitment bytes change on every run because the blinding is random. That’s the point: committing to 1,000 twice gives two unrelated envelopes.
2. Add commitments
Section titled “2. Add commitments”Anyone can add two commitments: C(30, r1) + C(12, r2) = C(42, r1 + r2). There’s no
PedersenCommitment.add; you add the points with JubjubPoint.add.
import org.zeroj.circuit.lib.jubjub.JubjubCurve;import org.zeroj.circuit.lib.jubjub.JubjubPoint;import org.zeroj.circuit.lib.jubjub.PedersenCommitment;
import java.math.BigInteger;import java.security.SecureRandom;
public class Homomorphic {
public static void main(String[] args) { SecureRandom random = new SecureRandom(); BigInteger v1 = BigInteger.valueOf(30), r1 = PedersenCommitment.randomBlinding(random); BigInteger v2 = BigInteger.valueOf(12), r2 = PedersenCommitment.randomBlinding(random);
JubjubPoint c1 = PedersenCommitment.commit(v1, r1); JubjubPoint c2 = PedersenCommitment.commit(v2, r2);
JubjubPoint sum = c1.add(c2); System.out.println("Sum opens to (42, r1 + r2)? " + PedersenCommitment.verify(sum, BigInteger.valueOf(42), r1.add(r2)));
// The arithmetic is modulo the group order l, not over the integers. BigInteger l = JubjubCurve.SUBGROUP_ORDER; JubjubPoint wrapped = PedersenCommitment.commit(l.subtract(BigInteger.ONE), r1) .add(PedersenCommitment.commit(BigInteger.ONE, r2)); System.out.println("C(l-1, r1) + C(1, r2) opens to (0, r1 + r2)? " + PedersenCommitment.verify(wrapped, BigInteger.ZERO, r1.add(r2))); }}Sum opens to (42, r1 + r2)? trueC(l-1, r1) + C(1, r2) opens to (0, r1 + r2)? trueThe second line is the most important thing on this page. Commitment arithmetic wraps around
at a 252-bit number l. A huge “value” plus 1 can look like 0, so a cheat could hide a negative
amount inside a sum. A sum of commitments proves nothing about real-world totals unless every
value is range-bounded. That’s what the circuit gadgets below do for you.
3. Prove a fact without opening
Section titled “3. Prove a fact without opening”This circuit proves “the value inside this public commitment is at least the public threshold”.
The commitment enters as two public inputs, its affine coordinates (u, v).
import org.zeroj.circuit.annotation.Prove;import org.zeroj.circuit.annotation.Public;import org.zeroj.circuit.annotation.Secret;import org.zeroj.circuit.annotation.UInt;import org.zeroj.circuit.annotation.ZKCircuit;import org.zeroj.circuit.annotation.ZkBool;import org.zeroj.circuit.annotation.ZkContext;import org.zeroj.circuit.annotation.ZkField;import org.zeroj.circuit.annotation.ZkUInt;import org.zeroj.circuit.lib.zk.ZkPedersen;
@ZKCircuit(name = "committed-threshold", version = 1)public class CommittedThreshold { @Prove ZkBool prove(ZkContext zk, @Public ZkField commitmentU, // the commitment, as affine (u, v) @Public ZkField commitmentV, @Public @UInt(bits = 64) ZkUInt threshold, @Secret @UInt(bits = 64) ZkUInt value, // never revealed @Secret @UInt(bits = 252) ZkUInt blinding) { // must be exactly 252 bits // 1. Recompute C = [value]G + [blinding]H and pin it to the public (u, v). ZkPedersen.commit(zk, value, blinding).assertAffineEquals(zk, commitmentU, commitmentV); // 2. The statement about the hidden value. return value.gte(threshold); }}The program below commits to 1,000, proves “at least 500”, and plays the verifier. It uses a
development-only setup, as the quickstart does, so run it with
-Dzeroj.allowInsecureTrustedSetup=true.
import org.zeroj.api.CircuitId;import org.zeroj.api.CurveId;import org.zeroj.api.ProofSystemId;import org.zeroj.api.PublicInputs;import org.zeroj.api.VerificationMaterial;import org.zeroj.circuit.lib.jubjub.JubjubPoint;import org.zeroj.circuit.lib.jubjub.PedersenCommitment;import org.zeroj.codec.SnarkjsJsonCodec;import org.zeroj.crypto.groth16.Groth16Keys;import org.zeroj.crypto.groth16.Groth16ProofBLS381;import org.zeroj.crypto.setup.PowersOfTauBLS381;import org.zeroj.crypto.snarkjs.SnarkjsGroth16Json;import org.zeroj.verifier.groth16.bls12381.Groth16BLS12381PureJavaVerifier;
import java.math.BigInteger;import java.nio.charset.StandardCharsets;import java.security.SecureRandom;
public class ThresholdProof {
public static void main(String[] args) { // 1. Committer (offline): commit to a balance and publish the 32-byte commitment. BigInteger balance = BigInteger.valueOf(1_000); BigInteger blinding = PedersenCommitment.randomBlinding(new SecureRandom()); byte[] published = PedersenCommitment.commit(balance, blinding).toBytes();
// 2. Compile, then a DEV-ONLY trusted setup (this process knows tau). var circuit = CommittedThresholdCircuit.build(); var r1cs = circuit.compileR1CS(CurveId.BLS12_381); BigInteger tau = PowersOfTauBLS381.generate(4).tauScalar(); // only tau is used try (var keys = Groth16Keys.setupInMemory( r1cs.constraints(), r1cs.numWires(), r1cs.numPublicInputs(), tau)) { String vkJson = SnarkjsGroth16Json.verificationKeyJson(keys);
// 3. Prover: knows (balance, blinding) and proves "balance >= 500". JubjubPoint c = PedersenCommitment.decode(published); var inputs = CommittedThresholdCircuit.inputs() .commitmentU(c.affineU()) .commitmentV(c.affineV()) .threshold(500) .value(balance) // secret .blinding(blinding); // secret BigInteger[] witness = inputs.calculateWitness(circuit, CurveId.BLS12_381); Groth16ProofBLS381 proof = keys.prove(witness, r1cs.constraints()); String proofJson = SnarkjsGroth16Json.proofJson(proof); String publicJson = SnarkjsGroth16Json.publicJson(inputs.publicValues().toArray(new BigInteger[0]));
// 4. Verifier: has the published commitment and its own threshold, never the balance. System.out.println("Accepted (balance >= 500)? " + accept(vkJson, proofJson, publicJson, published, 500)); System.out.println("Accepted as proof of >= 900? " + accept(vkJson, proofJson, publicJson, published, 900));
// 5. A false claim can't even produce a witness. try { inputs.threshold(2_000).calculateWitness(circuit, CurveId.BLS12_381); } catch (ArithmeticException e) { System.out.println("Witness for balance >= 2000 refused"); } } }
/** Rebuild the statement from data the verifier trusts, then check the proof. */ static boolean accept(String vkJson, String proofJson, String publicJson, byte[] publishedCommitment, long requiredThreshold) { JubjubPoint c = PedersenCommitment.decode(publishedCommitment); PublicInputs expected = CommittedThresholdCircuit.inputs() .commitmentU(c.affineU()) .commitmentV(c.affineV()) .threshold(requiredThreshold) .toPublicInputs(); if (!expected.equals(SnarkjsJsonCodec.parsePublicInputs(publicJson))) { return false; // the proof is about a different commitment or threshold } CircuitId id = CommittedThresholdCircuit.circuitId(); var envelope = SnarkjsJsonCodec.toEnvelopeFromJson(proofJson, vkJson, publicJson, id); var material = VerificationMaterial.of(vkJson.getBytes(StandardCharsets.UTF_8), ProofSystemId.GROTH16, CurveId.BLS12_381, id); return new Groth16BLS12381PureJavaVerifier().verify(envelope, material).proofValid(); }}Accepted (balance >= 500)? trueAccepted as proof of >= 900? falseWitness for balance >= 2000 refusedThe circuit has 2,671 constraints. Two details carry the security:
- The verifier rebuilds the public inputs from the commitment it already holds and the threshold it requires. Comparing them with the proof’s public inputs is what stops a prover from submitting a valid proof about a different commitment or a lower threshold.
- The blinding is declared
@Secret @UInt(bits = 252). ZeroJ refuses to build a circuit whose blinding is narrower, public or a constant:CommittedThresholdCircuit.build()throwsIllegalArgumentException. A 16-bit blinding could be brute-forced, which would reveal the value. The guard can’t tell whether your blinding is random, though, so always userandomBlinding(new SecureRandom()).
4. Prove that amounts balance
Section titled “4. Prove that amounts balance”To move value privately, prove that the hidden inputs equal the hidden outputs plus any public
fee. ZkPedersen.assertBalanced does this, and it refuses layouts that could wrap around l.
import org.zeroj.circuit.annotation.Prove;import org.zeroj.circuit.annotation.Public;import org.zeroj.circuit.annotation.Secret;import org.zeroj.circuit.annotation.UInt;import org.zeroj.circuit.annotation.ZKCircuit;import org.zeroj.circuit.annotation.ZkContext;import org.zeroj.circuit.annotation.ZkField;import org.zeroj.circuit.annotation.ZkUInt;import org.zeroj.circuit.lib.zk.ZkPedersen;import org.zeroj.circuit.lib.zk.ZkPedersenCommitment;
import java.util.List;
/** "The hidden input amount equals the hidden output amount plus the public fee." */@ZKCircuit(name = "confidential-transfer", version = 1)public class ConfidentialTransfer { @Prove void prove(ZkContext zk, @Public ZkField inU, @Public ZkField inV, // input commitment (u, v) @Public ZkField outU, @Public ZkField outV, // output commitment (u, v) @Public @UInt(bits = 32) ZkUInt fee, @Secret @UInt(bits = 64) ZkUInt inAmount, @Secret @UInt(bits = 252) ZkUInt inBlinding, @Secret @UInt(bits = 64) ZkUInt outAmount, @Secret @UInt(bits = 252) ZkUInt outBlinding) { var in = ZkPedersenCommitment.commit(zk, inAmount, inBlinding); var out = ZkPedersenCommitment.commit(zk, outAmount, outBlinding); in.assertAffineEquals(zk, inU, inV); out.assertAffineEquals(zk, outU, outV); // in = out + fee over the integers. 64 + 32-bit terms can't reach l, so nothing wraps; // assertBalanced checks that when the circuit is built. ZkPedersen.assertBalanced(zk, List.of(ZkPedersen.Term.of(in)), List.of(ZkPedersen.Term.of(out), ZkPedersen.Term.amount(fee))); }}Driven the same way as the threshold example (sending 5,000 as 4,750 plus a 250 fee), it gives:
Transfer accepted (fee 250)? trueTransfer accepted (fee 200)? falseUnbalanced witness refused: Constraint violation: inAmount(w6)=5000 != w17753=5001Wrapping layout refused: the left side of this balance can reach 1fff…fffe (hex), which is not belowthe subgroup order l. A relation mod l would not imply integer conservation; narrow the declaredwidths or coefficients (ADR-0051 D3a).The last line comes from a variant whose amounts are declared 252 bits wide. build() refuses it
before any proof exists. The rules assertBalanced enforces:
- every term has a declared width, through
@UInt(bits = …); - coefficients are positive constants (move a subtraction to the other side);
- the largest possible total on each side stays below
l.
The circuit has 4,886 constraints. The confidential loyalty points demo uses the same pattern for a 1-in, 2-out transfer.
5. Commit to several values at once
Section titled “5. Commit to several values at once”A vector commitment seals up to 16 values in one point, for example a credit profile of income, score, birth year and country. A proof can then check a rule over some fields and keep all of them hidden:
import org.zeroj.circuit.lib.zk.ZkPedersenVector;
// SCHEMA lists the fields and their widths: income/64, credit_score/16, birth_year/16, country/16.var binding = ZkPedersenVector.bindSchema(zk, SCHEMA, schemaDigest); // schemaDigest is @PublicZkPedersenVector.commit(zk, binding, List.of(income, creditScore, birthYear, country), blinding) .assertAffineEquals(zk, u, v);income.gte(minIncome).assertTrue();creditScore.gte(minScore).assertTrue();Vector commitments need two extra checks that single commitments don’t:
- The point doesn’t record its layout.
C([a], r)equalsC([a, 0], r), so every proof binds a public schema digest withbindSchema, and the verifier checks it against a trustedPedersenSchemaRegistry. - A commitment proves nothing about who issued it. Accept a received commitment only with an authenticated issuance record, and fail closed without one.
The full worked example is AnnotatedVectorCommitment in
zeroj-integration-tests,
and the credit gate shows it on
Cardano.
Commitments you didn’t make
Section titled “Commitments you didn’t make”If your circuit receives a commitment whose opening it doesn’t know, for example another party’s balance, there are three ways in. Pick by who checks the point:
| Situation | API | Who checks the point |
|---|---|---|
| The circuit knows the opening | ZkPedersenCommitment.commit(zk, value, blinding) + assertAffineEquals | The circuit recomputes it |
| The opening is unknown, the point is a witness | ZkPedersenCommitment.witnessInSubgroup(zk, u, v) | The circuit (about 5,500 extra constraints) |
| The opening is unknown, the point is public | ZkPedersenCommitment.fromVerifierCheckedPublic(zk, u, v) | Your verifier must PedersenCommitment.decode it first |
On Cardano, a validator can’t run the Jubjub subgroup check, so on-chain consumers use the first two rows.
Rules to follow
Section titled “Rules to follow”- Fresh random blinding, every time.
PedersenCommitment.randomBlinding(new SecureRandom()); never reuse one, never derive it from public data. - Commit offline.
commitandrandomBlindinguse variable-time arithmetic on secrets. Run them on the user’s device or in an isolated process. - Decode with
PedersenCommitment.decode, neverJubjubPoint.fromBytes, for received bytes. - Range-bound every value that means a number. Commitments bind values modulo
l:commit(v, r)equalscommit(v + l, r). Integer meaning comes only from declared widths andassertBalanced. Off-circuit point sums carry no such check. - Rebuild public inputs on the verifier side. A commitment is two public inputs,
uthenv. - The identity point is a valid commitment (to 0 with blinding 0). Check
isIdentity()if your application must exclude it. - A proof is not a permission. Replay protection, nullifiers and binding to the spending transaction are still your job. See Application security.
| Circuit | Constraints | Source |
|---|---|---|
Commitment with public (u, v), 64-bit value | 2,410 | zeroj-circuit-lib README |
| Same, 252-bit value | 4,042 | zeroj-circuit-lib README |
| “At least a threshold” (example 3) | 2,671 | measured for this page |
| 1-in, 1-out transfer with a fee (example 4) | 4,886 | measured for this page |
| Vector commitment, 1 / 4 / 16 values | 2,411 / 3,581 / 8,261 | vector benchmark |
Pure-Java proving for circuits this size took about 1.2 to 1.5 seconds per proof in the vector benchmark (2,400 to 8,300 constraints, one Apple M4 Max laptop), most of it fixed overhead. On Cardano, the proof is checked by ZeroJ’s ordinary Groth16 verifier, and the commitment is just two of its public inputs. See Verify proofs on Cardano.
Next steps
Section titled “Next steps”- Confidential notes: deliver the opening on-chain to the owner and an auditor
- ElGamal encryption: encrypt an amount so an auditor can read it
- Hide a number, prove facts about it: the pattern, with use cases
- Use cases: Proof of solvency with hidden balances, Confidential loyalty points