All public packages use the @arcanetech scope and are published on npm. Install the Stellar preset, a state adapter, the private-data client when you read private records, 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. To read private records, add @arcanetech/privacy-sdk-data-layer — see Private records package. For private sender or escrow sends, add @arcanetech/privacy-sdk-relay — see Protocol Relay package. Public withdraw is publicWithdraw.

​
Layered architecture

  • Plan — a Plan for one asset. Check that it is funded, which Step is underfunded, and whether a Step is executed or blocked. You pass a presence report. This package does not query a chain.
  • Plan progress — show a saved Plan. Call planProgress, readPinnedPresence, and waitingDeposit. Call createPlanClient to compose, revise, and confirm through an automation service. Call createSecretDepositSigner or pass your own signer. Call createSorobanPoolView when you read the pool.
  • Plan service — compose a Plan and run its Steps. Call compose, reviseFreeTokens, insertDeposit, moveDepositAmount, replaceStepInterval, confirm, depositToSign, read, authorizeDeposit, runDueSteps, and submitNextStep. Pass Fee quote, proof, inspect, and pool submit ports, or build them for Stellar from the /stellar entry. createMemoryPlanStore keeps Plans in memory, and composePlanStore combines your own store roles.
  • Core — intents, prepare/execute lifecycle, errors, progress events, and the private-data authorization envelope.
  • Private data — HTTP client for private records. You pass the schemas. find returns records only after your schema accepts the payload. Challenge methods stop before a request when you omit the completion schema.
  • 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, withdrawals, and public withdrawals.
  • publicWithdraw() — spends one private note and pays its full value to the connected wallet. Sender, recipient, asset, and amount are public. See Public withdraw.
  • assessIncomingNote() — reports whether a decrypted incoming note is spendable, still pending, or dead before you credit the balance. See State methods.
  • 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.

​
Private records package

Install @arcanetech/privacy-sdk-data-layer when the app reads private records. Use the release-v0 tag. That tag publishes 0.1.0.
createPrivateDataProvider returns find, createChallenge, and completeChallenge. Pass a Zod schema for each record. Pass a completion schema, a protocol, and an authorizer when the read needs a signed challenge. The provider returns a value only after your schema accepts it. @arcanetech/privacy-sdk-core rejects a challenge or proof that misses the authorization envelope before a request is sent. Omit completionSchema when you only list records. createChallenge and completeChallenge then stop before a request. Supply the record schema, data type, and protocol for your records. After you decrypt an incoming note, call assessIncomingNote before you add it to the spendable balance. To pay a note’s full value to the connected wallet, use Public withdraw.

​
Check a Plan

Decide whether a Plan is funded, which Step is underfunded, and whether a Step is executed or blocked. Install @arcanetech/privacy-sdk-automatization-plan and pass the Plan plus a presence report. Chain reads stay in that report.
See Plan for how a Plan works. See Check funding and Persist Plans for the calls.

​
Show Plan progress

Show each Row of a saved Plan and how far each Step has gone. Install @arcanetech/privacy-sdk-automatization-client and call planProgress with a presence report.
planProgress shows amounts, pinned notes, Free tokens, and whether each Step is executed or blocked. Draft, sign, and submit from Offchain automatization.

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

Offchain automatization

Draft a Plan, sign Deposits, and run scheduled payouts.