All public packages use the @arcanetech scope and are published on npm. Install the Stellar preset, a state adapter, and the optional Protocol Relay runtime explicitly. No additional cryptography packages are required for browser or Node.

​
Package map

@arcanetech/privacy-sdk-stellar ships bundled runtime assets for browser and Node. Pass network configuration, a wallet adapter, a state adapter, and policy — the preset handles the rest. For private sender or escrow sends, add @arcanetech/privacy-sdk-relay — see Protocol Relay package.

​
Layered architecture

  • Core — intents, prepare/execute lifecycle, errors, progress events.
  • Relay — Protocol Relay runtime: admission, polling, retry, and fallback over caller-supplied ports. It owns statuses, reason codes, and package JSON serialization, follows a caller-supplied submission path, and never inspects opaque package payloads or deposit amounts. Relaying is enabled only when the caller sets relayConfig.origin; otherwise the runtime Direct-submits and does not contact a relayer. Settlement polling is bounded. The package does not depend on Stellar or Soroban.
  • State adapters — persistence for SDK domain state.
  • Network preset — @arcanetech/privacy-sdk-stellar: client, contract bindings, and state schema extensions.
Internal transitive dependencies are not part of the public integration surface.

​
Entry points and subpaths

Shared packages: Stellar preset:

​
Stellar preset

Use @arcanetech/privacy-sdk-stellar for Stellar with Soroban smart contracts:
  • Pool contract — private deposits, transfers, and withdrawals.
  • Private-address registry — maps public Stellar accounts to private payment addresses.
  • Soroban RPC — submission and confirmation.
  • createStellarPrivacyClient() — main browser entrypoint.
  • requiredSubmissionMethod(prepared, zkConfigNonce?) — Direct Submission vs Protocol Relay for a prepared operation (positive public deposits stay direct; a zero public deposit uses relay). Pass the same zkConfigNonce as the pool (SDK default 3) so public-signal layout matches. Escrow sends require relay and a zero public deposit; a positive public deposit is refused rather than downgraded. Escrow sweeps use Direct Submission so the claimant wallet signs the envelope.
  • buildBlindedRecipientTagChallengeMessage(fields) — wallet-signed challenge string used to issue blinded recipient tags so a recipient can discover escrow notes after they register. See Transfer to unregistered recipient.
Address model: Bootstrap helpers:
  • loadDefaultStellarBrowserAssets() — bundled SDK WASM for the browser. Circuit schemes are selected by zkConfigNonce: 3 (2×2, default) and 7 (6×6).
  • transactEnvironment — network, KYT, optional zkConfigNonce / zkArtifactBaseUrl, and transaction signing hooks passed at client creation.
For React wiring and operation examples, continue to Stellar application development.

​
Protocol Relay package

Install @arcanetech/privacy-sdk-relay when the sender must stay private (zero public deposit) or you send to an unregistered recipient (escrow). Typical deposits keep the sender public and stay on Direct Submission — they do not need this package. The runtime does not depend on Stellar or Soroban.
The package owns admission, lifecycle polling, retry, and consented Direct-submit fallback. Callers supply five required ports (store, submitDirect, finalizeLocalState, drainDeliveries, persistUserTransaction). Relaying is off until relayConfig.origin is set; an unset origin Direct-submits and never contacts a relayer. origin may include a URI path prefix (for example https://payments.example/api). The runtime does not inspect opaque package payloads and has no Stellar, Soroban, or zero-knowledge dependencies. Main exports: createRelayApi, resolveRelayOrigin, submitAndAwaitPrivateOperation, throwIfRelayUnsuccessful, serializeRelayPackage / deserializeRelayPackage, resumePendingOperations, retryFailedRelayAttempt. See Examples for runnable Relay wiring after requiredSubmissionMethod. Operation detail: Withdraw and Transfer to unregistered recipient.

​
Which packages you need

​
Frontend vs backend package set

Runnable demos: Examples.

Set up the SDK

npm install and where live stand values come from.

State adapters

Choose in-memory or Redux state adapters.

Examples

Frontend or backend demo.

Install

Install the Stellar React stack.