# Confidential loyalty points

> Customers hold and move loyalty points with hidden amounts on Cardano, wallets recover their balances from chain data, and an auditor can still read every amount.

Canonical URL: https://zeroj.dev/use-cases/confidential-points/

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.

_The web version of this page has an interactive illustration here._

## The zero-knowledge idea

**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](https://zeroj.dev/learn/commitments-and-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.

## What stays private, what's public

| Value | Who can see it | Why |
|---|---|---|
| Amount of each note | Owner and auditor | Hidden from the public by the commitment, until it's redeemed (see below) |
| Blinding `r` | Owner and auditor | Part of the opening; inside the deliveries |
| Viewing keys and spending keys | Their holder only | Open deliveries; sign spends |
| Auditor's ElGamal secret key | Auditor only | Decrypts the limbs |
| Commitment `(u, v)` | Public | Stored in the note datum |
| Owner (key hash) | Public | The ledger checks the owner's signature on a spend |
| Deliveries and audit limbs | Public, but unreadable without a key | Stored in the note datum |
| Redemption price | Public | The shop is paid a visible amount |
| Auditor's public keys and generation | Public | Published 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.

## How it works

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

## The circuit

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.

```java title="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.

## Recovering notes from the chain

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:

```java title="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.

## On Cardano

- **`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`):

| Transaction | CPU steps (of per-tx limit) | Memory | Fee |
|---|---|---|---|
| Transfer (one note in, two out) | 75.8% | 13.8% | about 1.16 ADA |
| Redeem | 57.8% | 11.5% | about 0.98 ADA |
| Trusted issue (one note) | 2.1% | 4.3% | about 0.47 ADA |
| Registry init / rotate | 76.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.

## Security considerations

- **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](https://zeroj.dev/use-cases/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](https://zeroj.dev/learn/trusted-setup/).
- **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.

## Try it

The demo is the **A. Confidential points** tab of the [`pedersen-commitments`](https://github.com/bloxbean/zeroj-usecases/tree/main/pedersen-commitments) app in zeroj-usecases. With Yaci DevKit
running (see [Run the demos](https://zeroj.dev/use-cases/overview/#run-the-demos)):

```bash
./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.

## Related

- [Commitments & encryption, explained](https://zeroj.dev/learn/commitments-and-encryption/)
- [Choose how to disclose](https://zeroj.dev/selective-disclosure/)
- [Share with chosen readers](https://zeroj.dev/selective-disclosure/share-with-chosen-readers/) and
  [Hide a number](https://zeroj.dev/selective-disclosure/hide-a-number/)
- [Confidential notes guide](https://zeroj.dev/guides/confidential/confidential-notes/) and
  [Pedersen commitments guide](https://zeroj.dev/guides/confidential/pedersen/)
- [Confidential payroll](https://zeroj.dev/use-cases/confidential-payroll/): the same ledger with proved issuance
