Opertus

@opertus/wallet

Keys, encrypted notes, scanning, and IndexedDB note state.

This package derives wallet keys, creates encrypted notes, scans pool payloads, and persists note state in IndexedDB. It does not query a chain or submit transactions. Review keys and notes and the privacy model before exporting keys.

Keys

import { KeyManager } from '@opertus/wallet';

const wallet = KeyManager.fromMnemonic(mnemonic, 0);
const metaAddress = wallet.getMetaAddress();
const viewingKey = wallet.exportViewingKey();

Prop

Type

fromPrivateKey requires exactly 32 bytes encoded as 64 hex characters, with an optional 0x prefix. computeStealthSecret validates the packed BabyJubJub point and verifies that the derived secret matches ownerPubKey; it throws on malformed or mismatched input.

The viewing key decrypts notes and derives their nullifiers, so it reveals wallet activity even though it cannot derive a one-time spend scalar. The outgoing key is derived from it, so the viewing key also reads sent history: it is full read access. getSpendingKey and exportViewingKey allocate strings that wipe() cannot erase; prefer computeStealthSecret and call wipe() when the manager is no longer needed.

Create and scan notes

import { Scanner, Sender } from '@opertus/wallet';

const domain = {
  chainId: BigInt(await publicClient.getChainId()),
  poolAddress: BigInt(poolAddress),
};
const { note, payload, disclosure } = await Sender.prepareSend(
  recipientMetaAddress,
  BigInt(tokenAddress),
  value,
  domain,
  { memo: new TextEncoder().encode('invoice 42'), sender: wallet },
);

Prop

Type

Outgoing records

A note pays its recipient, and the recipient's view key finds it. The sender needs its own copy to rebuild sent history from the seed, so a note paid to someone else carries a 116-byte outgoing record after the ciphertext:

FieldBytes
Version (1)1
Recipient meta-address body99
Poly1305 tag16

The record names only the recipient. A sending wallet derives the note's ephemerals from its outgoing key, so it rebuilds the note key and reads the value and memo from the note itself.

The key is sha256(outgoingKey || viewEphemeral), which is unique per note, so the record reuses the note's nonce. The associated data is the note's view and spend ephemerals, so a record copied onto another note fails to decrypt. Notes to yourself, such as change, get no record; the view key already finds them.

Sender.prepareSend rejects malformed meta-addresses, token IDs outside the BN254 field, values outside [0, 2^120), and domain values that do not fit in 32 bytes. Sender.prepareReturn creates a value-zero return note whose final amount must come from a ReturnShielded event.

Every scanner item needs a commitment in item.commitment, item.metadata.commitment, or payload.commitment.

AspectNormal noteReturn note
Creation APISender.prepareSendSender.prepareReturn
Value at creationKnown and encoded in the noteZero placeholder until the pool measures the return
Ciphertext authenticationEphemeral keys, view tag, chain, pool, and commitmentEphemeral keys, view tag, chain, pool, token, and owner key
Scan-time valueRecovered from the encrypted noteFilled from the ReturnShielded event
Integrity checkRecompute and match the supplied commitmentInsert the measured value, then recompute and match the emitted commitment

A view tag is only an early rejection filter; authenticated decryption and commitment recomputation provide integrity.

Receipts

A receipt discloses one note and nothing else. Either side builds it from its seed: the recipient through its viewing key, the sender through its outgoing key. Anyone verifies it against the pool log. See selective disclosure for the format and the verification algorithm.

import { createReceipt, encodeReceipt } from '@opertus/wallet';

// `item` is a getLogs payload; its metadata carries transactionHash and logIndex.
const receipt = createReceipt(wallet, item, domain, { proveRecipient: true });
const shareable = encodeReceipt(receipt);

Prop

Type

A receipt reveals its note's token, value and memo, and lets the holder find the transaction that created it. It does not reveal whether the note was spent or any other note. Anyone who holds the note key can show the receipt, so it proves a payment, not who made it.

Spend-time note preparation

Derive the one-time spend secret

const [record] = found;
record.note.payload.ownerSecret = wallet.computeStealthSecret(
  record.spendEphemeralPubKey,
  record.note.payload.ownerPubKey!,
);

Recompute spend identifiers

record.commitment = record.note.getCommitment();
const nullifier = record.note.getNullifier();

Prop

Type

If both ownerSecret and ownerPubKey are present, getCommitment checks that they match. The memo is serialized but never part of the commitment.

Browser storage

import { StorageDB } from '@opertus/wallet';

await StorageDB.saveNote({ ...record, commitment: record.commitment });
const unspent = await StorageDB.getUnspentNotes();
await StorageDB.markAsSpent(record.commitment);

Prop

Type

Storage is a cache. Restoring from the seed resyncs from the pool's deploy block and rebuilds every store. Storage uses the global browser indexedDB. saveNote requires a computed commitment, deduplicates by commitment, and strips ownerSecret and nk before persistence. Re-derive both at spend time after loading a stored note. markAsSpent is a no-op when the commitment is absent.

On this page