One claim per person
Airdrops, faucets and community rewards get farmed. One person spins up a thousand wallets and claims a thousand times. Checking identity at claim time stops that, but then every claimant hands over personal data and every claim is linked to a person. What you want is one claim per real human per round, where the nullifier a claim publishes tells nobody, not even the issuer that vouched for each person, which person claimed.
Alicerecorded, then signedAliceagain: refused
m = Poseidon(personhoodId, 0) · sees only mPoseidon(personhoodId, 0) · it chose personhoodIdpersonhoodId, so it can't compute any nullifieryes: it hashes every personhoodId it handed out with the epoch and finds AliceSecond claim in round 1: same credential, same epoch, so the same nullifier.
0xb7d1…ea5fround 10xb4d1…4c9around 2
FaucetMintingPolicyissuer key and epoch matcheligible = 1exactly 1 receipt named nullifier≥ 2 ADA to the recipient's key hashGroth16 proof validproof fails: not the recipient it bindsRound 2 is a new epoch: a new policy ID.Receipt uniqueness on-chain is deferred: a replay with the replayer's own funds could mint a second receipt, but the faucet pays nothing.
1. Enrol
Alice's wallet draws its own personhoodId and sends the issuer only m = Poseidon(personhoodId, 0). After its one-human check, the issuer records Alice and signs m. A second request for Alice is refused, so nobody gets two credentials.
Before, the issuer chose each personhoodId (a counter or a hash of the name) and handed it out with the signature. That meant the issuer knew every identifier. Watch what that does on step 3.
2. Claim
Alice's wallet computes the nullifier Poseidon(personhoodId, epoch) and proves the issuer signed her credential, with this round's epoch and her chosen recipient as public inputs. The epoch is a tag for this deployment and round, not a small number. Switch to Public view: the personhood ID and signature never leave the wallet.
3. Pay once
The faucet checks the nullifier hasn't been paid, records it, and signs the payout. The policy verifies the proof, mints one receipt named after the nullifier, and requires 2 ADA to the recipient's key hash. Flip Swap recipient to see why a copied proof can't be redirected.
The claim goes through, but look at the issuer: knowing every personhoodId, it can compute each person's nullifier for this epoch and match this receipt to Alice. That's why the holder now chooses the identifier.
4. Repeat in the same round
Same credential and same epoch give the same nullifier. It's in the faucet's paid record, so the faucet refuses to pay. Bob's claim still works, because his credential gives a different nullifier.
5. Next round
Round 2 gives a new epoch and a new policy. Alice's credential gives an unrelated nullifier, so she can claim again, and nobody, the issuer included, can link her two nullifiers. To keep the claims themselves unlinked, she uses a fresh recipient key each round: the recipient is public, and so are the fee payer and timing.
The zero-knowledge idea
Section titled “The zero-knowledge idea”The claimant proves “a personhood issuer signed my credential, and this nullifier is the one my credential produces for this round”, and binds the payout to a recipient, without revealing the credential.
A personhood issuer checks, out of band, that each human gets exactly one credential. That’s the part zero knowledge can’t do for you. The credential works like this:
- The holder picks the identifier. The holder’s wallet draws a secret
personhoodId(252 bits,SecureRandom) and sends the issuer onlym = Poseidon(personhoodId, 0). The issuer signsmwith EdDSA over Jubjub and never seespersonhoodId. - Nullifier =
Poseidon(personhoodId, epoch). It’s the same for every claim in a round, so repeats are caught. A new round gives an unrelated value, so one person’s nullifiers can’t be linked across rounds. The recipient, the fee payer and timing can still link claims (see the security considerations). - Recipient binding. The payout’s key hash is a public input the proof commits to, and the minting policy checks that the transaction really pays it.
This is the same building block behind Semaphore-style signals and “one-per-human” claim tokens.
Why the issuer mustn’t choose the identifier
Section titled “Why the issuer mustn’t choose the identifier”In the first version of this demo the issuer assigned each person’s personhoodId (a counter or a
hash of the name). The issuer then knew every identifier it had handed out, and the nullifier
Poseidon(personhoodId, epoch) uses only that identifier and the public epoch. So the issuer
could compute every person’s nullifier for every round and link each claim to a name. Now the
holder chooses personhoodId and the issuer signs only its hash, so it can’t compute any
nullifier.
Holder-chosen identifiers need one more rule: one credential per person. Otherwise a person
could ask for two credentials with two identifiers and claim twice. The issuer keeps a durable
record of each person it has issued to, written before it signs, and refuses a second issuance.
The circuit didn’t change: it already proved knowledge of a personhoodId whose
Poseidon(personhoodId, 0) the issuer signed.
What stays private, what’s public
Section titled “What stays private, what’s public”| Input | Visibility | Why |
|---|---|---|
personhoodId | Secret | Chosen by the holder; the issuer sees only its hash |
Issuer signature (sigRU, sigRV, sigS) and helpers (kModL, kQuotient) | Secret | Revealing the signature would link claims |
pkU, pkV | Public | The issuer’s Jubjub key; pinned by the minting policy |
epoch | Public | This deployment and round (policyEpoch); pinned by the policy |
nullifier | Public | One per credential per round; becomes the minted receipt’s asset name |
recipient | Public | The payout’s 28-byte payment key hash, as a number |
eligible | Public | Must be 1 |
The epoch is a domain tag
Section titled “The epoch is a domain tag”The epoch isn’t a small round number. It’s a tag for one deployment and one round:
policyEpoch = Poseidon2(Poseidon2(tag("zeroj.airdrop.epoch.v1"), deploymentId), n)tag(s) = blake2b_256(UTF-8(s)) as an integer, top byte cleareddeploymentId = blake2b_256(txId ‖ I2OSP2(index)) of the faucet's seed UTxO, top byte clearedn = the round number, 1 ≤ n < 2^32Poseidon2 is ZeroJ’s PoseidonHash over PoseidonParamsBLS12_381T3. Two airdrops, even two
sibling outputs of one transaction used as seeds, never share a nullifier. The policy refuses
policyEpoch = 0 and any epoch at or above the field order.
How it works
Section titled “How it works”- Enrol. The holder draws
personhoodIdand sendsm = Poseidon(personhoodId, 0). After its one-human check, the issuer records the person and signsm. A second request for the same person is refused. - Claim. The holder proves with this round’s
policyEpochand the recipient they choose. - Pay once. The faucet refuses a nullifier it has already paid, or whose receipt was ever minted. Otherwise it records the nullifier, durably, before it signs the payout.
- Mint a receipt. The faucet minting policy verifies the proof, mints one receipt named after the nullifier, and requires an output paying the recipient’s key hash at least the payout.
- Repeat in the same round? Same credential and same round give the same nullifier, so the faucet refuses to pay.
- Next round. A new round number gives a new
policyEpochand a new policy, with fresh nullifiers.
holder ──m = Poseidon(personhoodId, 0)──▶ issuer (once per person) ──sig(m)──▶ holderholder ──proof(policyEpoch, recipient)──▶ faucet: nullifier not paid? record it, sign payout policy: issuer ✓ epoch ✓ eligible ✓ pays recipient ✓ pairing ✓ mint 1 × <nullifier> receiptThe circuit
Section titled “The circuit”This is the demo’s PersonhoodAirdropProof, lightly trimmed (imports and comments):
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.ZkPoseidon;
@ZKCircuit(name = "personhood-airdrop", version = 1)public class PersonhoodAirdropProof { private static final PoseidonParams POSEIDON = PoseidonParamsBLS12_381T3.INSTANCE;
@Prove ZkBool prove(ZkContext zk, @Public ZkField pkU, @Public ZkField pkV, @Public ZkField epoch, @Public ZkField nullifier, @Public ZkField recipient, @Public ZkBool eligible, @Secret ZkField personhoodId, @Secret ZkField sigRU, @Secret ZkField sigRV, @Secret @UInt(bits = 252) ZkUInt sigS, @Secret @UInt(bits = 252) ZkUInt kModL, @Secret @UInt(bits = 4) ZkUInt kQuotient) {
var claimsMsg = ZkPoseidon.hash(zk, POSEIDON, personhoodId, zk.constant(0)); ZkEdDSAJubjub.verifyWithRegisteredKey( zk, pkU, pkV, claimsMsg, sigRU, sigRV, sigS, kModL, kQuotient);
// Bind the public recipient into a real (non-degenerate) R1CS row. recipient.mul(personhoodId);
var computedNullifier = ZkPoseidon.hash(zk, POSEIDON, personhoodId, epoch); return eligible.and(computedNullifier.isEqual(nullifier)); }}The circuit compiles to 10,467 constraints (from the demo’s test runs) and uses a power-14 development SRS.
The line recipient.mul(personhoodId) deserves a closer look. The circuit doesn’t compute
anything with recipient, but a Groth16 proof only commits to a public input that appears in at
least one constraint. Multiplying two variables emits a real constraint row. A constant
multiplication such as recipient * 1 gets folded away and wouldn’t bind anything. ZeroJ’s native
Groth16 setup refuses a relation with an unbound public input rather than silently producing a key
that ignores it.
On Cardano
Section titled “On Cardano”The demo’s FaucetMintingPolicy is a JuLC minting policy parameterised by the verification key,
the issuer’s key, policyEpoch and payout. It reads the six public inputs from the receipt
output’s inline datum and requires:
- the mint under the policy is exactly one entry, quantity 1, named after the nullifier, and the receipt sits at the policy’s own script address;
- the issuer key and the epoch equal its parameters, with
0 < policyEpoch < r; eligible == 1;- an output whose payment credential is the key hash
recipient, carrying at leastpayoutlovelace. A script credential never qualifies, and the API accepts only key-credential addresses; - the proof verifies with
Groth16BLS12381Lib.verify(...).
The faucet pays each nullifier once. The faucet’s ADA sits at its admin key’s address, so a payout needs the admin’s signature. Before signing, the faucet refuses a nullifier that is in its paid record or whose receipt was ever minted (from the chain indexer; if that lookup fails, the claim is refused). It then records the nullifier atomically on disk, so the record survives restarts.
The policy itself keeps no “minted once” state, so receipt uniqueness on-chain is deferred. Someone replaying a claim with their own funds can mint a second receipt for the same nullifier, but takes nothing from the faucet. A sorted-list registry like the voting and NFT demos would close that.
Security considerations
Section titled “Security considerations”- The one-human check is out of band. ZK enforces “one claim per credential”. It can’t tell whether a person holds two credentials. Sybil resistance is only as good as the issuer’s enrolment checks; the demo stands in for them with the person’s name.
- A lost credential can’t be re-issued. One credential per person is what stops a second
claim, so a holder who loses
personhoodIdor the signature can’t claim again. - Stolen credentials claim once per round. Whoever holds
personhoodIdand the signature can claim. Revocation isn’t demonstrated. - Copied proofs. A mempool observer can copy a pending claim’s proof into its own transaction, but the policy still requires the payout to the proved recipient, so the copier can only pay the recipient from its own funds.
- The recipient is public. It’s a public input, written into the receipt’s datum, and the
transaction pays it, so the faucet and every chain observer see it. Use a fresh recipient key
each round: a reused recipient, the fee payer and timing can link claims even though the
nullifiers can’t. In the demo,
--runpays every claim to the faucet admin’s address. - Random, persisted keys. The issuer’s EdDSA-Jubjub key and the faucet admin wallet are
generated with
SecureRandomon first start and stored owner-only in the demo data directory. The first version derived the issuer key from a seed published in the source, so anyone could sign credentials. If deployment state exists but a key is missing or doesn’t match, the demo stops instead of making a new one. A production faucet keeps these keys in a KMS or HSM. - Static round. The round comes from configuration (
faucet.round), not chain time, and a new round deploys a new policy ID. - Keep issuance offline. The demo signs with
EdDSAJubjub.signCompatibilityOffline, which is meant for offline, isolated use, not a network signing service. - The demo is custodial. The server holds every holder’s wallet, so it knows each
personhoodId(the issuer component doesn’t). Its API is the operator’s view: privacy holds against chain and mempool observers, not against the demo server. Even so,/statusand/historyreturn no names next to nullifiers. - Trusted setup. The demo uses a single-party development setup; production needs an MPC ceremony (Trusted setup, explained). The demo is not externally reviewed.
Try it
Section titled “Try it”The demo lives in
personhood-airdrop.
Its tutorial
walks through the design. With Yaci DevKit running (see
Run the demos):
./demo.sh airdrop --runAt startup the demo enrols five holders (Alice, Bob, Charlie, Diana and Eve), each with its own
personhoodId. --run has Alice claim for round 1: the proof is generated, the receipt is
minted on-chain and 2 ADA is paid out (to the faucet admin’s own address, the demo default when no
recipient is given). Claim for Alice again and the service answers 409, because her nullifier
was already paid. Bob’s claim succeeds because his credential produces a different nullifier.
The issuer key, the policy parameters and the policy ID changed. If you ran an earlier version,
start fresh with ./demo.sh airdrop --clean-cache.
Related
Section titled “Related”- Private voting: nullifiers stored in an on-chain sorted list
- Age & KYC eligibility: the same in-circuit issuer signature, without rate limiting
- Circuits, constraints & witnesses: why unconstrained inputs are dangerous
- Application security