stellar-shade 0.0.2 → 0.1.0

package/dist/index.cjs

@@ -1,10 +1,11 @@
 'use strict';
 
-var utils = require('@noble/hashes/utils');
-var utils$1 = require('@noble/curves/abstract/utils');
 var sha256 = require('@noble/hashes/sha256');
 var ed25519 = require('@noble/curves/ed25519');
+var utils = require('@noble/hashes/utils');
+var utils$1 = require('@noble/curves/abstract/utils');
 var sha512 = require('@noble/hashes/sha512');
+require('@noble/hashes/hmac');
 var bip39 = require('@scure/bip39');
 var english = require('@scure/bip39/wordlists/english');
 var StellarSdk = require('@stellar/stellar-sdk');
@@ -29,7 +30,7 @@ function _interopNamespace(e) {
 
 var StellarSdk__namespace = /*#__PURE__*/_interopNamespace(StellarSdk);
 
-// ../crypto/src/errors.ts
+// ../crypto/dist/errors.js
 var PointAtInfinity = class extends Error {
   constructor(operation) {
     super(`Point at infinity encountered in ${operation}`);
@@ -55,21 +56,36 @@ var InvalidMetaAddress = class extends Error {
   }
 };
 var L = 2n ** 252n + 27742317777372353535851937790883648493n;
+function generateRandomScalar() {
+  const bytes = utils.randomBytes(32);
+  const scalar = utils$1.bytesToNumberLE(bytes) % L;
+  return utils$1.numberToBytesLE(scalar, 32);
+}
 function validatePoint(point) {
   if (point.length !== 32) {
     throw new InvalidPublicKey("Invalid point length");
   }
+  let p;
   try {
-    ed25519.ed25519.ExtendedPoint.fromHex(point);
-    return true;
+    p = ed25519.ed25519.ExtendedPoint.fromHex(point);
   } catch (e) {
-    if (e instanceof InvalidPublicKey) throw e;
+    if (e instanceof InvalidPublicKey)
+      throw e;
     throw new InvalidPublicKey("Point not on curve");
   }
+  if (p.equals(ed25519.ed25519.ExtendedPoint.ZERO)) {
+    throw new InvalidPublicKey("Point is the identity element");
+  }
+  if (!p.isTorsionFree()) {
+    throw new InvalidPublicKey("Point is not in the prime-order subgroup");
+  }
+  return true;
 }
 function pointAdd(p1, p2) {
-  if (p1.length !== 32) throw new InvalidPublicKey("Invalid p1 length");
-  if (p2.length !== 32) throw new InvalidPublicKey("Invalid p2 length");
+  if (p1.length !== 32)
+    throw new InvalidPublicKey("Invalid p1 length");
+  if (p2.length !== 32)
+    throw new InvalidPublicKey("Invalid p2 length");
   validatePoint(p1);
   validatePoint(p2);
   const point1 = ed25519.ed25519.ExtendedPoint.fromHex(p1);
@@ -81,7 +97,8 @@ function pointAdd(p1, p2) {
   return result.toRawBytes();
 }
 function scalarMultBase(scalar, allowZero = false) {
-  if (scalar.length !== 32) throw new InvalidScalar("Invalid scalar length");
+  if (scalar.length !== 32)
+    throw new InvalidScalar("Invalid scalar length");
   const s = utils$1.bytesToNumberLE(scalar) % L;
   if (s === 0n) {
     if (!allowZero) {
@@ -93,8 +110,10 @@ function scalarMultBase(scalar, allowZero = false) {
   return result.toRawBytes();
 }
 function scalarMult(scalar, point, allowZero = false) {
-  if (scalar.length !== 32) throw new InvalidScalar("Invalid scalar length");
-  if (point.length !== 32) throw new InvalidPublicKey("Invalid point length");
+  if (scalar.length !== 32)
+    throw new InvalidScalar("Invalid scalar length");
+  if (point.length !== 32)
+    throw new InvalidPublicKey("Invalid point length");
   validatePoint(point);
   const s = utils$1.bytesToNumberLE(scalar) % L;
   if (s === 0n) {
@@ -111,15 +130,20 @@ function scalarMult(scalar, point, allowZero = false) {
   return result.toRawBytes();
 }
 function scalarAdd(s1, s2) {
-  if (s1.length !== 32) throw new InvalidScalar("Invalid s1 length");
-  if (s2.length !== 32) throw new InvalidScalar("Invalid s2 length");
+  if (s1.length !== 32)
+    throw new InvalidScalar("Invalid s1 length");
+  if (s2.length !== 32)
+    throw new InvalidScalar("Invalid s2 length");
   const a = utils$1.bytesToNumberLE(s1) % L;
   const b = utils$1.bytesToNumberLE(s2) % L;
   const result = (a + b) % L;
+  if (result === 0n) {
+    throw new InvalidScalar("Zero scalar not allowed");
+  }
   return utils$1.numberToBytesLE(result, 32);
 }
 
-// ../crypto/src/keys.ts
+// ../crypto/dist/keys.js
 function generateMetaAddress() {
   const spendPrivKey = generateRandomScalar();
   const viewPrivKey = generateRandomScalar();
@@ -134,11 +158,6 @@ function generateMetaAddress() {
     }
   };
 }
-function generateRandomScalar() {
-  const bytes = utils.randomBytes(32);
-  const scalar = utils$1.bytesToNumberLE(bytes) % L;
-  return utils$1.numberToBytesLE(scalar, 32);
-}
 function encodeMetaAddress(meta) {
   if (meta.spendPubKey.length !== 32) {
     throw new InvalidMetaAddress("Invalid spend public key length");
@@ -164,23 +183,22 @@ function encodeMetaAddress(meta) {
   combined.set(payload, 0);
   combined.set(checksum, 64);
   const hex = Array.from(combined).map((b) => b.toString(16).padStart(2, "0")).join("");
-  return `st:stellar:${hex}`;
+  return `shade:stellar:${hex}`;
 }
 function decodeMetaAddress(encoded) {
-  if (!encoded.startsWith("st:stellar:")) {
+  if (!encoded.startsWith("shade:stellar:")) {
     throw new InvalidMetaAddress("Invalid meta-address prefix");
   }
-  const hex = encoded.slice(11);
+  const hex = encoded.slice(14);
   if (hex.length !== 136) {
     throw new InvalidMetaAddress("Invalid meta-address length");
   }
+  if (!/^[0-9a-fA-F]{136}$/.test(hex)) {
+    throw new InvalidMetaAddress("Invalid hex encoding");
+  }
   const combined = new Uint8Array(68);
   for (let i = 0; i < 68; i++) {
-    const byte = parseInt(hex.substr(i * 2, 2), 16);
-    if (isNaN(byte)) {
-      throw new InvalidMetaAddress("Invalid hex encoding");
-    }
-    combined[i] = byte;
+    combined[i] = parseInt(hex.substr(i * 2, 2), 16);
   }
   const payload = combined.slice(0, 64);
   const checksum = combined.slice(64, 68);
@@ -228,7 +246,7 @@ function viewTag(sharedSecret) {
   return hash[0];
 }
 
-// ../crypto/src/stellar-keys.ts
+// ../crypto/dist/stellar-keys.js
 var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
 var VERSION_BYTE_PUBLIC_KEY = 6 << 3;
 function crc16XModem(data) {
@@ -279,7 +297,7 @@ function encodePublicKey(pubKey) {
   return base32Encode(fullPayload);
 }
 
-// ../crypto/src/scan.ts
+// ../crypto/dist/scan.js
 function checkViewTag(viewPrivKey, ephemeralPubKey, expectedTag) {
   if (viewPrivKey.length !== 32) {
     throw new Error("Invalid view private key length");
@@ -307,9 +325,13 @@ function scanAnnouncements(viewPrivKey, spendPubKey, announcements) {
   const results = [];
   const tagMatches = [];
   for (const announcement of announcements) {
-    const tagResult = checkViewTag(viewPrivKey, announcement.ephemeralPubKey, announcement.viewTag);
-    if (tagResult.matches && tagResult.sharedSecret) {
-      tagMatches.push({ announcement, sharedSecret: tagResult.sharedSecret });
+    try {
+      const tagResult = checkViewTag(viewPrivKey, announcement.ephemeralPubKey, announcement.viewTag);
+      if (tagResult.matches && tagResult.sharedSecret) {
+        tagMatches.push({ announcement, sharedSecret: tagResult.sharedSecret });
+      }
+    } catch {
+      continue;
     }
   }
   for (const { announcement, sharedSecret } of tagMatches) {
@@ -326,24 +348,7 @@ function scanAnnouncements(viewPrivKey, spendPubKey, announcements) {
   }
   return results;
 }
-
-// ../crypto/src/recover.ts
-function recoverStealthPrivateKey(spendPrivKey, viewPrivKey, ephemeralPubKey) {
-  if (spendPrivKey.length !== 32) {
-    throw new Error("Invalid spend private key length");
-  }
-  if (viewPrivKey.length !== 32) {
-    throw new Error("Invalid view private key length");
-  }
-  if (ephemeralPubKey.length !== 32) {
-    throw new Error("Invalid ephemeral public key length");
-  }
-  const S = scalarMult(viewPrivKey, ephemeralPubKey);
-  const s = hashToScalar(S);
-  const stealthPrivKey = scalarAdd(spendPrivKey, s);
-  return stealthPrivKey;
-}
-function signWithStealthKey(message, privateScalar) {
+function signWithRawScalarBytes(message, privateScalar) {
   if (privateScalar.length !== 32) {
     throw new Error("Invalid stealth private key length");
   }
@@ -356,6 +361,7 @@ function signWithStealthKey(message, privateScalar) {
   nonceInput.set(privateScalar, 0);
   nonceInput.set(message, 32);
   const r = utils$1.bytesToNumberLE(sha512.sha512(nonceInput)) % L;
+  nonceInput.fill(0);
   const R = ed25519.ed25519.ExtendedPoint.BASE.multiply(r);
   const Rbytes = R.toRawBytes();
   const challengeInput = new Uint8Array(32 + 32 + message.length);
@@ -363,12 +369,114 @@ function signWithStealthKey(message, privateScalar) {
   challengeInput.set(pubKeyBytes, 32);
   challengeInput.set(message, 64);
   const k = utils$1.bytesToNumberLE(sha512.sha512(challengeInput)) % L;
+  challengeInput.fill(0);
   const S = (r + k * a) % L;
   const sig = new Uint8Array(64);
   sig.set(Rbytes, 0);
   sig.set(utils$1.numberToBytesLE(S, 32), 32);
   return sig;
 }
+var StealthScalar = class _StealthScalar {
+  /** Private field: invisible to structural typing, inaccessible outside. */
+  #bytes;
+  constructor(bytes) {
+    this.#bytes = bytes;
+  }
+  /**
+   * Wrap a raw 32-byte ed25519 scalar (interop/tests). The bytes are
+   * defensively copied — mutating (or zeroing) the input afterwards does not
+   * affect the wrapper, and vice versa.
+   *
+   * @param bytes - 32-byte raw scalar (little-endian)
+   * @throws {InvalidScalar} If `bytes` is not exactly 32 bytes.
+   */
+  static fromBytes(bytes) {
+    if (bytes.length !== 32) {
+      throw new InvalidScalar("Invalid stealth private key length");
+    }
+    return new _StealthScalar(new Uint8Array(bytes));
+  }
+  /** Throw if the scalar has been zeroized (an all-zero scalar is never valid). */
+  #assertLive() {
+    if (this.#bytes.every((b) => b === 0)) {
+      throw new InvalidScalar("Stealth scalar is all-zero (already zeroized?) \u2014 it can no longer be used");
+    }
+  }
+  /**
+   * Sign a message with the wrapped raw scalar. Produces a standard ed25519
+   * signature that verifies against {@link publicKey} (scalar * G).
+   *
+   * @param message - The message to sign (must be non-empty)
+   * @returns 64-byte ed25519 signature (R || S)
+   * @throws {InvalidScalar} If the scalar has been {@link zeroize}d.
+   */
+  sign(message) {
+    this.#assertLive();
+    return signWithRawScalarBytes(message, this.#bytes);
+  }
+  /**
+   * The stealth public key this scalar signs for (scalar * G). Compare it to
+   * the announced stealth public key to verify correspondence.
+   *
+   * @throws {InvalidScalar} If the scalar has been {@link zeroize}d.
+   */
+  publicKey() {
+    this.#assertLive();
+    return scalarMultBase(this.#bytes);
+  }
+  /**
+   * Overwrite the wrapped scalar with zeros. Call once you are done signing;
+   * any later {@link sign}/{@link publicKey}/{@link dangerouslyToRawBytes}
+   * throws instead of operating on a dead key. Idempotent.
+   */
+  zeroize() {
+    this.#bytes.fill(0);
+  }
+  /**
+   * DANGER — escape hatch returning a copy of the raw 32-byte scalar. Misuse
+   * of these bytes permanently destroys funds:
+   *
+   * The value is a raw ed25519 SCALAR, **not an ed25519 seed**. Seed-based
+   * Keypair APIs (`Keypair.fromRawEd25519Seed()`, `ed25519.sign()`, wallet
+   * key imports) HASH the input to derive a different signing scalar, so the
+   * resulting keypair's public key does NOT match the stealth address — the
+   * contract/network rejects its signatures and the funds at that address
+   * become PERMANENTLY UNWITHDRAWABLE.
+   *
+   * Only pass these bytes to APIs that consume raw scalars directly (e.g. the
+   * deprecated `signWithStealthKey(message, rawBytes)` overload). Prefer
+   * {@link sign}/{@link publicKey}, and zero any copy you make (`copy.fill(0)`)
+   * as soon as you are done with it.
+   *
+   * @returns A fresh copy of the 32-byte raw scalar.
+   * @throws {InvalidScalar} If the scalar has been {@link zeroize}d.
+   */
+  dangerouslyToRawBytes() {
+    this.#assertLive();
+    return new Uint8Array(this.#bytes);
+  }
+};
+
+// ../crypto/dist/recover.js
+function recoverStealthPrivateKey(spendPrivKey, viewPrivKey, ephemeralPubKey) {
+  if (spendPrivKey.length !== 32) {
+    throw new Error("Invalid spend private key length");
+  }
+  if (viewPrivKey.length !== 32) {
+    throw new Error("Invalid view private key length");
+  }
+  if (ephemeralPubKey.length !== 32) {
+    throw new Error("Invalid ephemeral public key length");
+  }
+  const S = scalarMult(viewPrivKey, ephemeralPubKey);
+  const s = hashToScalar(S);
+  const stealthPrivKey = scalarAdd(spendPrivKey, s);
+  const scalar = StealthScalar.fromBytes(stealthPrivKey);
+  stealthPrivKey.fill(0);
+  return scalar;
+}
+new TextEncoder().encode("amount");
+new TextEncoder().encode("amount-mac");
 function deriveStealthAddressWithSecret(spendPubKey, viewPubKey, ephemeralPrivKey) {
   const R = scalarMultBase(ephemeralPrivKey);
   const S = scalarMult(ephemeralPrivKey, viewPubKey);
@@ -394,8 +502,8 @@ function mnemonicToStealthKeys(mnemonic, passphrase) {
     throw new Error("Invalid mnemonic phrase");
   }
   const seed = bip39.mnemonicToSeedSync(mnemonic, "");
-  const spendTag = textEncoder.encode("stealth-spend");
-  const viewTag2 = textEncoder.encode("stealth-view");
+  const spendTag = textEncoder.encode("shade-spend");
+  const viewTag2 = textEncoder.encode("shade-view");
   const spendInput = new Uint8Array(spendTag.length + seed.length);
   spendInput.set(spendTag, 0);
   spendInput.set(seed, spendTag.length);
@@ -415,13 +523,347 @@ function mnemonicToStealthKeys(mnemonic, passphrase) {
     metaAddress: { spendPubKey, viewPubKey }
   };
 }
+
+// ../crypto/dist/derive-signature.js
+var textEncoder2 = new TextEncoder();
+var KEY_DERIVATION_CONTEXT_V1 = "stellar-shade-keys-v1";
+function buildKeyDerivationMessage(opts) {
+  const network = opts?.network ?? "any";
+  const appId = opts?.appId ?? "default";
+  return [
+    KEY_DERIVATION_CONTEXT_V1,
+    `network:${network}`,
+    `app:${appId}`,
+    "WARNING: Signing this message derives your stealth keys. Only sign it in apps you trust."
+  ].join("\n");
+}
+function deriveKeysFromSignature(signature) {
+  if (signature.length !== 64) {
+    throw new InvalidScalar("Signature must be 64 bytes");
+  }
+  if (signature.every((byte) => byte === 0)) {
+    throw new InvalidScalar("Signature must not be all zeros");
+  }
+  const spendTag = textEncoder2.encode("shade-spend");
+  const viewTag2 = textEncoder2.encode("shade-view");
+  const spendInput = new Uint8Array(spendTag.length + signature.length);
+  spendInput.set(spendTag, 0);
+  spendInput.set(signature, spendTag.length);
+  const viewInput = new Uint8Array(viewTag2.length + signature.length);
+  viewInput.set(viewTag2, 0);
+  viewInput.set(signature, viewTag2.length);
+  const spendPrivKey = hashToScalar(spendInput);
+  const viewPrivKey = hashToScalar(viewInput);
+  spendInput.fill(0);
+  viewInput.fill(0);
+  const spendPubKey = scalarMultBase(spendPrivKey);
+  const viewPubKey = scalarMultBase(viewPrivKey);
+  return {
+    spendPrivKey,
+    viewPrivKey,
+    metaAddress: { spendPubKey, viewPubKey }
+  };
+}
+
+// src/errors.ts
+var ShadeError = class extends Error {
+  /**
+   * Stable machine-readable identifier for this error kind (snake_case).
+   * Guaranteed not to change across SDK versions, unlike the message text.
+   */
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ShadeError";
+    this.code = code;
+  }
+};
+var MethodRequiredError = class extends ShadeError {
+  constructor() {
+    super(
+      "method_required",
+      "A delivery method is required. Pass opts.method: 'pool' | 'account' | 'auto'."
+    );
+    this.name = "MethodRequiredError";
+  }
+};
+var MethodNotEnabledError = class extends ShadeError {
+  constructor(method) {
+    super(
+      "method_not_enabled",
+      `Delivery method '${method}' is not enabled. Add it to ClientConfig.methods to use it.`
+    );
+    this.name = "MethodNotEnabledError";
+  }
+};
+var MethodNotAvailableError = class extends ShadeError {
+  constructor(message) {
+    super("method_not_available", message);
+    this.name = "MethodNotAvailableError";
+  }
+};
+var MinimumAmountError = class extends ShadeError {
+  constructor(amount) {
+    super(
+      "minimum_amount",
+      `Account sends require an amount strictly greater than 1 XLM (got ${amount}).`
+    );
+    this.name = "MinimumAmountError";
+  }
+};
+var ClaimAmountError = class extends ShadeError {
+  /** The maximum amount that could be claimed for this account. */
+  max;
+  constructor(requested, max) {
+    super(
+      "claim_amount_exceeds_max",
+      `Partial claim of ${requested} XLM exceeds the maximum claimable ${max} XLM (account must retain its base reserve and cover the fee).`
+    );
+    this.name = "ClaimAmountError";
+    this.max = max;
+  }
+};
+var ClaimAmountRequiresNoMergeError = class extends ShadeError {
+  constructor(kind = "native-merge") {
+    super(
+      "claim_amount_requires_no_merge",
+      kind === "token" ? "opts.amount is not supported on an account-method token claim: the claimable balance is always claimed (and paid out) in full. Drop opts.amount, then transfer any partial amount onward separately." : "opts.amount was passed but this account-method native claim would MERGE the stealth account and sweep its ENTIRE balance, ignoring amount. Pass opts.merge: false for a partial claim, or drop opts.amount to sweep."
+    );
+    this.name = "ClaimAmountRequiresNoMergeError";
+  }
+};
+var InvalidAmountError = class extends ShadeError {
+  constructor(amount) {
+    super(
+      "invalid_amount",
+      `Amount must be a positive finite number (got ${String(amount)}).`
+    );
+    this.name = "InvalidAmountError";
+  }
+};
+var SponsoredClaimMismatchError = class extends ShadeError {
+  constructor(detail) {
+    super(
+      "sponsored_claim_mismatch",
+      `Refusing to sign sponsored claim: prepared transaction does not match the expected operations (${detail}). The relayer may be malicious.`
+    );
+    this.name = "SponsoredClaimMismatchError";
+  }
+};
+var WrongPasswordError = class extends ShadeError {
+  constructor() {
+    super(
+      "wrong_password",
+      "Wrong password: could not decrypt the stored stealth keys."
+    );
+    this.name = "WrongPasswordError";
+  }
+};
+var SessionIntegrityError = class extends ShadeError {
+  constructor(which) {
+    super(
+      "session_integrity",
+      `Session integrity check failed: the stored ${which} public key does not match the decrypted private key. The stored session may have been tampered with.`
+    );
+    this.name = "SessionIntegrityError";
+  }
+};
+var NoBalanceError = class extends ShadeError {
+  constructor() {
+    super("no_balance", "Stealth address has no balance in the pool.");
+    this.name = "NoBalanceError";
+  }
+};
+var AnnouncementNotFoundError = class extends ShadeError {
+  constructor() {
+    super(
+      "announcement_not_found",
+      "Could not find announcement for this stealth address."
+    );
+    this.name = "AnnouncementNotFoundError";
+  }
+};
+var StealthAccountNotFoundError = class extends ShadeError {
+  constructor() {
+    super(
+      "stealth_account_not_found",
+      "Stealth account not found on Horizon \u2014 has the send confirmed?"
+    );
+    this.name = "StealthAccountNotFoundError";
+  }
+};
+var DestinationTrustlineError = class extends ShadeError {
+  constructor(message) {
+    super("destination_trustline", message);
+    this.name = "DestinationTrustlineError";
+  }
+};
+var FeePayerRequiredError = class extends ShadeError {
+  constructor() {
+    super(
+      "fee_payer_required",
+      "A fee payer secret is required for pool withdrawals."
+    );
+    this.name = "FeePayerRequiredError";
+  }
+};
+var FeePayerAddressRequiredError = class extends ShadeError {
+  constructor() {
+    super(
+      "fee_payer_address_required",
+      "feePayerAddress is required when signTransaction is set on a pool claim. Pass the fee payer G-address (opts.feePayerAddress) \u2014 the SDK signs it via signTransaction."
+    );
+    this.name = "FeePayerAddressRequiredError";
+  }
+};
+var EntryArchivedRestoringError = class extends ShadeError {
+  constructor(cause) {
+    super(
+      "entry_archived_restoring",
+      `Stealth entry is archived and the automatic restore failed (${cause}). The funds are safe but the withdraw cannot proceed until the Balance/Nonce entry is restored \u2014 retry, or restore the footprint manually.`
+    );
+    this.name = "EntryArchivedRestoringError";
+  }
+};
+var TransactionRetryableError = class extends ShadeError {
+  /** Marks this error as safe to retry (the tx never entered the ledger). */
+  retryable = true;
+  constructor(status) {
+    super(
+      "transaction_retryable",
+      `Transaction was not submitted (RPC status: ${status}). Nothing landed on-chain \u2014 retry the submission with a fresh transaction.`
+    );
+    this.name = "TransactionRetryableError";
+  }
+};
+var TransactionTimeoutError = class extends ShadeError {
+  /**
+   * NOT safe to blind-retry: unlike {@link TransactionRetryableError}, the
+   * transaction may still be applied after this error is thrown.
+   */
+  retryable = false;
+  /** Hash of the still-pending transaction — poll it before any resubmission. */
+  txHash;
+  constructor(txHash) {
+    super(
+      "transaction_timeout",
+      `Transaction ${txHash} confirmation timed out while still pending. It may STILL land on-chain \u2014 do NOT blindly resubmit (risk of double-send); poll this hash to a terminal status first.`
+    );
+    this.name = "TransactionTimeoutError";
+    this.txHash = txHash;
+  }
+};
+var RelayerHttpError = class extends ShadeError {
+  /** HTTP status the relayer responded with. */
+  status;
+  /** The relayer's own `code` field from the error body, when present. */
+  relayerCode;
+  constructor(path, status, relayerCode, detail) {
+    super(
+      "relayer_http_error",
+      `Relayer ${path} failed (${status}): ${relayerCode ?? detail ?? "unknown"}`
+    );
+    this.name = "RelayerHttpError";
+    this.status = status;
+    this.relayerCode = relayerCode;
+  }
+};
+var RelayerNetworkError = class extends ShadeError {
+  constructor(path, detail) {
+    super("relayer_unreachable", `Relayer ${path} unreachable: ${detail}`);
+    this.name = "RelayerNetworkError";
+  }
+};
+var IndexerHttpError = class extends ShadeError {
+  /** HTTP status the indexer responded with. */
+  status;
+  /** The indexer's own `code` field from the error body, when present. */
+  indexerCode;
+  constructor(path, status, indexerCode, detail) {
+    super(
+      "indexer_http_error",
+      `Indexer ${path} failed (${status}): ${indexerCode ?? detail ?? "unknown"}`
+    );
+    this.name = "IndexerHttpError";
+    this.status = status;
+    this.indexerCode = indexerCode;
+  }
+};
+var IndexerNetworkError = class extends ShadeError {
+  constructor(path, detail) {
+    super("indexer_network_error", `Indexer ${path} unreachable: ${detail}`);
+    this.name = "IndexerNetworkError";
+  }
+};
+var NoHealthyRelayerError = class extends ShadeError {
+  /** Per-URL rejection reason for every probed candidate. */
+  candidates;
+  constructor(candidates) {
+    const detail = Object.entries(candidates).map(([url, reason]) => `${url}: ${reason}`).join("; ");
+    super(
+      "no_healthy_relayer",
+      `No healthy relayer among ${Object.keys(candidates).length} candidate(s) \u2014 ${detail}`
+    );
+    this.name = "NoHealthyRelayerError";
+    this.candidates = candidates;
+  }
+};
+var ContractIdRequiredError = class extends ShadeError {
+  constructor(network) {
+    super(
+      "contract_id_required",
+      `contractId is required for network '${network}'. Deploy the pool contract and pass its C-address as ClientConfig.contractId (there is no built-in default).`
+    );
+    this.name = "ContractIdRequiredError";
+  }
+};
+var UnsupportedNetworkError = class extends ShadeError {
+  /** The unknown network name that was requested. */
+  network;
+  /** The network names this SDK build supports. */
+  supported;
+  constructor(network, supported) {
+    super(
+      "unsupported_network",
+      `Unsupported network '${network}'. Supported: ${supported.join(", ")}. (The local network has been removed \u2014 dev/test runs on testnet; mainnet arrives after the external audit.)`
+    );
+    this.name = "UnsupportedNetworkError";
+    this.network = network;
+    this.supported = supported;
+  }
+};
+
+// src/soroban.ts
+var NETWORKS = {
+  testnet: {
+    networkPassphrase: StellarSdk.Networks.TESTNET,
+    rpcUrl: "https://soroban-testnet.stellar.org",
+    horizonUrl: "https://horizon-testnet.stellar.org",
+    allowHttp: false
+  }
+  // post-audit (mainnet): uncomment and fill in the production RPC endpoint.
+  // public: {
+  //   networkPassphrase: Networks.PUBLIC,
+  //   rpcUrl: '<soroban mainnet rpc>',
+  //   horizonUrl: 'https://horizon.stellar.org',
+  //   allowHttp: false,
+  // },
+};
+function networkNameForPassphrase(passphrase) {
+  for (const [name, def] of Object.entries(NETWORKS)) {
+    if (def.networkPassphrase === passphrase) return name;
+  }
+  return void 0;
+}
 function getNetworkConfig(network) {
-  const networkPassphrase = network === "local" ? StellarSdk.Networks.STANDALONE : StellarSdk.Networks.TESTNET;
-  const rpcUrl = network === "local" ? "http://localhost:8000/soroban/rpc" : "https://soroban-testnet.stellar.org";
-  const server = new StellarSdk__namespace.rpc.Server(rpcUrl, {
-    allowHttp: network === "local"
-  });
-  return { networkPassphrase, rpcUrl, server };
+  const def = NETWORKS[network];
+  if (!def) {
+    throw new UnsupportedNetworkError(network, Object.keys(NETWORKS));
+  }
+  return {
+    ...def,
+    server: new StellarSdk__namespace.rpc.Server(def.rpcUrl, { allowHttp: def.allowHttp })
+  };
 }
 function createSimulationTx(operation, networkPassphrase) {
   return new StellarSdk.TransactionBuilder(
@@ -450,6 +892,17 @@ function resolveTokenAddress(assetArg, networkPassphrase) {
   }
   return new StellarSdk.Asset(parts[0], parts[1]).contractId(networkPassphrase);
 }
+function labelForToken(tokenAddress, networkPassphrase) {
+  if (!tokenAddress || tokenAddress === "unknown") return tokenAddress;
+  if (tokenAddress === "native" || tokenAddress === "XLM") return "XLM";
+  try {
+    if (tokenAddress === StellarSdk.Asset.native().contractId(networkPassphrase)) {
+      return "XLM";
+    }
+  } catch {
+  }
+  return tokenAddress;
+}
 async function waitForTransaction(server, hash) {
   let attempts = 0;
   while (attempts < 30) {
@@ -464,13 +917,32 @@ async function waitForTransaction(server, hash) {
     }
     attempts++;
   }
-  throw new Error("Transaction confirmation timed out");
+  throw new TransactionTimeoutError(hash);
+}
+async function resolveSendResult(server, result) {
+  switch (result.status) {
+    case "SUCCESS":
+      return result.hash;
+    case "PENDING":
+      await waitForTransaction(server, result.hash);
+      return result.hash;
+    case "DUPLICATE":
+      await waitForTransaction(server, result.hash);
+      return result.hash;
+    case "ERROR":
+      throw new Error("Transaction submission failed");
+    default:
+      throw new TransactionRetryableError(result.status);
+  }
 }
-async function fetchAnnouncements(contractId, server, networkPassphrase) {
+async function fetchAnnouncements(contractId, server, networkPassphrase, start = 0, limit = 1e3) {
   const result = await simulateReadOnly(
     contractId,
     "get_announcements",
-    [StellarSdk.nativeToScVal(0, { type: "u64" }), StellarSdk.nativeToScVal(1e3, { type: "u64" })],
+    [
+      StellarSdk.nativeToScVal(start, { type: "u64" }),
+      StellarSdk.nativeToScVal(limit, { type: "u64" })
+    ],
     server,
     networkPassphrase
   );
@@ -488,6 +960,17 @@ async function fetchAnnouncements(contractId, server, networkPassphrase) {
     };
   });
 }
+async function fetchAnnouncementCount(contractId, server, networkPassphrase) {
+  const result = await simulateReadOnly(
+    contractId,
+    "get_announcement_count",
+    [],
+    server,
+    networkPassphrase
+  );
+  if (result === null || result === void 0) return 0;
+  return Number(result);
+}
 async function queryBalance(contractId, stealthPk, tokenAddress, server, networkPassphrase) {
   const result = await simulateReadOnly(
     contractId,
@@ -523,15 +1006,21 @@ function u64ToBigEndian(value) {
   dv.setBigUint64(0, value);
   return buf;
 }
-function buildWithdrawMessage(stealthPk, tokenAddress, amount, destination, nonce) {
+function buildWithdrawMessage(stealthPk, tokenAddress, amount, destination, nonce, contractId, networkPassphrase) {
+  const domainTag = Buffer.from("SHADE-POOL-WITHDRAW-V1", "utf-8");
   const tokenBytes = Buffer.from(tokenAddress, "utf-8");
   const destBytes = Buffer.from(destination, "utf-8");
+  const contractBytes = Buffer.from(contractId, "utf-8");
   if (tokenBytes.length !== 56) throw new Error(`Token address must be 56 bytes StrKey, got ${tokenBytes.length}`);
   if (destBytes.length !== 56) throw new Error(`Destination must be 56 bytes StrKey, got ${destBytes.length}`);
+  if (contractBytes.length !== 56) throw new Error(`Contract address must be 56 bytes StrKey, got ${contractBytes.length}`);
   const amountBytes = i128ToBigEndian(amount);
   const nonceBytes = u64ToBigEndian(nonce);
-  const msg = new Uint8Array(32 + 56 + 16 + 56 + 8);
+  const networkId = sha256.sha256(Buffer.from(networkPassphrase, "utf-8"));
+  const msg = new Uint8Array(22 + 32 + 56 + 16 + 56 + 8 + 56 + 32);
   let offset = 0;
+  msg.set(domainTag, offset);
+  offset += 22;
   msg.set(stealthPk, offset);
   offset += 32;
   msg.set(tokenBytes, offset);
@@ -541,78 +1030,910 @@ function buildWithdrawMessage(stealthPk, tokenAddress, amount, destination, nonc
   msg.set(destBytes, offset);
   offset += 56;
   msg.set(nonceBytes, offset);
+  offset += 8;
+  msg.set(contractBytes, offset);
+  offset += 56;
+  msg.set(networkId, offset);
   return sha256.sha256(msg);
 }
 
-// src/client.ts
-var DEFAULT_CONTRACTS = {
-  local: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGABAX"
-};
-var StealthClient = class {
-  contractId;
-  networkPassphrase;
-  server;
-  constructor(config) {
-    this.contractId = config.contractId || DEFAULT_CONTRACTS[config.network] || "";
-    const netConfig = getNetworkConfig(config.network);
-    this.networkPassphrase = netConfig.networkPassphrase;
-    this.server = netConfig.server;
+// src/wallet.ts
+function stealthKeysFromRaw(raw) {
+  return {
+    metaAddress: encodeMetaAddress(raw.metaAddress),
+    spendPubKey: Buffer.from(raw.metaAddress.spendPubKey).toString("hex"),
+    spendPrivKey: Buffer.from(raw.spendPrivKey).toString("hex"),
+    viewPubKey: Buffer.from(raw.metaAddress.viewPubKey).toString("hex"),
+    viewPrivKey: Buffer.from(raw.viewPrivKey).toString("hex")
+  };
+}
+var DEFAULT_KEY_SCOPE = "stealth";
+var DEFAULT_APP_ID = "default";
+function decodeToBytes(raw) {
+  const isSignatureHex = raw.length === 128 && /^[0-9a-fA-F]+$/.test(raw);
+  const bytes = isSignatureHex ? new Uint8Array(Buffer.from(raw, "hex")) : new Uint8Array(Buffer.from(raw, "base64"));
+  if (bytes.length !== 64) {
+    throw new Error(
+      `Wallet signature must decode to exactly 64 bytes, got ${bytes.length}`
+    );
+  }
+  return bytes;
+}
+function normalizeSignature(result) {
+  let bytes;
+  if (result instanceof Uint8Array) {
+    bytes = result;
+  } else if (typeof result === "string") {
+    bytes = decodeToBytes(result);
+  } else if (result && typeof result === "object" && "signedMessage" in result) {
+    const inner = result.signedMessage;
+    bytes = inner instanceof Uint8Array ? inner : decodeToBytes(inner);
+  } else {
+    throw new Error("Unsupported signer result shape");
+  }
+  if (bytes.length !== 64) {
+    throw new Error(
+      `Wallet signature must be exactly 64 bytes, got ${bytes.length}`
+    );
+  }
+  return bytes;
+}
+function equalBytes(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+async function keysFromWalletSignature(signer, opts) {
+  const message = buildKeyDerivationMessage({
+    network: opts?.keyScope ?? DEFAULT_KEY_SCOPE,
+    appId: opts?.appId ?? DEFAULT_APP_ID
+  });
+  const signature = normalizeSignature(await signer(message));
+  if (opts?.verifyDeterminism !== false) {
+    const second = normalizeSignature(await signer(message));
+    if (!equalBytes(signature, second)) {
+      throw new Error(
+        "Signer is non-deterministic: two signatures over the same message differ. Wallet-derived stealth keys require a deterministic (RFC 8032) signer."
+      );
+    }
   }
+  return stealthKeysFromRaw(deriveKeysFromSignature(signature));
+}
+
+// src/horizon.ts
+var CLAIMABLE_BALANCE_PAGE_LIMIT = 200;
+var MAX_CLAIMABLE_BALANCE_PAGES = 50;
+var HorizonClient = class {
+  baseUrl;
+  fetchFn;
   /**
-   * Generate a new random stealth key pair.
-   * No network connection needed.
+   * @param baseUrl - Horizon root URL (no trailing slash required).
+   * @param fetchFn - Injectable fetch (defaults to the global `fetch`).
    */
-  static keygen() {
-    const keys = generateMetaAddress();
-    const metaAddress = encodeMetaAddress(keys.metaAddress);
-    return {
-      metaAddress,
-      spendPubKey: Buffer.from(keys.metaAddress.spendPubKey).toString("hex"),
-      spendPrivKey: Buffer.from(keys.spendPrivKey).toString("hex"),
-      viewPubKey: Buffer.from(keys.metaAddress.viewPubKey).toString("hex"),
-      viewPrivKey: Buffer.from(keys.viewPrivKey).toString("hex")
-    };
+  constructor(baseUrl, fetchFn) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.fetchFn = fetchFn ?? globalThis.fetch;
+  }
+  async getJson(path) {
+    const res = await this.fetchFn(`${this.baseUrl}${path}`);
+    if (!res.ok) {
+      throw new Error(`Horizon GET ${path} failed: ${res.status}`);
+    }
+    return await res.json();
   }
   /**
-   * Generate stealth keys from a BIP-39 mnemonic.
-   * Returns the mnemonic alongside the keys for backup.
-   * No network connection needed.
+   * 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).
    */
-  static fromMnemonic(mnemonic) {
-    const phrase = mnemonic || generateMnemonic();
-    const keys = mnemonicToStealthKeys(phrase);
-    const metaAddress = encodeMetaAddress(keys.metaAddress);
-    return {
-      mnemonic: phrase,
-      metaAddress,
-      spendPubKey: Buffer.from(keys.metaAddress.spendPubKey).toString("hex"),
-      spendPrivKey: Buffer.from(keys.spendPrivKey).toString("hex"),
-      viewPubKey: Buffer.from(keys.metaAddress.viewPubKey).toString("hex"),
-      viewPrivKey: Buffer.from(keys.viewPrivKey).toString("hex")
-    };
+  async getTransactions(cursor, limit = 200) {
+    const params = new URLSearchParams({
+      order: "asc",
+      limit: String(limit)
+    });
+    if (cursor) params.set("cursor", cursor);
+    const page = await this.getJson(
+      `/transactions?${params.toString()}`
+    );
+    return page._embedded?.records ?? [];
   }
   /**
-   * 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.
+   * 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.
+   */
+  async getLatestTransactionToken() {
+    const params = new URLSearchParams({ order: "desc", limit: "1" });
+    const page = await this.getJson(
+      `/transactions?${params.toString()}`
+    );
+    return page._embedded?.records?.[0]?.paging_token;
+  }
+  /**
+   * Fetch the operations belonging to a single transaction.
    *
-   * @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
+   * @param txHash - Transaction hash.
+   * @returns The transaction's operation records.
    */
-  async send(metaAddress, amount, senderSecret, opts) {
-    if (amount <= 0) throw new Error("Amount must be positive");
+  async getTransactionOperations(txHash) {
+    const page = await this.getJson(
+      `/transactions/${txHash}/operations?limit=200`
+    );
+    return page._embedded?.records ?? [];
+  }
+  /**
+   * Probe an account. Returns null if the account does not exist (404).
+   *
+   * @param address - Stellar G-address.
+   */
+  async getAccount(address) {
+    const res = await this.fetchFn(`${this.baseUrl}/accounts/${address}`);
+    if (res.status === 404) return null;
+    if (!res.ok) throw new Error(`Horizon GET account failed: ${res.status}`);
+    return await res.json();
+  }
+  /**
+   * 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.
+   */
+  async getClaimableBalances(claimant) {
+    const all = [];
+    let cursor;
+    for (let i = 0; i < MAX_CLAIMABLE_BALANCE_PAGES; i++) {
+      const cursorParam = cursor ? `&cursor=${encodeURIComponent(cursor)}` : "";
+      const page = await this.getJson(
+        `/claimable_balances?claimant=${claimant}&limit=${CLAIMABLE_BALANCE_PAGE_LIMIT}${cursorParam}`
+      );
+      const records = page._embedded?.records ?? [];
+      all.push(...records);
+      if (records.length < CLAIMABLE_BALANCE_PAGE_LIMIT) break;
+      const next = records[records.length - 1]?.paging_token ?? this.cursorFromNextLink(page._links?.next?.href);
+      if (!next || next === cursor) break;
+      cursor = next;
+    }
+    return all;
+  }
+  /**
+   * Extract the `cursor` query parameter from a Horizon `_links.next.href`.
+   * Fallback for full pages whose records carry no `paging_token`.
+   */
+  cursorFromNextLink(href) {
+    if (!href) return void 0;
+    try {
+      return new URL(href, this.baseUrl).searchParams.get("cursor") ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Submit a base64 transaction envelope XDR to Horizon.
+   *
+   * @param xdr - base64-encoded transaction envelope.
+   * @returns The submitted transaction hash.
+   */
+  async submitTransaction(xdr) {
+    const res = await this.fetchFn(`${this.baseUrl}/transactions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: `tx=${encodeURIComponent(xdr)}`
+    });
+    const body = await res.json();
+    if (!res.ok || !body.hash) {
+      throw new Error(
+        `Horizon submit failed: ${JSON.stringify(body.extras?.result_codes ?? res.status)}`
+      );
+    }
+    return { hash: body.hash };
+  }
+};
+
+// src/indexer.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var TIMED_OUT = /* @__PURE__ */ Symbol("timed out");
+function withTimeout(promise, ms) {
+  void promise.catch(() => {
+  });
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(TIMED_OUT), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+var IndexerClient = class {
+  baseUrl;
+  fetchFn;
+  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, fetchFn, opts) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.fetchFn = fetchFn ?? globalThis.fetch;
+    this.timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+  async get(path) {
+    let res;
+    try {
+      const raced = await withTimeout(
+        this.fetchFn(`${this.baseUrl}${path}`),
+        this.timeoutMs
+      );
+      if (raced === TIMED_OUT) {
+        throw new IndexerNetworkError(
+          path,
+          `request timed out after ${this.timeoutMs}ms`
+        );
+      }
+      res = raced;
+    } catch (err) {
+      if (err instanceof IndexerNetworkError) throw err;
+      throw new IndexerNetworkError(
+        path,
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+    return this.decode(path, res);
+  }
+  /**
+   * 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.
+   */
+  async decode(path, res) {
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      data = void 0;
+    }
+    if (!res.ok) {
+      throw new IndexerHttpError(path, res.status, data?.code, data?.error);
+    }
+    if (data === void 0) {
+      throw new IndexerNetworkError(path, "invalid JSON response body");
+    }
+    return data;
+  }
+  /** Probe the indexer's health and coverage window. */
+  async health() {
+    return this.get("/health");
+  }
+  /**
+   * 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.
+   */
+  async getAnnouncements(cursor, limit) {
+    const params = new URLSearchParams();
+    if (cursor !== void 0) params.set("cursor", cursor);
+    if (limit !== void 0) params.set("limit", String(limit));
+    const query = params.toString();
+    return this.get(
+      `/announcements${query ? `?${query}` : ""}`
+    );
+  }
+};
+
+// src/stroops.ts
+var STROOP_DECIMALS = 7;
+var STROOPS_PER_UNIT = 10n ** BigInt(STROOP_DECIMALS);
+function parseStroops(amount) {
+  const trimmed = amount.trim();
+  if (!/^\d+(\.\d+)?$/.test(trimmed)) {
+    throw new Error(
+      `Invalid amount "${amount}" \u2014 expected a non-negative decimal number.`
+    );
+  }
+  const parts = trimmed.split(".");
+  const wholePart = parts[0] ?? "0";
+  const fracPartRaw = parts[1] ?? "";
+  if (fracPartRaw.length > STROOP_DECIMALS) {
+    throw new Error(
+      `Amount "${amount}" has more than ${STROOP_DECIMALS} decimal places (smaller than one stroop).`
+    );
+  }
+  const fracPart = fracPartRaw.padEnd(STROOP_DECIMALS, "0");
+  return BigInt(wholePart) * STROOPS_PER_UNIT + BigInt(fracPart);
+}
+function numberToStroops(amount) {
+  if (!Number.isFinite(amount) || amount < 0) {
+    throw new Error(`Invalid amount ${amount} \u2014 expected a non-negative number.`);
+  }
+  return parseStroops(amount.toString());
+}
+function formatStroops(stroops) {
+  const negative = stroops < 0n;
+  const abs = negative ? -stroops : stroops;
+  const whole = abs / STROOPS_PER_UNIT;
+  const frac = abs % STROOPS_PER_UNIT;
+  const fracStr = frac.toString().padStart(STROOP_DECIMALS, "0");
+  return `${negative ? "-" : ""}${whole.toString()}.${fracStr}`;
+}
+function challengeMessage(endpoint, fundingAccount, nonce, amount, bind) {
+  const base = `shade-relayer:v1:${endpoint}:${fundingAccount}:${nonce}:${amount}`;
+  return bind ? `${base}:${bind}` : base;
+}
+var RelayerClient = class {
+  baseUrl;
+  fetchFn;
+  fundingSigner;
+  fundingAccount;
+  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, fetchFn, opts) {
+    this.baseUrl = baseUrl.replace(/\/relay\/?$/, "").replace(/\/$/, "");
+    this.fetchFn = fetchFn ?? globalThis.fetch;
+    this.fundingAccount = opts?.fundingAccount;
+    this.fundingSigner = opts?.fundingSigner;
+    this.rpcServer = opts?.rpcServer;
+  }
+  /**
+   * 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.
+   */
+  async confirmOnChain(txHash) {
+    if (!this.rpcServer) {
+      throw new Error(
+        "confirm: true requires an RPC handle: pass opts.rpcServer (an rpc.Server for the same network) to the RelayerClient constructor."
+      );
+    }
+    await waitForTransaction(this.rpcServer, txHash);
+  }
+  /**
+   * 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).
+   */
+  async signedAuth(endpoint, fundingAccount, signer, amount, bind) {
+    const account = fundingAccount ?? this.fundingAccount;
+    const fundingSigner = signer ?? this.fundingSigner;
+    if (!account || !fundingSigner) return void 0;
+    const authAmount = amount ?? "0";
+    const { nonce } = await this.get(
+      `/credit/challenge?account=${encodeURIComponent(account)}`
+    );
+    const message = challengeMessage(endpoint, account, nonce, authAmount, bind);
+    const raw = await fundingSigner(message);
+    const signature = typeof raw === "string" ? raw : Buffer.from(raw).toString("base64");
+    return { nonce, signature };
+  }
+  // Transport failures throw RelayerNetworkError and non-2xx responses throw
+  // RelayerHttpError (message text unchanged) so callers — and RelayerPool's
+  // failover — can branch on the failure KIND: unreachable/5xx is a relayer
+  // fault worth failing over, 4xx is this request's fault and would repeat.
+  async post(path, body) {
+    let res;
+    try {
+      res = await this.fetchFn(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      });
+    } catch (err) {
+      throw new RelayerNetworkError(
+        path,
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+    return this.decode(path, res);
+  }
+  async get(path) {
+    let res;
+    try {
+      res = await this.fetchFn(`${this.baseUrl}${path}`);
+    } catch (err) {
+      throw new RelayerNetworkError(
+        path,
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+    return this.decode(path, res);
+  }
+  /**
+   * 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.
+   */
+  async decode(path, res) {
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      data = void 0;
+    }
+    if (!res.ok) {
+      throw new RelayerHttpError(path, res.status, data?.code, data?.error);
+    }
+    if (data === void 0) {
+      throw new RelayerNetworkError(path, "invalid JSON response body");
+    }
+    return data;
+  }
+  /** Probe the relayer's health, balance, and address. */
+  async health() {
+    return this.get("/health");
+  }
+  /**
+   * 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.
+   */
+  async relay(xdr, opts) {
+    const fundingAccount = opts?.fundingAccount ?? this.fundingAccount;
+    const fundingSigner = opts?.fundingSigner ?? this.fundingSigner;
+    const innerTxHash = opts?.networkPassphrase ? new StellarSdk.Transaction(xdr, opts.networkPassphrase).hash().toString("hex") : void 0;
+    let authAmount = opts?.authAmount;
+    if (fundingAccount && fundingSigner && authAmount === void 0) {
+      authAmount = await this.maxRelayFee();
+    }
+    const auth = await this.signedAuth(
+      "relay",
+      fundingAccount,
+      opts?.fundingSigner,
+      authAmount,
+      innerTxHash
+    );
+    const result = await this.post("/relay", {
+      xdr,
+      fundingAccount,
+      ...auth ? { ...auth, authAmount } : {}
+    });
+    if (opts?.confirm) {
+      await this.confirmOnChain(result.txHash);
+    }
+    return result;
+  }
+  /** Cached per-client relayer fee ceiling (XLM, 7-dp), fetched from /health. */
+  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.
+   */
+  async maxRelayFee() {
+    if (this.cachedMaxRelayFee) return this.cachedMaxRelayFee;
+    let cap = 0.1;
+    try {
+      const h = await this.health();
+      if (typeof h.maxRelayFeeXlm === "number" && h.maxRelayFeeXlm > 0) {
+        cap = h.maxRelayFeeXlm;
+      }
+    } catch {
+    }
+    this.cachedMaxRelayFee = cap.toFixed(7);
+    return this.cachedMaxRelayFee;
+  }
+  /** Cached per-client sponsored-reserve estimate; `null` = fetched, absent. */
+  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}.
+   */
+  async sponsoredReserveEstimateStroops() {
+    if (this.cachedSponsoredReserve === void 0) {
+      let estimate = null;
+      try {
+        const h = await this.health();
+        if (typeof h.sponsoredReserveEstimate === "string") {
+          estimate = parseStroops(h.sponsoredReserveEstimate);
+        }
+      } catch {
+      }
+      this.cachedSponsoredReserve = estimate;
+    }
+    return this.cachedSponsoredReserve ?? void 0;
+  }
+  /**
+   * 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.
+   */
+  async sponsor(address, opts) {
+    const fundingAccount = opts?.fundingAccount ?? this.fundingAccount;
+    const auth = await this.signedAuth(
+      "sponsor",
+      fundingAccount,
+      opts?.fundingSigner,
+      opts?.authAmount
+    );
+    return this.post("/sponsor", {
+      address,
+      startingBalance: opts?.startingBalance,
+      fundingAccount,
+      ...auth ?? {}
+    });
+  }
+  /**
+   * 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}.
+   */
+  async sponsorClaimPrepare(args) {
+    return this.post("/sponsor-claim/prepare", args);
+  }
+  /**
+   * 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).
+   */
+  async sponsorClaimSubmit(xdr, args) {
+    const fundingAccount = args.fundingAccount ?? this.fundingAccount;
+    const auth = await this.signedAuth(
+      "sponsor-claim",
+      fundingAccount,
+      args.fundingSigner,
+      args.authAmount
+    );
+    const result = await this.post("/sponsor-claim/submit", {
+      xdr,
+      stealthAddress: args.stealthAddress,
+      asset: args.asset,
+      balanceId: args.balanceId,
+      destination: args.destination,
+      amount: args.amount,
+      fundingAccount,
+      ...auth ?? {}
+    });
+    if (args.confirm) {
+      await this.confirmOnChain(result.txHash);
+    }
+    return result;
+  }
+  /**
+   * Report a completed on-chain deposit to the relayer so it credits the app's
+   * funding account with the paid amount.
+   */
+  async creditClaim(fundingAccount, txHash) {
+    return this.post("/credit/claim", { fundingAccount, txHash });
+  }
+  /** Read the current credit balance for an app funding account. */
+  async creditBalance(fundingAccount) {
+    return this.get(`/credit/${fundingAccount}`);
+  }
+};
+
+// src/relayerPool.ts
+function normalizeRelayList(relay) {
+  if (relay === void 0) return void 0;
+  const list = (Array.isArray(relay) ? relay : [relay]).map((url) => url.trim()).filter(Boolean);
+  return list.length > 0 ? list : void 0;
+}
+var DEFAULT_PROBE_TIMEOUT_MS = 2500;
+var DEFAULT_ATTEMPT_TIMEOUT_MS = 1e4;
+var DEFAULT_MIN_RELAYER_BALANCE_XLM = 1;
+var DEFAULT_PROBE_TTL_MS = 3e4;
+var TIMED_OUT2 = /* @__PURE__ */ Symbol("timed out");
+function withTimeout2(promise, ms) {
+  void promise.catch(() => {
+  });
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(TIMED_OUT2), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+function shuffle(items, rng) {
+  for (let i = items.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [items[i], items[j]] = [items[j], items[i]];
+  }
+}
+var RelayerPool = class _RelayerPool {
+  candidates;
+  network;
+  selection;
+  fetchFn;
+  probeTimeoutMs;
+  attemptTimeoutMs;
+  minBalanceXlm;
+  probeTtlMs;
+  rng;
+  cachedProbe;
+  cachedProbeAt = 0;
+  constructor(candidates, opts) {
+    if (candidates.length === 0) {
+      throw new Error("RelayerPool requires at least one candidate URL");
+    }
+    this.candidates = [...candidates];
+    this.network = opts?.network;
+    this.selection = opts?.selection ?? "random";
+    this.fetchFn = opts?.fetchFn;
+    this.probeTimeoutMs = opts?.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    this.attemptTimeoutMs = opts?.attemptTimeoutMs ?? DEFAULT_ATTEMPT_TIMEOUT_MS;
+    this.minBalanceXlm = opts?.minBalanceXlm ?? DEFAULT_MIN_RELAYER_BALANCE_XLM;
+    this.probeTtlMs = opts?.probeTtlMs ?? DEFAULT_PROBE_TTL_MS;
+    this.rng = opts?.rng ?? Math.random;
+  }
+  /**
+   * 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, opts) {
+    const list = normalizeRelayList(relay);
+    return list ? new _RelayerPool(list, opts) : void 0;
+  }
+  /**
+   * 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.
+   */
+  async probe(force = false) {
+    const now = Date.now();
+    if (!force && this.cachedProbe && now - this.cachedProbeAt < this.probeTtlMs) {
+      return this.cachedProbe;
+    }
+    const outcomes = await Promise.all(
+      this.candidates.map(async (url) => {
+        const client = new RelayerClient(url, this.fetchFn);
+        try {
+          const health = await withTimeout2(client.health(), this.probeTimeoutMs);
+          if (health === TIMED_OUT2) return { url, reason: "timeout" };
+          return { url, health };
+        } catch (err) {
+          if (err instanceof RelayerHttpError) {
+            return { url, reason: `http_${err.status}` };
+          }
+          const detail = err instanceof Error ? err.message : String(err);
+          return { url, reason: `unreachable: ${detail}` };
+        }
+      })
+    );
+    this.cachedProbe = outcomes;
+    this.cachedProbeAt = now;
+    return outcomes;
+  }
+  /**
+   * 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).
+   */
+  async select(ctx) {
+    if (this.candidates.length === 1) return this.candidates[0];
+    const { healthy, reasons } = await this.rankHealthy(ctx);
+    if (healthy.length === 0) throw new NoHealthyRelayerError(reasons);
+    return healthy[0];
+  }
+  /**
+   * 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).
+   */
+  async withRelayer(fn, ctx) {
+    if (this.candidates.length === 1) {
+      const url = this.candidates[0];
+      return fn(this.buildClient(url, ctx), url);
+    }
+    const { healthy, reasons } = await this.rankHealthy(ctx);
+    if (healthy.length === 0) throw new NoHealthyRelayerError(reasons);
+    const attempts = healthy.slice(0, 2);
+    let lastError;
+    for (let i = 0; i < attempts.length; i++) {
+      const url = attempts[i];
+      const hasFallback = i < attempts.length - 1;
+      try {
+        const attempt = fn(this.buildClient(url, ctx), url);
+        const result = hasFallback ? await withTimeout2(attempt, this.attemptTimeoutMs) : await attempt;
+        if (result === TIMED_OUT2) {
+          lastError = new RelayerNetworkError(
+            url,
+            `attempt timed out after ${this.attemptTimeoutMs}ms`
+          );
+          continue;
+        }
+        return result;
+      } catch (err) {
+        const transient = err instanceof RelayerNetworkError || err instanceof RelayerHttpError && err.status >= 500;
+        if (transient && hasFallback) {
+          lastError = err;
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastError;
+  }
+  /** Per-call client carrying the caller's funding auth + confirm handle. */
+  buildClient(url, ctx) {
+    return new RelayerClient(url, this.fetchFn, {
+      fundingAccount: ctx?.fundingAccount,
+      fundingSigner: ctx?.fundingSigner,
+      rpcServer: ctx?.rpcServer
+    });
+  }
+  /**
+   * Classify every probed candidate for this call's context and order the
+   * healthy ones by the selection strategy.
+   */
+  async rankHealthy(ctx) {
+    const outcomes = await this.probe();
+    const healthy = [];
+    const reasons = {};
+    for (const outcome of outcomes) {
+      if (!outcome.health) {
+        reasons[outcome.url] = outcome.reason ?? "unreachable";
+        continue;
+      }
+      const reason = this.healthReason(outcome.health, ctx);
+      if (reason) reasons[outcome.url] = reason;
+      else healthy.push(outcome.url);
+    }
+    if (this.selection === "random") shuffle(healthy, this.rng);
+    return { healthy, reasons };
+  }
+  /** The health rule. Returns the rejection reason, or `undefined` = healthy. */
+  healthReason(health, ctx) {
+    if (health.status !== "ok") return "status_not_ok";
+    if (this.network !== void 0 && health.network !== void 0 && health.network !== this.network) {
+      return `network_mismatch (${health.network} != ${this.network})`;
+    }
+    if (health.balance !== void 0) {
+      const balance = Number(health.balance);
+      if (!Number.isFinite(balance) || balance < this.minBalanceXlm) {
+        return `balance_below_min (${health.balance} < ${this.minBalanceXlm})`;
+      }
+    }
+    const hasFundingAuth = !!(ctx?.fundingAccount && ctx?.fundingSigner);
+    if (health.requireCredit !== false && !hasFundingAuth) {
+      return "credit_gated_no_funding_auth";
+    }
+    return void 0;
+  }
+};
+async function signTx(tx, secretOrAddress, networkPassphrase, signer) {
+  if (signer) {
+    const signed = await signer(tx.toXDR(), {
+      networkPassphrase,
+      address: secretOrAddress
+    });
+    return StellarSdk.TransactionBuilder.fromXDR(signed, networkPassphrase);
+  }
+  tx.sign(StellarSdk.Keypair.fromSecret(secretOrAddress));
+  return tx;
+}
+async function prepareWithRestore(tx, rebuildTx, server, networkPassphrase, signRestore, submitRestore, notify) {
+  const sim = await server.simulateTransaction(tx);
+  if (StellarSdk.rpc.Api.isSimulationError(sim)) {
+    throw new Error(sim.error);
+  }
+  if (StellarSdk.rpc.Api.isSimulationRestore(sim)) {
+    notify?.("Stealth entry archived, restoring before withdraw\u2026");
+    await runRestore(
+      sim.restorePreamble,
+      tx.source,
+      server,
+      networkPassphrase,
+      signRestore,
+      submitRestore
+    );
+    let rebuilt;
+    try {
+      const freshAccount = await server.getAccount(tx.source);
+      rebuilt = rebuildTx(freshAccount);
+    } catch (err) {
+      throw new EntryArchivedRestoringError(err.message);
+    }
+    const fresh = await server.simulateTransaction(rebuilt);
+    if (StellarSdk.rpc.Api.isSimulationError(fresh)) {
+      throw new EntryArchivedRestoringError(fresh.error);
+    }
+    if (StellarSdk.rpc.Api.isSimulationRestore(fresh)) {
+      throw new EntryArchivedRestoringError(
+        "entry still archived after restore submitted"
+      );
+    }
+    return StellarSdk.rpc.assembleTransaction(rebuilt, fresh).build();
+  }
+  return StellarSdk.rpc.assembleTransaction(tx, sim).build();
+}
+async function runRestore(restorePreamble, source, server, networkPassphrase, signRestore, submitRestore) {
+  try {
+    const account = await server.getAccount(source);
+    const fee = (BigInt(restorePreamble.minResourceFee) + BigInt(StellarSdk.BASE_FEE)).toString();
+    const restoreTx = new StellarSdk.TransactionBuilder(account, {
+      fee,
+      networkPassphrase
+    }).setSorobanData(restorePreamble.transactionData.build()).addOperation(StellarSdk.Operation.restoreFootprint({})).setTimeout(30).build();
+    const signed = await signRestore(restoreTx);
+    await submitRestore(signed);
+  } catch (err) {
+    if (err instanceof EntryArchivedRestoringError) throw err;
+    throw new EntryArchivedRestoringError(err.message);
+  }
+}
+
+// src/methods/pool.ts
+var POOL_PAGE_SIZE = 200;
+var PoolAdapter = class {
+  constructor(contractId, networkPassphrase, server, opts) {
+    this.contractId = contractId;
+    this.networkPassphrase = networkPassphrase;
+    this.server = server;
+    this.relayerSelection = opts?.relayerSelection;
+  }
+  contractId;
+  networkPassphrase;
+  server;
+  method = "pool";
+  relayerSelection;
+  /**
+   * Derive a one-time stealth address and deposit into the pool contract,
+   * recording the announcement atomically with the deposit.
+   */
+  async send(params) {
+    const { metaAddress, amount, senderSecret, asset, signTransaction } = params;
+    if (amount <= 0) throw new Error("Amount must be positive");
     const { spendPubKey, viewPubKey } = decodeMetaAddress(metaAddress);
-    const senderPublicKey = opts?.signTransaction ? senderSecret : StellarSdk.Keypair.fromSecret(senderSecret).publicKey();
-    const tokenAddress = resolveTokenAddress(opts?.asset, this.networkPassphrase);
-    const stroops = BigInt(Math.round(amount * 1e7));
+    const senderPublicKey = signTransaction ? senderSecret : StellarSdk.Keypair.fromSecret(senderSecret).publicKey();
+    const tokenAddress = resolveTokenAddress(asset, this.networkPassphrase);
+    const stroops = numberToStroops(amount);
     const ephemeralPrivKey = new Uint8Array(utils.randomBytes(32));
     const stealth = deriveStealthAddressWithSecret(
       spendPubKey,
@@ -636,61 +1957,59 @@ var StealthClient = class {
       )
     ).setTimeout(30).build();
     const prepared = await this.server.prepareTransaction(depositTx);
-    const signed = await this.signTx(
+    const signed = await signTx(
       prepared,
       senderSecret,
-      senderPublicKey,
-      opts?.signTransaction
+      this.networkPassphrase,
+      signTransaction
     );
     const result = await this.server.sendTransaction(signed);
-    if (result.status === "ERROR") {
-      throw new Error("Transaction submission failed");
-    }
-    if (result.status === "PENDING") {
-      await waitForTransaction(this.server, result.hash);
-    }
+    const txHash = await resolveSendResult(this.server, result);
     return {
       stealthAddress: stealth.stealthAddress,
-      txHash: result.hash
+      txHash
     };
   }
   /**
-   * 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
-   */
-  async signTx(prepared, secretOrPublic, publicKey, signer) {
-    if (signer) {
-      const signedXdr = await signer(prepared.toXDR(), {
-        networkPassphrase: this.networkPassphrase,
-        address: publicKey
-      });
-      const tx = StellarSdk.TransactionBuilder.fromXDR(signedXdr, this.networkPassphrase);
-      return tx;
-    }
-    prepared.sign(StellarSdk.Keypair.fromSecret(secretOrPublic));
-    return prepared;
-  }
-  /**
-   * 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)
+   * 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.
    */
-  async scan(keys) {
+  async scan(keys, cursor) {
     const viewPrivKey = Buffer.from(keys.viewPrivKey, "hex");
     const spendPubKey = Buffer.from(keys.spendPubKey, "hex");
-    const announcements = await fetchAnnouncements(
+    const start = cursor ? Number(cursor) : 0;
+    const total = await fetchAnnouncementCount(
       this.contractId,
       this.server,
       this.networkPassphrase
     );
+    if (total <= start) {
+      return { payments: [], cursor: String(start) };
+    }
+    const announcements = [];
+    let offset = start;
+    while (offset < total) {
+      const page = await fetchAnnouncements(
+        this.contractId,
+        this.server,
+        this.networkPassphrase,
+        offset,
+        POOL_PAGE_SIZE
+      );
+      if (page.length === 0) break;
+      announcements.push(...page);
+      offset += page.length;
+    }
+    const nextCursor = String(start + announcements.length);
+    const payments = await this.matchAndPrice(
+      announcements,
+      viewPrivKey,
+      spendPubKey
+    );
+    return { payments, cursor: nextCursor };
+  }
+  async matchAndPrice(announcements, viewPrivKey, spendPubKey) {
     if (announcements.length === 0) return [];
     const matches = scanAnnouncements(
       viewPrivKey,
@@ -718,34 +2037,39 @@ var StealthClient = class {
         stealthAddress: ann.stealthAddress,
         ephemeralPubKey: Buffer.from(ann.ephemeralPubKey).toString("hex"),
         token: ann.token,
-        amount: Number(balance) / 1e7
+        asset: labelForToken(ann.token, this.networkPassphrase),
+        amount: Number(balance) / 1e7,
+        amountStroops: balance.toString(),
+        method: "pool"
       });
     }
     return payments;
   }
   /**
-   * Get balances for all your stealth addresses in the pool.
-   *
-   * @param keys - Your stealth keys (needs viewPrivKey + spendPubKey)
+   * Claim (withdraw) a pool payment: recover the stealth key, sign a withdraw
+   * message, and submit — directly or via a relayer fee-bump.
    */
-  async balance(keys) {
-    const payments = await this.scan(keys);
-    return payments.map((p) => ({
-      stealthAddress: p.stealthAddress,
-      token: p.token,
-      amount: p.amount
-    }));
+  async claim(payment, destination, opts) {
+    if (opts.signTransaction && !opts.feePayerAddress) {
+      throw new FeePayerAddressRequiredError();
+    }
+    const receipt = await this.withdraw(payment.stealthAddress, destination, {
+      keys: opts.keys,
+      feePayer: opts.feePayer ?? "",
+      relay: opts.relay,
+      asset: opts.asset,
+      amount: opts.amount,
+      signTransaction: opts.signTransaction,
+      feePayerAddress: opts.feePayerAddress,
+      fundingAccount: opts.fundingAccount,
+      fundingSigner: opts.fundingSigner,
+      confirm: opts.confirm
+    });
+    return { txHash: receipt.txHash, amount: receipt.amount, method: "pool" };
   }
   /**
-   * 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)
+   * The original pool withdraw path, preserved for the client's `@deprecated`
+   * `withdraw()` alias and reused by `claim()`.
    */
   async withdraw(stealthAddress, destination, opts) {
     if (!StellarSdk.StrKey.isValidEd25519PublicKey(stealthAddress)) {
@@ -754,15 +2078,36 @@ var StealthClient = class {
     if (!StellarSdk.StrKey.isValidEd25519PublicKey(destination)) {
       throw new Error("Invalid destination address");
     }
+    if (opts.signTransaction) {
+      if (!opts.feePayerAddress) {
+        throw new FeePayerAddressRequiredError();
+      }
+    } else if (!opts.feePayer) {
+      throw new FeePayerRequiredError();
+    }
     const viewPrivKey = Buffer.from(opts.keys.viewPrivKey, "hex");
     const spendPrivKey = Buffer.from(opts.keys.spendPrivKey, "hex");
     const spendPubKey = Buffer.from(opts.keys.spendPubKey, "hex");
     const tokenAddress = resolveTokenAddress(opts.asset, this.networkPassphrase);
-    const announcements = await fetchAnnouncements(
+    const total = await fetchAnnouncementCount(
       this.contractId,
       this.server,
       this.networkPassphrase
     );
+    const announcements = [];
+    let offset = 0;
+    while (offset < total) {
+      const page = await fetchAnnouncements(
+        this.contractId,
+        this.server,
+        this.networkPassphrase,
+        offset,
+        POOL_PAGE_SIZE
+      );
+      if (page.length === 0) break;
+      announcements.push(...page);
+      offset += page.length;
+    }
     const allMatches = scanAnnouncements(
       viewPrivKey,
       spendPubKey,
@@ -777,7 +2122,7 @@ var StealthClient = class {
       return allMatches.some((m) => m?.address === stealthAddress);
     });
     if (!matchedAnn) {
-      throw new Error("Could not find announcement for this stealth address");
+      throw new AnnouncementNotFoundError();
     }
     const stealthPrivKey = recoverStealthPrivateKey(
       spendPrivKey,
@@ -791,12 +2136,14 @@ var StealthClient = class {
       this.server,
       this.networkPassphrase
     );
-    if (balance <= 0n) throw new Error("Stealth address has no balance in the pool");
+    if (balance <= 0n) throw new NoBalanceError();
     let withdrawAmount;
     if (opts.amount !== void 0) {
-      withdrawAmount = BigInt(Math.round(opts.amount * 1e7));
+      withdrawAmount = numberToStroops(opts.amount);
       if (withdrawAmount > balance) {
-        throw new Error(`Requested ${opts.amount} but balance is ${Number(balance) / 1e7}`);
+        throw new Error(
+          `Requested ${opts.amount} but balance is ${formatStroops(balance)}`
+        );
       }
     } else {
       withdrawAmount = balance;
@@ -813,19 +2160,16 @@ var StealthClient = class {
       tokenAddress,
       withdrawAmount,
       destination,
-      nonce
+      nonce,
+      this.contractId,
+      this.networkPassphrase
     );
-    const signature = signWithStealthKey(messageHash, stealthPrivKey);
-    if (!opts.signTransaction && !opts.feePayer) {
-      throw new Error("Provide either opts.feePayer or opts.signTransaction + opts.feePayerAddress");
-    }
-    if (opts.signTransaction && !opts.feePayerAddress) {
-      throw new Error("opts.feePayerAddress is required when using opts.signTransaction");
-    }
+    const signature = stealthPrivKey.sign(messageHash);
+    stealthPrivKey.zeroize();
     const feePayerPublicKey = opts.signTransaction ? opts.feePayerAddress : StellarSdk.Keypair.fromSecret(opts.feePayer).publicKey();
     const contract = new StellarSdk.Contract(this.contractId);
     const feePayerAccount = await this.server.getAccount(feePayerPublicKey);
-    const withdrawTx = new StellarSdk.TransactionBuilder(feePayerAccount, {
+    const buildWithdrawTx = (source) => new StellarSdk.TransactionBuilder(source, {
       fee: "100",
       networkPassphrase: this.networkPassphrase
     }).addOperation(
@@ -839,42 +2183,1544 @@ var StealthClient = class {
         StellarSdk.nativeToScVal(Buffer.from(signature))
       )
     ).setTimeout(30).build();
-    const prepared = await this.server.prepareTransaction(withdrawTx);
-    const signedTx = await this.signTx(
-      prepared,
-      opts.feePayer ?? "",
-      feePayerPublicKey,
+    const withdrawTx = buildWithdrawTx(feePayerAccount);
+    const signLeg = (tx) => signTx(
+      tx,
+      opts.signTransaction ? feePayerPublicKey : opts.feePayer,
+      this.networkPassphrase,
       opts.signTransaction
     );
-    let txHash;
-    if (opts.relay) {
-      const url = opts.relay.endsWith("/relay") ? opts.relay : `${opts.relay}/relay`;
-      const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ xdr: signedTx.toEnvelope().toXDR("base64") })
-      });
-      if (!res.ok) {
-        const err = await res.json();
-        throw new Error(`Relay error: ${err.error || "unknown"}`);
-      }
-      const data = await res.json();
-      txHash = data.txHash;
-    } else {
-      const result = await this.server.sendTransaction(signedTx);
-      if (result.status === "ERROR") throw new Error("Transaction submission failed");
-      if (result.status === "PENDING") {
-        await waitForTransaction(this.server, result.hash);
+    const relayerPool = RelayerPool.from(opts.relay, {
+      network: networkNameForPassphrase(this.networkPassphrase),
+      selection: this.relayerSelection
+    });
+    const submit = async (signed) => {
+      if (relayerPool) {
+        const txHash2 = await relayerPool.withRelayer(
+          async (client) => (await client.relay(signed.toEnvelope().toXDR("base64"), {
+            fundingAccount: opts.fundingAccount,
+            networkPassphrase: this.networkPassphrase
+          })).txHash,
+          {
+            fundingAccount: opts.fundingAccount,
+            fundingSigner: opts.fundingSigner,
+            rpcServer: this.server
+          }
+        );
+        if (opts.confirm) await waitForTransaction(this.server, txHash2);
+        return txHash2;
       }
-      txHash = result.hash;
-    }
-    return {
-      txHash,
-      amount: Number(withdrawAmount) / 1e7
+      const result = await this.server.sendTransaction(signed);
+      return resolveSendResult(this.server, result);
+    };
+    const prepared = await prepareWithRestore(
+      withdrawTx,
+      buildWithdrawTx,
+      this.server,
+      this.networkPassphrase,
+      signLeg,
+      submit
+    );
+    const signedWithdraw = await signLeg(prepared);
+    const txHash = await submit(signedWithdraw);
+    return { txHash, amount: Number(withdrawAmount) / 1e7 };
+  }
+};
+var HORIZON_PAGE_SIZE = 200;
+var INDEXER_PAGE_SIZE = 200;
+var DEFAULT_INDEXER_MAX_LAG_SECONDS = 21600;
+var TOKEN_ACCOUNT_STARTING_BALANCE = "1.5001";
+var ACCOUNT_RESERVE_STROOPS = 10000000n;
+var SPONSORED_RESERVE_ESTIMATE_STROOPS = 10000000n;
+function isNativeAsset(asset) {
+  return !asset || asset === "native" || asset === "XLM";
+}
+function parseAsset(asset) {
+  if (isNativeAsset(asset)) return StellarSdk.Asset.native();
+  const [code, issuer] = asset.split(":");
+  if (!code || !issuer) {
+    throw new Error(`Invalid asset "${asset}" \u2014 expected CODE:ISSUER`);
+  }
+  return new StellarSdk.Asset(code, issuer);
+}
+function assetToString(asset) {
+  return asset.isNative() ? "native" : `${asset.getCode()}:${asset.getIssuer()}`;
+}
+function normalizeDestination(address) {
+  if (!address) return address;
+  if (!address.startsWith("M")) return address;
+  try {
+    return StellarSdk.MuxedAccount.fromAddress(address, "0").baseAccount().accountId();
+  } catch {
+    return address;
+  }
+}
+function isPredicateSatisfiable(predicate, nowSeconds) {
+  if (!predicate) return true;
+  if (predicate.unconditional) return true;
+  if (predicate.not) {
+    return !isPredicateSatisfiable(predicate.not, nowSeconds);
+  }
+  if (predicate.and) {
+    return predicate.and.every((p) => isPredicateSatisfiable(p, nowSeconds));
+  }
+  if (predicate.or) {
+    return predicate.or.some((p) => isPredicateSatisfiable(p, nowSeconds));
+  }
+  if (predicate.abs_before_epoch !== void 0) {
+    return nowSeconds < Number(predicate.abs_before_epoch);
+  }
+  if (predicate.abs_before !== void 0) {
+    const before = Math.floor(Date.parse(predicate.abs_before) / 1e3);
+    if (!Number.isNaN(before)) return nowSeconds < before;
+  }
+  return true;
+}
+function computeReceiverStealthAddress(viewPrivKey, spendPubKey, ephemeralPubKey) {
+  const S = scalarMult(viewPrivKey, ephemeralPubKey);
+  const s = hashToScalar(S);
+  const sG = scalarMultBase(s);
+  const P = pointAdd(spendPubKey, sG);
+  return encodePublicKey(P);
+}
+var AccountAdapter = class {
+  constructor(networkPassphrase, horizon, relayer, opts) {
+    this.networkPassphrase = networkPassphrase;
+    this.horizon = horizon;
+    this.relayer = relayer;
+    this.rpcServer = opts?.rpcServer;
+    this.relayerSelection = opts?.relayerSelection;
+    this.indexer = opts?.indexer;
+    this.indexerMaxLagSeconds = opts?.indexerMaxLagSeconds ?? DEFAULT_INDEXER_MAX_LAG_SECONDS;
+  }
+  networkPassphrase;
+  horizon;
+  relayer;
+  method = "account";
+  rpcServer;
+  relayerSelection;
+  indexer;
+  indexerMaxLagSeconds;
+  /**
+   * 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.
+   */
+  async send(params) {
+    const { asset } = params;
+    if (!isNativeAsset(asset)) {
+      return this.sendToken(params);
+    }
+    return this.sendNative(params);
+  }
+  /** Native XLM send: CreateAccount (falls back to Payment on retry). */
+  async sendNative(params) {
+    const { metaAddress, amount, senderSecret, signTransaction } = params;
+    if (amount <= 1) {
+      throw new MinimumAmountError(amount);
+    }
+    const { spendPubKey, viewPubKey } = decodeMetaAddress(metaAddress);
+    const ephemeralPrivKey = new Uint8Array(utils.randomBytes(32));
+    const stealth = deriveStealthAddressWithSecret(
+      spendPubKey,
+      viewPubKey,
+      ephemeralPrivKey
+    );
+    const memo = StellarSdk.Memo.hash(Buffer.from(stealth.ephemeralPubKey));
+    const startingBalance = formatStroops(numberToStroops(amount));
+    const senderPublicKey = signTransaction ? senderSecret : StellarSdk.Keypair.fromSecret(senderSecret).publicKey();
+    const submit = async (useCreate) => {
+      const account = await this.horizon.getAccount(senderPublicKey);
+      if (!account) {
+        throw new Error("Sender account not found on Horizon \u2014 is it funded?");
+      }
+      const source = new StellarSdk.Account(account.id, account.sequence);
+      const op = useCreate ? StellarSdk.Operation.createAccount({
+        destination: stealth.stealthAddress,
+        startingBalance
+      }) : StellarSdk.Operation.payment({
+        destination: stealth.stealthAddress,
+        asset: StellarSdk.Asset.native(),
+        amount: startingBalance
+      });
+      const tx = new StellarSdk.TransactionBuilder(source, {
+        fee: StellarSdk.BASE_FEE,
+        networkPassphrase: this.networkPassphrase
+      }).addOperation(op).addMemo(memo).setTimeout(30).build();
+      const signed = await signTx(
+        tx,
+        senderSecret,
+        this.networkPassphrase,
+        signTransaction
+      );
+      const res = await this.horizon.submitTransaction(
+        signed.toEnvelope().toXDR("base64")
+      );
+      return res.hash;
+    };
+    let txHash;
+    try {
+      txHash = await submit(true);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("op_already_exists")) {
+        txHash = await submit(false);
+      } else {
+        throw err;
+      }
+    }
+    return { stealthAddress: stealth.stealthAddress, txHash };
+  }
+  /**
+   * 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.
+   */
+  async sendToken(params) {
+    const { metaAddress, amount, senderSecret, asset } = params;
+    if (!Number.isFinite(amount) || amount <= 0) {
+      throw new InvalidAmountError(amount);
+    }
+    const stellarAsset = parseAsset(asset);
+    const { spendPubKey, viewPubKey } = decodeMetaAddress(metaAddress);
+    const ephemeralPrivKey = new Uint8Array(utils.randomBytes(32));
+    const stealth = deriveStealthAddressWithSecret(
+      spendPubKey,
+      viewPubKey,
+      ephemeralPrivKey
+    );
+    const memo = StellarSdk.Memo.hash(Buffer.from(stealth.ephemeralPubKey));
+    const senderPublicKey = params.signTransaction ? senderSecret : StellarSdk.Keypair.fromSecret(senderSecret).publicKey();
+    const account = await this.horizon.getAccount(senderPublicKey);
+    if (!account) {
+      throw new Error("Sender account not found on Horizon \u2014 is it funded?");
+    }
+    const source = new StellarSdk.Account(account.id, account.sequence);
+    const claimant = new StellarSdk.Claimant(
+      stealth.stealthAddress,
+      StellarSdk.Claimant.predicateUnconditional()
+    );
+    const tx = new StellarSdk.TransactionBuilder(source, {
+      fee: StellarSdk.BASE_FEE,
+      networkPassphrase: this.networkPassphrase
+    }).addOperation(
+      StellarSdk.Operation.createAccount({
+        destination: stealth.stealthAddress,
+        startingBalance: TOKEN_ACCOUNT_STARTING_BALANCE
+      })
+    ).addOperation(
+      StellarSdk.Operation.createClaimableBalance({
+        asset: stellarAsset,
+        amount: formatStroops(numberToStroops(amount)),
+        claimants: [claimant]
+      })
+    ).addMemo(memo).setTimeout(30).build();
+    const signed = await signTx(
+      tx,
+      senderSecret,
+      this.networkPassphrase,
+      params.signTransaction
+    );
+    const res = await this.horizon.submitTransaction(
+      signed.toEnvelope().toXDR("base64")
+    );
+    return { stealthAddress: stealth.stealthAddress, txHash: res.hash };
+  }
+  /**
+   * 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.
+   */
+  async scan(keys, cursor, opts) {
+    const ctx = {
+      viewPrivKey: new Uint8Array(Buffer.from(keys.viewPrivKey, "hex")),
+      spendPubKey: new Uint8Array(Buffer.from(keys.spendPubKey, "hex")),
+      suppressClaimedNative: opts?.suppressClaimedNative ?? false
+    };
+    const payments = [];
+    const meta = { indexerUsed: false, segments: [] };
+    const indexer = this.indexer;
+    const coverage = indexer ? await this.indexerCoverage(indexer) : void 0;
+    if (!indexer || !coverage || !coverage.usable) {
+      if (coverage && !coverage.usable) {
+        meta.indexerSkipReason = coverage.reason;
+        if (coverage.lagSeconds !== void 0) {
+          meta.indexerLagSeconds = coverage.lagSeconds;
+        }
+      }
+      const stats = { candidates: 0, matches: 0 };
+      const finalCursor2 = await this.walkHorizon(
+        cursor,
+        void 0,
+        ctx,
+        payments,
+        stats
+      );
+      meta.segments.push({ source: "horizon", role: "full", ...stats });
+      return { payments, cursor: finalCursor2, meta };
+    }
+    meta.indexerLagSeconds = coverage.lagSeconds;
+    const begin = cursor ?? (opts?.exhaustive ? void 0 : coverage.startCursor);
+    if (begin === void 0 || BigInt(begin) < BigInt(coverage.startCursor)) {
+      const preStats = { candidates: 0, matches: 0 };
+      await this.walkHorizon(begin, coverage.startCursor, ctx, payments, preStats);
+      meta.segments.push({ source: "horizon", role: "pre", ...preStats });
+    }
+    let cur = begin !== void 0 && BigInt(begin) > BigInt(coverage.startCursor) ? begin : coverage.startCursor;
+    const segmentStart = cur;
+    const preSegmentPayments = payments.length;
+    const indexerStats = { candidates: 0, matches: 0 };
+    try {
+      for (; ; ) {
+        const page = await indexer.getAnnouncements(cur, INDEXER_PAGE_SIZE);
+        meta.indexerUsed = true;
+        for (const record of page.records) {
+          await this.collectCandidate(
+            record,
+            record.operations,
+            ctx,
+            payments,
+            indexerStats
+          );
+        }
+        const prev = cur;
+        const adopt = (candidate) => {
+          if (typeof candidate === "string" && /^\d+$/.test(candidate) && BigInt(candidate) > BigInt(cur)) {
+            cur = candidate;
+          }
+        };
+        adopt(page.records[page.records.length - 1]?.paging_token);
+        adopt(page.cursor);
+        if (page.records.length < INDEXER_PAGE_SIZE) break;
+        if (cur === prev) break;
+      }
+    } catch (err) {
+      if (!(err instanceof IndexerHttpError) && !(err instanceof IndexerNetworkError)) {
+        throw err;
+      }
+    }
+    meta.segments.push({ source: "indexer", role: "indexer", ...indexerStats });
+    let tailFrom = cur;
+    try {
+      const post = await indexer.health();
+      meta.postCheck = post.status === "ok" ? "ok" : "unhealthy";
+    } catch {
+      meta.postCheck = "unreachable";
+    }
+    if (meta.postCheck !== "ok") {
+      tailFrom = segmentStart;
+      payments.length = preSegmentPayments;
+    }
+    const tailStats = { candidates: 0, matches: 0 };
+    let finalCursor = await this.walkHorizon(
+      tailFrom,
+      void 0,
+      ctx,
+      payments,
+      tailStats
+    );
+    meta.segments.push({ source: "horizon", role: "tail", ...tailStats });
+    if (finalCursor !== void 0 && finalCursor === tailFrom) {
+      const head = await this.horizon.getLatestTransactionToken();
+      if (head !== void 0 && BigInt(head) < BigInt(finalCursor)) {
+        meta.cursorClamped = true;
+        finalCursor = head;
+      }
+    }
+    return { payments, cursor: finalCursor, meta };
+  }
+  /**
+   * 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.
+   */
+  async indexerCoverage(indexer) {
+    let h;
+    try {
+      h = await indexer.health();
+    } catch {
+      return { usable: false, reason: "unreachable" };
+    }
+    if (h.status !== "ok") return { usable: false, reason: "unhealthy" };
+    if (h.network !== networkNameForPassphrase(this.networkPassphrase)) {
+      return { usable: false, reason: "network_mismatch" };
+    }
+    if (h.cursor == null || h.startCursor == null) {
+      return { usable: false, reason: "no_coverage" };
+    }
+    const lagSeconds = typeof h.lagSeconds === "number" ? h.lagSeconds : null;
+    if (lagSeconds !== null && lagSeconds > this.indexerMaxLagSeconds) {
+      return { usable: false, reason: "stale", lagSeconds };
+    }
+    return { usable: true, startCursor: h.startCursor, lagSeconds };
+  }
+  /**
+   * 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).
+   */
+  async walkHorizon(from, stopAtToken, ctx, payments, stats) {
+    let pageCursor = from;
+    let lastToken = from;
+    for (; ; ) {
+      const txs = await this.horizon.getTransactions(pageCursor, HORIZON_PAGE_SIZE);
+      if (txs.length === 0) break;
+      for (const tx of txs) {
+        if (stopAtToken !== void 0 && BigInt(tx.paging_token) > BigInt(stopAtToken)) {
+          return stopAtToken;
+        }
+        lastToken = tx.paging_token;
+        await this.collectCandidate(
+          tx,
+          () => this.horizon.getTransactionOperations(tx.hash),
+          ctx,
+          payments,
+          stats
+        );
+      }
+      if (txs.length < HORIZON_PAGE_SIZE) break;
+      pageCursor = txs[txs.length - 1].paging_token;
+    }
+    return lastToken;
+  }
+  /**
+   * 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.
+   */
+  async collectCandidate(tx, ops, ctx, payments, stats) {
+    if (tx.memo_type !== "hash" || !tx.memo) return;
+    if (tx.successful === false) return;
+    const ephemeralPubKey = new Uint8Array(Buffer.from(tx.memo, "base64"));
+    if (ephemeralPubKey.length !== 32) return;
+    stats.candidates++;
+    let derivedAddress;
+    try {
+      derivedAddress = computeReceiverStealthAddress(
+        ctx.viewPrivKey,
+        ctx.spendPubKey,
+        ephemeralPubKey
+      );
+    } catch {
+      return;
+    }
+    const resolvedOps = typeof ops === "function" ? await ops() : ops;
+    const ephHex = Buffer.from(ephemeralPubKey).toString("hex");
+    const cbMatch = resolvedOps.find(
+      (op) => op.type === "create_claimable_balance" && (op.claimants ?? []).some(
+        (c) => normalizeDestination(c.destination) === derivedAddress
+      )
+    );
+    const nativeMatch = resolvedOps.find(
+      (op) => op.type === "create_account" && normalizeDestination(op.account) === derivedAddress || op.type === "payment" && normalizeDestination(op.to) === derivedAddress
+    );
+    if (nativeMatch) {
+      const payment = await this.buildNativePayment(
+        nativeMatch,
+        derivedAddress,
+        ephHex,
+        tx.hash,
+        !!cbMatch,
+        ctx.suppressClaimedNative
+      );
+      if (payment) {
+        payments.push(payment);
+        stats.matches++;
+      }
+    }
+    if (cbMatch) {
+      const payment = await this.buildTokenPayment(
+        cbMatch,
+        derivedAddress,
+        ephHex,
+        tx.hash,
+        tx.source_account
+      );
+      if (payment) {
+        payments.push(payment);
+        stats.matches++;
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  async buildNativePayment(nativeMatch, derivedAddress, ephHex, txHash, hasTokenLeg, suppressClaimed) {
+    if (hasTokenLeg) return null;
+    const opAmountStr = nativeMatch.type === "create_account" ? nativeMatch.starting_balance ?? "0" : nativeMatch.amount ?? "0";
+    let stroops = parseStroops(opAmountStr);
+    if (suppressClaimed) {
+      const live = await this.horizon.getAccount(derivedAddress);
+      if (live) {
+        const nativeBal = live.balances.find((b) => b.asset_type === "native");
+        if (nativeBal !== void 0) stroops = parseStroops(nativeBal.balance);
+      }
+    }
+    if (stroops <= 0n) return null;
+    return {
+      stealthAddress: derivedAddress,
+      ephemeralPubKey: ephHex,
+      token: "native",
+      amount: Number(formatStroops(stroops)),
+      amountStroops: stroops.toString(),
+      method: "account",
+      txHash
+    };
+  }
+  /**
+   * 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.
+   */
+  async buildTokenPayment(cbMatch, derivedAddress, ephHex, txHash, txSource) {
+    const opAsset = cbMatch.asset;
+    const opAmountStroops = cbMatch.amount ? parseStroops(cbMatch.amount) : void 0;
+    const candidates = await this.horizon.getClaimableBalances(derivedAddress);
+    const cb = this.bindClaimableBalance(candidates, derivedAddress, {
+      txSource,
+      opAsset,
+      opAmountStroops
+    });
+    if (!cb) return null;
+    const stroops = parseStroops(cb.amount);
+    return {
+      stealthAddress: derivedAddress,
+      ephemeralPubKey: ephHex,
+      token: opAsset ?? cb.asset ?? "unknown",
+      asset: opAsset ?? cb.asset,
+      claimableBalanceId: cb.id,
+      amount: Number(formatStroops(stroops)),
+      amountStroops: stroops.toString(),
+      method: "account",
+      txHash
+    };
+  }
+  /**
+   * 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.
+   */
+  bindClaimableBalance(candidates, derivedAddress, expected) {
+    const nowSeconds = Math.floor(Date.now() / 1e3);
+    const claimableNow = candidates.filter(
+      (cb) => (cb.claimants ?? []).some((c) => {
+        if (normalizeDestination(c.destination) !== derivedAddress) return false;
+        return isPredicateSatisfiable(c.predicate, nowSeconds);
+      })
+    );
+    const assetAmountMatches = claimableNow.filter((cb) => {
+      const assetOk = expected.opAsset === void 0 || cb.asset === expected.opAsset;
+      const amountOk = expected.opAmountStroops === void 0 || parseStroops(cb.amount) === expected.opAmountStroops;
+      return assetOk && amountOk;
+    });
+    if (expected.txSource !== void 0) {
+      const sponsorBound = assetAmountMatches.find(
+        (cb) => cb.sponsor === expected.txSource
+      );
+      if (sponsorBound) return sponsorBound;
+    }
+    return assetAmountMatches[0];
+  }
+  /**
+   * 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.
+   */
+  async claim(payment, destination, opts) {
+    const isToken = !!payment.claimableBalanceId || !isNativeAsset(payment.asset);
+    if (isToken) {
+      return this.claimToken(payment, destination, opts);
+    }
+    return this.claimNative(payment, destination, opts);
+  }
+  /**
+   * 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.
+   */
+  async claimNative(payment, destination, opts) {
+    if (opts.amount !== void 0 && opts.merge !== false) {
+      throw new ClaimAmountRequiresNoMergeError("native-merge");
+    }
+    const stealthPrivKey = this.recoverKey(payment, opts);
+    const stealthAddress = payment.stealthAddress;
+    const account = await this.horizon.getAccount(stealthAddress);
+    if (!account) {
+      throw new StealthAccountNotFoundError();
+    }
+    const source = new StellarSdk.Account(account.id, account.sequence);
+    const merge = opts.merge !== false;
+    const relayed = !!(normalizeRelayList(opts.relay) ?? normalizeRelayList(this.relayer));
+    const feeStroops = BigInt(StellarSdk.BASE_FEE);
+    const nativeBal = account.balances.find((b) => b.asset_type === "native");
+    const balanceStroops = nativeBal ? parseStroops(nativeBal.balance) : 0n;
+    const builder = new StellarSdk.TransactionBuilder(source, {
+      fee: StellarSdk.BASE_FEE,
+      networkPassphrase: this.networkPassphrase
+    });
+    let amount;
+    if (merge) {
+      builder.addOperation(StellarSdk.Operation.accountMerge({ destination }));
+      const delivered = relayed ? balanceStroops : balanceStroops - feeStroops;
+      amount = Number(formatStroops(delivered));
+    } else {
+      if (opts.amount === void 0) {
+        throw new Error("Partial account claim requires opts.amount");
+      }
+      const requestedStroops = numberToStroops(opts.amount);
+      const maxClaimableStroops = balanceStroops - ACCOUNT_RESERVE_STROOPS - feeStroops;
+      if (requestedStroops > maxClaimableStroops) {
+        throw new ClaimAmountError(
+          opts.amount,
+          Number(formatStroops(maxClaimableStroops))
+        );
+      }
+      builder.addOperation(
+        StellarSdk.Operation.payment({
+          destination,
+          asset: StellarSdk.Asset.native(),
+          amount: formatStroops(requestedStroops)
+        })
+      );
+      amount = opts.amount;
+    }
+    const tx = builder.setTimeout(30).build();
+    const sig = stealthPrivKey.sign(tx.hash());
+    stealthPrivKey.zeroize();
+    tx.addSignature(stealthAddress, Buffer.from(sig).toString("base64"));
+    const txHash = await this.submit(tx.toEnvelope().toXDR("base64"), opts);
+    return { txHash, amount, method: "account" };
+  }
+  /**
+   * 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.
+   */
+  async claimToken(payment, destination, opts) {
+    if (opts.amount !== void 0) {
+      throw new ClaimAmountRequiresNoMergeError("token");
+    }
+    if (!payment.claimableBalanceId) {
+      throw new Error("Token claim requires a claimableBalanceId on the payment");
+    }
+    const asset = payment.asset ?? payment.token;
+    const stellarAsset = parseAsset(asset);
+    const amount = payment.amount;
+    const payoutAmount = this.resolveExactPayout(payment);
+    await this.assertDestinationTrusts(destination, stellarAsset);
+    const stealthAddress = payment.stealthAddress;
+    const account = await this.horizon.getAccount(stealthAddress);
+    const relays = normalizeRelayList(opts.relay) ?? normalizeRelayList(this.relayer);
+    if (opts.sponsored || !account) {
+      if (!relays) {
+        throw new Error(
+          "Sponsored token claim requires a relayer URL (opts.relay or client relayer)."
+        );
+      }
+      return this.claimTokenSponsored(
+        payment,
+        opts,
+        relays,
+        amount,
+        destination,
+        payoutAmount
+      );
+    }
+    const stealthPrivKey = this.recoverKey(payment, opts);
+    const source = new StellarSdk.Account(account.id, account.sequence);
+    const merge = opts.merge !== false;
+    const builder = new StellarSdk.TransactionBuilder(source, {
+      fee: StellarSdk.BASE_FEE,
+      networkPassphrase: this.networkPassphrase
+    }).addOperation(StellarSdk.Operation.changeTrust({ asset: stellarAsset })).addOperation(
+      StellarSdk.Operation.claimClaimableBalance({
+        balanceId: payment.claimableBalanceId
+      })
+    );
+    if (merge) {
+      builder.addOperation(
+        StellarSdk.Operation.payment({
+          destination,
+          asset: stellarAsset,
+          amount: payoutAmount
+        })
+      ).addOperation(StellarSdk.Operation.changeTrust({ asset: stellarAsset, limit: "0" })).addOperation(StellarSdk.Operation.accountMerge({ destination }));
+    }
+    const tx = builder.setTimeout(30).build();
+    const sig = stealthPrivKey.sign(tx.hash());
+    stealthPrivKey.zeroize();
+    tx.addSignature(stealthAddress, Buffer.from(sig).toString("base64"));
+    const txHash = await this.submit(tx.toEnvelope().toXDR("base64"), opts);
+    return { txHash, amount, method: "account" };
+  }
+  /**
+   * 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.
+   */
+  async claimTokenSponsored(payment, opts, relays, amount, destination, payoutAmount) {
+    const pool = new RelayerPool(relays, {
+      network: networkNameForPassphrase(this.networkPassphrase),
+      selection: this.relayerSelection
+    });
+    const relay = await pool.select({
+      fundingAccount: opts.fundingAccount,
+      fundingSigner: opts.fundingSigner,
+      rpcServer: this.rpcServer
+    });
+    const client = new RelayerClient(relay, void 0, {
+      fundingSigner: opts.fundingSigner,
+      rpcServer: this.rpcServer
+    });
+    const asset = payment.asset ?? payment.token;
+    const balanceId = payment.claimableBalanceId;
+    if (!balanceId) {
+      throw new Error("Sponsored token claim requires a claimableBalanceId");
+    }
+    const { xdr } = await client.sponsorClaimPrepare({
+      stealthAddress: payment.stealthAddress,
+      asset,
+      balanceId,
+      destination,
+      amount: payoutAmount
+    });
+    const tx = this.verifySponsoredClaimXdr(xdr, {
+      stealthAddress: payment.stealthAddress,
+      asset,
+      balanceId,
+      destination,
+      payoutAmount
+    });
+    const stealthPrivKey = this.recoverKey(payment, opts);
+    const sig = stealthPrivKey.sign(tx.hash());
+    stealthPrivKey.zeroize();
+    tx.addSignature(payment.stealthAddress, Buffer.from(sig).toString("base64"));
+    const reserveStroops = await client.sponsoredReserveEstimateStroops() ?? SPONSORED_RESERVE_ESTIMATE_STROOPS;
+    const authAmount = formatStroops(BigInt(tx.fee) + reserveStroops);
+    const { txHash } = await client.sponsorClaimSubmit(
+      tx.toEnvelope().toXDR("base64"),
+      {
+        stealthAddress: payment.stealthAddress,
+        asset,
+        balanceId,
+        destination,
+        amount: payoutAmount,
+        fundingAccount: opts.fundingAccount,
+        fundingSigner: opts.fundingSigner,
+        authAmount,
+        confirm: opts.confirm
+      }
+    );
+    return { txHash, amount, method: "account" };
+  }
+  /**
+   * 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.
+   */
+  verifySponsoredClaimXdr(xdr, expected) {
+    let tx;
+    try {
+      tx = new StellarSdk.Transaction(xdr, this.networkPassphrase);
+    } catch {
+      throw new SponsoredClaimMismatchError("prepared XDR is not a valid transaction");
+    }
+    if (tx.memo && tx.memo.type !== "none") {
+      throw new SponsoredClaimMismatchError("unexpected memo on the prepared transaction");
+    }
+    const relayer = tx.source;
+    const { stealthAddress, balanceId, destination, payoutAmount } = expected;
+    const wantAsset = parseAsset(expected.asset);
+    const wantAssetStr = wantAsset.isNative() ? "native" : `${wantAsset.getCode()}:${wantAsset.getIssuer()}`;
+    const amt = (value) => parseStroops(value).toString();
+    const opStr = (op) => {
+      const src = op.source ?? relayer;
+      switch (op.type) {
+        case "beginSponsoringFutureReserves":
+          return `begin|${src}|${op.sponsoredId}`;
+        case "createAccount": {
+          const o = op;
+          return `create|${src}|${o.destination}|${amt(o.startingBalance)}`;
+        }
+        case "changeTrust": {
+          const o = op;
+          return `trust|${src}|${assetToString(o.line)}`;
+        }
+        case "endSponsoringFutureReserves":
+          return `end|${src}`;
+        case "claimClaimableBalance":
+          return `claim|${src}|${op.balanceId}`;
+        case "payment": {
+          const o = op;
+          return `pay|${src}|${o.destination}|${assetToString(o.asset)}|${amt(o.amount)}`;
+        }
+        default:
+          return `UNSUPPORTED:${op.type}|${src}`;
+      }
+    };
+    const buildExpected = (withCreate2) => {
+      const ops = [];
+      ops.push(`begin|${relayer}|${stealthAddress}`);
+      if (withCreate2) ops.push(`create|${relayer}|${stealthAddress}|${amt("0")}`);
+      ops.push(`trust|${stealthAddress}|${wantAssetStr}`);
+      ops.push(`end|${stealthAddress}`);
+      ops.push(`claim|${stealthAddress}|${balanceId}`);
+      ops.push(`pay|${stealthAddress}|${destination}|${wantAssetStr}|${amt(payoutAmount)}`);
+      return ops;
+    };
+    const submitted = tx.operations.map(opStr);
+    const withCreate = buildExpected(true).join("\n");
+    const withoutCreate = buildExpected(false).join("\n");
+    const actual = submitted.join("\n");
+    if (actual !== withCreate && actual !== withoutCreate) {
+      throw new SponsoredClaimMismatchError(
+        `operations do not match the expected sponsor-claim sequence (got: ${actual})`
+      );
+    }
+    return tx;
+  }
+  /**
+   * 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).
+   */
+  resolveExactPayout(payment) {
+    if (payment.amountStroops) {
+      return formatStroops(BigInt(payment.amountStroops));
+    }
+    return payment.amount.toFixed(7);
+  }
+  /** Recover the stealth scalar for signing from the payment's ephemeral R. */
+  recoverKey(payment, opts) {
+    const viewPrivKey = new Uint8Array(Buffer.from(opts.keys.viewPrivKey, "hex"));
+    const spendPrivKey = new Uint8Array(
+      Buffer.from(opts.keys.spendPrivKey, "hex")
+    );
+    const ephemeralPubKey = new Uint8Array(
+      Buffer.from(payment.ephemeralPubKey, "hex")
+    );
+    return recoverStealthPrivateKey(spendPrivKey, viewPrivKey, ephemeralPubKey);
+  }
+  /** Fail with an actionable error unless the destination trusts the asset. */
+  async assertDestinationTrusts(destination, asset) {
+    if (asset.isNative()) return;
+    const dest = await this.horizon.getAccount(destination);
+    if (!dest) {
+      throw new DestinationTrustlineError(
+        `Destination ${destination} not found on Horizon \u2014 fund it and add a ${asset.getCode()} trustline before claiming.`
+      );
+    }
+    const code = asset.getCode();
+    const issuer = asset.getIssuer();
+    const trusts = dest.balances.some(
+      (b) => b.asset_code === code && b.asset_issuer === issuer
+    );
+    if (!trusts) {
+      throw new DestinationTrustlineError(
+        `Destination ${destination} does not trust ${assetToString(asset)}. Add the trustline on the destination account before claiming.`
+      );
+    }
+  }
+  /** Submit an XDR directly to Horizon, or via a relayer fee-bump when set. */
+  async submit(xdr, opts) {
+    const relays = normalizeRelayList(opts.relay) ?? normalizeRelayList(this.relayer);
+    if (relays) {
+      const pool = new RelayerPool(relays, {
+        network: networkNameForPassphrase(this.networkPassphrase),
+        selection: this.relayerSelection
+      });
+      const txHash = await pool.withRelayer(
+        async (client) => (await client.relay(xdr, {
+          fundingAccount: opts.fundingAccount,
+          networkPassphrase: this.networkPassphrase
+        })).txHash,
+        {
+          fundingAccount: opts.fundingAccount,
+          fundingSigner: opts.fundingSigner,
+          rpcServer: this.rpcServer
+        }
+      );
+      if (opts.confirm) {
+        if (!this.rpcServer) {
+          throw new Error(
+            "confirm: true requires an RPC handle: construct the AccountAdapter with opts.rpcServer (an rpc.Server for the same network)."
+          );
+        }
+        await waitForTransaction(this.rpcServer, txHash);
+      }
+      return txHash;
+    }
+    const res = await this.horizon.submitTransaction(xdr);
+    return res.hash;
+  }
+};
+
+// src/methods/spp.ts
+var SPP_MESSAGE = "the 'spp' method is reserved for future Stellar Private Payments integration";
+var SppAdapter = class {
+  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.
+   */
+  async send(_params) {
+    throw new MethodNotAvailableError(SPP_MESSAGE);
+  }
+  /** @throws {MethodNotAvailableError} Always — SPP is not yet implemented. */
+  async scan(_keys, _cursor) {
+    throw new MethodNotAvailableError(SPP_MESSAGE);
+  }
+  /** @throws {MethodNotAvailableError} Always — SPP is not yet implemented. */
+  async claim(_payment, _destination, _opts) {
+    throw new MethodNotAvailableError(SPP_MESSAGE);
+  }
+};
+
+// src/client.ts
+var StealthClient = class {
+  contractId;
+  networkPassphrase;
+  server;
+  enabledMethods;
+  adapters;
+  relayer;
+  relayerSelection;
+  constructor(config) {
+    this.contractId = config.contractId || "";
+    const netConfig = getNetworkConfig(config.network);
+    this.networkPassphrase = netConfig.networkPassphrase;
+    this.server = netConfig.server;
+    this.relayer = config.relayer;
+    this.relayerSelection = config.relayerSelection;
+    this.enabledMethods = config.methods && config.methods.length > 0 ? config.methods : ["pool"];
+    if (this.enabledMethods.includes("pool") && !this.contractId) {
+      throw new ContractIdRequiredError(config.network);
+    }
+    const horizonUrl = config.horizonUrl || netConfig.horizonUrl;
+    const horizon = new HorizonClient(horizonUrl);
+    const indexer = config.indexerUrl ? new IndexerClient(config.indexerUrl) : void 0;
+    this.adapters = /* @__PURE__ */ new Map();
+    for (const method of this.enabledMethods) {
+      switch (method) {
+        case "pool":
+          this.adapters.set(
+            "pool",
+            new PoolAdapter(this.contractId, this.networkPassphrase, this.server, {
+              relayerSelection: this.relayerSelection
+            })
+          );
+          break;
+        case "account":
+          this.adapters.set(
+            "account",
+            new AccountAdapter(this.networkPassphrase, horizon, this.relayer, {
+              // Confirm-poll handle for relayed claims (`confirm: true`): the
+              // Soroban RPC's getTransaction resolves classic tx hashes too.
+              rpcServer: this.server,
+              relayerSelection: this.relayerSelection,
+              indexer,
+              indexerMaxLagSeconds: config.indexerMaxLagSeconds
+            })
+          );
+          break;
+        case "spp":
+          this.adapters.set("spp", new SppAdapter());
+          break;
+      }
+    }
+  }
+  /**
+   * Generate a new random stealth key pair.
+   * No network connection needed.
+   */
+  static keygen() {
+    return stealthKeysFromRaw(generateMetaAddress());
+  }
+  /**
+   * Generate stealth keys from a BIP-39 mnemonic.
+   * Returns the mnemonic alongside the keys for backup.
+   * No network connection needed.
+   */
+  static fromMnemonic(mnemonic) {
+    const phrase = mnemonic || generateMnemonic();
+    return {
+      mnemonic: phrase,
+      ...stealthKeysFromRaw(mnemonicToStealthKeys(phrase))
+    };
+  }
+  /**
+   * Resolve `'auto'` to a concrete method: native asset AND amount > 1 AND
+   * 'account' enabled -> 'account'; otherwise 'pool'.
+   */
+  resolveMethod(requested, amount, asset) {
+    if (requested === "auto") {
+      const isNative = !asset || asset === "native" || asset === "XLM";
+      if (isNative && amount > 1 && this.adapters.has("account")) {
+        return "account";
+      }
+      return "pool";
+    }
+    return requested;
+  }
+  getAdapter(method) {
+    const adapter = this.adapters.get(method);
+    if (!adapter) throw new MethodNotEnabledError(method);
+    return adapter;
+  }
+  /**
+   * 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.
+   */
+  async send(metaAddress, amount, senderSecret, opts) {
+    if (!opts || !opts.method) {
+      throw new MethodRequiredError();
+    }
+    const method = this.resolveMethod(opts.method, amount, opts.asset);
+    const adapter = this.getAdapter(method);
+    return adapter.send({
+      metaAddress,
+      amount,
+      senderSecret,
+      asset: opts.asset,
+      signTransaction: opts.signTransaction
+    });
+  }
+  /**
+   * Scan for stealth payments across every enabled delivery method.
+   *
+   * @param keys - Your stealth keys (needs viewPrivKey + spendPubKey)
+   */
+  async scan(keys) {
+    const { payments } = await this.scanWithCursor(keys);
+    return payments;
+  }
+  /**
+   * 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
+   */
+  async scanWithCursor(keys, opts) {
+    return this.scanInternal(keys, opts, false);
+  }
+  /**
+   * 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.
+   */
+  async scanInternal(keys, opts, suppressClaimed) {
+    const methods = (opts?.methods ?? this.enabledMethods).filter(
+      (m) => this.adapters.has(m)
+    );
+    const cursor = { ...opts?.cursor ?? {} };
+    const payments = [];
+    const meta = {};
+    for (const method of methods) {
+      const adapter = this.getAdapter(method);
+      const prev = cursor[method];
+      const result = await adapter.scan(keys, prev, {
+        suppressClaimedNative: suppressClaimed,
+        exhaustive: opts?.exhaustive
+      });
+      for (const p of result.payments) {
+        payments.push({ ...p, method });
+      }
+      cursor[method] = result.cursor;
+      if (result.meta) meta[method] = result.meta;
+    }
+    return { payments, cursor, meta };
+  }
+  /**
+   * 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.
+   */
+  async balance(keys, opts) {
+    const { payments } = await this.balanceWithCursor(keys, opts);
+    return payments.map((p) => ({
+      stealthAddress: p.stealthAddress,
+      token: p.token,
+      amount: p.amount,
+      amountStroops: p.amountStroops
+    }));
+  }
+  /**
+   * 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
+   */
+  async balanceWithCursor(keys, opts) {
+    return this.scanInternal(keys, opts, true);
+  }
+  /**
+   * 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).
+   */
+  async claim(payment, destination, opts) {
+    const adapter = this.getAdapter(payment.method);
+    const relay = normalizeRelayList(opts.relay) ?? normalizeRelayList(this.relayer);
+    return adapter.claim(payment, destination, { ...opts, relay });
+  }
+  /**
+   * 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)
+   */
+  async withdraw(stealthAddress, destination, opts) {
+    const adapter = this.adapters.get("pool");
+    if (!(adapter instanceof PoolAdapter)) {
+      throw new MethodNotAvailableError(
+        "The 'pool' method must be enabled to use withdraw()"
+      );
+    }
+    const result = await adapter.withdraw(stealthAddress, destination, {
+      keys: opts.keys,
+      feePayer: opts.feePayer,
+      relay: normalizeRelayList(opts.relay) ?? normalizeRelayList(this.relayer),
+      asset: opts.asset,
+      amount: opts.amount,
+      fundingAccount: opts.fundingAccount,
+      fundingSigner: opts.fundingSigner,
+      confirm: opts.confirm
+    });
+    return { txHash: result.txHash, amount: result.amount };
+  }
+};
+
+// src/session.ts
+var PBKDF2_ITERATIONS = 6e5;
+var SALT_BYTES = 16;
+var IV_BYTES = 12;
+function toBase64(bytes) {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+function fromBase64(b64) {
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function fromHex(hex) {
+  if (typeof hex !== "string" || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) {
+    return null;
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  return diff === 0;
+}
+function assertPubKeyMatchesPriv(which, storedPubHex, privHex) {
+  const priv = fromHex(privHex);
+  const storedPub = fromHex(storedPubHex);
+  if (!priv || !storedPub) throw new SessionIntegrityError(which);
+  let derived;
+  try {
+    derived = scalarMultBase(priv);
+  } catch {
+    throw new SessionIntegrityError(which);
+  }
+  if (!bytesEqual(derived, storedPub)) throw new SessionIntegrityError(which);
+}
+var subtle = () => {
+  const c = globalThis.crypto?.subtle;
+  if (!c) {
+    throw new Error(
+      "WebCrypto SubtleCrypto is unavailable \u2014 StealthSession needs a browser or Node 18+."
+    );
+  }
+  return c;
+};
+async function deriveAesKey(password, salt, iterations) {
+  const material = await subtle().importKey(
+    "raw",
+    new TextEncoder().encode(password),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  return subtle().deriveKey(
+    { name: "PBKDF2", salt, iterations, hash: "SHA-256" },
+    material,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+async function encryptJson(value, password) {
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const key = await deriveAesKey(password, salt, PBKDF2_ITERATIONS);
+  const plaintext = new TextEncoder().encode(JSON.stringify(value));
+  const cipher = new Uint8Array(
+    await subtle().encrypt(
+      { name: "AES-GCM", iv },
+      key,
+      plaintext
+    )
+  );
+  return {
+    data: toBase64(cipher),
+    salt: toBase64(salt),
+    iv: toBase64(iv)
+  };
+}
+async function decryptJson(encrypted, password, iterations) {
+  const salt = fromBase64(encrypted.salt);
+  const iv = fromBase64(encrypted.iv);
+  const key = await deriveAesKey(password, salt, iterations);
+  let plaintext;
+  try {
+    plaintext = await subtle().decrypt(
+      { name: "AES-GCM", iv },
+      key,
+      fromBase64(encrypted.data)
+    );
+  } catch {
+    throw new WrongPasswordError();
+  }
+  return JSON.parse(new TextDecoder().decode(plaintext));
+}
+var StealthSession = class {
+  storage;
+  namespace;
+  unlockedKeys = null;
+  password = null;
+  constructor(opts) {
+    this.storage = opts.storage;
+    this.namespace = opts.namespace ?? "stealth";
+  }
+  get keysKey() {
+    return `${this.namespace}:keys`;
+  }
+  get scanKey() {
+    return `${this.namespace}:scan-state`;
+  }
+  /**
+   * 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.
+   */
+  async saveKeys(keys, password) {
+    const encrypted = await encryptJson(
+      {
+        metaAddress: keys.metaAddress,
+        spendPrivKey: keys.spendPrivKey,
+        viewPrivKey: keys.viewPrivKey
+      },
+      password
+    );
+    const envelope = {
+      version: 2,
+      kdf: "pbkdf2",
+      iterations: PBKDF2_ITERATIONS,
+      spendPublicKey: keys.spendPubKey,
+      viewPublicKey: keys.viewPubKey,
+      encrypted
+    };
+    await this.storage.setItem(this.keysKey, JSON.stringify(envelope));
+    this.unlockedKeys = keys;
+    this.password = password;
+  }
+  /**
+   * 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.
+   */
+  async unlock(password) {
+    const raw = await this.storage.getItem(this.keysKey);
+    if (!raw) {
+      throw new Error("No stored keys \u2014 call saveKeys() first.");
+    }
+    const envelope = JSON.parse(raw);
+    const secret = await decryptJson(envelope.encrypted, password, envelope.iterations);
+    assertPubKeyMatchesPriv("spend", envelope.spendPublicKey, secret.spendPrivKey);
+    assertPubKeyMatchesPriv("view", envelope.viewPublicKey, secret.viewPrivKey);
+    const keys = {
+      metaAddress: secret.metaAddress,
+      spendPubKey: envelope.spendPublicKey,
+      spendPrivKey: secret.spendPrivKey,
+      viewPubKey: envelope.viewPublicKey,
+      viewPrivKey: secret.viewPrivKey
+    };
+    this.unlockedKeys = keys;
+    this.password = password;
+    return keys;
+  }
+  /** The in-memory keys after {@link unlock}/{@link saveKeys}. */
+  get keys() {
+    if (!this.unlockedKeys) {
+      throw new Error("Session is locked \u2014 call unlock() first.");
+    }
+    return this.unlockedKeys;
+  }
+  /** Wipe in-memory key material (storage is untouched). */
+  lock() {
+    this.unlockedKeys = null;
+    this.password = null;
+  }
+  /** Whether keys are present in storage (does not require unlock). */
+  async hasKeys() {
+    return await this.storage.getItem(this.keysKey) !== null;
+  }
+  /** Remove all session data (keys + scan state) and lock in memory. */
+  async clear() {
+    await this.storage.removeItem(this.keysKey);
+    await this.storage.removeItem(this.scanKey);
+    this.lock();
+  }
+  /**
+   * 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.
+   */
+  async loadScanState() {
+    if (!this.password) {
+      throw new Error("Session is locked \u2014 call unlock() before loadScanState().");
+    }
+    const raw = await this.storage.getItem(this.scanKey);
+    if (!raw) return null;
+    const envelope = JSON.parse(raw);
+    return decryptJson(
+      envelope.encrypted,
+      this.password,
+      envelope.iterations
+    );
+  }
+  /**
+   * Encrypt and persist the scan-state cache under the session password.
+   * Requires an unlocked session.
+   */
+  async saveScanState(state) {
+    if (!this.password) {
+      throw new Error("Session is locked \u2014 call unlock() before saveScanState().");
+    }
+    const encrypted = await encryptJson(state, this.password);
+    const envelope = {
+      version: 2,
+      kdf: "pbkdf2",
+      iterations: PBKDF2_ITERATIONS,
+      encrypted
     };
+    await this.storage.setItem(this.scanKey, JSON.stringify(envelope));
   }
 };
 
+exports.AccountAdapter = AccountAdapter;
+exports.AnnouncementNotFoundError = AnnouncementNotFoundError;
+exports.ClaimAmountError = ClaimAmountError;
+exports.ClaimAmountRequiresNoMergeError = ClaimAmountRequiresNoMergeError;
+exports.ContractIdRequiredError = ContractIdRequiredError;
+exports.DEFAULT_APP_ID = DEFAULT_APP_ID;
+exports.DEFAULT_KEY_SCOPE = DEFAULT_KEY_SCOPE;
+exports.DestinationTrustlineError = DestinationTrustlineError;
+exports.EntryArchivedRestoringError = EntryArchivedRestoringError;
+exports.FeePayerAddressRequiredError = FeePayerAddressRequiredError;
+exports.FeePayerRequiredError = FeePayerRequiredError;
+exports.HorizonClient = HorizonClient;
+exports.IndexerClient = IndexerClient;
+exports.IndexerHttpError = IndexerHttpError;
+exports.IndexerNetworkError = IndexerNetworkError;
+exports.InvalidAmountError = InvalidAmountError;
+exports.MethodNotAvailableError = MethodNotAvailableError;
+exports.MethodNotEnabledError = MethodNotEnabledError;
+exports.MethodRequiredError = MethodRequiredError;
+exports.MinimumAmountError = MinimumAmountError;
+exports.NETWORKS = NETWORKS;
+exports.NoBalanceError = NoBalanceError;
+exports.NoHealthyRelayerError = NoHealthyRelayerError;
+exports.PoolAdapter = PoolAdapter;
+exports.RelayerClient = RelayerClient;
+exports.RelayerHttpError = RelayerHttpError;
+exports.RelayerNetworkError = RelayerNetworkError;
+exports.RelayerPool = RelayerPool;
+exports.SessionIntegrityError = SessionIntegrityError;
+exports.ShadeError = ShadeError;
+exports.SponsoredClaimMismatchError = SponsoredClaimMismatchError;
+exports.SppAdapter = SppAdapter;
+exports.StealthAccountNotFoundError = StealthAccountNotFoundError;
 exports.StealthClient = StealthClient;
+exports.StealthSession = StealthSession;
+exports.TransactionRetryableError = TransactionRetryableError;
+exports.TransactionTimeoutError = TransactionTimeoutError;
+exports.UnsupportedNetworkError = UnsupportedNetworkError;
+exports.WrongPasswordError = WrongPasswordError;
+exports.buildWithdrawMessage = buildWithdrawMessage;
+exports.challengeMessage = challengeMessage;
+exports.createSimulationTx = createSimulationTx;
+exports.formatStroops = formatStroops;
+exports.getNetworkConfig = getNetworkConfig;
+exports.keysFromWalletSignature = keysFromWalletSignature;
+exports.labelForToken = labelForToken;
+exports.networkNameForPassphrase = networkNameForPassphrase;
+exports.normalizeRelayList = normalizeRelayList;
+exports.numberToStroops = numberToStroops;
+exports.parseStroops = parseStroops;
+exports.prepareWithRestore = prepareWithRestore;
+exports.resolveTokenAddress = resolveTokenAddress;
+exports.simulateReadOnly = simulateReadOnly;
+exports.stealthKeysFromRaw = stealthKeysFromRaw;
+exports.waitForTransaction = waitForTransaction;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map