Skip to content

Tell chosen readers (confidential notes)

View Markdown

Use this when named parties must be able to read a hidden value from the chain: the owner of a balance, so a lost wallet can recover it, and an auditor, so oversight doesn’t depend on a side channel.

A confidential note is a Pedersen commitment plus its opening, encrypted separately for each reader, in the same transaction output. Each reader has a viewing key. Their wallet scans the chain, opens the delivery addressed to them, and accepts the value only if it recomputes the commitment. To everyone else, a note is a commitment and 89 bytes of ciphertext per reader.

Confidential note · step 1 / 5
Sendercreates the note
amount vSECRETHIDDEN250████████
blinding rSECRETHIDDEN0xac0e…97b1████████
Seals the opening (v, r) once per reader✉ to the owner's reader key, fresh one-time key✉ to the auditor's reader key, fresh one-time key

Done. The sender can go offline; nothing is sent privately.

Cardanothe note's datum

Waiting for the note.

commitment CPUBLIC0xd1c1…bab7
delivery 0 · owner · 89 bytesPUBLIC0xe97e…c021
delivery 1 · auditor · 89 bytesPUBLIC0x6528…0a76

The validator can only check each delivery's length. It can't tell whether one decrypts.

You hold the…
owner's viewing keySECRETHIDDEN0x540f…aead████████

Each reader published a 32-byte reader key earlier; the viewing key never leaves the wallet.

Opens delivery 0 (its own position)decrypts to (v = 250, r)commit(250, r) = C: accepted
Wallet scan, owner's key
  • Note A…
  • Note B…
  • Note C…
  • Note D…
Notes are matched by the owner field first; only those are opened.

1. Seal

The sender commits to 250 with a random blinding, then encrypts the opening (v, r) separately for each reader: the owner first, then the auditor. Each copy uses a fresh one-time key, as Zcash notes do.

2. Publish

The note goes on-chain: the commitment plus one 89-byte delivery per reader. The public sees a point and random-looking bytes. Switch to the public view to compare.

3. Open

A reader decrypts the delivery at its own position and accepts the opening only if it recomputes C. Pick the owner, the auditor or a stranger. A stranger's key opens nothing.

4. A bad delivery

A careless or hostile sender can write garbage into a delivery, and the ledger can't notice. The owner's wallet finds a note it owns but can't open, and reports it instead of hiding it. The auditor's copy is separate, so the auditor still reads 250. Untick the box to compare.

5. Recover from the chain

A wallet with only its viewing key can rebuild its balance by scanning the ledger: open the notes it owns, skip everyone else's, and flag owned notes that don't open. No private messages are needed.

SECRET only its holder knows itPUBLIC on-chain, anyone can see itPoint and byte values are illustrative.
PartyLearns
SenderThe amount (they created the note)
OwnerThe amount, from delivery 0
Each auditorThe amount, from its own delivery
Everyone elseThe commitment and that deliveries exist; never the amount
ConfidentialNote.java (core)
import org.zeroj.circuit.lib.jubjub.ConfidentialNotes;
import org.zeroj.circuit.lib.jubjub.JubjubPoint;
import org.zeroj.circuit.lib.jubjub.NoteOpening;
import org.zeroj.circuit.lib.jubjub.NoteReaderKey;
import org.zeroj.circuit.lib.jubjub.NoteScanner;
import org.zeroj.circuit.lib.jubjub.NoteViewingKey;
// Each reader creates a viewing key in its own wallet and publishes the 32-byte reader key
NoteViewingKey ownerKey = NoteViewingKey.generate(random);
NoteViewingKey auditorKey = NoteViewingKey.generate(random);
// Sender: commit to 250 and seal the opening for the owner (first) and the auditor
List<NoteReaderKey> readers = List.of(
NoteReaderKey.decode(ownerKey.readerKey().encode()),
NoteReaderKey.decode(auditorKey.readerKey().encode()));
NoteOpening opening = NoteOpening.random(BigInteger.valueOf(250), random);
JubjubPoint c = opening.commitment(); // goes in the datum
List<byte[]> deliveries = ConfidentialNotes.seal(opening, readers, random); // 2 x 89 bytes
// Owner and auditor each open their own position against the note's (u, v)
Optional<NoteOpening> mine = NoteScanner.of(ownerKey).open(deliveries.get(0), c.affineU(), c.affineV());
Optional<NoteOpening> audited = NoteScanner.of(auditorKey).open(deliveries.get(1), c.affineU(), c.affineV());
// both hold 250; anyone else's key gets Optional.empty()

The complete program, wallet scanning and the rules for wallets are in the Confidential notes guide.

  • Confidential loyalty points. Holders recover their balances from the chain; an auditor reads every amount. (use case)
  • Payroll. Each payslip is readable by the employee and the tax authority, nobody else. (use case)
  • Proof of solvency. Each customer opens their own committed balance from the attestation, and the auditor opens only the total. (use case)
  • Escrow and invoicing. A buyer, a seller and an arbitrator can each read a confidential invoice amount.
  • The sender must not be able to lie to the auditor. On-chain, a validator can only check that a delivery of the right length exists, not that it opens. A dishonest sender can deliver garbage. The reader notices (“unopenable”), but if the auditor’s copy has to be guaranteed, also encrypt for the auditor with a proof.
  • The reader should only see a total. Use split trust.
  • Report unopenable notes. A note you own but can’t open is value you can’t spend. Wallets must show it, never drop it.
  • Scan in your own process. The viewing key reads every past delivery to it, so never hand it to a shared scanning service. There’s no forward secrecy.
  • Open only your own position, and check the note’s owner field and script address yourself.
  • Maturity. Experimental. The delivery’s security assumptions (A1–A3) await external review.