Skip to content

Selective disclosure & reusable KYC

View Markdown

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.

BBS · step 1 / 5
IssuerKYC provider
issuer public keyPUBLIC0x393b…1ac6
One BBS signature over all five
  1. givenName
  2. dob
  3. country
  4. kycLevel
  5. docHash

No circuit and no trusted setup.

HolderAlice's wallet
0 · givenNameAlice Example████████REVEALEDSECRETHIDDEN
1 · dob1990-05-01████████REVEALEDSECRETHIDDEN
2 · countryUSA████████REVEALEDSECRETHIDDEN
3 · kycLevelverified████████REVEALEDSECRETHIDDEN
4 · docHash0x7d2e…a91c████████REVEALEDSECRETHIDDEN
π0x762c…e02cnew bytes each time
Verifierapp or Cardano validator
Policycountry is allowedkycLevel = verified
challenge (fresh, single-use)PUBLIC0x9ac9…9aa1
Presentation received
  • givenNameAlice Examplehidden, but signed
  • dob1990-05-01hidden, but signed
  • countryUSAhidden, but signed
  • kycLevelverifiedhidden, but signed
  • docHash0x7d2e…a91chidden, but signed
proof valid for the issuer keychallenge is new, now marked usedchallenge already used: rejectedpolicy meton Cardano, BbsKycClaimValidator pays the voucher

1. 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.

SECRET stays in the walletREVEALED the verifier sees the valueHash values are illustrative.

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 learnsA computed yes/no, such as dobYear ≤ currentYear − 21Chosen attribute values, such as country = USA
Computes over hidden values?Yes: ranges, Merkle membership, any circuitNo: each attribute is either revealed or hidden
SignatureEdDSA-Jubjub over a Poseidon hash of all fields, checked in-circuitBBS (IRTF CFRG draft-10) over all attributes
Circuit and trusted setupOne circuit and one setup per predicateNone
On-chainGroth16BLS12381LibBbsProofVerify (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.

Groth16 “senior doctor” predicate:

InputVisibilityWhy
dobYear, country, roleId, salaryBracket, nameHashSecretThe whole credential stays hidden
Issuer signature and helper witnessesSecretRevealing them would link presentations
pkU, pkVPublicThe issuer’s key; pinned by the validator
currentYearPublicPinned by the validator, so the prover can’t pick a convenient year
eligiblePublicThe predicate’s result; the validator requires 1

BBS reusable KYC:

InputVisibilityWhy
givenName, dob, docHashHiddenProven signed but never shown
country, kycLevelRevealedExactly what this verifier’s policy needs
Issuer public key, credential headerPublicIdentify the issuer and schema
Presentation header (challenge)PublicMakes the presentation single-use

Groth16 predicates:

  1. The issuer signs Poseidon(dobYear, country, roleId, salaryBracket, nameHash) once.
  2. 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.
  3. Each gate is a spending validator pinned to its own verification key, issuer key and policy values.

BBS:

  1. The issuer signs five attributes as one BBS credential.
  2. The verifier sends a fresh random challenge.
  3. The holder derives a presentation that reveals only the requested attributes, bound to that challenge.
  4. 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.

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.

SeniorDoctorProof.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.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)));
}
}

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 bytes
List<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 ascending
BbsPresentation 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 policy
boolean 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.

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 + maxFee is 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 maxFee minus the actual fee, so a funder should set maxFee close 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.

  • 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, and nameHash is Poseidon(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).

Both demos are in zeroj-usecases. With Yaci DevKit running (see Run the demos):

Terminal window
# 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 --run
  • selective-disclosure: --run locks 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: --run issues a credential, gets a verifier challenge, presents only country and kycLevel, then claims a voucher on-chain. The ledger verifies the BBS proof. The UI lets you pick which attributes to reveal.