The SDK reads and writes these objects during prepare and execute. On Stellar, public wallets use G... accounts and private payment addresses use stpl1....

​
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 still use a public wallet to, but the on-chain transfer looks like a private send.

​
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 Stellar preset uses this binding when building transactions. Populate the catalog from your backend in production — see State methods.

​
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 State methods.

​
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.

​
Escrow notes (unregistered recipient)

When you transfer to an unregistered recipient (public wallet to), the preset derives an escrow note owner from a nonce and the recipient G-address. The send stays indistinguishable from a private transfer. Escrow sends require Protocol Relay. After the recipient registers, they discover notes with blinded recipient tags and sweep with Direct Submission. See Transfer to unregistered recipient.

​
Entity relationships

Operations

How deposit, withdraw, and transfer use these entities.

State methods

Where production data for each entity comes from.

Security and privacy

What stays local vs on-chain.