Selective disclosure & reusable KYC
Every exchange, lending app and marketplace runs its own KYC, and each one keeps a copy of your documents. A signed credential lets you do KYC once. But if you then show the whole credential everywhere, you’ve only moved the problem. Selective disclosure is the missing piece. A library asks “over 21 and a resident?”, a healthcare portal asks “a doctor over 30?”, a DeFi app asks “KYC-verified and from an allowed country?”, and each one learns only its answer.
ZeroJ supports two complementary ways to do this, and each has a runnable demo.
givenNamedobcountrykycLeveldocHash
No circuit and no trusted setup.
country is allowedkycLevel = verifiedgivenNameAlice Examplehidden, but signeddob1990-05-01hidden, but signedcountryUSAhidden, but signedkycLevelverifiedhidden, but signeddocHash0x7d2e…a91chidden, but signed
BbsKycClaimValidator pays the voucher1. Issue
The KYC provider checks Alice's documents once and signs all five attributes as one BBS credential. Alice keeps it in her wallet.
2. Challenge
The verifier sends a fresh random challenge. The verifier picks it, never the holder, so a presentation made for this verifier can't be replayed elsewhere.
3. Present
Alice's wallet derives a presentation that reveals only the attributes she ticks, bound to the challenge. It proves the hidden attributes were signed too, without showing them. Each presentation has new proof bytes, so two verifiers can't link them. Try ticking other attributes.
4. Verify
The verifier checks the proof against the issuer's public key, checks that the challenge is one it issued and hasn't seen, then applies its policy. On Cardano, a validator runs the same BBS check natively and releases a voucher.
5. Replay
Someone resends the same presentation. Its challenge was already used, so it's rejected. On-chain, the challenge is derived from the voucher UTxO, which is already spent.
Poseidon(dobYear, country, roleId, salaryBracket, nameHash)Approved: USA, UK, Germany, France, Japan, committed as a Merkle root.
1. Issue
The issuer signs a Poseidon hash of all five fields with EdDSA-Jubjub, once. Pick Alice, Bob or Charlie to load their credential.
2. Prove
For each gate, the holder runs that gate's circuit on their own device. It recomputes the hash, checks the issuer's signature and checks the gate's rule. When the rule is false, no valid proof exists.
3. Unlock
Each gate is a spending validator with the issuer key and the current year pinned as script parameters. It verifies the proof and releases the funds. Switch to Gate's view: the gate never learns the birth year, country, role or salary.
The zero-knowledge idea
Section titled “The zero-knowledge idea”One issuer-signed credential; each verifier learns only the answer to its own question.
Groth16 predicates (selective-disclosure demo) | BBS selective disclosure (reusable-kyc demo) | |
|---|---|---|
| Verifier learns | A computed yes/no, such as dobYear ≤ currentYear − 21 | Chosen attribute values, such as country = USA |
| Computes over hidden values? | Yes: ranges, Merkle membership, any circuit | No: each attribute is either revealed or hidden |
| Signature | EdDSA-Jubjub over a Poseidon hash of all fields, checked in-circuit | BBS (IRTF CFRG draft-10) over all attributes |
| Circuit and trusted setup | One circuit and one setup per predicate | None |
| On-chain | Groth16BLS12381Lib | BbsProofVerify (fixed profile, see below) |
Use predicates when the verifier needs a fact computed from a value it must not see. Use BBS when revealing the value itself is fine and you want no circuits and no trusted setup. The two combine well: reveal some attributes with BBS, and prove a range over another with a small Groth16 circuit.
What stays private, what’s public
Section titled “What stays private, what’s public”Groth16 “senior doctor” predicate:
| Input | Visibility | Why |
|---|---|---|
dobYear, country, roleId, salaryBracket, nameHash | Secret | The whole credential stays hidden |
| Issuer signature and helper witnesses | Secret | Revealing them would link presentations |
pkU, pkV | Public | The issuer’s key; pinned by the validator |
currentYear | Public | Pinned by the validator, so the prover can’t pick a convenient year |
eligible | Public | The predicate’s result; the validator requires 1 |
BBS reusable KYC:
| Input | Visibility | Why |
|---|---|---|
givenName, dob, docHash | Hidden | Proven signed but never shown |
country, kycLevel | Revealed | Exactly what this verifier’s policy needs |
Issuer public key, credential header | Public | Identify the issuer and schema |
| Presentation header (challenge) | Public | Makes the presentation single-use |
How it works
Section titled “How it works”Groth16 predicates:
- The issuer signs
Poseidon(dobYear, country, roleId, salaryBracket, nameHash)once. - For each verifier, the holder runs that verifier’s predicate circuit. Every circuit recomputes the same claims hash, checks the same signature, then asserts its own predicate.
- Each gate is a spending validator pinned to its own verification key, issuer key and policy values.
BBS:
- The issuer signs five attributes as one BBS credential.
- The verifier sends a fresh random challenge.
- The holder derives a presentation that reveals only the requested attributes, bound to that challenge.
- The verifier checks the proof, that the challenge is one it issued and hasn’t seen before, and its policy. On-chain, a validator can do the same natively.
The circuit
Section titled “The circuit”This Groth16 predicate is from the demo’s SeniorDoctorProof. The AdultResidentProof next to it
reuses the same first half and adds a Merkle country check.
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.ZkPoseidonN;
@ZKCircuit(name = "senior-doctor", version = 1)public class SeniorDoctorProof { private static final PoseidonParams POSEIDON = PoseidonParamsBLS12_381T3.INSTANCE; private static final int MIN_AGE = 30; private static final long DOCTOR_ROLE_ID = 1001L;
@Prove ZkBool prove(ZkContext zk, @Public ZkField pkU, @Public ZkField pkV, @Public @UInt(bits = 16) ZkUInt currentYear, @Public ZkBool eligible, @Secret @UInt(bits = 16) ZkUInt dobYear, @Secret @UInt(bits = 16) ZkUInt country, @Secret ZkField roleId, @Secret @UInt(bits = 8) ZkUInt salaryBracket, @Secret ZkField nameHash, @Secret ZkField sigRU, @Secret ZkField sigRV, @Secret @UInt(bits = 252) ZkUInt sigS, @Secret @UInt(bits = 252) ZkUInt kModL, @Secret @UInt(bits = 4) ZkUInt kQuotient) {
// Every predicate recomputes the same signed message over all five fields var claims = ZkPoseidonN.hash(zk, POSEIDON, dobYear.asField(), country.asField(), roleId, salaryBracket.asField(), nameHash); ZkEdDSAJubjub.verifyWithRegisteredKey(zk, pkU, pkV, claims, sigRU, sigRV, sigS, kModL, kQuotient);
// The predicate: role == doctor AND born no later than currentYear - 30 var maxDobYear = ZkUInt.wrap(zk, currentYear.asField().sub(zk.constant(MIN_AGE)).signal(), 16); var roleOk = roleId.isEqual(zk.constant(DOCTOR_ROLE_ID)); return roleOk.and(eligible.isEqual(dobYear.lte(maxDobYear))); }}The BBS flow
Section titled “The BBS flow”With BBS there’s no circuit at all. This is the zeroj-bbs API as the reusable-KYC demo uses it,
condensed:
import java.nio.charset.StandardCharsets;import java.security.SecureRandom;import java.util.List;import org.zeroj.bbs.BbsKeyPair;import org.zeroj.bbs.BbsPresentation;import org.zeroj.bbs.BbsRevealedMessage;import org.zeroj.bbs.BbsService;import org.zeroj.bbs.BbsSignature;
var bbs = BbsService.pureJava();
// Issuer: sign all five attributes as one credential (index = position in the list)BbsKeyPair issuer = bbs.keyPair(keyMaterial, keyInfo); // keyMaterial: >= 32 secret random bytesList<byte[]> attributes = List.of(givenName, dob, country, kycLevel, docHash);BbsSignature signature = bbs.sign(issuer.secretKey(), issuer.publicKey(), attributes, header);
// Verifier: a fresh, single-use challenge. The verifier picks it, never the holder.byte[] challenge = new byte[32];new SecureRandom().nextBytes(challenge);
// Holder: reveal country (2) and kycLevel (3); indexes must be strictly ascendingBbsPresentation presentation = bbs.derivePresentation( issuer.publicKey(), signature, attributes, header, challenge, new int[] {2, 3});
// Verifier: check the proof (and that `challenge` is unused), then apply its policyboolean valid = bbs.verifyPresentation(issuer.publicKey(), presentation);for (BbsRevealedMessage m : presentation.revealedMessages()) { System.out.println(m.index() + " -> " + new String(m.message(), StandardCharsets.UTF_8));}verifyPresentation checks cryptography only. Issuer trust, schema, expiry, revocation and your
disclosure policy remain application logic. See the BBS guide.
On Cardano
Section titled “On Cardano”Groth16 gates. The demo’s AdultResidentValidator and SeniorDoctorValidator are JuLC
spending validators built on Groth16BLS12381Lib. The issuer key, currentYear and (for the adult
gate) the approved-country root are script parameters. Changing any of them deploys a new script,
so a caller can’t substitute weaker public inputs.
These are stateless, replayable demo gates: the validators check 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 deployment
binds the proof to the output it spends, for example with the spent TxOutRef and the payout
address as public inputs that the validator recomputes from ScriptContext.
BBS natively on-chain. BbsProofVerify in zeroj-onchain-julc runs BBS ProofVerify
inside Plutus V3. BbsToCardano in zeroj-bbs turns the issuer key into validator parameters and
a presentation into redeemer fields. The demo’s BbsKycClaimValidator locks a voucher UTxO and
releases it only if four things hold:
- the presentation verifies on the ledger;
- it discloses exactly the required values;
- its presentation header equals
blake2b_256(voucherTxId ‖ I2OSP(index, 8) ‖ recipientPkh), which the validator recomputes itself rather than trusting the claimer; - the voucher pays exactly what it owes, as described below.
Spending the voucher is the nullifier. The demo measured about 2.4×10⁹ CPU units for the check,
within Cardano’s per-transaction limit. The current BbsProofVerify profile is fixed to a
five-attribute credential disclosing indexes 2 and 3; other shapes need a different unrolling.
How the voucher pays. The voucher’s datum is
(requiredCountry, requiredKycLevel, recipientPkh, refundAmount, funderPkh, maxFee). The demo locks
10 ADA with a 2 ADA refund and a maxFee of 2 ADA, so 6 ADA goes back to the funder. A claim counts
only outputs whose inline datum is exactly the spent voucher’s TxOutRef, called tagged outputs:
- tagged outputs to the recipient’s key sum to at least
refundAmount; - tagged outputs to the funder’s key sum to at least the remainder,
voucher − refundAmount − maxFee(no funder output is needed when that is 0); - the voucher holds only ADA, and
refundAmount + maxFeeis at most the voucher’s value.
Why the tags? An earlier version only checked that some output paid the recipient at least 2 ADA. Anyone who saw a pending claim could resubmit the same redeemer, pay the recipient 2 ADA and keep the other 8 ADA (less fees). One output could also count as the payment for two vouchers in one transaction. Each tag is unique to one voucher, so no output can pay two vouchers, and the remainder must go back to the funder.
Two things remain:
- Fee slack. Whoever submits the claim can keep
maxFeeminus the actual fee, so a funder should setmaxFeeclose to the expected fee. - Composition. The tag guarantee holds only between validators that enforce tags. Spending a voucher in the same transaction as a script that counts any paying output is unsafe.
A valid proof is not authorization. For the BBS voucher, the header binding and the tagged payout checks above carry the authorization; the proof alone doesn’t. The Groth16 gates have no such checks, which is why they are replayable. See Application security.
Security considerations
Section titled “Security considerations”- Replay. A BBS presentation stays valid forever. It’s single-use only if the relying party chooses the challenge (off-chain) or derives it from the UTxO being spent (on-chain). The Groth16 demo proofs carry no nonce and aren’t bound to the UTxO they spend, so a copied proof opens any other UTxO at the same gate. Bind each proof to its session or to the spent output.
- Unsalted Groth16 credentials. The issuer signs
Poseidon(dobYear, country, roleId, salaryBracket, nameHash)with no salt, andnameHashisPoseidon(name, 0). Every field has a small or guessable domain, so anyone who sees the signed message or its signature, together with the issuer’s public key, can recover the fields by trying them. Equal fields give an equal signature. Add a random salt to the signed message in a real deployment. - Revealed values can identify you. A rare combination of disclosed attributes may be enough to re-identify someone. Reveal the minimum.
- Credential theft and sharing. Whoever holds the credential can present it. Neither demo binds the credential to a holder. The Groth16 credential names no holder key. A BBS presentation proves that the issuer signed these attributes, not that the presenter is their subject, so one KYC’d credential can satisfy many vouchers. Bind the credential to the holder’s key when that matters. BBS per-verifier pseudonyms are out of scope for the demo.
- Demo custody. Both demo servers hold the issuer key and the holders’ credentials and prove or present on their behalf; the reusable-KYC server also holds the funder’s wallet. Their APIs are the operator’s view. Privacy holds against chain and mempool observers, not against the demo servers. The voucher funder’s wallet and the Groth16 demo’s admin wallet come from Yaci DevKit’s well-known test mnemonic, so anyone can sign as them on a devnet; a real deployment replaces them.
- Issuer keys. The Jubjub issuer key of the Groth16 demo is random and persisted in the demo’s
data directory. It used to be derived from a seed published in the source, so anyone could sign
credentials the gates accepted; a credential signed with that old seed is now refused. For BBS,
the default pure-Java provider isn’t constant-time. Prefer the blst provider
(
BbsService.withBlsProvider(...)) for issuer keys. The Jubjub demo issuer (signCompatibilityOffline) is for offline, isolated use only. - Maturity. BBS follows an IRTF draft, not yet an RFC. The Groth16 demos use a single-party development setup (Trusted setup, explained).
Try it
Section titled “Try it”Both demos are in zeroj-usecases. With Yaci DevKit running (see Run the demos):
# Groth16 predicates from one signed credential./demo.sh selective-disclosure --run
# BBS: reveal a subset of attributes, verified natively on-chain./demo.sh reusable-kyc --runselective-disclosure:--runlocks ADA at the “adult resident” and “senior doctor” gates, then has Bob prove each predicate and unlock both on-chain. In the UI, Alice passes only the adult gate and Charlie passes neither.reusable-kyc:--runissues a credential, gets a verifier challenge, presents onlycountryandkycLevel, then claims a voucher on-chain. The ledger verifies the BBS proof. The UI lets you pick which attributes to reveal.
Related
Section titled “Related”- Choose how to disclose: every disclosure option, and when to use each
- BBS credentials guide
- Groth16, PlonK & BBS: when to reach for which
- Age & KYC eligibility: a single predicate from a minimal credential
- Application security