Skip to content

Confidential loyalty points

View Markdown

Put a loyalty programme on a public chain and every customer’s balance, every gift to a friend and every purchase becomes public. Anyone can see that Alice holds 1,000 points, sent 700 to Bob and that Bob spent 120 at the shop. Hiding the amounts fixes that, but it creates a new problem. The retailer still has to account for the points it owes, and a regulator or auditor may need to see every amount. Nobody should have to trust a database that the retailer runs.

This page follows a demo in which amounts are hidden from the public. Holders recover their own balances from the chain, and a designated auditor reads every amount. For notes created by a transfer or a redemption, a proof guarantees that what the auditor reads is the real amount.

Points · step 1 / 6
Try to cheat
Walletsretailer · Alice · Bob
Retailer (issuer)Ready to issue points.Issued 1,000 pts to Alice.Received Bob's 120 pts: receipt token.Nothing redeemed yet.told the auditor 100 pts
Alice's balanceSECRETHIDDEN1,000 pts300 pts████████
Bob's balanceSECRETHIDDEN700 pts580 pts0 pts spendable████████
Bob owns a note he can't open: unopenable, reportedboth wallets rebuilt their balances from chain data aloneAlice rebuilt hers from chain data; Bob's scan flags the bad note
π1,000 = 700 + 300Groth16
π700 = 120 + 580Groth16
CardanoNoteLedger UTxOs
AuditorRegistry · generation 0PUBLICPK 0x3dbc…95ea
both possession proofs verified on-chain
N1 · Alice · issued by the retailer · spentC0xc28f…d8d1amount1,000 pts██████owner + auditor deliveries · 2 audit limbs
N2 · Bob · transfer output · spentC0x5a73…550bamount700 pts██████owner + auditor deliveries · 2 audit limbs
N3 · Alice · transfer change · spentC0x248b…ae3aamount300 pts██████owner + auditor deliveries · 2 audit limbs
N4 · Bob · redeem change · spentC0xd73a…31c3amount580 pts██████owner + auditor deliveries · 2 audit limbs
N2's owner delivery is random bytes. The ledger only checks its length.
Auditorregulator or retailer's audit desk
ElGamal key + viewing keySECRETHIDDEN0x3dc3…67f9████████

Registers once. Every note that follows carries its amount encrypted to this key.

Every note, read from chain
N1 · Aliceissuer-claimed1,000 pts100 pts (delivery: 1,000 pts)████████
N2 · Bobproof-enforced700 pts████████
N3 · Aliceproof-enforced300 pts████████
N4 · Bobproof-enforced580 pts████████
N1 mismatch: the limbs and the auditor's own delivery disagreeN2 still reads 700 pts: the limbs are what the proof enforces

1. Register the auditor

The auditor publishes two keys in a one-of-a-kind registry UTxO: an ElGamal key for amounts and a viewing key for deliveries. The registry validator checks a proof that the auditor really holds each key.

2. Issue

The retailer issues 1,000 pts to Alice as a note: a Pedersen commitment, its opening sealed for Alice and for the auditor, and the amount encrypted to the auditor. Issuance is trusted for points, so nothing proves the auditor's copy is right. Here the retailer lies and encrypts 100 pts. The ledger accepts it.

3. Transfer

Alice sends Bob 700 pts. Her wallet spends N1 and creates N2 for Bob and N3 as her change. The proof shows 1,000 pts = 700 pts + 300 pts without showing any amount, and that each new note's encrypted limbs hold its real amount. Alice puts random bytes where Bob's delivery belongs. The ledger can't tell.

4. Redeem

Bob spends 120 pts at the shop. The price is public; the rest of his note, 580 pts, comes back as a new hidden note.

Bob can't open N2, so he can't build a proof to spend it. The points are his on-chain but stuck.

5. Recover from chain

No server keeps balances. Each wallet scans the ledger's UTxOs and opens the deliveries addressed to its viewing key, keeping only notes that name it as owner and that open to their commitment. A note Bob owns but can't open is reported, not ignored: it's evidence against the sender.

6. Audit

The auditor decrypts every note's limbs and cross-checks its own delivery. Notes created by a transfer or redeem are proof-enforced; the issued note is issuer-claimed. The lie shows up as a mismatch, but only because the retailer's delivery told the truth; the ledger didn't stop it. Payroll uses proved issuance to close that gap.

SECRET readable only with the right keyPUBLIC on the chain for anyone"Alice & Bob" combines both wallets: each one reads only its own notes.Commitment and key values are illustrative.

Each holding is a note on-chain: a sealed amount that the owner and the auditor can open, and that a proof keeps honest when it moves.

A note has three parts:

  • A Pedersen commitment C = v·G + r·H to the amount v with a random blinding r. It hides the amount, and the owner can’t later claim a different one. Commitments add up, so a proof can show that a spent note equals the notes it creates. See Commitments & encryption.
  • Sealed openings. The opening (v, r) is encrypted on-chain twice: once to the owner’s viewing key and once to the auditor’s. Each sealed copy is an 89-byte delivery. A reader accepts an opening only if it recomputes the commitment.
  • Audit limbs. The amount is also split into two 32-bit halves, and each half is encrypted to the auditor’s ElGamal key. The transfer proof shows that these limbs encrypt exactly the committed amount, so the auditor’s view is enforced, not just delivered.

Moving points is a proof: “the note I spend holds exactly as much as the two notes I create, and each new note’s limbs encrypt its amount”. The verifier sees only commitments and ciphertexts.

ValueWho can see itWhy
Amount of each noteOwner and auditorHidden from the public by the commitment, until it’s redeemed (see below)
Blinding rOwner and auditorPart of the opening; inside the deliveries
Viewing keys and spending keysTheir holder onlyOpen deliveries; sign spends
Auditor’s ElGamal secret keyAuditor onlyDecrypts the limbs
Commitment (u, v)PublicStored in the note datum
Owner (key hash)PublicThe ledger checks the owner’s signature on a spend
Deliveries and audit limbsPublic, but unreadable without a keyStored in the note datum
Redemption pricePublicThe shop is paid a visible amount
Auditor’s public keys and generationPublicPublished in the registry

Amounts are hidden; the transfer graph is not. Anyone can see that Alice’s note was spent in the same transaction that created a note owned by Bob.

Redeeming tells observers something about the note it spends, because the price is public. Redeeming a whole note (price equal to its amount, no change) publishes the note’s amount. A partial redemption shows that the note held at least the price.

  1. Register the auditor. The auditor publishes an ElGamal public key and a viewing key in a registry UTxO that holds a one-of-a-kind token. The registry validator verifies a proof that the auditor holds each secret key. Rotating the keys bumps a generation number.
  2. Issue. The retailer creates a note for Alice: a commitment to 1,000, deliveries for Alice and the auditor, and the auditor limbs. For points, issuance is trusted: nothing proves that the limbs match the commitment.
  3. Transfer. Alice sends Bob 700. Her wallet spends her note and creates a 700 note for Bob and a 300 note for herself, with a proof that 1,000 = 700 + 300 and that each new note’s limbs encrypt its amount under the current auditor key.
  4. Redeem. Bob spends 120 at the shop. The price is public; a proof shows his note covers it and returns 580 as a new hidden note.
  5. Recover. Each wallet scans the ledger’s UTxOs and opens the deliveries meant for it. No server keeps balances.
  6. Audit. The auditor decrypts every note’s limbs, cross-checks its own delivery, and labels each note proof-enforced (created by a transfer or redemption) or issuer-claimed (issued).

This is the core of the demo’s NoteTransferProof (one note in, two out), with the audit-limb helper inlined for the first output. Amounts are 64-bit, blindings and ElGamal randomness are 252-bit, and limbs are 32-bit.

NoteTransferProof.java (core)
// Each note's opening must produce its public commitment (u, v).
var in = ZkPedersenCommitment.commit(zk, inAmount, inBlinding);
var out1 = ZkPedersenCommitment.commit(zk, o1Amount, o1Blinding);
var out2 = ZkPedersenCommitment.commit(zk, o2Amount, o2Blinding);
in.assertAffineEquals(zk, inU, inV);
out1.assertAffineEquals(zk, o1U, o1V);
out2.assertAffineEquals(zk, o2U, o2V);
// in = out1 + out2 as whole numbers (the gadget refuses layouts that could wrap around).
ZkPedersen.assertBalanced(zk,
List.of(ZkPedersen.Term.of(in)),
List.of(ZkPedersen.Term.of(out1), ZkPedersen.Term.of(out2)));
// The auditor's key is a public input that the validator takes from the registry.
var key = ZkElGamalPublicKey.fromVerifierFixedPublic(zk, pkU, pkV);
// amount = L0 + 2^32·L1, and each limb is encrypted to the auditor's key (repeated for out2).
o1L0.asField().add(o1L1.asField().mul(zk.constant(TWO_32))).assertEqual(o1Amount.asField());
ZkElGamal.encrypt(zk, o1L0, o1K0, key).assertAffineEquals(zk, o1a0u, o1a0v, o1b0u, o1b0v);
ZkElGamal.encrypt(zk, o1L1, o1K1, key).assertAffineEquals(zk, o1a1u, o1a1v, o1b1u, o1b1v);

The full circuit has 24 public inputs: the three commitments, the auditor’s key and the 16 coordinates of the four limb ciphertexts. It compiles to 34,184 constraints. The redeem circuit, with a public price, has 18,366.

Why two 32-bit limbs instead of one 64-bit ciphertext? Decrypting exponential ElGamal ends in a search for a small number. The auditor can search 2³² values quickly with a lookup table; 2⁶⁴ is out of reach.

A wallet doesn’t need a server to know its balance. It reads the note UTxOs at the ledger address and hands the owner deliveries to ZeroJ’s NoteScanner with its viewing key:

Wallet scan
List<NoteScanner.Candidate> candidates = new ArrayList<>();
for (var note : ledgerNotes) { // read from the chain: datum fields of each note UTxO
boolean mine = Arrays.equals(note.owner(), myKeyHash);
candidates.add(NoteScanner.Candidate.of(note.ownerDelivery(), note.u(), note.v(), mine));
}
NoteScanner.Scan scan = NoteScanner.of(myViewingKey).scan(candidates);
scan.opened(); // openings that recompute their commitment: spendable if the note names you
scan.unopenableOwned(); // notes that name you as owner but don't open: report these

A note counts as yours only if it names your key hash as owner and its delivery opens to its commitment. A note you own but can’t open is reported rather than skipped. On-chain the ledger can only check a delivery’s length, so a sender could put random bytes there; the unopenable note is your evidence.

The auditor works from the same chain data. It decrypts the two limbs of each note with its ElGamal key and opens its own delivery with its viewing key, then compares the two. For a proof-enforced note the limbs are guaranteed. For an issued note they are only the issuer’s claim, and a disagreement with the delivery is flagged.

Scanning decrypts data that anyone can put on-chain. Run it in the user’s own wallet process, not on a shared server. The demo’s server scans on its wallets’ behalf for convenience.

  • NoteLedger is one JuLC multi-validator: it mints the note tokens (issue, split, receipt) and guards the note UTxOs (transfer, redeem). It verifies the Groth16 proofs and requires the owner’s signature on a spend. It also reads the auditor key from exactly one registry reference input and rejects limbs encrypted to a retired key.
  • Exact-address policy. Every output under the ledger’s payment credential must sit at the ledger’s exact enterprise address and hold only ADA and one note token. A note sent to a variant of the address with a stake credential is rejected.
  • AuditorRegistry holds the auditor’s keys under a one-shot token, so there is only ever one current entry. Registration and rotation verify two key-possession proofs on-chain.
  • Datum size. A note’s datum is about 0.6 KB (commitment, generation, eight limb coordinates and two 89-byte deliveries), so each note UTxO holds about 3.5 ADA.

Measured on Yaci DevKit for the complete transaction (zeroj-usecases ADR-0007 r3, fee figures with mainnet protocol parameters after commit 814b2f0):

TransactionCPU steps (of per-tx limit)MemoryFee
Transfer (one note in, two out)75.8%13.8%about 1.16 ADA
Redeem57.8%11.5%about 0.98 ADA
Trusted issue (one note)2.1%4.3%about 0.47 ADA
Registry init / rotate76.8% / 77.2%6.2% / 6.9%about 1.22 / 1.23 ADA

These figures were measured before ZeroJ PRs #85 and #86 reduced the on-chain Groth16 verifier’s decompression cost, and haven’t been re-measured since, so 0.1.0-pre13 and later should come in somewhat lower.

  • Points issuance is trusted. The retailer chooses what to encrypt for the auditor when it issues, and the ledger can’t check it. The auditor labels such notes issuer-claimed. The confidential payroll demo uses proved issuance instead, so an employer can’t under-report a salary.
  • Deliveries are only length-checked on-chain. A sender can give the recipient a delivery that doesn’t open. The recipient’s wallet reports the note as unopenable, but the points are stuck. The auditor’s limbs are the part a proof enforces.
  • Redemptions reveal amounts. The price is public, so redeeming a whole note publishes its amount, and a partial redemption shows the note held at least the price.
  • The transfer graph is public. Owners are key hashes in the datum, so who paid whom is visible even though the amounts aren’t.
  • Key custody in the demo. The demo server holds every wallet’s keys and the auditor’s keys, and scans on their behalf. Its API is the operator’s view, so the privacy described here holds against chain and mempool observers, not against the demo server. A real deployment keeps viewing keys and scanning in each user’s wallet, and the auditor’s keys with the auditor.
  • Development trusted setup. The demo’s Groth16 keys come from a single-party setup. Whoever ran it could forge proofs. See Trusted setup, explained.
  • Unreviewed assumptions. ZeroJ’s confidential-note profile rests on assumptions (A1–A3 in ADR-0055) about delivering the same opening to several readers, which still await external review. Nothing here is audited.

The demo is the A. Confidential points tab of the pedersen-commitments app in zeroj-usecases. With Yaci DevKit running (see Run the demos):

Terminal window
./demo.sh pedersen --run
# opens http://localhost:8093; --run plays a happy path in every tab, starting with points:
# 1,000 issued to Alice, 700 moved to Bob, and a redemption by Bob

To run it without Docker, use Java 25 and ./gradlew -p pedersen-commitments bootRun -PwithFrontend from the repository root.

The first start compiles the circuits and runs development setups, which takes a few minutes; later starts reuse the cached keys. In the tab, issue points to Alice, transfer to Bob and redeem. Then try the cheats: transfer more than a note holds (no proof exists), send a garbage delivery, under-report an issuance, encrypt limbs to a retired auditor key, or send a note to a stake-variant address. The ledger evaluates rejected transactions locally and doesn’t submit them.