Transaction lifecycle

Every deposit, transfer, and withdraw call prepares an operation. Check its status, then choose direct submission or Protocol Relay. The execute stages below describe direct submission.

Two-phase model

Phase	When	What happens
Prepare	`await client.deposit(intent)` (or transfer/withdraw)	Validate intent, read SDK state, check disclosure policy, plan consumed/output records
Execute	`await operation.execute(options)`	Wallet authorization, build transaction, compliance checks, submit, confirm, persist state

Prepare runs before the wallet prompt so validation errors (insufficient_state, unsupported_disclosure) surface without a signature request. Execute is one-shot — calling execute() twice on the same prepared operation throws an execution error.

Prepare outcomes

Rejected

const operation = await client.withdraw(intent);

if (operation.status === 'rejected') {
  for (const error of operation.errors) {
    console.error(error.code, error.message);
  }
  return;
}

Do not call execute() when status === 'rejected'. Inspect operation.errors — an array of structured PrivacySdkError values.

Prepared

When status === 'prepared', the operation includes:

Property	Meaning
`kind`	`deposit`, `transfer`, or `withdraw`
`intent`	Echo of your input for confirmation screens
`prepared`	Plan: selected notes, expected outputs, transact artifacts
`execute()`	Async function — run once to submit the transaction

The prepared payload is useful for advanced UI (showing change amounts). You can treat it as opaque for a basic integration.

Execute flow and progress events

Pass onEvent to receive stage updates during execute:

await operation.execute({
  onEvent(event) {
    if (event.status === 'begin') {
      console.log(`Starting ${event.stage}`);
    }
    if (event.status === 'error' && event.error) {
      console.error(event.error.code, event.message);
    }
  },
});

Stage	Typical activity
`validation`	Final intent checks
`stateRead`	Load private records, pool snapshot, registry cache
`authorization`	Wallet message or transaction signing
`preparation`	Build private transaction payload
`policyCheck`	Disclosure and compliance validation
`submission`	Submit to Stellar
`confirmation`	Wait for inclusion/finality
`storageCommit`	Write updated records and pool state locally

You can also pass signal: AbortSignal to cancel long-running execute work.

Direct Submission vs Protocol Relay

operation.execute() is Direct Submission: the connected wallet (or server keypair) signs and the transact engine submits to Soroban. It never calls @arcanetech/privacy-sdk-relay. After prepare, choose the path with requiredSubmissionMethod from @arcanetech/privacy-sdk-stellar/transact. Pass the same zkConfigNonce as the pool (SDK default 3n when omitted; demos use 7n):

Method	When	What to call
`direct`	Positive public deposit (typical deposit); escrow sweep	`operation.execute()`
`relay`	Zero public deposit (private sender) or escrow send to an unregistered recipient	Build a relay package and submit through `@arcanetech/privacy-sdk-relay` — do not call `execute()`

Relaying is off until relayConfig.origin is set. An unset origin Direct-submits a typical deposit and never contacts a relayer. An escrow send without origin fails with escrow_relay_unconfigured — it is not downgraded to Direct. Runnable wiring: Examples. Operation examples: Withdraw, Transfer to unregistered recipient.

Error model

Code	Typical cause	Recoverable
`unsupported_disclosure`	Disclosure combo not allowed for this route	Yes — adjust disclosure
`missing_dependency`	Client missing wallet, state, network, or policy	Yes — fix bootstrap
`invalid_intent`	Malformed or inconsistent intent field	Yes — fix user input
`insufficient_state`	Missing notes, stale pool root, unknown recipient	Yes — sync state and retry
`user_rejected`	Wallet declined signing	Yes — user can retry
`execution_error`	Submission or confirmation failed	Usually no — inspect `stage`
`unsupported_operation`	Operation not implemented	No

Prepare-time errors appear in operation.errors when status === 'rejected'. Execute-time errors arrive through progress events (status: 'error') or as thrown/rejected promises from execute().

Persisted state after success

On the storageCommit stage the SDK updates local domain state:

mark spent private records as consumed
insert new output records (recipient note, change note)
refresh pool commitment snapshot
append delivery metadata when configured

Save private records using protected storage scoped to the account and network. Restore them before preparing a spend. Redux alone does not preserve state across reloads. See State adapters and Frontend integration.

Operations

What each operation kind does.

State adapters

Why prepare reads SDK state.

Disclosure policy

Policy errors during prepare and execute.

Examples

Frontend or backend demo with Direct and Relay.

Introduction

Compliance Platform

Privacy Layer

Custom KYT providers

Support

Transaction lifecycle

Two-phase model

Prepare outcomes

Rejected

Prepared

Execute flow and progress events

Direct Submission vs Protocol Relay

Error model

Persisted state after success

Operations

State adapters

Disclosure policy

Examples

​Two-phase model

​Prepare outcomes

​Rejected

​Prepared

​Execute flow and progress events

​Direct Submission vs Protocol Relay

​Error model

​Persisted state after success

​Related

Operations

State adapters

Disclosure policy

Examples

Two-phase model

Prepare outcomes

Rejected

Prepared

Execute flow and progress events

Direct Submission vs Protocol Relay

Error model

Persisted state after success

Related