Frontend integration

Frontend example on GitHub

Follow the React and TypeScript application: connect a wallet, deposit XLM, send private transfers, and withdraw.

This guide follows the example’s SDK integration. Transactions run in the browser, and Freighter signs through Stellar Wallets Kit. React and Redux are choices made by the example, not requirements of the Arcane Privacy SDK.

Run the example

Use Node.js 20 or later and a browser with Freighter installed. Select Stellar testnet in the wallet and fund the account with test XLM.

git clone https://github.com/arcanetechhq/pl-frontend-sdk-demo.git
cd pl-frontend-sdk-demo
cp .env.example .env
npm install
npm run dev

The example uses test application 3722412212248783. Keep the matching settings from its environment file. See Set up the SDK to register your own application. In the app, connect Freighter, select Create private address (or Restore), and make a small Deposit. Then try Transfer and Withdraw.

Connect the SDK

Client setup connects five inputs:

Network and application configuration from .env.
The connected wallet’s address and signing functions.
The SDK state adapter.
The browser runtime asset.
KYT and transaction-submission configuration.

The example calls resolveStellarPrivacyClientConfig, checks the result, and creates the client with createStellarPrivacyClientFromResolvedConfig. It also loads the XLM asset configuration with upsertAssets. Use bootstrapPrivacyClient() from the example to initialise that setup. Later operations obtain the same client through getPrivacyClient(). These are application helpers, not SDK exports.

Connect state to the UI

The example uses @arcanetech/privacy-sdk-state-redux. The core wiring in store.ts is:

import { configureStore } from '@reduxjs/toolkit';
import {
  bindReduxStateAdapter,
  createReduxStateAdapter,
} from '@arcanetech/privacy-sdk-state-redux';

const privacySdkState = createReduxStateAdapter({
  reducerPath: 'privacySdkState',
});

const store = configureStore({
  reducer: { [privacySdkState.reducerPath]: privacySdkState.reducer },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware({ serializableCheck: false })
      .concat(privacySdkState.middleware),
});

bindReduxStateAdapter(privacySdkState, store);

Pass privacySdkState.adapter as the client’s state. The full example also initialises the state and restores the connected account’s saved snapshot. If your frontend does not use Redux, use @arcanetech/privacy-sdk-state-memory and update your UI after operations. In either case, saving and restoring account data is an application responsibility.

Create or restore a private address

Private-address setup asks the wallet to sign an SDK-generated message, derives the private address, saves the account data, and checks its registration. The example exposes createOrRestorePrivateAddress(owner) for this flow. Restore an existing address rather than treating a fresh browser store as a new account. This user-account step is separate from the test application’s registration.

Deposit funds

operations.ts exposes runDeposit, runTransfer, and runWithdraw. These helpers include pool synchronisation, preparation checks, and submission. Call them from your UI after account setup:

import { runDeposit } from '@shared/api/privacy';

await runDeposit({
  owner: connectedWalletAddress,
  amount: 10_000_000n, // 1 XLM in stroops
  onEvent: (message) => setStatus(message),
});

The import above belongs to the example application. Inside runDeposit, the SDK prepares the operation with:

const operation = await client.deposit({
  from: input.owner,
  to: privateAddress,
  asset: env.assetId,
  amount: input.amount,
  disclosure: {
    senderAddress: 'public',
    recipientAddress: 'private',
    assetAddress: 'public',
    amount: 'public',
  },
});

The submission helper uses direct submission for this deposit. Approve the wallet prompts and wait for confirmation before showing success.

Transfer and withdraw

Use the same application helpers for the next operations:

import { runTransfer, runWithdraw } from '@shared/api/privacy';

await runTransfer({
  owner: connectedWalletAddress,
  recipient: recipientAddress,
  amount: 1_000_000n, // 0.1 XLM
  onEvent: (message) => setStatus(message),
});

// Withdraw to the connected wallet.
await runWithdraw({
  owner: connectedWalletAddress,
  amount: 1_000_000n,
  onEvent: (message) => setStatus(message),
});

A transfer accepts a private stpl1 address or a Stellar G address. The example resolves whether the recipient is registered and selects the corresponding transfer flow. Transfers and withdrawals in this example keep the sender private and use Relay. Keep the submission helper connected; calling execute() directly is not a substitute for Relay.

Preserve account state

The example restores and saves an account-scoped snapshot so a page refresh does not discard its private records. When accounts change, it loads the selected account’s state.

The example stores private account data in browser local storage, including spending material. Treat it as a test application, not a secure-storage template for real funds. Its incoming-note mailbox is also local to the browser; it does not deliver notes across devices.

For your application, choose protected storage and a delivery mechanism suited to your users. Preserve private records and unresolved transaction state, and isolate accounts and networks.

Explore the implementation

Task	Example source
Configure the client	bootstrap.ts
Create or restore an account	privateAddress.ts
Deposit, transfer, and withdraw	operations.ts
Submit and track transactions	relay.ts
Save and restore state	store.ts

Introduction

Compliance Platform

Privacy Layer

Custom KYT providers

Support

Frontend integration

Frontend example on GitHub

Run the example

Connect the SDK

Connect state to the UI

Create or restore a private address

Deposit funds

Transfer and withdraw

Preserve account state

Explore the implementation

Frontend example on GitHub

​Run the example

​Connect the SDK

​Connect state to the UI

​Create or restore a private address

​Deposit funds

​Transfer and withdraw

​Preserve account state

​Explore the implementation

Run the example

Connect the SDK

Connect state to the UI

Create or restore a private address

Deposit funds

Transfer and withdraw

Preserve account state

Explore the implementation