Skip to content

One claim per person

View Markdown

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.

One claim per person · step 1 / 5
Issuerpersonhood
personhoodId chosen bythe demo nowthe demo before
Issued to · one credential per person
  1. Alicerecorded, then signed
  2. Aliceagain: refused
The one-human check happens outside the system.
issuer keyPUBLIC0x3fcf…ac2e
Signs with EdDSA-Jubjubm = Poseidon(personhoodId, 0) · sees only mPoseidon(personhoodId, 0) · it chose personhoodId
Can the issuer link the nullifier to Alice?no: it never saw personhoodId, so it can't compute any nullifieryes: it hashes every personhoodId it handed out with the epoch and finds Alice
Alice's walletA claimantidentity hidden
personhoodId · drawn here, 252-bitpersonhoodId · from the issuerSECRETHIDDEN0x473c…3bfe████████
issuer signatureSECRETHIDDEN0x36ba…16ea████████
m sent to the issuerTO ISSUERHIDDEN0xda54…5e05████████
epoch · round 1epoch · round 2PUBLIC0xfeee…6b0d0x01ee…7fe6
recipientPUBLICkey hash 0xb886…a25c
nullifier = Poseidon(personhoodId, epoch)PUBLIC0xb7d1…ea5f0xb4d1…4c9a
πGroth16 proofbinds recipient

Second claim in round 1: same credential, same epoch, so the same nullifier.

Faucetservice + Cardano
datum recipientPUBLICkey hash 0xb886…a25ckey hash 0x74fe…7ecb
Paid nullifiers · durable record
  1. 0xb7d1…ea5fround 1
  2. 0xb4d1…4c9around 2
none yetnone yetRecorded before the admin key signs the payout.refused: already paid in round 1
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.
claim tx pays 2 ADAnothing minted or paid

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.

SECRET never leaves the holder's walletPUBLIC seen by the faucet and on CardanoHash values are illustrative.

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 only m = Poseidon(personhoodId, 0). The issuer signs m with EdDSA over Jubjub and never sees personhoodId.
  • 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.

InputVisibilityWhy
personhoodIdSecretChosen by the holder; the issuer sees only its hash
Issuer signature (sigRU, sigRV, sigS) and helpers (kModL, kQuotient)SecretRevealing the signature would link claims
pkU, pkVPublicThe issuer’s Jubjub key; pinned by the minting policy
epochPublicThis deployment and round (policyEpoch); pinned by the policy
nullifierPublicOne per credential per round; becomes the minted receipt’s asset name
recipientPublicThe payout’s 28-byte payment key hash, as a number
eligiblePublicMust be 1

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 cleared
deploymentId = blake2b_256(txId ‖ I2OSP2(index)) of the faucet's seed UTxO, top byte cleared
n = the round number, 1 ≤ n < 2^32

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

  1. Enrol. The holder draws personhoodId and sends m = Poseidon(personhoodId, 0). After its one-human check, the issuer records the person and signs m. A second request for the same person is refused.
  2. Claim. The holder proves with this round’s policyEpoch and the recipient they choose.
  3. 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.
  4. 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.
  5. Repeat in the same round? Same credential and same round give the same nullifier, so the faucet refuses to pay.
  6. Next round. A new round number gives a new policyEpoch and a new policy, with fresh nullifiers.
holder ──m = Poseidon(personhoodId, 0)──▶ issuer (once per person) ──sig(m)──▶ holder
holder ──proof(policyEpoch, recipient)──▶ faucet: nullifier not paid? record it, sign payout
policy: issuer ✓ epoch ✓ eligible ✓ pays recipient ✓ pairing ✓
mint 1 × <nullifier> receipt

This is the demo’s PersonhoodAirdropProof, lightly trimmed (imports and comments):

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

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 least payout lovelace. 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.

  • 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 personhoodId or the signature can’t claim again.
  • Stolen credentials claim once per round. Whoever holds personhoodId and 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, --run pays 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 SecureRandom on 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, /status and /history return 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.

The demo lives in personhood-airdrop. Its tutorial walks through the design. With Yaci DevKit running (see Run the demos):

Terminal window
./demo.sh airdrop --run

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