Skip to content

Circuits, constraints & witnesses

View Markdown

In Zero-knowledge in plain English we treated a circuit as a function that returns true or false. That’s a useful first picture, but it isn’t how circuits work, and the gap between the two is where most ZK security bugs come from. This page closes that gap.

A ZK circuit doesn’t run. It’s a list of equations, called constraints, over a set of variables, called wires. A proof shows that the prover knows values for all the wires that make every equation true at once.

Here’s the statement “I know x such that x³ + x + 5 = 35”, written as constraints:

Circuit · x³ + x + 5 = 35

What you're seeing: the circuit is just three equations. The prover's job is to fill in a value for every wire so that all three hold at once. Slide x to find the answer, then try to cheat.

Witnessevery wire, filled in
  1. [0]one1CONST
  2. [1]out35PUBLIC
  3. [2]x3SECRETHIDDEN
  4. [3]v19SECRETHIDDEN
  5. [4]v227SECRETHIDDEN
Constraintsall three must hold
  1. v1 = x · x9 = 3 · 3holds
  2. v2 = v1 · x27 = 9 · 3holds
  3. out = v2 + x + 535 = 27 + 3 + 5holds

The equations are public: they're the circuit. The verifier never sees x,v1 or v2, only out = 35 and a proof that some values fit all three.

All three equations hold, so [1, 35, 3, 9, 27] is a valid witness and the prover can make a proof.Proof valid. The verifier learns that the prover knows an x with x³ + x + 5 = 35, and nothing else.
SECRET stays with the proverPUBLIC part of the statementSmall numbers here, so nothing wraps around the field.

With x = 3, the wires are v1 = 9, v2 = 27, out = 35, and all three equations hold. The verifier never sees x, v1, or v2. It only learns that some assignment satisfies every constraint with out = 35.

Notice the shape: each constraint does at most one multiplication. That’s not a style choice. It’s the format the proof system understands.

Groth16 consumes circuits in R1CS form (rank-1 constraint system). Every constraint looks like:

(linear combination A) × (linear combination B) = (linear combination C)

A linear combination is a sum of wires times constants, like v2 + x + 5. Additions are free; they fold into the linear combinations. Multiplications of two wires each cost one constraint. The simplest possible circuit, “I know b such that a · b = product”, is a single constraint:

(a) × (b) = (product)

When people say a circuit has “54 constraints” or “19 million constraints”, they’re counting these rows. More constraints mean a bigger proving key and a slower prover. Verification cost doesn’t change: Groth16 verification depends on the number of public inputs, not the number of constraints.

Field arithmetic: numbers that wrap around

Section titled “Field arithmetic: numbers that wrap around”

Circuit wires don’t hold Java ints or longs. They hold field elements, which are whole numbers modulo a large prime. For BLS12-381, the curve ZeroJ uses for Cardano, that prime is a 255-bit number called r:

r = 52435875175126190479447740508185965837690552500527637822603658699938581184513

Think of it as a clock with r hours. Arithmetic works like normal until you pass r, then it wraps around. That has consequences Java developers don’t expect:

ExpressionIn JavaIn the field
3 - 5-2r - 2, a huge positive number. There are no negative numbers.
1 / 20(r + 1) / 2, the number that gives 1 when doubled. There are no fractions or decimals, only inverses.
x > 5a comparisonNot defined. Field elements have no built-in order.
(r - 1) + 1r (using BigInteger)0

The last two rows are the dangerous ones. To prove “age ≥ 18”, a circuit can’t just compare. It has to prove the numbers are small, by splitting them into bits, and only then compare the bits. Proving that a value fits in n bits is called a range check, and forgetting one is the most common way to break a circuit.

The witness is the complete list of values for every wire in the circuit: the public inputs, the secret inputs, and every intermediate value. For the x³ + x + 5 example it’s [1, 35, 3, 9, 27].

In ZeroJ, calculateWitness(...) produces it as a BigInteger[] with a fixed layout:

index 0 the constant 1 (every R1CS uses a "one" wire for constants)
index 1..n the n public inputs, in the circuit's declared order
index n+1.. secret inputs and intermediate wires

The explainer near the top of this page shows that layout for x³ + x + 5: the constant, then the public out, then the secret wires.

The witness contains your secrets, so it never leaves the prover. The prover turns it into a proof, and only the proof and the public inputs travel.

Constraints describe; they don’t execute

Section titled “Constraints describe; they don’t execute”

Because a circuit is a set of equations and not a program, ordinary Java control flow doesn’t translate.

No if on secrets. An if in your Java code runs once, while the circuit is being built, before any secret exists. It can’t depend on a secret value. Instead, you compute both branches and use a constraint to pick one:

// In Java you'd write: fee == (isMember ? 0 : 5)
ZkField expected = isMember.select(zk.constant(0), zk.constant(5));
return expected.isEqual(fee);

Under the hood, select is the equation result = isMember · (0 − 5) + 5. It only works as a choice if isMember is exactly 0 or 1.

No &&, ||, ! on secrets. Same reason. Use ZkBool.and(...), or(...), and not(), which emit the equivalent equations.

Booleans need their own constraint. In a field, a “boolean” is just a number. A value is only 0 or 1 if a constraint says so: b · (b − 1) = 0. In the select above, a cheater who sets isMember = 2 would get expected = 2 · (−5) + 5, which is not a fee anyone intended. ZeroJ’s ZkBool adds the boolean constraint for you, so isMember = 2 is rejected.

Here’s the most important idea on this page:

A circuit only enforces the equations you actually wrote down, not the ones you meant.

If an intended rule has no constraint behind it, a cheater can pick any value that satisfies the remaining equations, and the proof will verify. This is called an under-constrained circuit, and it’s the most common serious bug class in ZK applications.

Here’s a concrete, runnable example. The idea: “prove age ≥ threshold by showing age = threshold + diff, where diff is a non-negative secret”.

BuggyAgeCheck.java
// BUG: nothing says `diff` is small and non-negative.
@ZKCircuit(name = "buggy-age-check", version = 1)
public class BuggyAgeCheck {
@Prove
ZkBool prove(@Secret ZkField age,
@Secret ZkField diff,
@Public ZkField threshold) {
return age.isEqual(threshold.add(diff));
}
}

An honest 25-year-old uses diff = 7, and everything looks fine. Tests with honest inputs pass. Now a 16-year-old cheats:

Under-constrained circuit · age = threshold + diff

What you're seeing: a toy circuit that proves age ≥ threshold by writing age = threshold + diff. Pick who is proving, then add or remove the range check on diff.

Who's proving
CircuitBuggyAgeCheckFixedAgeCheck
age == threshold + diffage, diff, threshold each in 0 … 255nothing says diff is small or non-negative
ageSECRETHIDDEN2516████
thresholdPUBLIC18
diffSECRETHIDDEN7r − 2████

5 constraints.56 constraints: the extra ones are exactly the missing rule.

In the fielda clock with r hours
0r − 216182518 + 7= 2518 + (r − 2)= 16

Seven steps round the clock: 18 + 7 lands on 25.There are no negative numbers: −2 is written r − 2. Adding it goes almost a full turn and lands on 16.

18 + 7 = 25 = age18 + (r − 2) = r + 16, which wraps to 16 = age7 fits in 8 bitsr − 2 is a 255-bit number, not 8 bits
Every constraint holds, so the proof verifies.Honest inputs pass whether or not the range check is there, which is why honest tests can't find this bug.The bug: every constraint holds, so the proof verifies. A 16-year-old just proved age ≥ 18. The circuit said "equal", and in the field the values are equal. It never said diff is a small, non-negative number.The cheat fails. r − 2 doesn't fit in 8 bits, so no valid witness exists and no proof can be made.The verifier sees threshold 18 and a valid proof, and accepts.The verifier sees threshold 18 and a valid proof, and accepts. From here, a cheat looks exactly like an honest proof: only the circuit could have stopped it.No valid proof exists, so there's nothing for the verifier to accept.
SECRET stays with the proverPUBLIC the verifier sees itr is BLS12-381's 255-bit prime.

ZeroJ’s own witness calculator accepts these inputs, and the resulting proof verifies. The circuit said “equal”, and the values are equal in the field. It never said “diff is a small, non-negative number”.

The fix is to state the missing rule. In ZeroJ, ZkUInt with @UInt(bits = N) adds range constraints that force each value into 0 … 2ᴺ − 1:

FixedAgeCheck.java
@ZKCircuit(name = "fixed-age-check", version = 1)
public class FixedAgeCheck {
@Prove
ZkBool prove(@Secret @UInt(bits = 8) ZkUInt age,
@Secret @UInt(bits = 8) ZkUInt diff,
@Public @UInt(bits = 8) ZkUInt threshold) {
return age.isEqual(threshold.add(diff));
}
}

Now diff = r − 2 doesn’t fit in 8 bits, so no valid witness exists. The fixed circuit has 56 constraints instead of 5, and those extra constraints are exactly the rules that were missing. In a real circuit you’d simply write age.gte(threshold), which does the same range-checked comparison for you.

ZeroJ can’t design your circuit for you, but it removes the most common traps:

  • Symbolic types. You write circuits with ZkField, ZkBool, ZkUInt, and friends instead of Java primitives. You can’t accidentally branch on a secret, because a ZkBool isn’t a boolean.
  • Range checks by declaration. @UInt(bits = N) on a ZkUInt input adds its range constraints when the value is created. Comparisons like gte and lt require range-checked operands.
  • Constrained booleans. Every ZkBool is constrained to 0 or 1.
  • A gadget library. Poseidon hashing, Merkle membership, comparators, bit decomposition, and more are written once and reused. For Cardano circuits, use Poseidon with explicit BLS12-381 parameters (PoseidonParamsBLS12_381T3.INSTANCE). See Gadgets.
  • Witness checking. calculateWitness(...) checks every constraint and throws an ArithmeticException when one fails, which makes invalid-witness tests easy to write.

A small annotated circuit, and a test that it rejects a false claim, looks like this:

AgeCheck.java
@ZKCircuit(name = "age-check", version = 1)
public class AgeCheck {
@Prove
ZkBool prove(@Secret @UInt(bits = 8) ZkUInt age,
@Public @UInt(bits = 8) ZkUInt threshold) {
return age.gte(threshold);
}
}
AgeCheckTest.java
var circuit = AgeCheckCircuit.build(); // generated by the annotation processor
// Honest witness: 25 ≥ 18
var ok = AgeCheckCircuit.inputs().age(25).threshold(18);
circuit.calculateWitness(ok.toWitnessMap(), CurveId.BLS12_381);
// Invalid witnesses must be rejected
var tooYoung = AgeCheckCircuit.inputs().age(16).threshold(18);
assertThrows(ArithmeticException.class,
() -> circuit.calculateWitness(tooYoung.toWitnessMap(), CurveId.BLS12_381));
var outOfRange = AgeCheckCircuit.inputs().age(300).threshold(18); // doesn't fit in 8 bits
assertThrows(ArithmeticException.class,
() -> circuit.calculateWitness(outOfRange.toWitnessMap(), CurveId.BLS12_381));