SDK Reference

import { StealthClient } from 'stellar-shade';

const client = new StealthClient({
  network: 'testnet',
  contractId: 'C...',                 // required when the pool method is enabled
  methods: ['pool', 'account'],
  relayer: 'https://your-relayer.example', // optional; also accepts a list (see RelayerPool)
});

const bob = StealthClient.keygen();   // share bob.metaAddress ("shade:stellar:...")

await client.send(bob.metaAddress, 100, aliceSecret, { method: 'auto' });

const payments = await client.scan(bob);
await client.claim(payments[0], bobPublicKey, { keys: bob, feePayer: feePayerSecret });

new StealthClient(config: ClientConfig)

interface ClientConfig {
  network: 'testnet';     // 'testnet' only today; the NETWORKS table gains mainnet after the audit
  contractId?: string;    // required whenever 'pool' is enabled (no built-in default: pass your deployed pool id)
  horizonUrl?: string;    // override the Horizon endpoint (account method)
  indexerUrl?: string;    // announcement-indexer URL; the account-method discovery accelerator
  indexerMaxLagSeconds?: number;  // skip indexers self-reporting more lag (default 21600 = 6 h; null lag is never stale)
  methods?: DeliveryMethod[];  // default: ['pool']
  relayer?: string | string[];  // default relayer(s) for fee-bumped submissions
  relayerSelection?: 'random' | 'first';  // multi-URL pick strategy (default 'random')
}

StealthClient.keygen(): StealthKeys
StealthClient.fromMnemonic(mnemonic?: string): StealthKeys & { mnemonic: string }

send(
  metaAddress: string,
  amount: number,
  senderSecret: string,
  opts?: SendOpts,
): Promise<SendReceipt>

scan(keys: StealthKeys): Promise<Payment[]>
scanWithCursor(keys: StealthKeys, opts?: ScanOpts): Promise<ScanResult>

balance(keys: StealthKeys): Promise<Balance[]>

claim(
  payment: Payment,
  destination: string,
  opts: ClaimOpts,
): Promise<ClaimReceipt>

withdraw(
  stealthAddress: string,
  destination: string,
  opts: WithdrawOpts,
): Promise<WithdrawReceipt>

type DeliveryMethod = 'pool' | 'account';

interface StealthKeys {
  metaAddress: string;   // shade:stellar:... (share publicly)
  spendPubKey: string;   // hex
  spendPrivKey: string;  // hex; NEVER share
  viewPubKey: string;    // hex
  viewPrivKey: string;   // hex; safe to share with scanning services
}

interface SendReceipt {
  stealthAddress: string;
  txHash: string;
}

interface Payment {
  stealthAddress: string;
  ephemeralPubKey: string;      // hex
  token: string;                // SAC contract address, or 'native'
  asset?: string;               // "CODE:ISSUER" / 'native' (account-method token payments)
  claimableBalanceId?: string;  // present means this is a token claim
  amount: number;               // whole units
  amountStroops: string;        // exact stroop count; prefer this over `amount`
  method: DeliveryMethod;
  txHash?: string;
}

interface Balance {
  stealthAddress: string;
  token: string;
  amount: number;
  amountStroops: string;
}

interface ClaimReceipt { txHash: string; amount: number; method: DeliveryMethod; }
interface WithdrawReceipt { txHash: string; amount: number; }

interface ScanCursor { pool?: string; account?: string; }
interface ScanOpts   {
  methods?: DeliveryMethod[];
  cursor?: ScanCursor;
  exhaustive?: boolean;  // cold scan with an indexer: walk from genesis instead of fast-starting at its coverage
}
interface ScanResult {
  payments: Payment[];
  cursor: ScanCursor;
  meta?: Partial<Record<DeliveryMethod, MethodScanMeta>>;  // per-method scan diagnostics (account today)
}
interface MethodScanMeta {
  indexerUsed: boolean;
  indexerSkipReason?: 'unhealthy' | 'network_mismatch' | 'no_coverage' | 'stale' | 'unreachable';
  indexerLagSeconds?: number | null;
  postCheck?: 'ok' | 'unhealthy' | 'unreachable';  // post-segment /health re-check; non-'ok' = segment discarded
  cursorClamped?: boolean;                         // indexer-claimed position exceeded the Horizon head
  segments: { source: 'indexer' | 'horizon'; role: 'pre' | 'indexer' | 'tail' | 'full'; candidates: number; matches: number }[];
}

interface SendOpts {
  method: DeliveryMethod | 'auto';   // REQUIRED
  asset?: string;                    // "CODE:ISSUER"; default native XLM
  signTransaction?: TransactionSigner;
  feePayerAddress?: string;          // unused by send(); present for symmetry
}

interface ClaimOpts {
  keys: StealthKeys;          // required
  relay?: string | string[];  // fee-bumped submission; a list is probed + routed like ClientConfig.relayer
  merge?: boolean;            // account method: sweep via AccountMerge (default true)
  feePayer?: string;          // pool method: secret paying the Soroban fee
  asset?: string;             // pool method
  amount?: number;            // partial claim
  sponsored?: boolean;        // account-method token claim via the relayer
  fundingAccount?: string;    // credit-gated relayer: account to debit
  fundingSigner?: FundingSigner;  // credit-gated relayer: signs the proof-of-control challenge
  confirm?: boolean;          // relayed only: poll the returned txHash until it lands on-chain
  signTransaction?: TransactionSigner;
  feePayerAddress?: string;   // required when signTransaction is set on a pool claim
}

type TransactionSigner = (
  xdr: string,
  opts: { networkPassphrase: string; address?: string },
) => Promise<string>;

import freighterApi from '@stellar/freighter-api';

const signTransaction = async (xdr: string) => {
  const { signedTxXdr } = await freighterApi.signTransaction(xdr, { networkPassphrase });
  return signedTxXdr;
};

// Pass a G-address where a secret normally goes.
await client.send(bob.metaAddress, 100, alicePublicKey, {
  method: 'account',
  signTransaction,
});

import { keysFromWalletSignature, DEFAULT_KEY_SCOPE, DEFAULT_APP_ID } from 'stellar-shade';

const keys = await keysFromWalletSignature(
  (msg) => freighter.signMessage(msg),
  { appId: 'my-app' },
);

interface WalletKeysOpts {
  keyScope?: string;            // default 'stealth'; decoupled from the transport network
  appId?: string;               // default 'default'
  verifyDeterminism?: boolean;  // default TRUE; signs twice and throws if they differ
}

import { StealthSession } from 'stellar-shade';

const session = new StealthSession({ storage: window.localStorage });
await session.saveKeys(keys, password);
// ... later ...
await session.unlock(password);
const keys = session.keys;

interface KVStorage {
  getItem(key: string): string | null | Promise<string | null>;
  setItem(key: string, value: string): void | Promise<void>;
  removeItem(key: string): void | Promise<void>;
}

import { RelayerClient } from 'stellar-shade';

const relayer = new RelayerClient('http://localhost:3000');
const { status } = await relayer.health();

import { RelayerPool } from 'stellar-shade';

const pool = RelayerPool.from(['https://relay-a.example', 'https://relay-b.example'], {
  network: 'testnet',          // /health must not contradict this
  selection: 'random',         // default
});

const outcomes = await pool.probe();          // per-URL health or rejection reason
const url = await pool.select(ctx);           // one healthy URL (throws NoHealthyRelayerError)
const txHash = await pool.withRelayer(        // run with failover on relayer faults
  (client) => client.relay(xdr, { fundingAccount, networkPassphrase }).then((r) => r.txHash),
  { fundingAccount, fundingSigner },          // ctx: lets credit-gated relayers count as healthy
);

import { IndexerClient } from 'stellar-shade';

const indexer = new IndexerClient('http://localhost:3100');   // (baseUrl, fetchFn?, { timeoutMs? }); 10 s default timeout
const { cursor, startCursor } = await indexer.health();
const page = await indexer.getAnnouncements(startCursor ?? undefined, 200);

import { MethodRequiredError, ContractIdRequiredError, NoBalanceError,
         AnnouncementNotFoundError, StealthAccountNotFoundError,
         DestinationTrustlineError, FeePayerRequiredError,
         TransactionTimeoutError, ClaimAmountRequiresNoMergeError,
         SponsoredClaimMismatchError, ShadeError } from 'stellar-shade';

try {
  await client.claim(payment, dest, { keys });
} catch (e) {
  if (e instanceof DestinationTrustlineError) { /* add a trustline first */ }
}

import { parseStroops, numberToStroops, formatStroops,
         labelForToken, resolveTokenAddress,
         prepareWithRestore, HorizonClient,
         PoolAdapter, AccountAdapter } from 'stellar-shade';

import {
  generateMetaAddress, encodeMetaAddress, decodeMetaAddress,
  deriveStealthAddress, computeStealthAddress, deriveStealthAddressWithSecret,
  scanAnnouncements, checkViewTag, isMyStealthAddress,
  recoverStealthPrivateKey, signWithStealthKey, proveOwnership, verifyOwnership,
  encodePublicKey, decodePublicKey,
  generateMnemonic, validateMnemonic, mnemonicToStealthKeys,
  buildKeyDerivationMessage, deriveKeysFromSignature, KEY_DERIVATION_CONTEXT_V1,
  encryptAmount, decryptAmount,
  L, validatePoint, pointAdd, scalarMult, scalarMultBase, scalarAdd,
  generateRandomScalar, hashToScalar, viewTag,
} from '@shade/crypto';

/** The public halves of both keys: what a meta-address encodes. */
interface StealthMetaAddress {
  spendPubKey: Uint8Array;   // 32 bytes
  viewPubKey: Uint8Array;    // 32 bytes
}

/** A complete key set. NOTE: this is NOT the SDK's StealthKeys (see the warning below). */
interface StealthKeys {
  spendPrivKey: Uint8Array;  // 32 bytes
  viewPrivKey: Uint8Array;   // 32 bytes
  metaAddress: StealthMetaAddress;
}

/** One on-chain announcement, as scanning consumes it. */
interface Announcement {
  ephemeralPubKey: Uint8Array;  // 32-byte R = r·G
  viewTag: number;              // single byte, 0–255
  stealthAddress: string;       // G... StrKey
  txHash?: string;              // optional
}

/** A stealth address that scanning matched to you. */
interface StealthAddress {
  publicKey: Uint8Array;   // 32 bytes
  address: string;         // G... StrKey
}

/** What the sender gets from deriveStealthAddress / computeStealthAddress. */
interface StealthDerivation {
  stealthPubKey: Uint8Array;    // 32-byte P
  stealthAddress: string;       // G... StrKey
  ephemeralPubKey: Uint8Array;  // 32-byte R; publish this
  viewTag: number;              // publish this
  ephemeralPrivKey: Uint8Array; // 32-byte r; sender's records only, never publish
}

/** deriveStealthAddressWithSecret additionally exposes the ECDH secret. */
interface StealthDerivationWithSecret extends StealthDerivation {
  sharedSecret: Uint8Array;     // 32-byte S; feeds encryptAmount/decryptAmount
}