Skip to content

Age & KYC eligibility

View Markdown

Regulated DeFi, age-gated content and jurisdiction checks all ask the same thing: are you allowed to use this? Today the answer usually means uploading a passport to every app, which stores it and can leak it. Credentials fix half of that problem. A KYC provider checks you once and signs your attributes. Zero knowledge fixes the other half: you prove the signed attributes satisfy the rule, and the app never sees them.

Age & KYC · step 1 / 5
IssuerKYC provider
issuer keyPUBLIC0x2197…2d7f
EdDSA-Jubjub signature overPoseidon(age, country)

Checks the person out of band, signs offline, keeps its secret key.

Holdertheir own deviceidentity hidden
ageSECRETHIDDEN25████████
countrySECRETHIDDEN840 · USA████████
signatureSECRETHIDDENσ 0x36ba…16ea████████
Merkle pathSECRETHIDDEN4 sibling hashes████████
The circuit checks1. the issuer signed these attributes2. USA is a leaf of countryRoot3. eligible = (age ≥ 18) = 1

The validator never sees these checks run, only their proof.

πeligible = 1192 bytes
ValidatorCardano script
CredentialGatedValidator
pinned parametersPUBLICVK · issuer key · minAge 18 · countryRoot
The demo locks 5 ADA here.
Approved countriesUSAGBRDEUFRAJPN
countryRootPUBLIC0xabc6…eeca
issuer key and policy are the pinned oneseligible = 1pairing check passes5 ADA unlocked
no nullifier: the credential can prove againstateless gate: a copied proof passes too

1. Issue

The KYC provider checks the person once, out of band, and signs Poseidon(age, country) with EdDSA over Jubjub. The holder gets their attributes and the signature. Pick a holder to load their credential.

2. Deploy the gate

The protocol compiles a validator with the verification key, the issuer's public key, minAge 18 and the approved-country root as script parameters. Changing the policy produces a new script address.

3. Prove

On the holder's device, one circuit checks that the issuer signed these attributes, that the country is a leaf of the approved-country tree, and that eligible equals age ≥ 18. Try Charlie (16) and Diana (Brazil), then switch to Validator's view.

4. Spend

The redeemer carries the proof and five public inputs: the issuer key's two coordinates, minAge, countryRoot and eligible. The validator checks the issuer and the policy, requires eligible = 1 and runs the pairing check.

5. Reuse

No nullifier is involved, so the same credential can prove eligibility again and again. The flip side: this gate is stateless, so anyone who sees an unlock transaction can copy its proof. A real protocol binds the proof to the recipient or the spent TxOutRef.

SECRET stays on the holder's devicePUBLIC in the redeemer or the scriptHash values are illustrative.

The holder proves “a registered issuer signed my age and country, my age meets the minimum, and my country is on the approved list”. The only public outputs are the issuer’s key, the policy and the result.

The issuer signs Poseidon(age, country) with EdDSA over Jubjub. Jubjub is a curve defined over the BLS12-381 scalar field, so checking its signatures inside a BLS12-381 circuit is comparatively cheap. The circuit then does three things:

  1. verifies the issuer’s signature on the hidden attributes;
  2. compares age ≥ minAge as 8-bit integers;
  3. proves country is a leaf of the approved-country Merkle tree, whose root is public.

The demo circuit is about 11,000 constraints. The on-chain check costs the same whatever the circuit contains, because it’s a Groth16 pairing check over a handful of public inputs.

InputVisibilityWhy
ageSecret8-bit integer, range-checked; only the comparison result matters
countrySecretNumeric country code; only membership in the approved set matters
Issuer signature (sigRU, sigRV, sigS) and helper witnesses (kModL, kQuotient)SecretRevealing the signature would make every presentation linkable
Merkle path (siblings, pathBits)SecretThe path would reveal which country
pkU, pkVPublicThe issuer’s Jubjub public key; the validator pins it
minAgePublicThe policy threshold; pinned
countryRootPublicThe approved-country set; pinned
eligiblePublicProven equal to age ≥ minAge; the validator requires 1
  1. Issue. The KYC provider verifies the person out of band, signs Poseidon(age, country) and hands the holder their attributes plus the signature. The issuer keeps its secret key.
  2. Deploy the gate. The protocol compiles a validator with the verification key, the issuer’s public key, minAge and countryRoot as script parameters. Changing the policy produces a new script address.
  3. Prove. The holder generates a Groth16 proof on their own device. The demo does this server-side for convenience.
  4. Spend. The transaction’s redeemer carries the proof plus the five public inputs. The validator checks the issuer, the policy, eligible == 1 and the proof.
  5. Reuse. No nullifier is involved. The same credential can prove eligibility again and again, which suits ongoing access.
issuer ──sign(Poseidon(age, country))──▶ holder ──Groth16 proof──▶ validator
(off-chain, once) (local) params: VK, issuer key, minAge, countryRoot
checks: registered issuer + policy + eligible==1 + pairing

This is lightly simplified from the demo’s CredentialProof: constructor validation is trimmed and the steps are reordered for reading.

CredentialProof.java
import org.zeroj.circuit.annotation.*;
import org.zeroj.circuit.lib.poseidon.PoseidonParams;
import org.zeroj.circuit.lib.poseidon.PoseidonParamsBLS12_381T3;
import org.zeroj.circuit.lib.zk.ZkEdDSAJubjub;
import org.zeroj.circuit.lib.zk.ZkMerkle;
import org.zeroj.circuit.lib.zk.ZkPoseidon;
@ZKCircuit(name = "credential-verify-eddsa",
nameTemplate = "credential-verify-eddsa-d{countryTreeDepth}-bls-poseidon", version = 1)
public class CredentialProof {
private static final PoseidonParams POSEIDON = PoseidonParamsBLS12_381T3.INSTANCE;
public CredentialProof(@CircuitParam("countryTreeDepth") int countryTreeDepth) {}
@Prove
ZkBool prove(ZkContext zk,
@Public ZkField pkU,
@Public ZkField pkV,
@Public @UInt(bits = 8) ZkUInt minAge,
@Public ZkField countryRoot,
@Public ZkBool eligible,
@Secret @UInt(bits = 8) ZkUInt age,
@Secret ZkField country,
@Secret ZkField sigRU,
@Secret ZkField sigRV,
@Secret @UInt(bits = 252) ZkUInt sigS,
@Secret @UInt(bits = 252) ZkUInt kModL,
@Secret @UInt(bits = 4) ZkUInt kQuotient,
@Secret @FixedSize(param = "countryTreeDepth") ZkArray<ZkField> siblings,
@Secret @FixedSize(param = "countryTreeDepth") ZkArray<ZkBool> pathBits) {
// 1. The issuer signed these exact attributes
var claims = ZkPoseidon.hash(zk, POSEIDON, age.asField(), country);
ZkEdDSAJubjub.verifyWithRegisteredKey(zk, pkU, pkV, claims, sigRU, sigRV, sigS, kModL, kQuotient);
// 2. The country is in the approved set
ZkMerkle.verifyProofPoseidon(zk, POSEIDON, country, countryRoot, siblings, pathBits);
// 3. The age meets the minimum
return eligible.isEqual(age.gte(minAge));
}
}

verifyWithRegisteredKey is the right entry point here because the issuer key is a public input that the verifier pins. If the prover could choose the key, you’d need verifyStrict, which also checks the key’s subgroup membership inside the circuit. The name reminds you that “is this a trusted issuer?” is the validator’s job.

The demo’s CredentialGatedValidator is a JuLC spending validator. It composes Groth16BLS12381Lib.verify(…) and takes the verification key, the issuer’s key coordinates and the policy values (minAge, countryRoot) as parameters. It accepts a spend only if the redeemer’s public inputs match the registered issuer and policy, eligible == 1, and the pairing check passes.

A valid proof is not authorization. This is a stateless, replayable demo gate: the validator checks the proof, not the transaction that spends it. Anyone who sees an unlock transaction, on the chain or still pending, can copy its proof and use it to open any other UTxO locked at the same gate. A real protocol should bind the proof to its context: add the recipient or the spent TxOutRef as a bound public input that the validator recomputes from ScriptContext, or use a per-epoch nullifier when access should be rate-limited. See Application security.

  • You trust the issuer. A dishonest or compromised issuer can sign anything. Plan for key rotation and revocation: short-lived credentials, or a periodically refreshed validity tree the circuit checks.
  • The issuer key must be secret. The demo generates its issuer key with SecureRandom on first start and keeps it, owner-only, in its data directory. Earlier versions derived the key from a seed published in the demo’s source, so anyone could sign credentials that the deployed validator accepted. A credential signed with that old seed is now refused.
  • Keep issuance offline. The demo signs with EdDSAJubjub.signCompatibilityOffline. ZeroJ’s Jubjub signing isn’t constant-time and is meant for offline, isolated use. Don’t expose it as a network signing service.
  • Credentials can be shared. A proof shows knowledge of a credential, not identity, and the demo credential names no holder. Holder binding helps: include the holder’s key in the signed message and prove control of it.
  • Unsalted credentials. The issuer signs Poseidon(age, country) with no salt. That message has a small domain, so anyone who sees it or its signature, together with the issuer’s public key, can recover the attributes by trying every age and country. Two holders with the same age and country get the same signature. Add a random salt to the signed message in a real deployment.
  • Replay of stateless proofs, as described above.
  • Demo custody. The demo server holds the issuer key and every holder’s credential, and proves on their behalf. Its API is the operator’s view. Privacy holds against chain and mempool observers, not against the demo server.
  • Linkability outside the proof. The same wallet, fee payer or timing can still link two presentations.
  • Trusted setup. The demo uses a single-party development setup; production needs an MPC ceremony (Trusted setup, explained).

The demo lives in identity-kyc. With Yaci DevKit running (see Run the demos):

Terminal window
./demo.sh identity-kyc --run

--run locks 5 ADA at the credential-gated script, proves that Alice (25, USA) is eligible and unlocks the funds with that proof on-chain. The UI lists five test users. Charlie is 16 and Diana’s country isn’t on the approved list, so neither can produce a proof that unlocks the gate.

Design notes: ZK identity & credentials — detailed design (credential lifecycle, revocation options, issuer registries).