Tell chosen readers (confidential notes)
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.
Done. The sender can go offline; nothing is sent privately.
Waiting for the note.
The validator can only check each delivery's length. It can't tell whether one decrypts.
Each reader published a 32-byte reader key earlier; the viewing key never leaves the wallet.
- Note A…
- Note B…
- Note C…
- Note D…
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.
Who learns what
Section titled “Who learns what”| Party | Learns |
|---|---|
| Sender | The amount (they created the note) |
| Owner | The amount, from delivery 0 |
| Each auditor | The amount, from its own delivery |
| Everyone else | The commitment and that deliveries exist; never the amount |
In code
Section titled “In code”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 keyNoteViewingKey ownerKey = NoteViewingKey.generate(random);NoteViewingKey auditorKey = NoteViewingKey.generate(random);
// Sender: commit to 250 and seal the opening for the owner (first) and the auditorList<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 datumList<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.
Real-world uses
Section titled “Real-world uses”- 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.
When not to use it
Section titled “When not to use it”- 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.
Watch out for
Section titled “Watch out for”- 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.