Selective disclosure
Disclose one payment with a per-note key, or a whole history with the viewing key. Specification and test vectors.
Opertus discloses at two levels:
| Key | Reveals | Who can produce it |
|---|---|---|
Per-note key K | One note: token, value, memo, and its opening | The sender or the recipient, rebuilt from the seed |
| Viewing key | Every received note, every sent note (through ovk), and spent status (through nk) | The account owner |
Neither key can spend. Spending needs the one-time spend scalar, which only the holder of the recipient's spend key can derive. Share a receipt for a single payment; share the viewing key only for a full audit.
This page is the specification. The TypeScript wallet is one implementation of it, and test vectors let any other implementation check itself.
Key tree
seed ─┬─ viewPriv (secp256k1) ─┬─ nk = deriveNullifierKey(viewPriv) spent status
│ └─ ovk = sha256("opertus/ovk" || viewPriv) sent notes
└─ spendScalar (BabyJubJub) spending, clonesClone salts are Poseidon(spendScalar, diversifier), so the viewing key does
not reveal which clones belong to the account or what they called.
Per-note key
Every note has two ephemerals: a secp256k1 view ephemeral E = e·G and a
BabyJubJub spend ephemeral R = r·Base8.
viewSecret = keccak256(compressed(e · viewPub)) = keccak256(compressed(viewPriv · E))
viewTag = viewSecret[0..2]
K = HKDF-SHA256(ikm = viewSecret, salt = empty, info = "stealth-note-v1", L = 32)The recipient computes K from its viewing key and E. For the sender to do
the same after a restore, a sending wallet derives e and r from its outgoing
key instead of drawing them at random. The 24-byte nonce is random and drawn first:
e = HKDF-SHA512(ikm = ovk, salt = nonce, info = "opertus/view-esk/v1" || recipientViewPub, L = 64) mod (n - 1) + 1
r = HKDF-SHA512(ikm = ovk, salt = nonce, info = "opertus/spend-esk/v1" || recipientSpendPub, L = 64) mod (l - 1) + 1n is the secp256k1 order and l the BabyJubJub subgroup order. The 64-byte
output makes the reduction unbiased. The recipient key in info gives two notes
with the same nonce different ephemerals when their recipients differ. The view
and spend tags keep the two scalars independent.
A deposit made without a sending wallet uses random ephemerals. The SDK returns
K and the tweak to the caller, who must keep them to disclose that note later.
Stealth tweak
S = r · spendPub = spendScalar · R
t = Poseidon(S.x, S.y) mod l
owner = spendPub + t · Base8
ownerPubKey = Poseidon(owner.x, owner.y)The sender knows r; the recipient knows spendScalar. Revealing t lets a
verifier check ownerPubKey against the recipient's spendPub. Spending needs
spendScalar + t, so t alone is useless to anyone without the spend key.
Outgoing record
A note paid to someone other than the sender carries a 116-byte record after the ciphertext:
| Field | Bytes |
|---|---|
| Version (1) | 1 |
| Recipient meta-address body | 99 |
| Poly1305 tag | 16 |
recordKey = sha256(ovk || E)
record = XChaCha20-Poly1305(recordKey, nonce, plaintext, ad = E || R)To rebuild a sent note, the sender opens the record, derives e and r from
ovk, the nonce and the recipient, checks that they reproduce E and R,
computes K, and decrypts the note itself for its value and memo.
Receipt
A receipt is JSON with fixed-width hex. Hex is lowercase only, so each receipt has one encoding. Unknown fields are rejected.
| Field | Encoding | Required |
|---|---|---|
version | Number, 1 | Yes |
chainId | Decimal string | Yes |
pool | 20-byte hex, nonzero | Yes |
transactionHash | 32-byte hex | Yes |
logIndex | Number | Yes |
commitment | 32-byte hex, nonzero | Yes |
noteKey | 32-byte hex, K | Yes |
recipient | Meta-address | Exactly one of recipient and blind |
tweak | 32-byte hex, t | Optional, needs recipient |
blind | 32-byte hex, Poseidon(N, blinding) | Exactly one of recipient and blind |
What each variant proves:
| Variant | Proves |
|---|---|
recipient and tweak | This value of this token was committed to this meta-address, and only its spend key can spend it |
recipient | This value of this token was committed with this recipient's N |
blind | This value of this token was committed in this log. The recipient is not named |
Verification
The verifier uses its own RPC, and its own chain ID and pool address:
- Parse the receipt. Reject unknown fields, uppercase or malformed hex, wrong lengths, a zero
poolorcommitment(format), and versions other than 1 (version). - Reject a receipt for another chain (
chain) or another pool (pool). - Fetch the transaction receipt. Require success, a log at
logIndexemitted by the pool, and aNoteCommittedorReturnShieldedevent (log). Take the commitment from the log's indexedcommitmenttopic, never from the encrypted payload (logif it is missing). - Require the log's commitment to equal the receipt's (
commitment). - Decrypt the ciphertext with
K. The associated data is the one the sender used. For a normal note it binds the commitment. For a return note it binds the token and owner fromReturnShielded(decrypt). - For a return note, require the decrypted token and
ownerPubKeyto equal theReturnShieldedfields (commitment). - Take
blindfrom the receipt, or computePoseidon(N, blinding)withNfromrecipient. For a return note, take the value fromReturnShielded. RecomputePoseidon(token, value, ownerPubKey, randomness, blind)and compare (commitment). - With a tweak, check
Poseidon(spendPub + t · Base8) = ownerPubKey(owner). - Look for an earlier
NoteCommittedorReturnShieldedlog from the pool with the same commitment, at a lower leaf index. If there is one, the receipt is valid but markedduplicate.
The codes in brackets are the ReceiptError codes the SDK throws.
Duplicate commitments
The pool can log the same commitment twice. Both copies open the same note and share one
nullifier, so only one can ever be spent. A verifier counts a commitment once: a receipt
marked duplicate adds no value, and two receipts naming the same commitment are one payment.
What a receipt reveals
A receipt shows its note and the transaction that created it: the time, the
relayer or depositor, the other output ciphertexts (unreadable), and the input
nullifiers (unlinkable without nk). It does not show whether the note was
spent, who sent it, or any other note. Anyone holding K can show the receipt,
so it proves the payment, not its author. The memo is part of the note and is
disclosed with it.
Receipts do not link payments to each other. Each note has fresh ephemerals, so a recipient holding several receipts cannot tell whether they came from one sender.
Test vectors
test/vectors/disclosure.json in the wallet package
holds, for fixed mnemonics:
- ephemeral derivations:
ovk, nonce, recipient keys,e,r,E,R,K, view tag,t,ownerPubKey; - a sent note, a return note and a deposit without a sender wallet, each with its payload, log metadata, three receipts and the values a verifier must recover;
- failure cases, each with the
ReceiptErrorcode a verifier must return.
Bigints are {"$bigint": "0x.."} and byte strings {"$bytes": "0x.."}.
npx tsx scripts/genDisclosureVectors.ts in the wallet package regenerates it.