Opertus

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:

KeyRevealsWho can produce it
Per-note key KOne note: token, value, memo, and its openingThe sender or the recipient, rebuilt from the seed
Viewing keyEvery 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, clones

Clone 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) + 1

n 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:

FieldBytes
Version (1)1
Recipient meta-address body99
Poly1305 tag16
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.

FieldEncodingRequired
versionNumber, 1Yes
chainIdDecimal stringYes
pool20-byte hex, nonzeroYes
transactionHash32-byte hexYes
logIndexNumberYes
commitment32-byte hex, nonzeroYes
noteKey32-byte hex, KYes
recipientMeta-addressExactly one of recipient and blind
tweak32-byte hex, tOptional, needs recipient
blind32-byte hex, Poseidon(N, blinding)Exactly one of recipient and blind

What each variant proves:

VariantProves
recipient and tweakThis value of this token was committed to this meta-address, and only its spend key can spend it
recipientThis value of this token was committed with this recipient's N
blindThis 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:

  1. Parse the receipt. Reject unknown fields, uppercase or malformed hex, wrong lengths, a zero pool or commitment (format), and versions other than 1 (version).
  2. Reject a receipt for another chain (chain) or another pool (pool).
  3. Fetch the transaction receipt. Require success, a log at logIndex emitted by the pool, and a NoteCommitted or ReturnShielded event (log). Take the commitment from the log's indexed commitment topic, never from the encrypted payload (log if it is missing).
  4. Require the log's commitment to equal the receipt's (commitment).
  5. 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 from ReturnShielded (decrypt).
  6. For a return note, require the decrypted token and ownerPubKey to equal the ReturnShielded fields (commitment).
  7. Take blind from the receipt, or compute Poseidon(N, blinding) with N from recipient. For a return note, take the value from ReturnShielded. Recompute Poseidon(token, value, ownerPubKey, randomness, blind) and compare (commitment).
  8. With a tweak, check Poseidon(spendPub + t · Base8) = ownerPubKey (owner).
  9. Look for an earlier NoteCommitted or ReturnShielded log from the pool with the same commitment, at a lower leaf index. If there is one, the receipt is valid but marked duplicate.

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 ReceiptError code a verifier must return.

Bigints are {"$bigint": "0x.."} and byte strings {"$bytes": "0x.."}. npx tsx scripts/genDisclosureVectors.ts in the wallet package regenerates it.

On this page