Private NFT ownership
On Cardano, owning an NFT means a UTxO holding it sits at your address. To prove ownership, you usually connect your wallet or point at that UTxO, and the verifier (plus anyone watching) learns your address, your balance, every other token you hold and your transaction history. That’s a steep price for a concert ticket, a holders-only chat or a DAO forum. Zero knowledge lets you prove “I’m a holder” and nothing more.
ZeroJTicket_1CIP-8 ✓ZeroJTicket_1again: refused
Each leaf is Poseidon(Poseidon(s, 0), t), which hides the token. The demo's tree has depth 10 (up to 1,024 holders).
Trust point: one use per registration rests on the indexer admitting one leaf per token, from its holder. It can't see which token a leaf commits to.
(contextId, tokenName, leaf)Second access with the same leaf: the same nullifier.
ZkProofMintingPolicyparametersnapshotRootparametercontextId = nft-demo-v1Groth16 over [root, context, 1, nullifier]mints exactly 1 token named nullifierNullifierListValidator · sorted listroot nodeseed spent: once0x6ac6…7acb0x4efb…45dcinserted
nft-demo-v1 finds ZeroJTicket_1, and so the wallet that holds it1. Register
The app draws a 252-bit holder secret s and registers the leaf Poseidon(Poseidon(s, 0), t) for token t. The registration is signed (CIP-8) by the address that holds the token on-chain. The indexer takes one registration per token, so a second one for ZeroJTicket_1 is refused.
2. Build the snapshot
The indexer builds the Merkle tree and publishes the root, and registration closes. The event's scripts are deployed with the root and contextId as parameters, and the nullifier list's root is created once, by spending a seed UTxO.
3. Prove
The holder finds the Merkle path to its leaf, computes the nullifier for this event, and proves the leaf is in the snapshot without saying which one. Switch to Public view to see what leaves the device.
4. Access
The transaction mints one token named after the nullifier. The policy verifies the proof against its own root and context, and the list inserts a node whose key is that nullifier. Nobody can tell which NFT was used. Switch to version 1 to see why the old nullifier leaked.
Version 1 hashed only the token name and the event. Both are public, so anyone could hash every token name of the collection and match this nullifier: it named the NFT, and so the wallet. Version 2 adds the holder's secret.
5. Reuse is rejected
The same leaf in the same event gives the same nullifier. It's already in the list, so the insert fails and the transaction is rejected. Because the indexer admitted one leaf per token, that's one use per registration.
Version 1 also caught a second use, since the same NFT always gave the same nullifier. But the old list didn't tie its new key to the proved nullifier and let nodes be removed, so a nullifier could be inserted again.
The zero-knowledge idea
Section titled “The zero-knowledge idea”The holder proves “one leaf of this event’s ownership snapshot is mine, and this is my one-time nullifier for the event”, without revealing which leaf, which NFT or which wallet.
Live UTxOs change with every transaction, so the proof is made against a snapshot. An indexer
collects registrations from holders and builds a Merkle tree. Each holder has a holder secret
s: a 252-bit random value that the app draws with SecureRandom. For token t the leaf is:
leaf = Poseidon(Poseidon(s, 0), t)The root is published, and the holder proves their leaf is in the tree without saying which leaf.
The nullifier marks one use per event:
nullifier = Poseidon(Poseidon(s, t), contextId)contextId names the event. The same leaf in the same event always gives the same nullifier, so a
second use is caught. A different event gives an unrelated value, so one holder’s nullifiers can’t
be linked across events. Without s, nobody can compute the nullifier for any token.
Why not just hash the token name?
Section titled “Why not just hash the token name?”The first version of this demo used Poseidon(tokenName, contextId) as the nullifier. It looks
private, because the token name stays a secret input. But every input to that hash is public:
the collection’s token names are listed on-chain, and contextId is a public input. Anyone could
hash each token name with the event’s contextId and find the published nullifier. That showed
which NFT was used, and because an NFT’s holder address is public on Cardano, which wallet too.
The fix is to make the nullifier absorb a value nobody else can guess: the holder’s 252-bit secret.
It has to be large. A short secret such as 42 could be found by trying every small number, so
the API refuses secrets shorter than 240 bits (below 2^239). Deriving the nullifier from the leaf, as
Poseidon(leaf, contextId), wouldn’t work either: if the snapshot’s leaves are published, anyone
could recompute it.
What stays private, what’s public
Section titled “What stays private, what’s public”| Input | Visibility | Why |
|---|---|---|
secretKey | Secret | The holder’s 252-bit secret; the leaf and the nullifier absorb it |
tokenName | Secret | Which NFT; the nullifier no longer reveals it |
Merkle path (siblings, pathBits) | Secret | The path would reveal the leaf’s position |
snapshotRoot | Public | The event’s snapshot; a parameter of the event’s minting policy |
contextId | Public | The event; also a policy parameter |
isOwner | Public | Must be 1 |
nullifier | Public | Minted as a token name and inserted into the on-chain list |
An observer of the chain or the mempool learns that some holder in the snapshot used the gate, and nothing about which NFT or which wallet.
One use per what?
Section titled “One use per what?”With the old nullifier, the circuit itself gave each NFT exactly one nullifier per event. Now each
leaf gives one nullifier per event, so a holder who registered two leaves for one NFT would get
two uses. Keeping the count right is now the indexer’s job. In the demo, SnapshotService
plays the indexer, and registration:
- refuses a second registration for a token already in the snapshot;
- requires a CIP-8 signature from the holding address. The holder signs
(contextId, tokenName, leaf)with the payment key of the address that holds the token on-chain, and the indexer checks on-chain that this address holds exactly one unit of it; - freezes when the snapshot is built. No leaf can be added after the root is fixed.
So the snapshot has at most one leaf per authenticated holding, and each leaf gets in once. One limit remains: the leaf hides the token, so the indexer can’t check that a leaf registered under token A really commits to A. A holder of A could register a leaf over another token B. That changes which token a proof names, not how many uses there are: one use per authenticated holding, not one use per specific NFT. The snapshot is a trust point either way.
How it works
Section titled “How it works”- Register. For each NFT, the app draws a holder secret and registers the leaf
Poseidon(Poseidon(s, 0), t), signed (CIP-8) by the wallet that holds the token. - Build the snapshot. The root is fixed and registration closes. The event’s scripts are
deployed: a minting policy with the root and
contextIdas parameters, and a nullifier list whose root can be created only once. - Prove. The holder generates a Groth16 proof with ZeroJ’s pure-Java prover.
- Access. A transaction mints one token named after the nullifier. The policy verifies the proof on-chain, and the list inserts a node keyed by that nullifier.
- Reuse is rejected. The same holder in the same event produces the same nullifier, and the list already holds it.
holder: s, t ─sign (CIP-8)─▶ indexer: one leaf per token ─▶ snapshotRoot, frozendeploy: ZkProofMintingPolicy(snapshotRoot, contextId, VK) + NullifierListValidator(zkPolicyId, seed)holder: s, t, path ─prove─▶ tx: mint 1 × <nullifier>, insert node keyed by <nullifier>The circuit
Section titled “The circuit”This is the demo’s NFTOwnershipProof, version 2, with constructor validation trimmed.
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.ZkMerkle;import org.zeroj.circuit.lib.zk.ZkPoseidon;
@ZKCircuit(name = "nft-ownership", nameTemplate = "nft-ownership-d{treeDepth}-bls-poseidon", version = 2)public class NFTOwnershipProof { private static final PoseidonParams POSEIDON = PoseidonParamsBLS12_381T3.INSTANCE;
public NFTOwnershipProof(@CircuitParam("treeDepth") int treeDepth) {}
@Prove ZkBool prove(ZkContext zk, @Public ZkField snapshotRoot, @Public ZkField contextId, @Public ZkBool isOwner, @Public ZkField nullifier, @Secret ZkField secretKey, @Secret ZkField tokenName, @Secret @FixedSize(param = "treeDepth") ZkArray<ZkField> siblings, @Secret @FixedSize(param = "treeDepth") ZkArray<ZkBool> pathBits) {
// Leaf (unchanged from version 1): Poseidon(Poseidon(secretKey, 0), tokenName). var ownerHash = ZkPoseidon.hash(zk, POSEIDON, secretKey, zk.constant(0)); var leaf = ZkPoseidon.hash(zk, POSEIDON, ownerHash, tokenName); ZkMerkle.verifyProofPoseidon(zk, POSEIDON, leaf, snapshotRoot, siblings, pathBits);
// Nullifier: Poseidon(Poseidon(secretKey, tokenName), contextId). var holderToken = ZkPoseidon.hash(zk, POSEIDON, secretKey, tokenName); var computedNullifier = ZkPoseidon.hash(zk, POSEIDON, holderToken, contextId); return isOwner.and(computedNullifier.isEqual(nullifier)); }}The leaf is the same as in version 1; only the nullifier changed. Token names and event labels enter the circuit as their bytes read as one big-endian number (1 to 31 bytes, with no leading zero byte, so each name has one value). The demo builds a depth-10 tree, which holds up to 1,024 holders. At depth 4, as in the end-to-end test, the circuit compiles to 1,942 constraints, and each extra level adds one Poseidon hash and doubles the tree’s capacity (and the potential anonymity set).
On Cardano
Section titled “On Cardano”Building the snapshot deploys two JuLC scripts for the event. Both run in every access transaction.
-
ZkProofMintingPolicytakessnapshotRoot,contextIdand the verification key as script parameters, so there is one policy per event. The redeemer carries only the proof and the nullifier. The policy requires the mint under it to be exactly one token, quantity 1, whose 32-byte name is the nullifier, and verifies the proof withGroth16BLS12381Lib.verifyFour(snapshotRoot, contextId, 1, nullifier, ...). A proof against another snapshot or event fails, because those inputs come from the parameters. -
NullifierListValidatorkeeps nullifiers in a sorted linked list, one UTxO per entry:- One-shot root. The list is parameterised by a seed UTxO that the root’s creation must spend, so the root exists once.
- The new key is the proved nullifier. An insert must mint exactly one ZK token, and the new node’s key is that token’s name (its low 31 bytes). The ZK token sits in the new node.
- Insert-only. A node can be spent only as the anchor of an insert, one list input per transaction, and nothing is ever burned, so nodes are never removed.
An insert also proves the key sits between two neighbours, so a nullifier already in the list can’t be added again.
The first version of the list checked only that the ZK policy minted something, not that the new key was the proved nullifier, and its root could be minted again and its nodes removed, so one proof could gate any number of accesses.
A token minted under the ZK policy outside a list insert grants nothing: readers count access only from list nodes. Each node locks about 2 ADA, which stays locked because nodes are never removed. See On-chain verification for the verifier side.
Security considerations
Section titled “Security considerations”- The indexer decides the snapshot. It is trusted to admit one registration per token, from the address holding it. The demo doesn’t publish the snapshot’s leaves; a real deployment should, so anyone can rebuild the root.
- One use per authenticated holding, not per NFT, as explained above.
- Front-running. A mempool observer can copy a holder’s proof from a pending transaction and submit it first; the access then goes to that transaction. The fix is a fresh one-time beneficiary key hash as a public input, with the gate’s output paid to it. It is deferred to keep circuit version 2 minimal.
- Using the gate shows that some snapshot holder acted. Also consider fee payer and timing linkability when holders submit their own transactions.
- Staleness. A holder who sells after the snapshot can still prove against it. A new snapshot is a new event.
- One event per run. The demo’s event comes from
zk.default-context; a new event needs a restart with a new context. - The demo is custodial. The server holds the custody wallet that holds the NFTs and signs registrations. It draws each holder secret and returns it once, without storing it, and it proves for the holder. Its API is the operator’s view: privacy holds against chain and mempool observers, not against the demo server.
- 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
nft-ownership. With Yaci
DevKit running (see Run the demos):
./demo.sh nft-ownership --run--run mints ZeroJTicket_1 into the custody wallet and registers it. The server draws a fresh
252-bit holder secret, returns it once, and signs the registration with the custody wallet. Then
it builds the snapshot (which deploys the event’s scripts), generates a proof for the event
nft-demo-v1, and submits the access transaction. The proof is verified on-chain and the
nullifier lands in the sorted list. Submit the same nullifier again and the service answers 403,
“Already accessed (nullifier exists on-chain)”; forcing the insert past that check is rejected by
the list script. Registering ZeroJTicket_1 a second time is refused, and so is a typed-in secret
such as 42.
The circuit, scripts and script hashes changed in version 2. If you ran an earlier version, start
fresh with ./demo.sh nft-ownership --clean-cache.
Design notes:
DESIGN.md in the
demo, and
Private NFT ownership — detailed design
(snapshot vs. on-chain registries, threshold “whale” proofs, shielded transfers).
Related
Section titled “Related”- Private allowlist with a Merkle tree: the same membership and nullifier pattern, step by step
- Private voting: the same sorted-list nullifier registry
- Authenticated state: larger, updatable registries (experimental)
- Application security