stellar-shade 0.0.2 → 0.1.0

package/dist/index.d.cts

@@ -1,6 +1,686 @@
+import * as StellarSdk from '@stellar/stellar-sdk';
+import { Networks, Account, Transaction, rpc } from '@stellar/stellar-sdk';
+
+/** Static endpoints and passphrase for one supported Stellar network. */
+interface NetworkDefinition {
+    networkPassphrase: string;
+    rpcUrl: string;
+    horizonUrl: string;
+    allowHttp: boolean;
+}
+/**
+ * The single source of truth for the networks this SDK can talk to. Adding a
+ * network is ONE new entry here: {@link NetworkName} (and with it every
+ * `ClientConfig.network` union across the SDK and its consumers) widens
+ * automatically.
+ */
+declare const NETWORKS: {
+    readonly testnet: {
+        readonly networkPassphrase: Networks.TESTNET;
+        readonly rpcUrl: "https://soroban-testnet.stellar.org";
+        readonly horizonUrl: "https://horizon-testnet.stellar.org";
+        readonly allowHttp: false;
+    };
+};
+/** The names of the currently supported networks (today: `'testnet'`). */
+type NetworkName = keyof typeof NETWORKS;
+/** Network configuration resolved from a network name. */
+interface NetworkConfig extends NetworkDefinition {
+    server: StellarSdk.rpc.Server;
+}
+/**
+ * Reverse lookup: the {@link NETWORKS} name whose passphrase matches, or
+ * `undefined` for a passphrase outside the table. Lets components that only
+ * hold a passphrase (the delivery adapters) derive the network name a relayer
+ * `/health` should report; an unknown passphrase yields `undefined`, which
+ * callers treat as "skip the check" rather than a failure (mainnet-open).
+ */
+declare function networkNameForPassphrase(passphrase: string): NetworkName | undefined;
+/**
+ * Build network config (endpoints + a connected RPC server) from a network
+ * name. Unknown names throw {@link UnsupportedNetworkError} — the type system
+ * already prevents them, but plain-JS callers and stale configs need the
+ * runtime guard too.
+ */
+declare function getNetworkConfig(network: NetworkName): NetworkConfig;
+/** Create a dummy transaction for read-only contract simulation. */
+declare function createSimulationTx(operation: StellarSdk.xdr.Operation, networkPassphrase: string): StellarSdk.Transaction;
+/** Execute a read-only contract call via simulation. Returns the decoded native result. */
+declare function simulateReadOnly(contractId: string, method: string, args: StellarSdk.xdr.ScVal[], server: StellarSdk.rpc.Server, networkPassphrase: string): Promise<unknown | null>;
+/** Resolve an asset string ("native", "XLM", or "CODE:ISSUER") to a SAC contract address. */
+declare function resolveTokenAddress(assetArg: string | undefined, networkPassphrase: string): string;
+/**
+ * Give a human-readable label for a SAC token contract address (the opaque
+ * `C...` string stored in pool announcements). The native XLM SAC has a
+ * deterministic contract id — `Asset.native().contractId(passphrase)` — so we
+ * detect it and return `'XLM'`; anything else cannot be reversed to CODE:ISSUER
+ * from the address alone, so the original `C...` address is returned unchanged.
+ *
+ * This is what turns a balance/scan row from an unreadable C-address into a
+ * recognizable token name for the common (native) case.
+ *
+ * @param tokenAddress - The token's SAC contract address, or 'native'/'unknown'.
+ * @param networkPassphrase - Passphrase used to derive the native SAC id.
+ * @returns 'XLM' for the native SAC (or the literal 'native'); otherwise the input.
+ */
+declare function labelForToken(tokenAddress: string, networkPassphrase: string): string;
+/**
+ * The minimal transaction-status surface of `rpc.Server` needed to poll a tx
+ * hash to a terminal status. Structural, so confirm-polling callers (e.g. the
+ * `RelayerClient` confirm option) can inject a real server or a test stub.
+ */
+interface TransactionStatusSource {
+    getTransaction(hash: string): Promise<{
+        status: string;
+    }>;
+}
+/**
+ * Poll for transaction confirmation. Throws on failure or timeout.
+ *
+ * The timeout is a typed {@link TransactionTimeoutError} carrying the tx hash:
+ * a still-PENDING transaction MAY land after we stop polling, so callers must
+ * be able to distinguish "gave up waiting" (poll the hash, do NOT resubmit)
+ * from a hard failure — a generic error here invites retry loops that
+ * double-send funds.
+ */
+declare function waitForTransaction(server: TransactionStatusSource, hash: string): Promise<void>;
+/**
+ * Build the withdraw message hash. Must be byte-identical to the contract's
+ * `build_withdraw_message`.
+ *
+ * Layout (concatenated, then SHA-256) — 278-byte preimage:
+ *   domain_tag[22] ("SHADE-POOL-WITHDRAW-V1" ASCII) || stealth_pk[32]
+ *   || token_strkey_ascii[56] || amount_be_i128[16]
+ *   || dest_strkey_ascii[56] || nonce_be_u64[8]
+ *   || contract_strkey_ascii[56] || network_id[32]
+ *
+ * The leading static domain tag (SH-3) separates withdraw preimages from any
+ * other message a stealth key might sign; the trailing contract address and
+ * network id provide domain separation so a signature cannot be replayed on a
+ * different deployment or network.
+ * `networkId` equals `SHA-256(utf8(networkPassphrase))`, which matches the
+ * on-chain `env.ledger().network_id()`.
+ */
+declare function buildWithdrawMessage(stealthPk: Uint8Array, tokenAddress: string, amount: bigint, destination: string, nonce: bigint, contractId: string, networkPassphrase: string): Uint8Array;
+
+/**
+ * Minimal Horizon REST helper with an injectable `fetch`.
+ *
+ * The account delivery method relies only on Horizon's classic REST API
+ * (transaction paging + operations + account probe + submit). Keeping this in a
+ * tiny, dependency-free wrapper with an injectable fetch makes the account
+ * scanner unit-testable fully offline: tests pass a stub fetch returning
+ * synthetic fixtures, no docker network required.
+ */
+/** A subset of a Horizon transaction record relevant to the account method. */
+interface HorizonTx {
+    id: string;
+    hash: string;
+    paging_token: string;
+    memo_type: string;
+    memo?: string;
+    successful?: boolean;
+    /** The account that submitted (and pays for) the transaction. */
+    source_account?: string;
+}
+/**
+ * A CAP-23 claim predicate as Horizon serializes it. A missing/`unconditional`
+ * predicate is always claimable; the time-bounded variants are evaluated
+ * against ledger time so an unsatisfiable CB is not reported as income.
+ */
+interface HorizonPredicate {
+    unconditional?: boolean;
+    and?: HorizonPredicate[];
+    or?: HorizonPredicate[];
+    not?: HorizonPredicate;
+    /** RFC-3339 timestamp: claimable strictly BEFORE this absolute time. */
+    abs_before?: string;
+    /** Same bound as an epoch-seconds string (Horizon includes both). */
+    abs_before_epoch?: string;
+    /** Seconds since the CB was created after which it becomes claimable. */
+    rel_before?: string;
+}
+/** A single claimant on a create_claimable_balance operation. */
+interface HorizonClaimant {
+    destination: string;
+    predicate?: HorizonPredicate;
+}
+/** A subset of a Horizon operation record relevant to the account method. */
+interface HorizonOp {
+    id: string;
+    type: string;
+    transaction_hash: string;
+    /** create_account: the newly created account */
+    account?: string;
+    /** create_account: starting balance (string, whole units) */
+    starting_balance?: string;
+    /** payment: destination account */
+    to?: string;
+    /** payment: amount (string, whole units) */
+    amount?: string;
+    /** payment / create_claimable_balance: asset type ('native' for XLM) */
+    asset_type?: string;
+    /** create_claimable_balance: asset in "CODE:ISSUER" form (or 'native') */
+    asset?: string;
+    /** create_claimable_balance: the claimants list */
+    claimants?: HorizonClaimant[];
+}
+/** A Horizon claimable-balance record (used by the token account method). */
+interface HorizonClaimableBalance {
+    id: string;
+    asset: string;
+    amount: string;
+    sponsor?: string;
+    claimants: HorizonClaimant[];
+    /** Horizon paging token — used to resume the next page of a listing. */
+    paging_token?: string;
+}
+/** Horizon account record subset (used to probe existence + sequence). */
+interface HorizonAccount {
+    id: string;
+    sequence: string;
+    balances: Array<{
+        asset_type: string;
+        balance: string;
+    }>;
+}
+/** Injectable fetch signature (compatible with the global `fetch`). */
+type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+/** A thin, injectable-fetch Horizon REST client. */
+declare class HorizonClient {
+    private readonly baseUrl;
+    private readonly fetchFn;
+    /**
+     * @param baseUrl - Horizon root URL (no trailing slash required).
+     * @param fetchFn - Injectable fetch (defaults to the global `fetch`).
+     */
+    constructor(baseUrl: string, fetchFn?: FetchLike);
+    private getJson;
+    /**
+     * Page transactions in ascending order.
+     *
+     * @param cursor - Paging token to resume from (omit for the beginning).
+     * @param limit - Page size (default 200, Horizon's max).
+     * @returns The page's transaction records (may be empty).
+     */
+    getTransactions(cursor?: string, limit?: number): Promise<HorizonTx[]>;
+    /**
+     * The paging token of the newest transaction this Horizon serves (one
+     * `order=desc&limit=1` page), or undefined on an empty network. The scan
+     * uses it to sanity-clamp cursors adopted from indexer-supplied data: a
+     * persisted scan cursor must never exceed the chain position Horizon
+     * itself reports, or a malicious feed could blind every future scan.
+     */
+    getLatestTransactionToken(): Promise<string | undefined>;
+    /**
+     * Fetch the operations belonging to a single transaction.
+     *
+     * @param txHash - Transaction hash.
+     * @returns The transaction's operation records.
+     */
+    getTransactionOperations(txHash: string): Promise<HorizonOp[]>;
+    /**
+     * Probe an account. Returns null if the account does not exist (404).
+     *
+     * @param address - Stellar G-address.
+     */
+    getAccount(address: string): Promise<HorizonAccount | null>;
+    /**
+     * List ALL claimable balances for which the given address is a claimant,
+     * paging through every Horizon page (not just the first).
+     *
+     * Used by the token account method: a direct token send lands as a
+     * CreateClaimableBalance to the derived stealth address, which the recipient
+     * later claims. Returns an empty array when the account has none.
+     *
+     * Paging matters for correctness, not just completeness: anyone can create a
+     * claimable balance naming a (public, on-chain) stealth address as claimant,
+     * so an attacker could spam cheap balances to push the genuine payment past
+     * the first page and make the scanner silently miss it. Each page is resumed
+     * via the last record's `paging_token` (falling back to the `cursor` in
+     * `_links.next.href`), stopping on a short page, a non-advancing cursor, or
+     * the defensive {@link MAX_CLAIMABLE_BALANCE_PAGES} bound.
+     *
+     * @param claimant - Stellar G-address to filter claimable balances by.
+     */
+    getClaimableBalances(claimant: string): Promise<HorizonClaimableBalance[]>;
+    /**
+     * Extract the `cursor` query parameter from a Horizon `_links.next.href`.
+     * Fallback for full pages whose records carry no `paging_token`.
+     */
+    private cursorFromNextLink;
+    /**
+     * Submit a base64 transaction envelope XDR to Horizon.
+     *
+     * @param xdr - base64-encoded transaction envelope.
+     * @returns The submitted transaction hash.
+     */
+    submitTransaction(xdr: string): Promise<{
+        hash: string;
+    }>;
+}
+
+/**
+ * Signs a canonical challenge message with the funding account's ed25519 key,
+ * proving control of that account for a fee-spending relayer request. Returns
+ * the signature as base64 or hex (or raw bytes). Kept abstract so an app can
+ * back it by a wallet, an HSM, or a raw secret key without the SDK ever holding
+ * the funding key.
+ */
+type FundingSigner = (message: string) => Promise<Uint8Array | string> | Uint8Array | string;
+/** Response from `GET /credit/challenge`. */
+interface CreditChallenge {
+    account: string;
+    nonce: string;
+}
+/**
+ * Canonical single-line message the funding account signs to authorize a spend.
+ * MUST match the relayer's `challengeMessage` byte-for-byte. When `bind` is
+ * supplied (e.g. the inner-tx hash on the `/relay` path) it is appended so the
+ * signature is pinned to that specific transaction and cannot be paired with a
+ * different attacker-signed inner XDR of the same amount.
+ */
+declare function challengeMessage(endpoint: string, fundingAccount: string, nonce: string, amount: string, bind?: string): string;
+/** Relayer `/health` response. */
+interface RelayerHealth {
+    status: string;
+    network?: string;
+    relayerAddress?: string;
+    balance?: string;
+    /** Whether the relayer gates fee-spending endpoints on credit. */
+    requireCredit?: boolean;
+    /** Advertised ceiling (XLM) on a fee-bump — the amount a client authorizes. */
+    maxRelayFeeXlm?: number;
+    /**
+     * The reserve component (7-dp XLM string, e.g. `'1.0000000'`) a credit-gated
+     * relayer adds to a sponsor-claim tx's fee when verifying the
+     * proof-of-control signature. Clients signing the EXACT `fee + reserve`
+     * total should prefer this over mirroring the relayer-side constant.
+     */
+    sponsoredReserveEstimate?: string;
+    /** Credit-ledger backend: `'postgres'` (durable) or `'json'` (dev fallback). */
+    store?: string;
+    /** Nonce/rate-limit backend: `'redis'` (multi-instance) or `'memory'`. */
+    sharedState?: string;
+}
+/** Options for {@link RelayerClient.relay}. */
+interface RelayOpts {
+    /** App account to debit the fee-bump fee against (credit-gated relayers). */
+    fundingAccount?: string;
+    /** Signer proving control of `fundingAccount` (credit-gated relayers). */
+    fundingSigner?: FundingSigner;
+    /**
+     * The fee/amount (7-dp XLM string) the proof-of-control signature authorizes.
+     * MUST equal the fee the relayer will charge, or the relayer rejects with 401.
+     */
+    authAmount?: string;
+    /**
+     * Network passphrase used to compute the inner-tx hash bound into the
+     * proof-of-control signature. MUST match the passphrase the relayer verifies
+     * under, or a credit-gated relayer rejects with 401. Required to bind the
+     * inner tx on a credit-gated `/relay`; omit for the free/default path.
+     */
+    networkPassphrase?: string;
+    /**
+     * Do not trust the relayer's returned txHash at face value: poll it to a
+     * terminal on-chain status before resolving (SDK-TXHASH-TRUST). Requires an
+     * `rpcServer` in the {@link RelayerClient} constructor opts. Throws
+     * `TransactionTimeoutError` (carrying the txHash) if the poll window closes
+     * while the tx is still unseen/pending, or an error if it FAILED on-chain.
+     * Default `false`: resolve as soon as the relayer responds, exactly as before.
+     */
+    confirm?: boolean;
+}
+/** Options for {@link RelayerClient.sponsor}. */
+interface SponsorOpts {
+    /** Starting balance for the newly created account (whole XLM). */
+    startingBalance?: string;
+    /** App account to debit against (credit-gated relayers). */
+    fundingAccount?: string;
+    /** Signer proving control of `fundingAccount` (credit-gated relayers). */
+    fundingSigner?: FundingSigner;
+    /**
+     * The total (startingBalance + fee, 7-dp XLM string) the proof-of-control
+     * signature authorizes. MUST equal what the relayer will charge.
+     */
+    authAmount?: string;
+}
+/** Arguments for {@link RelayerClient.sponsorClaimPrepare}. */
+interface SponsorClaimPrepareArgs {
+    /** The stealth address that will claim the balance. */
+    stealthAddress: string;
+    /** Asset to add a trustline for, in "CODE:ISSUER" form. */
+    asset: string;
+    /** Claimable balance id to claim. */
+    balanceId: string;
+    /** Destination that the claimed token is paid out to (must trust the asset). */
+    destination: string;
+    /** Amount of the claimed token to pay out to the destination (7-dp string). */
+    amount: string;
+}
+/** Response from {@link RelayerClient.sponsorClaimPrepare}. */
+interface SponsorClaimPrepared {
+    /** Unsigned transaction XDR for the client to co-sign with the stealth key. */
+    xdr: string;
+    /** ISO timestamp after which the prepared tx's timebounds expire. */
+    expiresAt: string;
+}
+/** A read-only credit-ledger view for an app funding account. */
+interface CreditView {
+    fundingAccount: string;
+    balance: string;
+    updatedAt?: string;
+}
+/**
+ * Thin HTTP client for the reserve relayer service. Every fee-spending endpoint
+ * is exposed as a typed method so the SDK (and apps) never hand-roll fetch calls
+ * or URL joining. Construct once and reuse.
+ *
+ * @example
+ * ```typescript
+ * const relayer = new RelayerClient('http://localhost:3000');
+ * const { status } = await relayer.health();
+ * ```
+ */
+declare class RelayerClient {
+    private readonly baseUrl;
+    private readonly fetchFn;
+    private readonly fundingSigner?;
+    private readonly fundingAccount?;
+    private readonly rpcServer?;
+    /**
+     * @param baseUrl - Relayer root URL. A trailing `/relay` is stripped so a
+     *   bare relay URL (back-compat) resolves to the service root.
+     * @param fetchFn - Injectable fetch (defaults to the global `fetch`).
+     * @param opts - Optional default `fundingAccount` + `fundingSigner` used to
+     *   authenticate fee-spending requests against a credit-gated relayer, and
+     *   an optional `rpcServer` (an `rpc.Server`, or any object with its
+     *   `getTransaction`) used to confirm-poll returned tx hashes when a call
+     *   sets `confirm: true`.
+     */
+    constructor(baseUrl: string, fetchFn?: FetchLike, opts?: {
+        fundingAccount?: string;
+        fundingSigner?: FundingSigner;
+        rpcServer?: TransactionStatusSource;
+    });
+    /**
+     * Poll a relayer-returned txHash until it lands on-chain (SDK-TXHASH-TRUST).
+     * A relayer could return a fabricated or failed hash with a 200; polling to a
+     * terminal status is what turns "the relayer said so" into "the chain says
+     * so". Deliberately loud when no poll handle exists — silently skipping the
+     * confirmation a caller asked for would defeat its purpose. On timeout the
+     * underlying `waitForTransaction` throws `TransactionTimeoutError` carrying
+     * the txHash, so the caller can keep polling instead of blindly resubmitting.
+     */
+    private confirmOnChain;
+    /**
+     * Fetch a fresh challenge nonce for `fundingAccount`, sign the canonical
+     * message binding `endpoint` + account + nonce + `amount`, and return the
+     * `{ fundingAccount, nonce, signature }` to attach to a fee-spending request.
+     * Returns `undefined` when no signer is available (non-gated relayer path).
+     */
+    private signedAuth;
+    private post;
+    private get;
+    /**
+     * Decode a relayer response. A non-JSON body on an error status (e.g. a
+     * proxy's HTML 502 page) must not mask the status, so decode failures fall
+     * back to an empty body there; a non-JSON body on a 2xx is a broken relayer
+     * and surfaces as a transport error.
+     */
+    private decode;
+    /** Probe the relayer's health, balance, and address. */
+    health(): Promise<RelayerHealth>;
+    /**
+     * Fee-bump and submit a signed transaction envelope.
+     *
+     * @param xdr - base64 signed transaction envelope.
+     * @param opts - Optional funding account to debit the fee against, and
+     *   `confirm` to poll the returned hash to an on-chain terminal status.
+     * @returns The submitted transaction hash.
+     */
+    relay(xdr: string, opts?: RelayOpts): Promise<{
+        txHash: string;
+    }>;
+    /** Cached per-client relayer fee ceiling (XLM, 7-dp), fetched from /health. */
+    private cachedMaxRelayFee?;
+    /**
+     * The relayer's advertised max fee-bump fee (`maxRelayFeeXlm` from /health),
+     * as the fee ceiling to authorize. Falls back to the protocol default cap
+     * (0.1 XLM) when an older relayer does not advertise it. Cached per client.
+     */
+    private maxRelayFee;
+    /** Cached per-client sponsored-reserve estimate; `null` = fetched, absent. */
+    private cachedSponsoredReserve?;
+    /**
+     * The relayer's advertised sponsored-reserve estimate
+     * (`sponsoredReserveEstimate` from /health), parsed to exact stroops.
+     * Returns `undefined` when the relayer does not advertise one, the value is
+     * unparsable, or /health is unreachable — the caller falls back to its own
+     * mirrored constant, so a health fault never breaks a claim. Cached per
+     * client, mirroring {@link maxRelayFee}.
+     */
+    sponsoredReserveEstimateStroops(): Promise<bigint | undefined>;
+    /**
+     * Create a stealth account from the relayer's own balance (funded
+     * CreateAccount — no sponsorship sandwich).
+     *
+     * @param address - Stealth G-address to create.
+     * @param opts - Starting balance and optional funding account.
+     */
+    sponsor(address: string, opts?: SponsorOpts): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Ask the relayer to build the sponsored claimable-balance-claim transaction.
+     * Returns UNSIGNED XDR the client must co-sign with the stealth key before
+     * calling {@link sponsorClaimSubmit}.
+     */
+    sponsorClaimPrepare(args: SponsorClaimPrepareArgs): Promise<SponsorClaimPrepared>;
+    /**
+     * Submit a sponsor-claim transaction the client has co-signed. The relayer
+     * re-derives the expected operations from the trusted inputs
+     * (`stealthAddress`, `asset`, `balanceId`) and verifies the submitted ops
+     * match field-by-field before adding its signature and submitting.
+     *
+     * @param xdr - The stealth-co-signed transaction XDR.
+     * @param args - The trusted claim inputs (and optional funding account).
+     *   `confirm: true` polls the returned hash to an on-chain terminal status
+     *   (requires `rpcServer` in the constructor opts).
+     */
+    sponsorClaimSubmit(xdr: string, args: {
+        stealthAddress: string;
+        asset: string;
+        balanceId: string;
+        destination: string;
+        amount: string;
+        fundingAccount?: string;
+        fundingSigner?: FundingSigner;
+        /** Total (reserve + fee) the proof-of-control signature authorizes. */
+        authAmount?: string;
+        /** Poll the returned txHash until it lands on-chain (see {@link RelayOpts.confirm}). */
+        confirm?: boolean;
+    }): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Report a completed on-chain deposit to the relayer so it credits the app's
+     * funding account with the paid amount.
+     */
+    creditClaim(fundingAccount: string, txHash: string): Promise<CreditView>;
+    /** Read the current credit balance for an app funding account. */
+    creditBalance(fundingAccount: string): Promise<CreditView>;
+}
+
+/**
+ * How a healthy relayer is picked from the candidate list. `'random'` is the
+ * default deliberately: users spread across the relayer set instead of herding
+ * onto the first entry, preserving the anonymity-set benefit of shared
+ * relayers. `'first'` gives deterministic priority ordering.
+ */
+type RelayerSelection = 'random' | 'first';
+/** Tuning knobs for a {@link RelayerPool}. Every field has a safe default. */
+interface RelayerPoolOpts {
+    /**
+     * Network name a candidate's `/health` must report. Omit (or an unknown
+     * passphrase upstream) to skip the check; a candidate that reports no
+     * network also passes — only an explicit contradiction rejects.
+     */
+    network?: NetworkName;
+    /** Selection strategy. Default `'random'`. */
+    selection?: RelayerSelection;
+    /** Injectable fetch (tests); defaults to the global `fetch`. */
+    fetchFn?: FetchLike;
+    /** Shared parallel `/health` probe budget in ms. Default 2500. */
+    probeTimeoutMs?: number;
+    /**
+     * Per-attempt budget in ms inside {@link RelayerPool.withRelayer}, applied
+     * ONLY while a failover alternative remains. Default 10000.
+     */
+    attemptTimeoutMs?: number;
+    /**
+     * Minimum XLM balance a candidate must report to count as healthy — a
+     * relayer one fee-bump from empty is operationally dead. Default 1 XLM
+     * (~10 fee-bumps at the default 0.1 cap).
+     */
+    minBalanceXlm?: number;
+    /** Probe cache TTL in ms (per pool instance). Default 30000. */
+    probeTtlMs?: number;
+    /** Injectable RNG for `'random'` selection (tests). Default `Math.random`. */
+    rng?: () => number;
+}
+/**
+ * Per-call context the health rule and the built clients need: a credit-gated
+ * relayer only counts as healthy when the caller can actually pass its gate
+ * (`fundingAccount` + `fundingSigner` present).
+ */
+interface RelayerCallCtx {
+    fundingAccount?: string;
+    fundingSigner?: FundingSigner;
+    rpcServer?: TransactionStatusSource;
+}
+/** One candidate's probe result: a health document, or the rejection reason. */
+interface ProbeOutcome {
+    url: string;
+    health?: RelayerHealth;
+    reason?: string;
+}
+/**
+ * Normalize a relayer config value into a clean URL list: trims entries, drops
+ * empties, and collapses an empty result to `undefined` so `[]` and `['']`
+ * mean "no relayer" everywhere a truthiness check gates relayed behavior
+ * (e.g. the account claim's merge-fee arithmetic).
+ */
+declare function normalizeRelayList(relay?: string | string[]): string[] | undefined;
+/**
+ * Health-probing selector and failover harness over a list of relayer URLs
+ * (A3 BYO-relayer discovery).
+ *
+ * A candidate is healthy iff its `/health` reports `status === 'ok'`, its
+ * network matches the expected one (when both sides are known), its balance
+ * meets the minimum, and its credit gate is passable — `requireCredit ===
+ * false`, or the caller brought funding auth. `requireCredit` missing is
+ * treated as gated (fail-closed, matching the relayer's gating-on default).
+ *
+ * A single-URL pool is a transparent pass-through: no probe, no timeout —
+ * byte-identical behavior to constructing a `RelayerClient` directly, so
+ * existing single-relayer callers see no new traffic or failure modes.
+ */
+declare class RelayerPool {
+    readonly candidates: readonly string[];
+    private readonly network?;
+    private readonly selection;
+    private readonly fetchFn?;
+    private readonly probeTimeoutMs;
+    private readonly attemptTimeoutMs;
+    private readonly minBalanceXlm;
+    private readonly probeTtlMs;
+    private readonly rng;
+    private cachedProbe?;
+    private cachedProbeAt;
+    constructor(candidates: string[], opts?: RelayerPoolOpts);
+    /**
+     * Build a pool from any accepted relayer config shape, or `undefined` when
+     * the input normalizes to "no relayer" — the back-compat seam that lets
+     * `RelayerPool.from(opts.relay)` slot in wherever a single URL was used.
+     */
+    static from(relay: string | string[] | undefined, opts?: RelayerPoolOpts): RelayerPool | undefined;
+    /**
+     * Probe every candidate's `/health` in parallel under one shared time
+     * budget. Results are cached per pool instance for {@link
+     * RelayerPoolOpts.probeTtlMs}; `force` refreshes. Only transport-level
+     * outcomes are recorded here — health-rule classification happens per call
+     * in {@link select}/{@link withRelayer}, because it depends on the caller's
+     * funding context.
+     */
+    probe(force?: boolean): Promise<ProbeOutcome[]>;
+    /**
+     * Pick one healthy relayer URL for this call, or throw
+     * {@link NoHealthyRelayerError} naming every candidate's rejection reason.
+     * A single-candidate pool returns its URL without probing (pass-through).
+     */
+    select(ctx?: RelayerCallCtx): Promise<string>;
+    /**
+     * Run `fn` against a selected relayer, failing over to the next healthy
+     * candidate ONLY on transport faults — {@link RelayerNetworkError}, a 5xx
+     * {@link RelayerHttpError}, or an attempt timeout. A 4xx (bad request,
+     * insufficient credit) or any non-transport error would just repeat and
+     * rethrows immediately. At most 2 attempts; the attempt timeout applies
+     * only while another candidate remains.
+     *
+     * Failover after an ambiguous timeout cannot double-spend: both attempts
+     * fee-bump the SAME signed inner tx, so its sequence number lets at most
+     * one land (`txBAD_SEQ` for the loser).
+     */
+    withRelayer<T>(fn: (client: RelayerClient, url: string) => Promise<T>, ctx?: RelayerCallCtx): Promise<T>;
+    /** Per-call client carrying the caller's funding auth + confirm handle. */
+    private buildClient;
+    /**
+     * Classify every probed candidate for this call's context and order the
+     * healthy ones by the selection strategy.
+     */
+    private rankHealthy;
+    /** The health rule. Returns the rejection reason, or `undefined` = healthy. */
+    private healthReason;
+}
+
+/**
+ * A delivery method describes HOW a stealth payment reaches its recipient.
+ * - `'pool'`  — deposit into the Soroban pool contract (default, private, any SAC token).
+ * - `'account'` — a direct classic Stellar payment that creates/pays a one-time stealth
+ *   account, with the ephemeral key carried in a MemoHash. Native XLM only for now.
+ * - `'spp'` — reserved slot for a future Stellar Private Payments (ZK shielded pool) integration.
+ */
+type DeliveryMethod = 'pool' | 'account' | 'spp';
+/**
+ * An external transaction signer, shaped like Freighter's `signTransaction`.
+ *
+ * Takes an UNSIGNED transaction XDR and returns a SIGNED transaction XDR. This
+ * lets a browser wallet (e.g. Freighter) sign the SENDER and FEE-PAYER legs of
+ * an SDK transaction so a dapp never touches a raw Stellar secret. The recovered
+ * stealth-key legs still sign locally — a wallet cannot hold the derived stealth
+ * scalar — so a signer is only ever applied to the sender / fee-payer legs.
+ *
+ * @param xdr - The unsigned transaction XDR (base64).
+ * @param opts - Network passphrase and, optionally, the G-address expected to
+ *   sign (the public key the caller passed where a secret normally goes).
+ * @returns The signed transaction XDR (base64).
+ */
+type TransactionSigner = (xdr: string, opts: {
+    networkPassphrase: string;
+    address?: string;
+}) => Promise<string>;
 /** Stealth key material. All keys are hex-encoded strings for easy serialization. */
 interface StealthKeys {
-    /** Meta-address string (st:stellar:...) — share this publicly */
+    /** Meta-address string (shade:stellar:...) — share this publicly */
     metaAddress: string;
     /** Spend public key (hex) */
     spendPubKey: string;
@@ -22,12 +702,45 @@ interface SendReceipt {
 interface Payment {
     /** The stealth address holding the funds */
     stealthAddress: string;
-    /** Ephemeral public key from the announcement (hex) */
+    /** Ephemeral public key from the announcement/memo (hex) */
     ephemeralPubKey: string;
-    /** Token contract address */
+    /**
+     * Token identifier — tri-modal, depending on how the payment arrived:
+     * - pool method: the SAC token CONTRACT address (`C...`);
+     * - account method, native send: the literal string `'native'`;
+     * - account method, token send: Horizon's `"CODE:ISSUER"` form.
+     */
     token: string;
+    /**
+     * Human-oriented asset label. Set on EVERY pool payment (`'XLM'` for the
+     * native SAC, otherwise the `C...` address — see `labelForToken`) and on
+     * account-method token payments (`"CODE:ISSUER"`, from the claimable
+     * balance). Absent only on account-method NATIVE payments, where
+     * {@link token} is already `'native'`.
+     */
+    asset?: string;
+    /**
+     * Claimable balance id (account-method token payments only). Its presence is
+     * what marks a payment as a token claim rather than a plain XLM send.
+     */
+    claimableBalanceId?: string;
     /** Amount in whole units (e.g. 100.0 = 100 XLM) */
     amount: number;
+    /**
+     * Exact amount as a decimal `bigint` count of stroops (1e-7 units), serialized
+     * as a string. ALWAYS set alongside {@link amount}, so callers that need
+     * exactness above ~9.007e8 XLM (where a float can no longer represent every
+     * stroop) can avoid the lossy `number`. The SDK's scan adapters populate it on
+     * every payment; when building a `Payment` by hand (or rehydrating one from an
+     * older cache that predates this field), compute it from the exact on-chain
+     * amount — claims prefer it over the lossy `number`. The `number` field is
+     * retained for display and backwards compatibility.
+     */
+    amountStroops: string;
+    /** Which delivery method surfaced this payment */
+    method: DeliveryMethod;
+    /** Transaction hash that delivered the payment (when known) */
+    txHash?: string;
 }
 /** Balance entry for a stealth address. */
 interface Balance {
@@ -37,6 +750,12 @@ interface Balance {
     token: string;
     /** Amount in whole units */
     amount: number;
+    /**
+     * Exact amount as a decimal `bigint` count of stroops, serialized as a string.
+     * Always set, so callers can sum/display without a lossy float. See
+     * {@link Payment.amountStroops}.
+     */
+    amountStroops: string;
 }
 /** Result of a withdrawal. */
 interface WithdrawReceipt {
@@ -45,161 +764,1552 @@ interface WithdrawReceipt {
     /** Amount withdrawn in whole units */
     amount: number;
 }
-/**
- * External transaction signer.
- *
- * Given the base64 XDR of a prepared transaction, return the base64 XDR of the
- * signed transaction. This is exactly the shape of a browser wallet's signing
- * call (e.g. Freighter's `signTransaction`), allowing the client to sign
- * without ever handling a raw secret key.
- */
-type TransactionSigner = (xdr: string, context: {
-    /** Network passphrase the transaction must be signed against. */
-    networkPassphrase: string;
-    /** The account expected to sign (public key, G...). */
-    address: string;
-}) => Promise<string>;
 /** Options for sending to a stealth address. */
 interface SendOpts {
+    /**
+     * Delivery method to use. REQUIRED — callers must pick a method on every send.
+     * Pass `'auto'` to let the client resolve one (native + amount > 1 + 'account'
+     * enabled -> 'account'; otherwise 'pool').
+     */
+    method: DeliveryMethod | 'auto';
     /** Asset to send. Default: native XLM. Format: "CODE:ISSUER" */
     asset?: string;
     /**
-     * Sign with an external wallet instead of a raw secret key. When provided,
-     * the `senderSecret` argument of `send()` is treated as the sender's public
-     * key (G...) and is never used to sign.
+     * External signer for the SENDER leg (Freighter-style). When set, the caller
+     * passes a PUBLIC key (G...) where a secret is normally expected — `send()`'s
+     * `senderSecret` positional carries the sender's G-address — and the SDK
+     * delegates signing to this function instead of `Keypair.fromSecret`. The
+     * stealth-key legs (claim/withdraw signatures) are unaffected: a wallet cannot
+     * hold the derived stealth scalar, so those always sign locally.
      */
     signTransaction?: TransactionSigner;
+    /**
+     * The G-address of the fee payer when {@link signTransaction} is used on a
+     * flow that needs a distinct fee payer. Unused by `send()` (whose fee payer is
+     * the sender itself); present here for symmetry with {@link ClaimOpts}.
+     */
+    feePayerAddress?: string;
 }
-/** Options for withdrawing from a stealth address. */
+/** Options for withdrawing from a stealth address (pool method). */
 interface WithdrawOpts {
     /** Stealth keys (need view + spend private keys) */
     keys: StealthKeys;
+    /** Secret key of account paying the Soroban invocation fee */
+    feePayer: string;
     /**
-     * Secret key of the account paying the Soroban invocation fee.
-     * Optional when `signTransaction` + `feePayerAddress` are supplied instead.
+     * Relay URL(s) for fee-bumped submission (privacy-preserving). A list is
+     * health-probed and routed like {@link ClientConfig.relayer}.
      */
-    feePayer?: string;
-    /**
-     * Sign the fee-payer side with an external wallet instead of `feePayer`.
-     * The stealth withdraw authorization is still produced internally from
-     * `keys`; only the transaction envelope signature is delegated.
-     */
-    signTransaction?: TransactionSigner;
-    /** Fee payer's public key (G...). Required when using `signTransaction`. */
-    feePayerAddress?: string;
-    /** Relay URL for fee-bumped submission (privacy-preserving) */
-    relay?: string;
+    relay?: string | string[];
     /** Asset to withdraw. Default: native XLM. Format: "CODE:ISSUER" */
     asset?: string;
     /** Amount to withdraw. Default: full balance */
     amount?: number;
+    /**
+     * App funding account (G-address) to debit the relayer fee against when the
+     * relayer is credit-gated. Threaded into the `/relay` call so a gated relayer
+     * does not respond 402 `insufficient_credit`. Ignored by a non-gated relayer.
+     * See {@link ClaimOpts.fundingAccount}.
+     */
+    fundingAccount?: string;
+    /**
+     * Signer proving control of {@link fundingAccount}: a credit-gated relayer
+     * requires a fresh challenge nonce signed by the funding account before it
+     * debits credit for the fee-bump (proof-of-control; without it every gated
+     * `/relay` call is rejected 402 `missing_auth`). Omit for non-gated relayers.
+     */
+    fundingSigner?: FundingSigner;
+    /**
+     * Relayed submissions only: poll the relayer-returned txHash until it is
+     * on-chain before returning (SDK-TXHASH-TRUST), surfacing a
+     * `TransactionTimeoutError` (with the hash) if it never lands.
+     */
+    confirm?: boolean;
 }
-/** Client configuration. */
-interface ClientConfig {
-    /** Network to connect to */
-    network: 'local' | 'testnet';
-    /** Override the default contract ID for the stealth pool */
-    contractId?: string;
+/** Per-method scan cursors, so each adapter can resume where it left off. */
+interface ScanCursor {
+    /** Pool announcement start index (next unread announcement) */
+    pool?: string;
+    /** Horizon paging token for the account method */
+    account?: string;
+    /** Reserved for the spp method */
+    spp?: string;
 }
-
 /**
- * High-level client for stealth payments on Stellar.
- *
- * Wraps DKSAP cryptography and Soroban contract interaction into a simple API.
- * Developers don't need to understand the underlying protocol to use this.
- *
- * @example
- * ```typescript
- * const client = new StealthClient({ network: 'local', contractId: 'CXXX...' });
- *
- * // Generate keys
- * const keys = StealthClient.keygen();
- *
- * // Send 100 XLM to a stealth address
- * const receipt = await client.send(keys.metaAddress, 100, 'SXXX...');
- *
- * // Scan for received payments
- * const payments = await client.scan(keys);
- *
- * // Withdraw
- * await client.withdraw(payments[0].stealthAddress, 'GDEST...', {
- *   keys,
- *   feePayer: 'SXXX...',
- * });
- * ```
+ * Options controlling a cursor-aware scan. Also accepted by the balance path
+ * (`StealthClient.balance`/`balanceWithCursor`), whose account phase otherwise
+ * re-walks the entire Horizon history on every call.
  */
-declare class StealthClient {
-    private readonly contractId;
-    private readonly networkPassphrase;
-    private readonly server;
-    constructor(config: ClientConfig);
+interface ScanOpts {
+    /** Restrict the scan to these methods (default: all enabled adapters) */
+    methods?: DeliveryMethod[];
+    /** Resume from a previously returned cursor */
+    cursor?: ScanCursor;
     /**
-     * Generate a new random stealth key pair.
-     * No network connection needed.
+     * Account method with an indexer configured ({@link ClientConfig.indexerUrl})
+     * only: a COLD scan (no cursor) walks the full Horizon history from genesis
+     * instead of fast-starting at the indexer's first covered position. Set it
+     * to discover payments that predate the indexer's coverage. Without an
+     * indexer the Horizon walk is always exhaustive, so this has no effect.
      */
-    static keygen(): StealthKeys;
+    exhaustive?: boolean;
+}
+/**
+ * Diagnostics for ONE slice of a segmented scan. The account method walks up
+ * to three segments per scan (Horizon pre-segment, indexer-covered span,
+ * Horizon tail) — or a single unbounded Horizon walk when no indexer applies —
+ * and reports each slice's throughput so operators can see where discovery
+ * work actually happened.
+ */
+interface ScanSegmentMeta {
+    /** Which feed served this segment's transactions. */
+    source: 'indexer' | 'horizon';
     /**
-     * Generate stealth keys from a BIP-39 mnemonic.
-     * Returns the mnemonic alongside the keys for backup.
-     * No network connection needed.
+     * The segment's position in the scan: the bounded Horizon walk before
+     * indexer coverage (`'pre'`), the indexer-covered span (`'indexer'`), the
+     * always-run Horizon tail (`'tail'`), or the single unbounded walk of a
+     * scan with no usable indexer (`'full'`).
      */
-    static fromMnemonic(mnemonic?: string): StealthKeys & {
-        mnemonic: string;
-    };
+    role: 'pre' | 'indexer' | 'tail' | 'full';
+    /** Hash-memo txs that entered the matcher with a plausible 32-byte R. */
+    candidates: number;
+    /** Payments collected from this segment. */
+    matches: number;
+}
+/**
+ * Per-method scan diagnostics. Produced by the account method today, and
+ * strictly observability: the numbers describe how a scan discovered its
+ * payments, never which payments it finds — the Horizon tail bounds
+ * correctness regardless of what happens to the indexer segment.
+ */
+interface MethodScanMeta {
+    /** True once at least one `/announcements` page was successfully consumed. */
+    indexerUsed: boolean;
     /**
-     * Send tokens to a stealth address.
-     *
-     * Derives a one-time stealth address from the recipient's meta-address,
-     * deposits tokens into the pool contract, and records the announcement.
-     *
-     * Signing: by default the transaction is signed with `senderSecret` (a
-     * Stellar secret key). If `opts.signTransaction` is provided, signing is
-     * delegated to that external signer (e.g. a browser wallet) and the
-     * `senderSecret` argument is treated as the sender's public key instead.
-     *
-     * @param metaAddress - Recipient's meta-address (st:stellar:... format)
-     * @param amount - Amount in whole units (e.g. 100 = 100 XLM)
-     * @param senderSecret - Sender's secret key, or public key when using `opts.signTransaction`
-     * @param opts - Optional: asset to send, external signer
+     * Why a CONFIGURED indexer was skipped by the health guard (absent when no
+     * indexer is configured, or when it was used). `'stale'` means the indexer's
+     * self-reported lag exceeded `ClientConfig.indexerMaxLagSeconds`.
      */
-    send(metaAddress: string, amount: number, senderSecret: string, opts?: SendOpts): Promise<SendReceipt>;
+    indexerSkipReason?: 'unhealthy' | 'network_mismatch' | 'no_coverage' | 'stale' | 'unreachable';
     /**
-     * Sign a prepared transaction either with a local secret key (legacy path)
-     * or by delegating to an external signer that returns signed XDR.
-     *
-     * @param prepared - The prepared transaction to sign
-     * @param secretOrPublic - Secret key (local signing) or public key (external)
-     * @param publicKey - Signer's public key (G...)
-     * @param signer - Optional external signer; when present, no secret is used
+     * The indexer's self-reported lag when `/health` was read (`null` when the
+     * indexer did not report one). Absent when `/health` was never readable.
      */
-    private signTx;
+    indexerLagSeconds?: number | null;
     /**
-     * Scan for stealth payments you received.
-     *
-     * Uses the view key to detect which announcements are yours,
-     * then queries the contract for current balances.
-     *
-     * @param keys - Your stealth keys (needs viewPrivKey + spendPubKey)
+     * The post-segment `/health` re-check verdict (present whenever the scan
+     * entered the indexer branch). Anything but `'ok'` means the segment's
+     * results and adopted positions were DISCARDED and the Horizon tail
+     * re-walked the whole span — a gap recorded while the segment was being
+     * paged must not advance the client cursor past a hole.
      */
-    scan(keys: StealthKeys): Promise<Payment[]>;
+    postCheck?: 'ok' | 'unhealthy' | 'unreachable';
     /**
-     * Get balances for all your stealth addresses in the pool.
-     *
-     * @param keys - Your stealth keys (needs viewPrivKey + spendPubKey)
+     * True when the final cursor came from indexer-supplied data, exceeded the
+     * chain head Horizon reports, and was clamped down to that head — a
+     * persisted cursor must never point past the chain, or one malicious feed
+     * response would blind every future scan.
+     */
+    cursorClamped?: boolean;
+    /** The scan's segments, in the order they ran. */
+    segments: ScanSegmentMeta[];
+}
+/**
+ * Result of a cursor-aware scan — and of `StealthClient.balanceWithCursor`,
+ * which returns the same shape with balance-view rows (claimed payments
+ * dropped, native rows reporting the live remaining balance).
+ */
+interface ScanResult {
+    /** Detected payments across all scanned methods */
+    payments: Payment[];
+    /** Updated cursor to persist and pass to the next scan */
+    cursor: ScanCursor;
+    /**
+     * Per-method scan diagnostics; populated by the account method today.
+     * Observability only — never affects which payments are found.
      */
-    balance(keys: StealthKeys): Promise<Balance[]>;
+    meta?: Partial<Record<DeliveryMethod, MethodScanMeta>>;
+}
+/** Options for claiming a detected payment. */
+interface ClaimOpts {
+    /** Stealth keys (need view + spend private keys) */
+    keys: StealthKeys;
     /**
-     * Withdraw tokens from the stealth pool.
-     *
-     * Recovers the stealth private key, signs a withdraw message,
-     * and submits the transaction. Use `opts.relay` for privacy-preserving
-     * withdrawal via a relayer.
-     *
-     * @param stealthAddress - The stealth address to withdraw from
-     * @param destination - Destination Stellar address (G...)
-     * @param opts - Withdraw options (keys, feePayer, optional relay/asset/amount)
+     * Relay URL(s) for fee-bumped submission (privacy-preserving). A list is
+     * health-probed and routed like {@link ClientConfig.relayer}.
      */
-    withdraw(stealthAddress: string, destination: string, opts: WithdrawOpts): Promise<WithdrawReceipt>;
+    relay?: string | string[];
+    /**
+     * For the account method: sweep the whole account via AccountMerge (default true).
+     * Set false to leave the stealth account open (Payment, keeping the base reserve).
+     * For the pool method this flag is ignored.
+     */
+    merge?: boolean;
+    /** Secret key of an account paying the fee (pool method direct submission) */
+    feePayer?: string;
+    /** Asset to claim (pool method). Default: native XLM. Format: "CODE:ISSUER" */
+    asset?: string;
+    /**
+     * Amount to claim. Default: full balance. Honored by POOL claims (partial
+     * withdrawal) AND by account-method NATIVE claims with `merge: false`
+     * (partial payout that keeps the stealth account open). Passing it on an
+     * account-method native claim WITHOUT `merge: false`, or on an
+     * account-method token claim (always claimed in full), throws
+     * {@link ClaimAmountRequiresNoMergeError} instead of being silently ignored.
+     */
+    amount?: number;
+    /**
+     * For the account-method token claim: use the relayer's sponsor-claim pair
+     * (prepare -> stealth-sign -> submit) instead of a self-funded stealth tx.
+     * Needed when the stealth account stub is missing / cannot pay reserves.
+     */
+    sponsored?: boolean;
+    /**
+     * App funding account (G-address) to debit the relayer fee against when the
+     * relayer is credit-gated (`RELAYER_REQUIRE_CREDIT=1`). Threaded into the
+     * relay / sponsor-claim submit calls so a gated relayer does not respond 402
+     * `insufficient_credit`. Ignored by a non-gated relayer.
+     */
+    fundingAccount?: string;
+    /**
+     * Signer proving control of {@link fundingAccount}: a credit-gated relayer
+     * requires a fresh challenge nonce signed by the funding account before it
+     * debits credit (proof-of-control; without it every gated relay /
+     * sponsor-claim submit is rejected 401 `missing_auth`). Omit for non-gated
+     * relayers.
+     */
+    fundingSigner?: FundingSigner;
+    /**
+     * Relayed submissions only: poll the relayer-returned txHash until it is
+     * on-chain before returning (SDK-TXHASH-TRUST), surfacing a
+     * `TransactionTimeoutError` (with the hash) if it never lands.
+     */
+    confirm?: boolean;
+    /**
+     * External signer for the FEE-PAYER leg (Freighter-style). When set on a pool
+     * claim, the caller passes the fee payer's PUBLIC key via
+     * {@link ClaimOpts.feePayerAddress} where a secret is normally expected (in
+     * {@link ClaimOpts.feePayer}) and the SDK delegates signing of the fee-paying
+     * transaction to this function instead of `Keypair.fromSecret`. The
+     * stealth-key withdrawal signature is unaffected — a wallet cannot hold the
+     * derived stealth scalar, so it always signs locally.
+     */
+    signTransaction?: TransactionSigner;
+    /**
+     * The fee payer's G-address, required when {@link signTransaction} is set on a
+     * pool claim (which needs a fee payer). The SDK never calls
+     * `Keypair.fromSecret` on this value; it is handed to {@link signTransaction}
+     * as the address to sign with. When {@link signTransaction} is set but this is
+     * missing, a {@link FeePayerAddressRequiredError} is thrown.
+     */
+    feePayerAddress?: string;
+}
+/** Receipt returned after a successful claim. */
+interface ClaimReceipt {
+    /** Transaction hash */
+    txHash: string;
+    /** Amount claimed in whole units */
+    amount: number;
+    /** Which delivery method the claim used */
+    method: DeliveryMethod;
+}
+/** Client configuration. */
+interface ClientConfig {
+    /** Network to connect to (a key of the SDK's `NETWORKS` table) */
+    network: NetworkName;
+    /** Override the default contract ID for the stealth pool */
+    contractId?: string;
+    /** Override the Horizon REST endpoint (used by the account method) */
+    horizonUrl?: string;
+    /**
+     * Optional announcement-indexer URL — an account-method DISCOVERY
+     * accelerator. When set, `scan`/`balance` consume the indexer's
+     * pre-extracted announcement feed (operations inlined, no per-tx Horizon
+     * round-trip) instead of walking every Horizon transaction. Horizon remains
+     * the source of truth: the scan verifies the indexer's /health coverage
+     * first and falls back to the pure Horizon walk automatically when the
+     * indexer is unreachable, unhealthy, or on the wrong network — and always
+     * finishes with a Horizon tail so indexer lag cannot hide a payment.
+     */
+    indexerUrl?: string;
+    /**
+     * Cap (seconds) on the indexer's self-reported `/health` lag before the
+     * account scan skips it entirely. Default 21600 (6 hours) — deliberately
+     * lenient: the Horizon tail already bounds correctness (a lagging indexer
+     * can never hide a payment), and skipping a merely-slow indexer would force
+     * cold scans back toward the full-history walk — so the cap exists only to
+     * disqualify operationally abandoned indexers. `Number.POSITIVE_INFINITY`
+     * disables the cap.
+     */
+    indexerMaxLagSeconds?: number;
+    /** Delivery methods to enable. Default: ['pool'] */
+    methods?: DeliveryMethod[];
+    /**
+     * Default relayer(s) for fee-bumped submissions. A list enables BYO-relayer
+     * discovery: candidates are health-probed in parallel and relayed calls
+     * route to a healthy one (with failover on relayer faults) per
+     * {@link relayerSelection}. A single string behaves exactly as before.
+     */
+    relayer?: string | string[];
+    /**
+     * How a healthy relayer is picked from a multi-URL {@link relayer} list.
+     * Default `'random'` — spreads users across the relayer set instead of
+     * herding onto the first entry (anonymity-set preserving). Only meaningful
+     * with more than one URL.
+     */
+    relayerSelection?: RelayerSelection;
+}
+
+/**
+ * High-level client for stealth payments on Stellar.
+ *
+ * Wraps DKSAP cryptography behind pluggable delivery methods. Each method
+ * (`'pool'`, `'account'`, and the reserved `'spp'`) is an adapter; the client
+ * builds a registry from `config.methods` and routes send/scan/claim through it.
+ *
+ * @example
+ * ```typescript
+ * const client = new StealthClient({
+ *   network: 'testnet',
+ *   contractId: 'C...', // your deployed pool contract (required for 'pool')
+ *   methods: ['pool', 'account'],
+ * });
+ *
+ * const keys = StealthClient.keygen();
+ *
+ * // A method is REQUIRED on every send — no implicit default.
+ * await client.send(keys.metaAddress, 100, 'SXXX...', { method: 'auto' });
+ *
+ * const { payments } = await client.scanWithCursor(keys);
+ * await client.claim(payments[0], 'GDEST...', { keys });
+ * ```
+ */
+declare class StealthClient {
+    private readonly contractId;
+    private readonly networkPassphrase;
+    private readonly server;
+    private readonly enabledMethods;
+    private readonly adapters;
+    private readonly relayer?;
+    private readonly relayerSelection?;
+    constructor(config: ClientConfig);
+    /**
+     * Generate a new random stealth key pair.
+     * No network connection needed.
+     */
+    static keygen(): StealthKeys;
+    /**
+     * Generate stealth keys from a BIP-39 mnemonic.
+     * Returns the mnemonic alongside the keys for backup.
+     * No network connection needed.
+     */
+    static fromMnemonic(mnemonic?: string): StealthKeys & {
+        mnemonic: string;
+    };
+    /**
+     * Resolve `'auto'` to a concrete method: native asset AND amount > 1 AND
+     * 'account' enabled -> 'account'; otherwise 'pool'.
+     */
+    private resolveMethod;
+    private getAdapter;
+    /**
+     * Send tokens to a stealth address via the chosen delivery method.
+     *
+     * A method is REQUIRED on every call (`opts.method`). Pass `'auto'` to let the
+     * client resolve one; there is deliberately no implicit default.
+     *
+     * @param metaAddress - Recipient's meta-address (shade:stellar:... format)
+     * @param amount - Amount in whole units (e.g. 100 = 100 XLM)
+     * @param senderSecret - Sender's Stellar secret key
+     * @param opts - Delivery method (required) and optional asset
+     * @throws {MethodRequiredError} If no method is provided.
+     * @throws {MethodNotEnabledError} If the resolved method is not enabled.
+     */
+    send(metaAddress: string, amount: number, senderSecret: string, opts: SendOpts): Promise<SendReceipt>;
+    /**
+     * Scan for stealth payments across every enabled delivery method.
+     *
+     * @param keys - Your stealth keys (needs viewPrivKey + spendPubKey)
+     */
+    scan(keys: StealthKeys): Promise<Payment[]>;
+    /**
+     * Cursor-aware scan across enabled (or explicitly requested) methods. Returns
+     * the merged payments plus an updated per-method cursor to persist and pass to
+     * the next scan for incremental discovery.
+     *
+     * @param keys - Your stealth keys (needs viewPrivKey + spendPubKey)
+     * @param opts - Optional method filter and resume cursor
+     */
+    scanWithCursor(keys: StealthKeys, opts?: ScanOpts): Promise<ScanResult>;
+    /**
+     * Shared scan implementation. When `suppressClaimed` is set (the balance
+     * path), the account adapter drops fully-swept/merged native accounts (live
+     * balance 0) so a spent stealth account is not reported as spendable — while
+     * the plain discovery scan keeps returning still-claimable rows.
+     */
+    private scanInternal;
+    /**
+     * Get balances for all your stealth payments across enabled methods.
+     *
+     * @param keys - Your stealth keys (needs viewPrivKey + spendPubKey)
+     * @param opts - Optional method filter and resume cursor (a cursor returned
+     *   by a previous {@link scanWithCursor}/{@link balanceWithCursor}). With no
+     *   opts the whole history is scanned, exactly as before. Passing the
+     *   persisted cursor turns the account phase from a full Horizon re-walk
+     *   into O(new transactions); use {@link balanceWithCursor} when you also
+     *   need the advanced cursor back to persist it.
+     */
+    balance(keys: StealthKeys, opts?: ScanOpts): Promise<Balance[]>;
+    /**
+     * Cursor-aware balance check: like {@link balance}, but resumes the
+     * underlying scan from `opts.cursor` and returns the full live payments
+     * (ephemeral key, txHash, claimable-balance id) PLUS the advanced cursor so
+     * callers can persist it for the next call — the exact counterpart of
+     * {@link scanWithCursor} for the balance path.
+     *
+     * The rows are the balance view: claimed/fully-swept payments are dropped
+     * and native rows report the LIVE remaining account balance (not the
+     * original per-transaction amount). Callers that persist discovered
+     * payments should merge these rows into their cache BEFORE persisting the
+     * advanced cursor, since the next resumed scan will skip everything behind
+     * it.
+     *
+     * @param keys - Your stealth keys (needs viewPrivKey + spendPubKey)
+     * @param opts - Optional method filter and resume cursor
+     */
+    balanceWithCursor(keys: StealthKeys, opts?: ScanOpts): Promise<ScanResult>;
+    /**
+     * Claim a detected payment to a destination, branching on the payment's
+     * delivery method: `'pool'` uses the withdraw path, `'account'` sweeps or
+     * partially pays out the stealth account.
+     *
+     * @param payment - A payment returned from {@link scan}/{@link scanWithCursor}.
+     * @param destination - Destination Stellar G-address.
+     * @param opts - Claim options (keys required; relay/merge/feePayer optional).
+     */
+    claim(payment: Payment, destination: string, opts: ClaimOpts): Promise<ClaimReceipt>;
+    /**
+     * Withdraw tokens from the stealth pool.
+     *
+     * @deprecated Use {@link claim} with a pool payment instead. Retained for
+     * backwards compatibility; behaves exactly like the original pool withdraw.
+     *
+     * @param stealthAddress - The stealth address to withdraw from
+     * @param destination - Destination Stellar address (G...)
+     * @param opts - Withdraw options (keys, feePayer, optional relay/asset/amount)
+     */
+    withdraw(stealthAddress: string, destination: string, opts: WithdrawOpts): Promise<WithdrawReceipt>;
+}
+
+/**
+ * Crypto's raw (`Uint8Array`-based) meta-address, mirrored here.
+ *
+ * The SDK's own {@link StealthMetaAddress} is a `shade:stellar:` *string*; this
+ * is the byte-level pair the crypto layer works with.
+ */
+interface RawStealthMetaAddress {
+    /** 32-byte ed25519 public key for spending */
+    spendPubKey: Uint8Array;
+    /** 32-byte ed25519 public key for viewing */
+    viewPubKey: Uint8Array;
+}
+/**
+ * Crypto's raw (`Uint8Array`-based) stealth keys, exposed under a distinct name
+ * so code that mixes both layers has one import site: convert with
+ * {@link stealthKeysFromRaw} to get the SDK's hex-string {@link StealthKeys}.
+ */
+interface RawStealthKeys {
+    /** 32-byte ed25519 private key for spending */
+    spendPrivKey: Uint8Array;
+    /** 32-byte ed25519 private key for viewing */
+    viewPrivKey: Uint8Array;
+    /** Derived meta-address containing public keys */
+    metaAddress: RawStealthMetaAddress;
+}
+
+/**
+ * Convert crypto's raw stealth keys (Uint8Array scalars + meta-address object,
+ * as returned by `generateMetaAddress`, `mnemonicToStealthKeys`, or
+ * `deriveKeysFromSignature`) into the SDK's hex-string {@link StealthKeys}
+ * shape used by every client/session API.
+ *
+ * The two packages deliberately reuse the name `StealthKeys` for different
+ * shapes; import the raw one as `RawStealthKeys` (re-exported from the SDK
+ * index) and convert at the boundary with this helper.
+ */
+declare function stealthKeysFromRaw(raw: RawStealthKeys): StealthKeys;
+/**
+ * A wallet signer. Given the derivation message it returns an ed25519 signature
+ * in one of the shapes real wallets produce: raw bytes, a hex/base64 string, or
+ * Freighter's `{ signedMessage }` envelope.
+ */
+type WalletSigner = (message: string) => Promise<Uint8Array | string | {
+    signedMessage: string | Uint8Array;
+}>;
+/**
+ * The default key-derivation scope. This is DECOUPLED from any transport network
+ * (e.g. testnet vs. local) so that a wallet re-derives the same stealth keys
+ * regardless of which network a transaction is later submitted to. The CLI's
+ * `--key-scope` flag defaults to this exact value so both tools line up.
+ */
+declare const DEFAULT_KEY_SCOPE = "stealth";
+/** The default application id used to scope derived keys. */
+declare const DEFAULT_APP_ID = "default";
+/** Options for {@link keysFromWalletSignature}. */
+interface WalletKeysOpts {
+    /**
+     * Key-derivation scope folded into the signed message (crypto's `network`
+     * field). This MUST be decoupled from the transport network: use the same
+     * value everywhere you derive from this wallet, or you will get different
+     * (unrecoverable) keys. Defaults to {@link DEFAULT_KEY_SCOPE} (`'stealth'`),
+     * matching the CLI's `--key-scope` default so both tools derive identical keys.
+     */
+    keyScope?: string;
+    /**
+     * Application id to scope keys (folded into the signed message). Defaults to
+     * {@link DEFAULT_APP_ID} (`'default'`), matching the CLI's `--app-id` default.
+     */
+    appId?: string;
+    /**
+     * Sign the message TWICE and throw when the two signatures differ. This guards
+     * against randomized/hardware signers that would otherwise derive different
+     * (unrecoverable) keys on every call. Defaults to `true`; pass `false` only
+     * for a signer you KNOW is deterministic (RFC 8032) to skip the extra signature.
+     */
+    verifyDeterminism?: boolean;
+}
+/**
+ * Derive stealth keys from a wallet's signature over the canonical derivation
+ * message.
+ *
+ * Because RFC 8032 ed25519 signatures are deterministic, the same wallet
+ * signing the same message always re-derives the same stealth keys — that is
+ * what lets a user recover stealth keys from their wallet alone, with no extra
+ * secret to store. Wallet compromise equals stealth-key compromise; this is the
+ * accepted trade-off for keyless recovery.
+ *
+ * @param signer - Callback that signs the derivation message (see {@link WalletSigner}).
+ * @param opts - Optional keyScope/appId scoping and determinism verification.
+ *   `keyScope` and `appId` MUST match across every tool that derives from this
+ *   wallet (they default to `'stealth'` / `'default'`, the same as the CLI).
+ * @returns Hex-string {@link StealthKeys} in the same shape as `keygen()`.
+ * @throws If the signature is not exactly 64 bytes, or (unless
+ *   `verifyDeterminism: false`) if two signatures over the same message differ.
+ *
+ * @example
+ * ```typescript
+ * // verifyDeterminism defaults to true; pass false only for a known-good signer.
+ * const keys = await keysFromWalletSignature(
+ *   (msg) => freighter.signMessage(msg),
+ *   { appId: 'my-app' },
+ * );
+ * ```
+ */
+declare function keysFromWalletSignature(signer: WalletSigner, opts?: WalletKeysOpts): Promise<StealthKeys>;
+
+/**
+ * Base class for every error the SDK throws deliberately.
+ *
+ * Carries a stable, machine-readable {@link code} so applications can branch on
+ * the error KIND without string-matching messages (which may be reworded) or
+ * relying on `instanceof` (which breaks across duplicated package instances).
+ * Subclasses keep their own `name` and human-readable message.
+ */
+declare class ShadeError extends Error {
+    /**
+     * Stable machine-readable identifier for this error kind (snake_case).
+     * Guaranteed not to change across SDK versions, unlike the message text.
+     */
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown when `send()` is called without an explicit delivery method.
+ * The SDK deliberately has NO implicit default: the app must choose a method
+ * (or `'auto'`) on every send so the privacy trade-off is always a conscious one.
+ */
+declare class MethodRequiredError extends ShadeError {
+    constructor();
+}
+/**
+ * Thrown when a requested delivery method is not present in the client's
+ * configured `methods` list.
+ */
+declare class MethodNotEnabledError extends ShadeError {
+    constructor(method: DeliveryMethod);
+}
+/**
+ * Thrown when a delivery method exists but cannot service the request
+ * (e.g. a non-native asset over the account method, or the reserved spp method).
+ */
+declare class MethodNotAvailableError extends ShadeError {
+    constructor(message: string);
+}
+/**
+ * Thrown when an account-method XLM send is below the protocol minimum
+ * (amount must be strictly greater than 1 XLM to fund a new stealth account).
+ */
+declare class MinimumAmountError extends ShadeError {
+    constructor(amount: number);
+}
+/**
+ * Thrown when a partial account claim requests more than the stealth account can
+ * pay out while keeping its base reserve and covering the fee. The message names
+ * the maximum claimable amount so the caller can retry within bounds.
+ */
+declare class ClaimAmountError extends ShadeError {
+    /** The maximum amount that could be claimed for this account. */
+    readonly max: number;
+    constructor(requested: number, max: number);
+}
+/**
+ * Thrown when `opts.amount` is passed to a claim that CANNOT honor it, instead
+ * of silently moving a different amount (fund-safety):
+ * - An account-method NATIVE claim with an effective merge (`merge` omitted or
+ *   `true`) sweeps the ENTIRE balance via AccountMerge — `amount` would be
+ *   ignored. Pass `merge: false` for a partial claim, or drop `amount` to sweep.
+ * - An account-method TOKEN claim always claims the claimable balance in full;
+ *   `amount` is not supported there at all.
+ *
+ * Pool claims are unaffected: `amount` is honored as a partial withdrawal.
+ */
+declare class ClaimAmountRequiresNoMergeError extends ShadeError {
+    constructor(kind?: 'native-merge' | 'token');
+}
+/**
+ * Thrown when a send/claim amount is not a positive finite number, caught before
+ * building the transaction so the caller gets an actionable SDK error rather than
+ * an on-chain failure after the fee is burned.
+ */
+declare class InvalidAmountError extends ShadeError {
+    constructor(amount: unknown);
+}
+/**
+ * Thrown by the sponsored token-claim path when the relayer-prepared XDR does
+ * NOT match the operation list the client re-derives from its own trusted inputs
+ * (stealth address, asset, balanceId, destination, amount). A malicious relayer
+ * could otherwise redirect the payout or append an AccountMerge to steal the
+ * just-claimed token; the client refuses to sign such a transaction. The message
+ * names the specific mismatch (e.g. a tampered payout destination or an extra
+ * appended operation) so the failure is diagnosable.
+ */
+declare class SponsoredClaimMismatchError extends ShadeError {
+    constructor(detail: string);
+}
+/**
+ * Thrown by {@link StealthSession.unlock} when the supplied password fails to
+ * decrypt the stored envelope. Surfaces as an AES-GCM authentication failure
+ * (the tag does not verify), which is indistinguishable from tampering — either
+ * way the key material must not be trusted.
+ */
+declare class WrongPasswordError extends ShadeError {
+    constructor();
+}
+/**
+ * Thrown by {@link StealthSession.unlock} when the public keys stored in the
+ * clear on the envelope do NOT match the public keys re-derived from the
+ * decrypted private scalars. The private material is protected by AES-GCM, but
+ * the cleartext `spendPublicKey`/`viewPublicKey` are not — a storage-WRITE
+ * attacker (no password) could otherwise substitute a wrong pubkey and silently
+ * break scanning (denial of discovery). Re-deriving and asserting equality on
+ * unlock turns that silent mis-scan into a loud, diagnosable failure.
+ */
+declare class SessionIntegrityError extends ShadeError {
+    constructor(which: 'spend' | 'view');
+}
+/**
+ * Thrown by the pool withdraw path when the resolved stealth address holds no
+ * balance in the pool contract for the requested asset — there is nothing to
+ * withdraw. Recoverable: the caller may have already withdrawn, or is querying
+ * the wrong asset.
+ */
+declare class NoBalanceError extends ShadeError {
+    constructor();
+}
+/**
+ * Thrown by the pool withdraw path when no announcement matching the given
+ * stealth address can be found for these keys — the payment is not ours or has
+ * not yet been indexed.
+ */
+declare class AnnouncementNotFoundError extends ShadeError {
+    constructor();
+}
+/**
+ * Thrown by the account claim path when the stealth account cannot be found on
+ * Horizon — typically because the funding send has not yet confirmed.
+ */
+declare class StealthAccountNotFoundError extends ShadeError {
+    constructor();
+}
+/**
+ * Thrown by a token claim when the destination account does not (or cannot yet)
+ * trust the asset being claimed. The message names the actionable fix — add the
+ * trustline on the destination before claiming.
+ */
+declare class DestinationTrustlineError extends ShadeError {
+    constructor(message: string);
+}
+/**
+ * Thrown by the pool withdraw path when a fee-payer secret is required (to pay
+ * the Soroban invocation fee) but none was supplied.
+ */
+declare class FeePayerRequiredError extends ShadeError {
+    constructor();
+}
+/**
+ * Thrown by the pool claim path when an external {@link TransactionSigner} is
+ * supplied (via `signTransaction`) but no `feePayerAddress` is given. A pool
+ * claim needs a fee payer; with external signing the fee payer is identified by
+ * its G-address, never a secret. Failing loudly here prevents the SDK from ever
+ * calling `Keypair.fromSecret` on a public key.
+ */
+declare class FeePayerAddressRequiredError extends ShadeError {
+    constructor();
+}
+/**
+ * Thrown by the pool withdraw path when the recipient's persistent Balance/Nonce
+ * ledger entry has been archived (Soroban state expiration) and the automatic
+ * RestoreFootprint transaction that must precede the withdraw could not be
+ * completed. Withdrawing over an archived footprint fails on-chain even though
+ * `get_balance`/`scan` still report the funds, so the SDK restores the entry
+ * first; if that restore itself fails the funds are recoverable but the withdraw
+ * cannot proceed until the entry is restored. The message carries the underlying
+ * cause so the operator can diagnose (e.g. an unfunded fee payer or a relayer
+ * rejection).
+ */
+declare class EntryArchivedRestoringError extends ShadeError {
+    constructor(cause: string);
+}
+/**
+ * Thrown when the RPC `sendTransaction` returns a non-terminal status that means
+ * the transaction did NOT land — `TRY_AGAIN_LATER` (the node dropped it without
+ * queueing) or any other non-`PENDING`/`SUCCESS` status. Nothing was submitted,
+ * so the caller may safely retry with a fresh submission. Treating this as a
+ * (retryable) failure prevents returning a success receipt for a tx that never
+ * entered the ledger (SDK-01).
+ */
+declare class TransactionRetryableError extends ShadeError {
+    /** Marks this error as safe to retry (the tx never entered the ledger). */
+    readonly retryable: true;
+    constructor(status: string);
+}
+/**
+ * Thrown when confirmation polling gives up while the transaction is still
+ * PENDING. The transaction was ACCEPTED by the RPC and MAY STILL LAND on-chain
+ * after this error — blindly resubmitting could double-send the funds. The
+ * error carries {@link txHash} so callers can keep polling that hash (e.g.
+ * `getTransaction`) to a terminal status before deciding to retry;
+ * `retryable` is `false` to distinguish it from
+ * {@link TransactionRetryableError} in shared retry loops.
+ */
+declare class TransactionTimeoutError extends ShadeError {
+    /**
+     * NOT safe to blind-retry: unlike {@link TransactionRetryableError}, the
+     * transaction may still be applied after this error is thrown.
+     */
+    readonly retryable: false;
+    /** Hash of the still-pending transaction — poll it before any resubmission. */
+    readonly txHash: string;
+    constructor(txHash: string);
+}
+/**
+ * Thrown when a relayer HTTP endpoint responds non-2xx. Carries the HTTP
+ * {@link status} and the relayer's own machine-readable {@link relayerCode}
+ * (e.g. `insufficient_credit`, `missing_auth`) so callers — and the
+ * `RelayerPool` failover — can branch on the KIND of failure: 5xx is a relayer
+ * fault worth failing over, 4xx is this request's fault and would only repeat.
+ */
+declare class RelayerHttpError extends ShadeError {
+    /** HTTP status the relayer responded with. */
+    readonly status: number;
+    /** The relayer's own `code` field from the error body, when present. */
+    readonly relayerCode?: string;
+    constructor(path: string, status: number, relayerCode?: string, detail?: string);
+}
+/**
+ * Thrown when a relayer cannot be reached at the transport level (DNS failure,
+ * refused connection, aborted fetch, invalid response body). Distinct from
+ * {@link RelayerHttpError} so the `RelayerPool` can treat it as a candidate
+ * fault (fail over) rather than a request fault.
+ */
+declare class RelayerNetworkError extends ShadeError {
+    constructor(path: string, detail: string);
+}
+/**
+ * Thrown when an indexer HTTP endpoint responds non-2xx. Carries the HTTP
+ * {@link status} and the indexer's own machine-readable {@link indexerCode}
+ * from the `{ error, code }` body so callers can branch on the failure KIND.
+ * The account scan treats it as "abandon the indexer segment" and falls back
+ * to the Horizon walk — Horizon remains the source of truth.
+ */
+declare class IndexerHttpError extends ShadeError {
+    /** HTTP status the indexer responded with. */
+    readonly status: number;
+    /** The indexer's own `code` field from the error body, when present. */
+    readonly indexerCode?: string;
+    constructor(path: string, status: number, indexerCode?: string, detail?: string);
+}
+/**
+ * Thrown when an indexer cannot be reached at the transport level (DNS
+ * failure, refused connection, request timeout, invalid response body).
+ * Distinct from {@link IndexerHttpError} for parity with the relayer errors;
+ * the account scan treats both the same way (fall back to Horizon).
+ */
+declare class IndexerNetworkError extends ShadeError {
+    constructor(path: string, detail: string);
+}
+/**
+ * Thrown by the `RelayerPool` when no candidate relayer is usable for this
+ * call. {@link candidates} maps every probed URL to the reason it was rejected
+ * (`unreachable: ...`, `timeout`, `http_<status>`, `status_not_ok`,
+ * `network_mismatch (...)`, `balance_below_min (...)`,
+ * `credit_gated_no_funding_auth`), so the failure is diagnosable per relayer
+ * instead of a bare "nothing worked".
+ */
+declare class NoHealthyRelayerError extends ShadeError {
+    /** Per-URL rejection reason for every probed candidate. */
+    readonly candidates: Record<string, string>;
+    constructor(candidates: Record<string, string>);
+}
+/**
+ * Thrown by the {@link StealthClient} constructor when a pool-capable method is
+ * enabled but no contract id was supplied (there are no built-in defaults —
+ * pool deployments are per-operator). Failing here — rather than deep inside a
+ * later Soroban call with an opaque error — makes the misconfiguration obvious:
+ * pass `contractId` explicitly.
+ */
+declare class ContractIdRequiredError extends ShadeError {
+    constructor(network: string);
+}
+/**
+ * Thrown by `getNetworkConfig` (and therefore the {@link StealthClient}
+ * constructor) when the requested network name is not in the `NETWORKS` table.
+ * The type system already restricts `network` to the supported names; this is
+ * the runtime guard for plain-JS callers and stale configs. The message lists
+ * the currently supported networks, so it stays accurate as new networks
+ * (e.g. `'public'` after the external audit) are added to the table.
+ */
+declare class UnsupportedNetworkError extends ShadeError {
+    /** The unknown network name that was requested. */
+    readonly network: string;
+    /** The network names this SDK build supports. */
+    readonly supported: string[];
+    constructor(network: string, supported: string[]);
+}
+
+/**
+ * Exact decimal <-> stroop conversions.
+ *
+ * A stroop is 1e-7 of a Stellar asset unit. Converting whole-unit amounts with
+ * `Math.round(amount * 1e7)` or `Number(stroops) / 1e7` silently loses precision
+ * once the magnitude exceeds `Number.MAX_SAFE_INTEGER` stroops (~9.007e8 XLM) —
+ * a float can no longer represent every integer stroop, so large sends drift.
+ * These helpers keep the value as a `bigint` count of stroops end to end and
+ * only render a string at the display edge, so no amount ever round-trips
+ * through a lossy float.
+ */
+/**
+ * Parse a decimal amount string (whole units, e.g. `"100.5"`) into an exact
+ * `bigint` count of stroops.
+ *
+ * @param amount - Decimal string with at most 7 fractional digits.
+ * @throws {Error} If the input is not a non-negative decimal, or carries more
+ *   than 7 fractional digits (which cannot be represented in stroops).
+ */
+declare function parseStroops(amount: string): bigint;
+/**
+ * Convert a `number` amount (whole units) into exact stroops, rejecting values
+ * that cannot be represented exactly (non-finite, negative, or with sub-stroop
+ * fractional precision). Prefer {@link parseStroops} when the amount originates
+ * as a string; this exists for the numeric SDK surface.
+ *
+ * @param amount - Non-negative finite whole-unit amount.
+ */
+declare function numberToStroops(amount: number): bigint;
+/**
+ * Render an exact `bigint` stroop count back to a fixed 7-decimal string
+ * (e.g. `12345000000n` -> `"1234.5000000"`). Never goes through a float.
+ *
+ * @param stroops - Stroop count (non-negative).
+ */
+declare function formatStroops(stroops: bigint): string;
+
+/**
+ * Indexer `/health` response. Coverage is the OPEN interval
+ * `(startCursor, cursor]` over Horizon's ascending transaction feed: the tx
+ * whose paging_token equals `startCursor` is NOT covered (the scan fetches it
+ * from Horizon), while everything after it up to `cursor` is.
+ */
+interface IndexerHealth {
+    status: string;
+    network?: string;
+    /** Announcement store backend. */
+    store?: string;
+    /** Feed position fully covered by the indexer; `null` before first ingest. */
+    cursor: string | null;
+    /** First covered feed position (exclusive); `null` before first ingest. */
+    startCursor: string | null;
+    /** Close time of the last ingested ledger (ISO timestamp). */
+    lastCloseTime?: string | null;
+    /** Seconds the indexer lags the network head. */
+    lagSeconds?: number | null;
+    /** Total announcements held by the store. */
+    announcements?: number;
+    /**
+     * Coverage holes (ledger ranges the indexer knows it skipped). A gapped
+     * indexer reports `status: 'degraded'` and is therefore skipped by the
+     * scan's health guard — listed here so operators can see WHAT is missing.
+     */
+    gaps?: Array<{
+        fromLedger: number;
+        toLedger: number;
+        detectedAt: string;
+    }>;
+    /** Ingest-loop diagnostics (shape owned by the indexer service). */
+    ingest?: unknown;
+}
+/**
+ * One announcement served by the indexer: a successful hash-memo transaction
+ * with its operation records inlined VERBATIM (the same `HorizonOp` shapes
+ * Horizon's `/transactions/{hash}/operations` returns), so consumers need no
+ * per-tx Horizon round-trip.
+ */
+interface IndexerAnnouncement {
+    hash: string;
+    paging_token: string;
+    /** base64 32-byte ephemeral key R (Horizon's MemoHash encoding). */
+    memo: string;
+    memo_type: string;
+    successful: boolean;
+    created_at?: string;
+    /**
+     * Transaction-level source account, when the indexer has it. Enables the
+     * sponsor-precise claimable-balance binding without a per-tx Horizon
+     * round-trip; older feeds omit it and the scan falls back to the
+     * asset+amount binding.
+     */
+    source_account?: string;
+    /** Verbatim Horizon operation records for this transaction. */
+    operations: HorizonOp[];
+}
+/**
+ * Response page from `GET /announcements`. `records` ascend by paging_token
+ * and are strictly greater than the request cursor. `cursor` is the position
+ * to adopt directly for the next call: the last record's token on a full
+ * page, otherwise max(request cursor, indexer global cursor).
+ */
+interface AnnouncementsPage {
+    records: IndexerAnnouncement[];
+    cursor: string;
+}
+/**
+ * Thin HTTP client for the announcement indexer service — the account
+ * method's discovery accelerator. Horizon remains the source of truth: every
+ * failure here surfaces as a typed error the scan treats as "fall back to the
+ * Horizon walk", never as a lost payment.
+ *
+ * Transport failures and timeouts throw {@link IndexerNetworkError}; non-2xx
+ * responses throw {@link IndexerHttpError} carrying the HTTP status and the
+ * indexer's `{ error, code }` body code.
+ *
+ * @example
+ * ```typescript
+ * const indexer = new IndexerClient('http://localhost:3100');
+ * const { cursor } = await indexer.health();
+ * ```
+ */
+declare class IndexerClient {
+    private readonly baseUrl;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    /**
+     * @param baseUrl - Indexer root URL (no trailing slash required).
+     * @param fetchFn - Injectable fetch (defaults to the global `fetch`).
+     * @param opts - Optional per-request timeout in ms (default 10000).
+     */
+    constructor(baseUrl: string, fetchFn?: FetchLike, opts?: {
+        timeoutMs?: number;
+    });
+    private get;
+    /**
+     * Decode an indexer response. A non-JSON body on an error status (e.g. a
+     * proxy's HTML 502 page) must not mask the status, so decode failures fall
+     * back to an empty body there; a non-JSON body on a 2xx is a broken indexer
+     * and surfaces as a transport error.
+     */
+    private decode;
+    /** Probe the indexer's health and coverage window. */
+    health(): Promise<IndexerHealth>;
+    /**
+     * Fetch one page of announcements strictly after `cursor` (omit for the
+     * start of coverage).
+     *
+     * @param cursor - Feed position to resume from (records returned are > it).
+     * @param limit - Page size (the service caps it at 200).
+     * @returns The page's records plus the cursor to adopt for the next call.
+     */
+    getAnnouncements(cursor?: string, limit?: number): Promise<AnnouncementsPage>;
+}
+
+/**
+ * A minimal key/value storage interface. `window.localStorage` satisfies it
+ * directly; cookie / IndexedDB / React-Native wrappers are the app's job. All
+ * methods may be sync or async so async backends work transparently.
+ */
+interface KVStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/** Options for {@link StealthSession}. */
+interface StealthSessionOpts {
+    /** The backing key/value store (e.g. `window.localStorage`). */
+    storage: KVStorage;
+    /** Storage-key namespace prefix. Default `'stealth'`. */
+    namespace?: string;
+}
+/** Cached scan progress so returning users neither re-key nor rescan from zero. */
+interface ScanState {
+    /** Per-method resume cursor. */
+    cursor: ScanCursor;
+    /** Discovered payments so far. */
+    payments: Payment[];
+    /** ISO timestamp of the last update. */
+    updatedAt: string;
+}
+/**
+ * Storage-agnostic, encrypted web session for stealth keys and scan state.
+ *
+ * Keys and scan history are encrypted with AES-256-GCM under a PBKDF2-SHA256
+ * (600k iterations) key derived from the user's password, using only
+ * `globalThis.crypto.subtle` — no new dependencies, works in browsers and Node
+ * 18+. This is intentionally separate from the CLI keystore (which stays on
+ * Node's scrypt).
+ *
+ * @example
+ * ```typescript
+ * const session = new StealthSession({ storage: window.localStorage });
+ * await session.saveKeys(keys, password);
+ * // ... later / new page load ...
+ * await session.unlock(password);
+ * const keys = session.keys;
+ * ```
+ */
+declare class StealthSession {
+    private readonly storage;
+    private readonly namespace;
+    private unlockedKeys;
+    private password;
+    constructor(opts: StealthSessionOpts);
+    private get keysKey();
+    private get scanKey();
+    /**
+     * Encrypt and persist the stealth keys under the given password. The public
+     * keys are stored in the clear (they are shareable); only the private key
+     * material is encrypted.
+     */
+    saveKeys(keys: StealthKeys, password: string): Promise<void>;
+    /**
+     * Decrypt the stored keys into memory using the password.
+     *
+     * @throws {WrongPasswordError} If the password fails the AES-GCM auth check.
+     * @throws If no keys are stored.
+     */
+    unlock(password: string): Promise<StealthKeys>;
+    /** The in-memory keys after {@link unlock}/{@link saveKeys}. */
+    get keys(): StealthKeys;
+    /** Wipe in-memory key material (storage is untouched). */
+    lock(): void;
+    /** Whether keys are present in storage (does not require unlock). */
+    hasKeys(): Promise<boolean>;
+    /** Remove all session data (keys + scan state) and lock in memory. */
+    clear(): Promise<void>;
+    /**
+     * Load the encrypted scan-state cache. Requires an unlocked session (the same
+     * derived key protects it, since payment history is private). Returns null
+     * when nothing is cached.
+     */
+    loadScanState(): Promise<ScanState | null>;
+    /**
+     * Encrypt and persist the scan-state cache under the session password.
+     * Requires an unlocked session.
+     */
+    saveScanState(state: ScanState): Promise<void>;
+}
+
+/**
+ * How to sign a transaction leg for the restore flow — either the fee-payer
+ * secret / external signer already used by the withdraw, expressed as a single
+ * async callback. The helper stays agnostic to local-vs-Freighter signing.
+ */
+type RestoreSigner = (tx: Transaction) => Promise<Transaction>;
+/**
+ * How to submit a signed transaction — either directly to the RPC or fee-bumped
+ * through the relayer, mirroring whatever the withdraw itself uses. Returns the
+ * submitted transaction hash.
+ */
+type RestoreSubmit = (tx: Transaction) => Promise<string>;
+/**
+ * Optional progress reporter (the CLI wires this to a spinner/log line; the SDK
+ * leaves it undefined).
+ */
+type RestoreNotify = (message: string) => void;
+/**
+ * Rebuild the invocation transaction (e.g. the withdraw) from a freshly-fetched
+ * source account. Used ONLY on the restore branch: after the RestoreFootprint
+ * consumes the source account's next sequence number, the invocation must be
+ * rebuilt on the new sequence — reusing the original pre-restore transaction
+ * would submit at an already-consumed sequence (`txBAD_SEQ`). The factory must
+ * produce the exact same operation/fee/timeout as the original build so only the
+ * sequence differs.
+ */
+type RebuildInvocation = (account: Account) => Transaction;
+/**
+ * Prepare a Soroban invocation transaction for submission, transparently
+ * restoring an archived persistent footprint first when required.
+ *
+ * `server.prepareTransaction` only throws on a simulation ERROR — it never
+ * consults `sim.restorePreamble`. When a recipient's persistent Balance/Nonce
+ * entry has archived (Soroban state expiration), simulation returns
+ * SUCCESS-with-restorePreamble; the bare prepare then assembles the withdraw
+ * over the archived footprint, which submits but fails on-chain while
+ * `get_balance`/`scan` still show the funds — an opaque brick.
+ *
+ * This helper reproduces `prepareTransaction`'s behavior for the normal path
+ * (simulate → assemble the passed-in `tx`) but, when
+ * {@link rpc.Api.isSimulationRestore} is true, first builds and submits a
+ * RestoreFootprint transaction from `sim.restorePreamble`, waits for it to
+ * succeed, then — because the restore consumes the fee-payer's next sequence
+ * number — **re-fetches the source account and rebuilds the invocation on the
+ * fresh sequence** via {@link RebuildInvocation} before re-simulating and
+ * assembling. This avoids a `txBAD_SEQ` collision between the restore and the
+ * withdraw. The non-archived path is behaviorally identical to the original
+ * `prepareTransaction` call (the passed-in `tx` is assembled untouched).
+ *
+ * @param tx - The unsigned Soroban invocation transaction (e.g. the withdraw),
+ *   already built on the source account's current sequence. Used directly on the
+ *   non-archived path.
+ * @param rebuildTx - Rebuilds the invocation from a freshly-fetched source
+ *   account; used only on the restore branch to obtain a non-colliding sequence.
+ * @param server - The Soroban RPC server.
+ * @param networkPassphrase - Network passphrase for building the restore tx.
+ * @param signRestore - Signs the RestoreFootprint transaction (fee-payer leg).
+ * @param submitRestore - Submits the signed RestoreFootprint transaction.
+ * @param notify - Optional progress reporter.
+ * @returns The assembled invocation transaction, ready to sign and submit.
+ * @throws {EntryArchivedRestoringError} If the entry is archived and the
+ *   restore transaction could not be completed.
+ */
+declare function prepareWithRestore(tx: Transaction, rebuildTx: RebuildInvocation, server: rpc.Server, networkPassphrase: string, signRestore: RestoreSigner, submitRestore: RestoreSubmit, notify?: RestoreNotify): Promise<Transaction>;
+
+/** Parameters passed to a delivery adapter's `send`. */
+interface AdapterSendParams {
+    /** Recipient meta-address (shade:stellar:... or spend:view hex) */
+    metaAddress: string;
+    /** Amount in whole units */
+    amount: number;
+    /**
+     * Sender's Stellar secret key — OR, when {@link signTransaction} is set, the
+     * sender's PUBLIC G-address (the SDK never calls `Keypair.fromSecret` on it).
+     */
+    senderSecret: string;
+    /** Asset to send. Default: native XLM. Format: "CODE:ISSUER" */
+    asset?: string;
+    /**
+     * Optional external signer for the sender leg (Freighter-style). When set,
+     * {@link senderSecret} carries the sender's G-address and the adapter
+     * delegates signing to this function instead of `Keypair.fromSecret`.
+     */
+    signTransaction?: TransactionSigner;
+}
+/**
+ * A pluggable delivery method. Each adapter fully owns one way of getting funds
+ * to a stealth recipient: how to send, how to discover incoming payments, and
+ * how to claim them. The client just wires adapters together per config.
+ */
+interface DeliveryAdapter {
+    /** The delivery method this adapter implements. */
+    readonly method: DeliveryMethod;
+    /**
+     * Send funds to a stealth recipient using this method.
+     *
+     * @param params - Recipient, amount, sender secret, and optional asset.
+     * @returns The one-time stealth address and delivering transaction hash.
+     */
+    send(params: AdapterSendParams): Promise<SendReceipt>;
+    /**
+     * Discover incoming payments for the given keys.
+     *
+     * @param keys - Recipient stealth keys (needs viewPrivKey + spendPubKey).
+     * @param cursor - Opaque per-method resume cursor.
+     * @param opts - `suppressClaimedNative` drops swept accounts (balance view);
+     *   `exhaustive` disables the account adapter's indexer fast cold start.
+     *   Adapters ignore flags that do not apply to their method.
+     * @returns Detected payments, the next cursor to persist, and optional
+     *   per-scan diagnostics (observability only — see {@link MethodScanMeta}).
+     */
+    scan(keys: StealthKeys, cursor?: string, opts?: {
+        suppressClaimedNative?: boolean;
+        exhaustive?: boolean;
+    }): Promise<{
+        payments: Payment[];
+        cursor?: string;
+        meta?: MethodScanMeta;
+    }>;
+    /**
+     * Claim a previously discovered payment to a destination.
+     *
+     * @param payment - The payment to claim (from `scan`).
+     * @param destination - Destination Stellar G-address.
+     * @param opts - Claim options (keys, relay, merge, etc.).
+     * @returns The claim transaction hash, amount, and method.
+     */
+    claim(payment: Payment, destination: string, opts: ClaimOpts): Promise<ClaimReceipt>;
+}
+
+/**
+ * The pool delivery adapter: deposit/scan/withdraw against the Soroban pool
+ * contract. This is the original, private, multi-token path — the logic here is
+ * the behavior previously inlined in `StealthClient`, extracted unchanged so the
+ * client can treat it as one adapter among several.
+ */
+declare class PoolAdapter implements DeliveryAdapter {
+    private readonly contractId;
+    private readonly networkPassphrase;
+    private readonly server;
+    readonly method: "pool";
+    private readonly relayerSelection?;
+    constructor(contractId: string, networkPassphrase: string, server: StellarSdk.rpc.Server, opts?: {
+        relayerSelection?: RelayerSelection;
+    });
+    /**
+     * Derive a one-time stealth address and deposit into the pool contract,
+     * recording the announcement atomically with the deposit.
+     */
+    send(params: AdapterSendParams): Promise<SendReceipt>;
+    /**
+     * Scan pool announcements starting at the cursor (announcement index). The
+     * cursor advances by the number of announcements returned; a cheap
+     * `get_announcement_count` lets callers skip a full scan when nothing is new.
+     */
+    scan(keys: StealthKeys, cursor?: string): Promise<{
+        payments: Payment[];
+        cursor?: string;
+    }>;
+    private matchAndPrice;
+    /**
+     * Claim (withdraw) a pool payment: recover the stealth key, sign a withdraw
+     * message, and submit — directly or via a relayer fee-bump.
+     */
+    claim(payment: Payment, destination: string, opts: ClaimOpts): Promise<ClaimReceipt>;
+    /**
+     * The original pool withdraw path, preserved for the client's `@deprecated`
+     * `withdraw()` alias and reused by `claim()`.
+     */
+    withdraw(stealthAddress: string, destination: string, opts: {
+        keys: StealthKeys;
+        feePayer: string;
+        /** Relay URL(s); a list is health-probed and routed with failover. */
+        relay?: string | string[];
+        asset?: string;
+        amount?: number;
+        signTransaction?: TransactionSigner;
+        feePayerAddress?: string;
+        /** App funding account to debit against (credit-gated relayers). */
+        fundingAccount?: string;
+        /**
+         * Signer proving control of `fundingAccount` — a credit-gated relayer
+         * rejects `/relay` without a signed challenge (proof-of-control), so
+         * `fundingAccount` alone is not enough to spend credit.
+         */
+        fundingSigner?: FundingSigner;
+        /**
+         * Relayed submissions only: poll the relayer-returned txHash until it is
+         * actually on-chain before returning (SDK-TXHASH-TRUST), surfacing a
+         * `TransactionTimeoutError` (with the hash) if it never lands. Default
+         * `false`: trust the relayer's response, exactly as before. The direct
+         * (non-relay) path already confirms via `resolveSendResult` regardless.
+         */
+        confirm?: boolean;
+    }): Promise<{
+        txHash: string;
+        amount: number;
+    }>;
+}
+
+/**
+ * The account delivery adapter: a direct classic Stellar payment that
+ * creates/pays a one-time stealth account, with the ephemeral key R carried in
+ * a 32-byte MemoHash. No view tag is needed — the destination match against the
+ * DKSAP-derived address IS the full verification.
+ *
+ * Native XLM lands via CreateAccount/Payment; tokens land as a
+ * CreateClaimableBalance the recipient later claims (adding a trustline first).
+ */
+declare class AccountAdapter implements DeliveryAdapter {
+    private readonly networkPassphrase;
+    private readonly horizon;
+    private readonly relayer?;
+    readonly method: "account";
+    private readonly rpcServer?;
+    private readonly relayerSelection?;
+    private readonly indexer?;
+    private readonly indexerMaxLagSeconds;
+    constructor(networkPassphrase: string, horizon: HorizonClient, relayer?: string | string[] | undefined, opts?: {
+        rpcServer?: TransactionStatusSource;
+        relayerSelection?: RelayerSelection;
+        /** Optional discovery accelerator consumed by {@link scan}. */
+        indexer?: IndexerClient;
+        /**
+         * Cap on the indexer's self-reported lag before the health guard skips
+         * it (default {@link DEFAULT_INDEXER_MAX_LAG_SECONDS}; see the rationale
+         * there). `Number.POSITIVE_INFINITY` disables the cap.
+         */
+        indexerMaxLagSeconds?: number;
+    });
+    /**
+     * Send funds directly to a one-time stealth account. Native XLM uses a plain
+     * CreateAccount/Payment; a non-native asset uses CreateAccount (to open the
+     * stealth account) plus a CreateClaimableBalance carrying the token. Amount
+     * MUST be strictly greater than 1 XLM for native sends.
+     */
+    send(params: AdapterSendParams): Promise<SendReceipt>;
+    /** Native XLM send: CreateAccount (falls back to Payment on retry). */
+    private sendNative;
+    /**
+     * Token send: one classic tx carrying two operations —
+     * CreateAccount(stealth, 1.5001 XLM) to open the account with trustline
+     * headroom, then CreateClaimableBalance(asset, amount, claimant: stealth,
+     * unconditional). The 0.5 XLM claimable-balance reserve returns to the sender
+     * when the recipient claims. The ephemeral R rides in the MemoHash exactly as
+     * for native sends.
+     *
+     * Not idempotent on retry: unlike {@link sendNative} (which falls back to a
+     * Payment on `op_already_exists`), a token send has no such fallback. Each
+     * token send uses a fresh ephemeral — hence a fresh, never-before-created
+     * stealth address — so a resubmit targets a new account rather than colliding,
+     * making the retry path unnecessary here.
+     */
+    private sendToken;
+    /**
+     * Discover incoming direct payments over Horizon's ascending transaction
+     * feed. For each tx with a hash memo, the memo decodes to a candidate R;
+     * deriving the stealth address from (viewPrivKey, spendPubKey, R) and
+     * finding an operation whose destination equals that address confirms the
+     * payment is ours. Three op shapes are matched:
+     * - `create_account` / `payment` -> a native XLM send.
+     * - `create_claimable_balance` with our address as a claimant -> a token send;
+     *   the claimable balance id is resolved via Horizon's claimable-balances API.
+     *
+     * With an indexer configured (and passing the health guard) the walk is
+     * segmented: a bounded Horizon pre-segment covers anything before the
+     * indexer's coverage window, the covered span consumes pre-extracted
+     * announcements with inlined operations (no per-tx round-trip), and a
+     * Horizon tail ALWAYS runs from the last adopted position so indexer lag —
+     * or an indexer fault mid-segment — can never hide a payment. A cold scan
+     * fast-starts at the indexer's first covered position; payments predating
+     * that coverage need `exhaustive: true`. Without an indexer the behavior is
+     * exactly the original unbounded Horizon walk.
+     *
+     * Every path also returns `meta` — per-segment candidate/match counts plus
+     * the indexer guard's verdict. Strictly observability: the numbers describe
+     * how the scan ran, never which payments it finds.
+     */
+    scan(keys: StealthKeys, cursor?: string, opts?: {
+        suppressClaimedNative?: boolean;
+        exhaustive?: boolean;
+    }): Promise<{
+        payments: Payment[];
+        cursor?: string;
+        meta: MethodScanMeta;
+    }>;
+    /**
+     * Probe the configured indexer and classify whether it is usable for THIS
+     * scan: `status === 'ok'`, same network as this adapter, a non-null
+     * coverage interval, and self-reported lag within the configured cap. On
+     * any guard failure the scan stays on the pure Horizon walk (Horizon is the
+     * source of truth); the returned reason feeds {@link MethodScanMeta} so the
+     * otherwise-silent fallback is observable. A null/absent `lagSeconds` is
+     * NOT stale — lag cannot be measured then, and correctness is tail-bounded
+     * anyway.
+     */
+    private indexerCoverage;
+    /**
+     * Ascending Horizon transaction walk shared by every scan segment,
+     * processing candidates from `from` (exclusive, Horizon cursor semantics).
+     * Unbounded when `stopAtToken` is undefined. When bounded, txs with
+     * `BigInt(paging_token) <= BigInt(stopAtToken)` are processed — INCLUSIVE
+     * of the boundary tx, matching the indexer's open coverage interval
+     * (startCursor, cursor] — and the walk returns `stopAtToken` at the first
+     * tx beyond it. Otherwise returns the last seen paging token (the scan
+     * cursor), or `from` when nothing new was seen. `stats` accumulates the
+     * segment's candidate/match counts (observability only).
+     */
+    private walkHorizon;
+    /**
+     * Run one transaction through the candidate pipeline: verify the memo
+     * shape, decode the ephemeral R, derive the receiver-side stealth address,
+     * and — on an ownership match — collect the native and/or token payment
+     * rows into `payments`.
+     *
+     * `ops` is either the inline operation records (indexer announcements carry
+     * them verbatim — no per-tx round-trip) or a lazy fetch invoked only after
+     * the candidate checks pass (the Horizon walk — preserving the pre-indexer
+     * behavior of never fetching operations for non-candidate txs). The memo
+     * checks run here even for indexer-served records, so a corrupt feed entry
+     * degrades to "not a candidate" rather than a bogus derivation.
+     *
+     * `stats.candidates` counts every tx that passes the memo-shape checks —
+     * BEFORE derivation, so Horizon- and indexer-served sources count
+     * identically — and `stats.matches` counts every payment pushed.
+     */
+    private collectCandidate;
+    /**
+     * Build the native income row for a matched create_account/payment leg, or
+     * `null` to suppress it.
+     *
+     * Suppression is gated on whether the SAME tx also delivered a matching token
+     * claimable balance (`hasTokenLeg`): the token path fronts a fixed reserve via
+     * a create_account stub, which must NOT surface as a native payment — but this
+     * is decided by the presence of the token leg, NOT by any magic starting
+     * balance, so a genuine native send that merely happens to equal the reserve
+     * constant is still discovered.
+     *
+     * On the balance path (`suppressClaimed`) the row reports the account's LIVE
+     * native balance (what remains after any partial claim), and a fully-swept
+     * (0) account is dropped. The discovery path reports the per-tx op amount so
+     * two sends to the same address each surface independently.
+     */
+    private buildNativePayment;
+    /**
+     * Build the token income row for a matched create_claimable_balance leg, or
+     * `null` when no genuine, currently-claimable CB binds to it.
+     *
+     * The candidate CBs (Horizon lists ALL CBs the derived address can claim) are
+     * bound to THIS specific op — not resolved by first-claimant — so an attacker
+     * who creates their own CreateClaimableBalance naming the public stealth
+     * address cannot mask/misattribute the real payment. Binding matches the CB
+     * whose sponsor is the tx source AND whose asset+amount equal this op's, and
+     * whose claim predicate for the derived address is currently satisfiable.
+     */
+    private buildTokenPayment;
+    /**
+     * Select the live claimable balance that genuinely corresponds to this tx's
+     * create_claimable_balance op. Filters candidates to those whose claimant is
+     * the derived address with a currently-satisfiable predicate, then binds by
+     * sponsor === tx source AND asset === op asset AND amount === op amount. Only
+     * when that precise binding is ambiguous or the tx source is unknown does it
+     * fall back to an asset+amount match — never a bare first-claimant pick, so an
+     * attacker CB cannot shadow the real one.
+     */
+    private bindClaimableBalance;
+    /**
+     * Claim a direct-account payment. Branches on the payment shape: a claimable
+     * balance (token send) runs the trustline + claim recipe; a plain XLM send
+     * sweeps or partially pays out the stealth account.
+     */
+    claim(payment: Payment, destination: string, opts: ClaimOpts): Promise<ClaimReceipt>;
+    /**
+     * Claim a native XLM direct send. The stealth account is a real funded Stellar
+     * account with a sequence number. Full sweep (default) uses AccountMerge; a
+     * partial claim uses Payment. Signing uses the raw stealth scalar (verifies as
+     * standard ed25519). Optionally fee-bumped via a relayer.
+     *
+     * Passing `opts.amount` without `merge: false` is rejected up front
+     * ({@link ClaimAmountRequiresNoMergeError}): the default merge sweeps the
+     * ENTIRE balance via AccountMerge, so silently ignoring `amount` would move
+     * more funds than the caller asked for.
+     */
+    private claimNative;
+    /**
+     * Claim a token direct send delivered as a claimable balance. Requires the
+     * destination to already trust the asset (probed first with an actionable
+     * error otherwise).
+     *
+     * Self-funded path (stealth account exists): ChangeTrust(asset) ->
+     * ClaimClaimableBalance(id) -> optional full exit
+     * [Payment(asset, destination) -> ChangeTrust(limit '0') ->
+     * AccountMerge(destination)].
+     *
+     * Sponsored path (`opts.sponsored`, or account stub missing): delegate to the
+     * relayer's sponsor-claim pair — prepare returns XDR, we attach the stealth
+     * signature and submit.
+     */
+    private claimToken;
+    /**
+     * Sponsored claim: relayer prepares the XDR (BeginSponsoring -> [CreateAccount]
+     * -> ChangeTrust -> EndSponsoring -> ClaimClaimableBalance -> Payment to the
+     * destination), we co-sign with the stealth key, relayer submits and pays the
+     * fee. The claimed token is delivered to `destination` in the same tx — the
+     * stealth account never needs its own fee balance. The receipt's amount is the
+     * amount that reached the destination.
+     */
+    private claimTokenSponsored;
+    /**
+     * Parse and verify a relayer-prepared sponsored-claim XDR against the client's
+     * OWN trusted inputs BEFORE signing. This is the client-side security control:
+     * the relayer-side `opsMatch` protects the relayer, not us, so a malicious
+     * relayer could otherwise redirect the payout Payment or append an
+     * AccountMerge to steal the just-claimed token.
+     *
+     * Verifies, throwing {@link SponsoredClaimMismatchError} on any mismatch:
+     * - the tx is sourced by the relayer (never the stealth account);
+     * - the tx carries no memo;
+     * - every operation is one of the allowed sponsor-claim shapes, in the exact
+     *   order the relayer builds — BeginSponsoring(stealth) -> optional
+     *   CreateAccount(stealth, '0') -> ChangeTrust(asset, source stealth) ->
+     *   EndSponsoring(source stealth) -> ClaimClaimableBalance(balanceId, source
+     *   stealth) -> Payment(destination, asset, amount, source stealth);
+     * - every value-moving op is sourced by the stealth account;
+     * - the payout Payment's destination/asset/amount equal the caller's intent;
+     * - no extra, missing, or reordered operations.
+     *
+     * Returns the parsed {@link Transaction} (ready to co-sign) on success.
+     */
+    private verifySponsoredClaimXdr;
+    /**
+     * Resolve the EXACT 7-dp payout string for a token claim from the precise
+     * stroop count, never the lossy `payment.amount` double. Prefers the exact
+     * `payment.amountStroops` string; when it is absent, falls back to the 7-dp
+     * `payment.amount` double with NO extra Horizon read (the amount is already in
+     * hand from the scan). Above 2^53 stroops the double in `payment.amount`
+     * cannot represent every stroop, so an exact stroop count should always be
+     * threaded through when available (SDK-PREC-1).
+     */
+    private resolveExactPayout;
+    /** Recover the stealth scalar for signing from the payment's ephemeral R. */
+    private recoverKey;
+    /** Fail with an actionable error unless the destination trusts the asset. */
+    private assertDestinationTrusts;
+    /** Submit an XDR directly to Horizon, or via a relayer fee-bump when set. */
+    private submit;
+}
+
+/**
+ * Reserved adapter slot for Stellar Private Payments (SPP).
+ *
+ * SPP is the Nethermind ZK shielded-pool research prototype (testnet-only
+ * today). This adapter intentionally implements the full {@link DeliveryAdapter}
+ * surface but every method throws {@link MethodNotAvailableError}. The slot
+ * exists so applications can opt into SPP later — by adding `'spp'` to
+ * `ClientConfig.methods` — with ZERO API changes: the same `send`/`scan`/`claim`
+ * calls simply start routing through a real SPP implementation once it lands.
+ */
+declare class SppAdapter implements DeliveryAdapter {
+    readonly method: "spp";
+    /**
+     * @throws {MethodNotAvailableError} Always — SPP is not yet implemented. The
+     * declared return type is {@link SendReceipt} (never actually returned) so the
+     * adapter's surface matches the {@link DeliveryAdapter} interface exactly.
+     */
+    send(_params: AdapterSendParams): Promise<SendReceipt>;
+    /** @throws {MethodNotAvailableError} Always — SPP is not yet implemented. */
+    scan(_keys: StealthKeys, _cursor?: string): Promise<{
+        payments: Payment[];
+        cursor?: string;
+    }>;
+    /** @throws {MethodNotAvailableError} Always — SPP is not yet implemented. */
+    claim(_payment: Payment, _destination: string, _opts: ClaimOpts): Promise<ClaimReceipt>;
 }
 
-export { type Balance, type ClientConfig, type Payment, type SendOpts, type SendReceipt, StealthClient, type StealthKeys, type TransactionSigner, type WithdrawOpts, type WithdrawReceipt };
+export { AccountAdapter, type AdapterSendParams, AnnouncementNotFoundError, type AnnouncementsPage, type Balance, ClaimAmountError, ClaimAmountRequiresNoMergeError, type ClaimOpts, type ClaimReceipt, type ClientConfig, ContractIdRequiredError, type CreditChallenge, type CreditView, DEFAULT_APP_ID, DEFAULT_KEY_SCOPE, type DeliveryAdapter, type DeliveryMethod, DestinationTrustlineError, EntryArchivedRestoringError, FeePayerAddressRequiredError, FeePayerRequiredError, type FetchLike, type FundingSigner, type HorizonAccount, type HorizonClaimableBalance, type HorizonClaimant, HorizonClient, type HorizonOp, type HorizonPredicate, type HorizonTx, type IndexerAnnouncement, IndexerClient, type IndexerHealth, IndexerHttpError, IndexerNetworkError, InvalidAmountError, type KVStorage, MethodNotAvailableError, MethodNotEnabledError, MethodRequiredError, type MethodScanMeta, MinimumAmountError, NETWORKS, type NetworkConfig, type NetworkDefinition, type NetworkName, NoBalanceError, NoHealthyRelayerError, type Payment, PoolAdapter, type ProbeOutcome, type RawStealthKeys, type RawStealthMetaAddress, type RebuildInvocation, type RelayOpts, type RelayerCallCtx, RelayerClient, type RelayerHealth, RelayerHttpError, RelayerNetworkError, RelayerPool, type RelayerPoolOpts, type RelayerSelection, type RestoreNotify, type RestoreSigner, type RestoreSubmit, type ScanCursor, type ScanOpts, type ScanResult, type ScanSegmentMeta, type ScanState, type SendOpts, type SendReceipt, SessionIntegrityError, ShadeError, type SponsorClaimPrepareArgs, type SponsorClaimPrepared, type SponsorOpts, SponsoredClaimMismatchError, SppAdapter, StealthAccountNotFoundError, StealthClient, type StealthKeys, StealthSession, type StealthSessionOpts, TransactionRetryableError, type TransactionSigner, type TransactionStatusSource, TransactionTimeoutError, UnsupportedNetworkError, type WalletKeysOpts, type WalletSigner, type WithdrawOpts, type WithdrawReceipt, WrongPasswordError, buildWithdrawMessage, challengeMessage, createSimulationTx, formatStroops, getNetworkConfig, keysFromWalletSignature, labelForToken, networkNameForPassphrase, normalizeRelayList, numberToStroops, parseStroops, prepareWithRestore, resolveTokenAddress, simulateReadOnly, stealthKeysFromRaw, waitForTransaction };