Quick start (Stellar preset)

This tutorial walks through a minimal Stellar preset integration using an in-memory state adapter — no Redux, no React provider. It is a learning exercise, not a production app layout. For full React wiring, see Setup.

What you will build

A short script that:

Creates a Stellar privacy client with in-memory state.
Seeds the minimum fixture data prepare expects.
Calls deposit, checks the prepare result, and runs execute with progress logging.

Prerequisites

Node.js 20.10 or later
Packages: @arcanetech/privacy-sdk-stellar, @arcanetech/privacy-sdk-state-memory

npm install @arcanetech/privacy-sdk-stellar @arcanetech/privacy-sdk-state-memory

Need Redux and React too? See Install.

Step 1 — In-memory state adapter

The SDK keeps domain data — private records, pool snapshot, registry cache, wallet keys — that prepare reads to decide whether an operation is valid. If notes, pool root, or wallet secrets are missing or stale, prepare returns rejected with insufficient_state instead of opening the wallet. An in-memory adapter stores this data in process memory. It is ideal for tutorials and unit tests; it does not survive reloads.

You pass the adapter to createStellarPrivacyClient as state. The SDK reads and updates domain data through the adapter library — you do not implement low-level storage APIs yourself.

import { createInMemoryStateAdapter } from '@arcanetech/privacy-sdk-state-memory';

const state = createInMemoryStateAdapter();

Step 2 — Wallet stub

The Stellar preset signs through a wallet adapter. Replace this stub with your wallet SDK in production.

import type { StellarWalletAdapter } from '@arcanetech/privacy-sdk-stellar';

const wallet: StellarWalletAdapter = {
  getAddress: async () => 'GDSENDER7EXAMPLEPUBLICKEYAAAAAAAAAAAAAAAAAAAA',
  authorizeMessage: async (message) =>
    new TextEncoder().encode(typeof message === 'string' ? message : ''),
  signTransactionPayload: async (payload) => ({ ...payload, signed: true }),
};

getAddress identifies the connected account. authorizeMessage proves control of a private payment address. signTransactionPayload signs the Soroban transaction XDR before submission.

Step 3 — Create the client

Load bundled runtime assets, configure Soroban network contracts, and create the client once.

import {
  createStellarPolicyAdapterFromEnvironment,
  createStellarPrivacyClient,
  isStellarPrivacyClient,
  loadDefaultStellarBrowserAssets,
} from '@arcanetech/privacy-sdk-stellar';
import type { StellarTransactEnvironment } from '@arcanetech/privacy-sdk-stellar/transact';

const transactEnvironment: StellarTransactEnvironment = {
  network: {
    id: 'stellar-testnet',
    rpcUrl: 'https://soroban-testnet.stellar.org',
    networkPassphrase: 'Test SDF Network ; September 2015',
    poolContract: 'CBVQTSTSIJ4UZMN5FQBFHPUIYSW3ATGSP57BZDJNKTOBNQODQTRGE4K5',
    registryContract: 'CCO5QRTS5HFVPR356FFC4NI62IMBQNDGMOAXR4K5UVTV3YMRWDZGKXGC',
    applicationId: '00000000-0000-0000-0000-000000000001',
  },
  kyt: {
    apiBaseUrl: 'https://example.invalid',
    kytPassageRegistryContract: 'CKYTEXAMPLECONTRACTIDAAAAAAAAAAAAAAAAAAAAAA',
  },
  signTransaction: async ({ xdr }) => ({ signedTxXdr: xdr }),
};

const assets = await loadDefaultStellarBrowserAssets();

const created = await createStellarPrivacyClient({
  network: transactEnvironment.network,
  wallet,
  state,
  assets,
  auditPublicKeyHex:
    'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2',
  transactEnvironment,
  policy: createStellarPolicyAdapterFromEnvironment(transactEnvironment),
});

if (!isStellarPrivacyClient(created)) {
  throw new Error('Client creation failed');
}

const client = created;

loadDefaultStellarBrowserAssets() returns bundled runtime assets required by the Stellar preset. transactEnvironment ties together network contracts, optional KYT, and your app’s transaction signing hook.

Step 4 — Seed minimal fixture state

The block below is tutorial fixture data — in production, assets and wallet secrets come from your backend and wallet flows. See Data sources.

const POOL = transactEnvironment.network.poolContract;
const OWNER = await wallet.getAddress();
const PRIVATE_ADDRESS = 'stpl1sender7exampleprivateaddress0000000000';

await client.upsertAssets([
  {
    id: 1,
    assetId: 'usdc',
    name: 'USDC',
    logoUrl: null,
    issuerAddress: null,
    clientContract: 'CTOKENCONTRACTEXAMPLEAAAAAAAAAAAAAAAAAAAAAA',
    poolContracts: [POOL],
    poolContract: POOL,
    mintable: false,
    mintAmount: null,
  },
]);
await client.saveWalletPrivateAddressRecord({
  owner: OWNER,
  nonce: '1',
  privateAddress: PRIVATE_ADDRESS,
  createdAt: Date.now(),
});
await client.saveWalletPrivateAddressScalar({
  owner: OWNER,
  nonce: '1',
  scalarHex: '0xabc123scalarhexexample000000000000000000000000000000000000',
});
await client.setPoolMerkleState({
  poolContract: POOL,
  commitments: ['0xmerklecommitmenthexexample00000000000000000000000000000000'],
  commitmentCount: 1,
  merkleRootHex: '0xmerkleroothexexample000000000000000000000000000000000000',
  updatedAt: Date.now(),
});

Prepare checks this cache before asking the wallet to sign. Missing asset catalog rows or wallet scalars are common reasons for early rejected results.

Step 5 — Prepare and execute

const operation = await client.deposit({
  from: OWNER,
  to: PRIVATE_ADDRESS,
  asset: 'usdc',
  amount: 50_0000000n,
  disclosure: {
    senderAddress: 'public',
    recipientAddress: 'private',
    assetAddress: 'public',
    amount: 'public',
  },
});

if (operation.status === 'rejected') {
  throw new Error(operation.errors[0]?.message ?? 'Prepare failed');
}

await operation.execute({
  onEvent(event) {
    if (event.status === 'begin') {
      console.log(`[${event.stage}] started`);
    }
  },
});

Always branch on operation.status before calling execute(). Use onEvent to drive progress UI — stages are listed in Operation lifecycle.

Next steps

State integration

Move from in-memory to Redux for production React.

Data sources

Replace fixtures with live backend and chain sync.

Setup

Full Stellar application shell with persistence.

Deposit how-to

Complete deposit reference with disclosure tiles.

Compliance Platform

Privacy Layer

Custom KYT providers

Support

Quick start (Stellar preset)

What you will build

Prerequisites

Step 1 — In-memory state adapter

Step 2 — Wallet stub

Step 3 — Create the client

Step 4 — Seed minimal fixture state

Step 5 — Prepare and execute

Next steps

State integration

Data sources

Setup

Deposit how-to

​What you will build

​Prerequisites

​Step 1 — In-memory state adapter

​Step 2 — Wallet stub

​Step 3 — Create the client

​Step 4 — Seed minimal fixture state

​Step 5 — Prepare and execute

​Next steps

State integration

Data sources

Setup

Deposit how-to

What you will build

Prerequisites

Step 1 — In-memory state adapter

Step 2 — Wallet stub

Step 3 — Create the client

Step 4 — Seed minimal fixture state

Step 5 — Prepare and execute

Next steps