Before writing integration code, understand the domain objects the SDK reads and writes. These concepts are multi-chain — address formats and contract names depend on your network preset.

​
Address types

Typical patterns:
  • Deposit — from public wallet, to private payment address.
  • Withdraw — from private payment address, to public wallet.
  • Transfer — both sides are usually private payment addresses; unregistered recipients use a public wallet to with onboarding at execute time.

​
Private address registry

The registry links public wallet owners to their private payment addresses. The SDK caches registry lookups in local state so prepare can resolve recipients without a round trip on every click.

​
Assets and pool binding

Your asset catalog maps human-readable asset IDs (for example usdc) to on-chain token identifiers and the privacy pool contract that holds notes for that asset. The preset uses this binding when building transactions. Populate the catalog from your backend in production — see Data sources.

​
Private records (notes)

A private record represents spendable balance inside the pool: After a successful withdraw or transfer, spent records are marked consumed and change notes may appear as new records.

​
Pool state

The pool maintains a Merkle structure of commitments. The SDK caches:
  • commitment list and count
  • current Merkle root hash
  • last update timestamp
Prepare reads this snapshot to validate that notes reference the current pool state. Sync the snapshot from chain events or your indexer — see Data sources.

​
Wallet secrets in state

Each wallet owner may have:
  • a private address record (nonce, private payment address, creation time)
  • a scalar derived from wallet authorization — used during transaction preparation
These values never leave the client in plaintext and must not appear in server-side responses your app exposes.
Treat wallet scalars and coinNote secrets like private keys. Persist them only through your chosen state adapter and per-wallet storage policy.

​
Pending claims

When you transfer to an unregistered recipient (public wallet to), the preset can attach an onboarding payload at execute time. The recipient later registers and claims the pending note through your application flow. Preset-specific hooks for this path are documented in Transfer to unregistered recipient.

​
Entity relationships

Operations

How deposit, withdraw, and transfer use these entities.

Data sources

Where production data for each entity comes from.

Security and privacy

What stays local vs on-chain.