@augustdigital/sdk 8.10.0 → 8.12.0

package/lib/adapters/stellar/soroban.js

@@ -8,6 +8,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createServer = createServer;
 exports.resolveNetworkConfig = resolveNetworkConfig;
+exports.resetHealthyServerCache = resetHealthyServerCache;
+exports.redactRpcUrl = redactRpcUrl;
+exports.getHealthyServer = getHealthyServer;
+exports.isRetryableRpcError = isRetryableRpcError;
+exports.isRetryableSimulationError = isRetryableSimulationError;
+exports.withEndpointFailover = withEndpointFailover;
 exports.toBigIntAmount = toBigIntAmount;
 exports.queryContract = queryContract;
 exports.buildSorobanTx = buildSorobanTx;
@@ -20,14 +26,410 @@ function createServer(rpcUrl) {
     });
 }
 /**
- * Resolve RPC URL and network passphrase for a Stellar network.
+ * Ordered public Soroban RPC endpoints per network, for health-gated failover.
+ *
+ * The first entry is the default primary ({@link SOROBAN_RPC_URLS}); the rest
+ * are keyless public fallbacks. A provider node can stall — most visibly around
+ * a protocol upgrade, when it freezes behind the network head and every
+ * simulation fails with a snapshot error — so a single endpoint means one bad
+ * node takes down all reads, deposits, and submits. Module-private: an internal
+ * resilience detail, not part of the adapter's public surface.
+ */
+const SOROBAN_FALLBACK_RPC_URLS = {
+    mainnet: [constants_1.SOROBAN_RPC_URLS.mainnet, 'https://mainnet.sorobanrpc.com'],
+    testnet: [constants_1.SOROBAN_RPC_URLS.testnet],
+};
+/**
+ * Resolve the ordered RPC endpoints and network passphrase for a Stellar network.
+ *
+ * When `overrideRpcUrl` is supplied (e.g. a consumer's keyed Alchemy endpoint),
+ * it becomes the primary with the built-in public endpoints kept behind it as
+ * failover — so opting into a premium provider still degrades to the public
+ * network rather than becoming a new single point of failure. The endpoint is
+ * injected rather than hardcoded, so the adapter depends on configuration, not a
+ * constant.
  */
-function resolveNetworkConfig(network) {
+function resolveNetworkConfig(network, overrideRpcUrl) {
+    const defaults = SOROBAN_FALLBACK_RPC_URLS[network];
+    const rpcUrls = overrideRpcUrl
+        ? [overrideRpcUrl, ...defaults]
+        : [...defaults];
     return {
-        rpcUrl: constants_1.SOROBAN_RPC_URLS[network],
+        rpcUrl: rpcUrls[0],
+        rpcUrls,
         passphrase: constants_1.NETWORK_PASSPHRASES[network],
     };
 }
+/** How long a health-checked endpoint choice is reused before re-probing. */
+const HEALTHY_SERVER_TTL_MS = 30_000;
+/**
+ * Shorter reuse window after a fully-failed probe (no endpoint healthy). Caps
+ * probe traffic during an outage — failing fast on the primary beats re-probing
+ * every endpoint on every call — while keeping recovery within a few seconds.
+ */
+const NEGATIVE_CACHE_TTL_MS = 5_000;
+/**
+ * Bound on a single `getHealth` probe so a *hung* (not erroring) node can't
+ * block the failover loop; a timeout is treated like an unhealthy endpoint.
+ */
+const HEALTH_PROBE_TIMEOUT_MS = 3_000;
+/**
+ * Bound on a single real RPC operation (simulate / getAccount / build) so an
+ * endpoint that passed `getHealth()` but then *hangs* on the actual call fails
+ * over instead of blocking indefinitely; a timeout is treated as retryable.
+ */
+const RPC_OPERATION_TIMEOUT_MS = 15_000;
+const healthyServerCache = new Map();
+// De-dupes concurrent probes for the same endpoint set (e.g. the parallel reads
+// a vault listing issues) so a cold cache costs one probe, not one per call.
+const inFlightProbes = new Map();
+/**
+ * Clear the health-check cache and any in-flight probes. Test-only seam.
+ * @internal
+ */
+function resetHealthyServerCache() {
+    healthyServerCache.clear();
+    inFlightProbes.clear();
+}
+/**
+ * Host-only view of an RPC URL, safe for logs. Keyed provider endpoints put the
+ * API key in the path (e.g. Alchemy `/v2/<key>`), so logging the raw URL would
+ * leak the secret into SDK logs / crash reporters. Returns just protocol+host.
+ * @internal
+ */
+function redactRpcUrl(url) {
+    try {
+        const { protocol, host } = new URL(url);
+        return `${protocol}//${host}`;
+    }
+    catch {
+        return '<invalid-url>';
+    }
+}
+/**
+ * Return a copy of `value` with every configured RPC URL reduced to protocol+host
+ * in any string it carries, so a keyed endpoint (e.g. Alchemy `/v2/<key>`) can't
+ * leak its API key through a thrown error's chained `cause`.
+ *
+ * Handles Errors, plain objects, and arrays — not just Errors: Soroban's
+ * JSON-RPC helper throws the raw `{ code, message, data }` object, which
+ * `AugustSDKError.toJSON()` serializes wholesale, so an unscrubbed object cause
+ * would leak the key. Cloned recursively (depth- and cycle-bounded); the
+ * original is never mutated.
+ */
+function scrubErrorUrls(value, scrub, depth = 0, seen = new WeakSet()) {
+    if (typeof value === 'string')
+        return scrub(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (depth >= 4)
+        return '[TRUNCATED]';
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    if (value instanceof Error) {
+        const clone = new Error(scrub(value.message));
+        clone.name = value.name;
+        if (value.stack)
+            clone.stack = scrub(value.stack);
+        // Carry over any extra own props (e.g. a JSON-RPC `code` / `data`), scrubbed.
+        for (const key of Object.getOwnPropertyNames(value)) {
+            if (key === 'message' || key === 'stack' || key === 'name')
+                continue;
+            clone[key] = scrubErrorUrls(value[key], scrub, depth + 1, seen);
+        }
+        return clone;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => scrubErrorUrls(v, scrub, depth + 1, seen));
+    }
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        out[key] = scrubErrorUrls(v, scrub, depth + 1, seen);
+    }
+    return out;
+}
+/**
+ * Race a promise against a timeout so a hung call can't block indefinitely. The
+ * timer is always cleared, so a fast-resolving promise leaves nothing pending.
+ */
+function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * Return a Soroban RPC server backed by a healthy endpoint for `config`. Thin
+ * wrapper over {@link resolveHealthyServer} for callers (e.g. submission) that
+ * only need the server, not the URL it resolved to.
+ *
+ * @internal
+ */
+function getHealthyServer(config) {
+    return resolveHealthyServer(config).then((r) => r.server);
+}
+/**
+ * Resolve a healthy endpoint for `config`, returning both the server and the URL
+ * it was built from.
+ *
+ * Probes `config.rpcUrls` in priority order via `getHealth()` and uses the first
+ * that reports healthy, so a stalled or lagging provider node is skipped instead
+ * of failing every call. The choice is cached for {@link HEALTHY_SERVER_TTL_MS},
+ * and concurrent callers on a cold cache share a single in-flight probe — so a
+ * burst of parallel reads costs one health probe, not one per call. When no
+ * endpoint reports healthy, falls back to the first reachable endpoint so the
+ * caller still attempts the request and surfaces the node's real error.
+ *
+ * The URL is returned (not just the server) so {@link withEndpointFailover} can
+ * skip the just-attempted endpoint and promote a working fallback into the cache.
+ */
+function resolveHealthyServer(config) {
+    // Prefer the ordered failover list; fall back to the single primary for a
+    // hand-built config that predates `rpcUrls`.
+    const rpcUrls = config.rpcUrls && config.rpcUrls.length > 0
+        ? config.rpcUrls
+        : [config.rpcUrl];
+    // Key by the full ordered endpoint set, not just the primary: the same
+    // primary paired with different fallback lists selects a different server, so
+    // keying on `rpcUrls[0]` alone could return one endpoint set's choice for
+    // another during the TTL.
+    const cacheKey = rpcUrls.join('|');
+    const cached = healthyServerCache.get(cacheKey);
+    if (cached) {
+        // A fully-failed probe is cached only briefly (NEGATIVE_CACHE_TTL_MS) so an
+        // outage doesn't re-probe every endpoint on every call, yet recovers fast.
+        const ttl = cached.healthy ? HEALTHY_SERVER_TTL_MS : NEGATIVE_CACHE_TTL_MS;
+        if (Date.now() - cached.checkedAt < ttl) {
+            return Promise.resolve({
+                server: cached.server,
+                url: cached.url,
+                healthy: cached.healthy,
+            });
+        }
+    }
+    const existing = inFlightProbes.get(cacheKey);
+    if (existing)
+        return existing;
+    const probe = probeHealthyServer(rpcUrls, cacheKey).finally(() => {
+        inFlightProbes.delete(cacheKey);
+    });
+    inFlightProbes.set(cacheKey, probe);
+    return probe;
+}
+async function probeHealthyServer(rpcUrls, cacheKey) {
+    // The first endpoint we can even construct — the fallback when none report
+    // healthy. Tracked separately from `rpcUrls[0]` so a malformed primary (e.g. a
+    // typo'd consumer override) is skipped rather than disabling every call.
+    let firstConstructable;
+    let firstConstructableUrl;
+    for (const url of rpcUrls) {
+        let server;
+        try {
+            // Construct inside the guard: a malformed URL throws from the rpc.Server
+            // ctor, and must skip to the next endpoint rather than abort the loop and
+            // disable every fallback.
+            server = createServer(url);
+        }
+        catch (err) {
+            core_1.Logger.log.warn('getHealthyServer', 'Skipping invalid Soroban RPC endpoint; trying next endpoint', { url: redactRpcUrl(url), error: String(err) });
+            continue;
+        }
+        if (firstConstructable === undefined) {
+            firstConstructable = server;
+            firstConstructableUrl = url;
+        }
+        try {
+            const health = await withTimeout(server.getHealth(), HEALTH_PROBE_TIMEOUT_MS, 'getHealth');
+            if (health.status === 'healthy') {
+                healthyServerCache.set(cacheKey, {
+                    server,
+                    url,
+                    checkedAt: Date.now(),
+                    healthy: true,
+                });
+                return { server, url, healthy: true };
+            }
+            core_1.Logger.log.warn('getHealthyServer', `Soroban RPC reported status "${health.status}"; trying next endpoint`, { url: redactRpcUrl(url) });
+        }
+        catch (err) {
+            core_1.Logger.log.warn('getHealthyServer', 'Soroban RPC health check failed; trying next endpoint', 
+            // Scrub the endpoint from the error message too — SDK errors often
+            // embed the request URL (key and all).
+            {
+                url: redactRpcUrl(url),
+                error: String(err).split(url).join(redactRpcUrl(url)),
+            });
+        }
+    }
+    if (firstConstructable === undefined) {
+        // Every configured URL was malformed — there is nothing to call.
+        throw new core_1.AugustSDKError('UNKNOWN', 'No valid Soroban RPC endpoint could be constructed from the configured URLs');
+    }
+    const fallbackUrl = firstConstructableUrl;
+    core_1.Logger.log.warn('getHealthyServer', 'No healthy Soroban RPC endpoint; falling back to first reachable endpoint', { primary: redactRpcUrl(fallbackUrl) });
+    // Negative-cache the fallback (short TTL) so a sustained outage fails fast
+    // instead of re-probing every endpoint on every call.
+    healthyServerCache.set(cacheKey, {
+        server: firstConstructable,
+        url: fallbackUrl,
+        checkedAt: Date.now(),
+        healthy: false,
+    });
+    return { server: firstConstructable, url: fallbackUrl, healthy: false };
+}
+/**
+ * A thrown RPC error is retryable on another endpoint UNLESS it is one of our
+ * typed domain errors. Those mark a *deterministic* outcome — a contract revert,
+ * an unfunded account, archived state needing restore, a bad input, or a local
+ * assembly failure — which reproduces identically on every node, so retrying
+ * elsewhere only wastes calls. Any other throw (a transport hang/reset, or a
+ * method-specific node error from an endpoint that still answered `getHealth()`)
+ * is worth the next endpoint.
+ *
+ * Exported so an operation with different semantics (e.g. an idempotency-aware
+ * submission path) can compose or replace this policy via
+ * {@link FailoverOptions.isRetryable} — extension without editing the core.
+ * @internal
+ */
+function isRetryableRpcError(err) {
+    return !(err instanceof core_1.AugustValidationError || err instanceof core_1.AugustSDKError);
+}
+/**
+ * Signatures of simulation errors that indicate a stalled/lagging *node* rather
+ * than a deterministic contract revert. The canonical case is the Protocol 27
+ * boundary, where a node frozen behind the network head answered `getHealth()`
+ * but reported reads with a "not present in the snapshot" error. Extend this
+ * list as new node-side signatures surface.
+ */
+const RETRYABLE_SIMULATION_ERROR_SIGNATURES = ['not present in the snapshot'];
+/**
+ * Whether a simulation *error* string is a node/infrastructure failure (which
+ * clears on another endpoint) rather than a genuine contract revert (which
+ * reproduces on every node). `isSimulationError` alone can't tell these apart —
+ * both arrive as a populated `error` field — so callers use this to decide
+ * whether to fail over or treat the error as terminal.
+ * @internal
+ */
+function isRetryableSimulationError(errorText) {
+    const lower = errorText.toLowerCase();
+    return RETRYABLE_SIMULATION_ERROR_SIGNATURES.some((sig) => lower.includes(sig));
+}
+/**
+ * Drop a cached endpoint choice so a server that just failed a *real* call is
+ * not re-used for the remainder of its {@link HEALTHY_SERVER_TTL_MS} window.
+ */
+function dropCachedServer(rpcUrls) {
+    healthyServerCache.delete(rpcUrls.join('|'));
+}
+/**
+ * Run an idempotent, side-effect-free `operation` (a read or a tx build) against
+ * a Soroban endpoint, failing over to the remaining endpoints on a retryable
+ * failure.
+ *
+ * {@link getHealthyServer} only proves an endpoint answered `getHealth()`, and
+ * caches that choice for {@link HEALTHY_SERVER_TTL_MS} — but the node can still
+ * hang or return a method-specific error on the *real* call. So we run the op on
+ * the health-gated server first (the fast, cached path) and, on a retryable
+ * failure, drop that cached choice and retry the op against every endpoint in
+ * priority order. Deterministic contract/domain errors short-circuit (see
+ * {@link isRetryableRpcError}); each attempt is time-boxed so a hung node can't
+ * stall the loop.
+ *
+ * The `operation` is a strategy (dependency-injected), so new read/build calls
+ * reuse this failover without changing it; `options` keeps retry policy and
+ * timeout open for extension. Submission is deliberately NOT routed through here
+ * — re-sending a signed transaction across endpoints risks a double-submit, so
+ * it needs sequence/DUPLICATE-based idempotency rather than blind retry.
+ * @internal
+ */
+async function withEndpointFailover(config, method, operation, options = {}) {
+    const isRetryable = options.isRetryable ?? isRetryableRpcError;
+    const timeoutMs = options.timeoutMs ?? RPC_OPERATION_TIMEOUT_MS;
+    const rpcUrls = config.rpcUrls && config.rpcUrls.length > 0
+        ? config.rpcUrls
+        : [config.rpcUrl];
+    const runOn = (server) => withTimeout(operation(server), timeoutMs, `Soroban ${method}`);
+    const cacheKey = rpcUrls.join('|');
+    // Reduce every configured endpoint URL to protocol+host in anything surfaced
+    // from here (logs, the thrown message, the chained cause). SDK errors embed the
+    // request URL — which for a keyed provider carries the API key in its path — so
+    // an unscrubbed `String(err)` would leak it. Belt-and-suspenders with the
+    // analytics sanitizer, and it also covers the thrown error that escapes to the
+    // caller (which our telemetry sanitizer never sees).
+    const scrub = (text) => rpcUrls.reduce((acc, u) => acc.split(u).join(redactRpcUrl(u)), text);
+    let lastError;
+    // A terminal "everything failed" error, scrubbed so a keyed endpoint can't
+    // leak through the message or chained cause.
+    const failAllEndpoints = () => new core_1.AugustSDKError('UNKNOWN', `Soroban ${method} failed on all endpoints: ${scrub(String(lastError))}`, { cause: scrubErrorUrls(lastError, scrub), context: { method } });
+    // Fast path: the health-gated, cross-call-cached endpoint.
+    const { server: primaryServer, url: primaryUrl, healthy, } = await resolveHealthyServer(config);
+    try {
+        return await runOn(primaryServer);
+    }
+    catch (err) {
+        if (!isRetryable(err))
+            throw err;
+        lastError = err;
+        if (!healthy) {
+            // The resolved endpoint is a negative-cached fallback: a prior probe found
+            // no healthy endpoint, so the whole set is down. Re-looping every endpoint
+            // (and re-probing on the next read) would only amplify load during the
+            // outage, so fail fast and leave the short-TTL negative entry in place —
+            // subsequent reads within NEGATIVE_CACHE_TTL_MS fast-fail on the primary too.
+            throw failAllEndpoints();
+        }
+        // A "healthy" endpoint failed the real call — drop it and fail over.
+        dropCachedServer(rpcUrls);
+        core_1.Logger.log.warn('withEndpointFailover', `Soroban ${method} failed on the health-gated endpoint; failing over`, { error: scrub(String(err)) });
+    }
+    // Failover: the remaining endpoints in priority order. Skip the one the fast
+    // path already tried (no point paying its timeout twice). On success, promote
+    // the working endpoint into the cache so the next call starts there instead of
+    // repeating the failed-primary-then-fallback sequence.
+    for (const url of rpcUrls) {
+        if (url === primaryUrl)
+            continue;
+        let server;
+        try {
+            server = createServer(url);
+        }
+        catch {
+            continue; // malformed endpoint URL — skip
+        }
+        try {
+            const result = await runOn(server);
+            healthyServerCache.set(cacheKey, {
+                server,
+                url,
+                checkedAt: Date.now(),
+                healthy: true,
+            });
+            return result;
+        }
+        catch (err) {
+            if (!isRetryable(err))
+                throw err;
+            lastError = err;
+            core_1.Logger.log.warn('withEndpointFailover', `Soroban ${method} failed; trying next endpoint`, {
+                url: redactRpcUrl(url),
+                error: scrub(String(err)),
+            });
+        }
+    }
+    // Every endpoint's real op failed even though one health-probed OK. Negative-
+    // cache the health-gated server (it constructed fine) so subsequent reads
+    // fast-fail within NEGATIVE_CACHE_TTL_MS instead of re-probing + re-looping the
+    // whole set during a sustained outage.
+    healthyServerCache.set(cacheKey, {
+        server: primaryServer,
+        url: primaryUrl,
+        checkedAt: Date.now(),
+        healthy: false,
+    });
+    throw failAllEndpoints();
+}
 /**
  * Validate and convert a string amount to a non-negative BigInt.
  * Throws a descriptive error if the value is not a valid non-negative integer string.
@@ -60,7 +462,8 @@ function extractSimulationError(simulated) {
 }
 async function queryContract(config, contractId, method, args = []) {
     try {
-        const server = createServer(config.rpcUrl);
+        // Build the simulation tx once — it is endpoint-independent, so only the
+        // simulate call is failed over across endpoints (not the tx assembly).
         const contract = new stellar_sdk_1.Contract(contractId);
         const sourceKeypair = stellar_sdk_1.Keypair.random();
         const account = new stellar_sdk_1.Account(sourceKeypair.publicKey(), '0');
@@ -73,20 +476,27 @@ async function queryContract(config, contractId, method, args = []) {
             .addOperation(contract.call(method, ...args))
             .setTimeout(constants_1.QUERY_TIMEOUT_SECONDS)
             .build();
-        const simulated = await server.simulateTransaction(tx);
-        if (stellar_sdk_1.rpc.Api.isSimulationError(simulated)) {
-            core_1.Logger.log.warn('queryContract', `Soroban simulation error for ${method}: ${extractSimulationError(simulated)}`, {
-                contractId,
-            });
+        return await withEndpointFailover(config, method, async (server) => {
+            const simulated = await server.simulateTransaction(tx);
+            if (stellar_sdk_1.rpc.Api.isSimulationError(simulated)) {
+                const errorText = extractSimulationError(simulated);
+                if (isRetryableSimulationError(errorText)) {
+                    // A stalled/lagging node reports the read as a simulation error too
+                    // (e.g. a post-upgrade snapshot gap) — not a real revert. Throw so the
+                    // failover wrapper tries another endpoint instead of returning null.
+                    throw new Error(`Soroban simulation node error for ${method}: ${errorText}`);
+                }
+                // A genuine contract revert is deterministic across nodes — surface null
+                // (best-effort read) rather than failing over to repeat it.
+                core_1.Logger.log.warn('queryContract', `Soroban simulation error for ${method}: ${errorText}`, { contractId });
+                return null;
+            }
+            if (stellar_sdk_1.rpc.Api.isSimulationSuccess(simulated) && simulated.result) {
+                return simulated.result.retval;
+            }
+            core_1.Logger.log.warn('queryContract', `Unexpected simulation state for ${method} — no result returned`, { contractId });
             return null;
-        }
-        if (stellar_sdk_1.rpc.Api.isSimulationSuccess(simulated) && simulated.result) {
-            return simulated.result.retval;
-        }
-        core_1.Logger.log.warn('queryContract', `Unexpected simulation state for ${method} — no result returned`, {
-            contractId,
         });
-        return null;
     }
     catch (err) {
         core_1.Logger.log.warn('queryContract', `Soroban query failed: ${method}`, {
@@ -132,54 +542,67 @@ async function getNetworkCloseTime(server) {
  * using MAX_FEE_STROOPS as the fee ceiling and incorporating the simulated resource fee.
  */
 async function buildSorobanTx(config, sourceAddress, contractId, method, args) {
-    const server = createServer(config.rpcUrl);
-    // Read the network clock in parallel with the account fetch — it overlaps the
-    // account round-trip, so it adds no latency on the happy path.
-    const networkCloseTimePromise = getNetworkCloseTime(server);
-    let account;
-    try {
-        account = await server.getAccount(sourceAddress);
-    }
-    catch (err) {
-        // Soroban rpc currently throws plain `Error("Account not found: ...")`
-        // for unfunded accounts; check `NotFoundError` too so this survives an
-        // SDK refactor to typed errors.
-        const msg = err instanceof Error ? err.message : String(err);
-        const isAccountNotFound = err instanceof stellar_sdk_1.NotFoundError || /Account not found/.test(msg);
-        if (isAccountNotFound) {
-            throw new core_1.AugustValidationError('ACCOUNT_NOT_FUNDED', `Stellar account ${sourceAddress} is not funded. Send at least 1 XLM to this address to activate it before depositing or redeeming.`, { cause: err, context: { sourceAddress, method, contractId } });
-        }
-        throw err;
-    }
     const contract = new stellar_sdk_1.Contract(contractId);
-    const builder = new stellar_sdk_1.TransactionBuilder(account, {
-        fee: constants_1.MAX_FEE_STROOPS,
-        networkPassphrase: config.passphrase,
-    }).addOperation(contract.call(method, ...args));
-    const networkCloseTime = await networkCloseTimePromise;
-    if (networkCloseTime !== null) {
-        // Absolute deadline anchored to the network clock — survives signer skew.
-        builder.setTimebounds(0, networkCloseTime + constants_1.TX_TIMEOUT_SECONDS);
-    }
-    else {
-        // RPC couldn't report network time; fall back to the local-clock window.
-        builder.setTimeout(constants_1.TX_TIMEOUT_SECONDS);
-    }
-    const tx = builder.build();
-    const simulated = await server.simulateTransaction(tx);
-    if (stellar_sdk_1.rpc.Api.isSimulationError(simulated)) {
-        throw new core_1.AugustSDKError('UNKNOWN', `Soroban simulation failed: ${extractSimulationError(simulated)}`, { context: { method, contractId } });
-    }
-    if ('restorePreamble' in simulated && simulated.restorePreamble) {
-        throw new core_1.AugustSDKError('UNKNOWN', `Contract ledger state needs restoration before invoking ${method}. ` +
-            'Submit a restore footprint transaction first.', { context: { method, contractId } });
-    }
-    try {
-        const assembled = stellar_sdk_1.rpc.assembleTransaction(tx, simulated).build();
-        return assembled.toXDR();
-    }
-    catch (assemblyErr) {
-        throw new core_1.AugustSDKError('UNKNOWN', `Failed to assemble Soroban transaction for ${method}: ${String(assemblyErr)}`, { cause: assemblyErr, context: { method, contractId } });
-    }
+    // Build is idempotent (no on-chain side effects), so the whole account-fetch →
+    // simulate → assemble sequence is failed over across endpoints. Deterministic
+    // outcomes (unfunded account, simulation/restore/assembly errors) throw typed
+    // errors and short-circuit the failover; transport errors get the next node.
+    return withEndpointFailover(config, method, async (server) => {
+        // Read the network clock in parallel with the account fetch — it overlaps
+        // the account round-trip, so it adds no latency on the happy path.
+        const networkCloseTimePromise = getNetworkCloseTime(server);
+        let account;
+        try {
+            account = await server.getAccount(sourceAddress);
+        }
+        catch (err) {
+            // Soroban rpc currently throws plain `Error("Account not found: ...")`
+            // for unfunded accounts; check `NotFoundError` too so this survives an
+            // SDK refactor to typed errors. An unfunded account is deterministic
+            // across nodes (typed error → no failover); any other getAccount error is
+            // transport-ish and falls over.
+            const msg = err instanceof Error ? err.message : String(err);
+            const isAccountNotFound = err instanceof stellar_sdk_1.NotFoundError || /Account not found/.test(msg);
+            if (isAccountNotFound) {
+                throw new core_1.AugustValidationError('ACCOUNT_NOT_FUNDED', `Stellar account ${sourceAddress} is not funded. Send at least 1 XLM to this address to activate it before depositing or redeeming.`, { cause: err, context: { sourceAddress, method, contractId } });
+            }
+            throw err;
+        }
+        const builder = new stellar_sdk_1.TransactionBuilder(account, {
+            fee: constants_1.MAX_FEE_STROOPS,
+            networkPassphrase: config.passphrase,
+        }).addOperation(contract.call(method, ...args));
+        const networkCloseTime = await networkCloseTimePromise;
+        if (networkCloseTime !== null) {
+            // Absolute deadline anchored to the network clock — survives signer skew.
+            builder.setTimebounds(0, networkCloseTime + constants_1.TX_TIMEOUT_SECONDS);
+        }
+        else {
+            // RPC couldn't report network time; fall back to the local-clock window.
+            builder.setTimeout(constants_1.TX_TIMEOUT_SECONDS);
+        }
+        const tx = builder.build();
+        const simulated = await server.simulateTransaction(tx);
+        if (stellar_sdk_1.rpc.Api.isSimulationError(simulated)) {
+            const errorText = extractSimulationError(simulated);
+            if (isRetryableSimulationError(errorText)) {
+                // Node/snapshot error (a stale node), not a contract revert — throw a
+                // retryable error so the failover wrapper tries another endpoint.
+                throw new Error(`Soroban simulation node error for ${method}: ${errorText}`);
+            }
+            throw new core_1.AugustSDKError('UNKNOWN', `Soroban simulation failed: ${errorText}`, { context: { method, contractId } });
+        }
+        if ('restorePreamble' in simulated && simulated.restorePreamble) {
+            throw new core_1.AugustSDKError('UNKNOWN', `Contract ledger state needs restoration before invoking ${method}. ` +
+                'Submit a restore footprint transaction first.', { context: { method, contractId } });
+        }
+        try {
+            const assembled = stellar_sdk_1.rpc.assembleTransaction(tx, simulated).build();
+            return assembled.toXDR();
+        }
+        catch (assemblyErr) {
+            throw new core_1.AugustSDKError('UNKNOWN', `Failed to assemble Soroban transaction for ${method}: ${String(assemblyErr)}`, { cause: assemblyErr, context: { method, contractId } });
+        }
+    });
 }
 //# sourceMappingURL=soroban.js.map

package/lib/adapters/stellar/submit.d.ts

@@ -9,6 +9,9 @@ import type { IStellarNetwork } from './types';
  *
  * @param signedXdr - Base64-encoded XDR of the signed transaction
  * @param network - Stellar network name
+ * @param sorobanRpcUrl - Optional override Soroban RPC endpoint (e.g. a keyed
+ *   Alchemy URL); becomes the primary with the SDK's public endpoints kept as
+ *   failover. Omit to use the public endpoints.
  * @returns The transaction hash once the network confirms it as successful
  * @throws {@link AugustTimeoutError} when the transaction is not confirmed
  *   within the poll budget (`MAX_POLL_ATTEMPTS`).
@@ -28,4 +31,4 @@ import type { IStellarNetwork } from './types';
  * }
  * ```
  */
-export declare function submitStellarTransaction(signedXdr: string, network: IStellarNetwork): Promise<string>;
+export declare function submitStellarTransaction(signedXdr: string, network: IStellarNetwork, sorobanRpcUrl?: string): Promise<string>;

package/lib/adapters/stellar/submit.js

@@ -53,6 +53,9 @@ function safeStringify(value) {
  *
  * @param signedXdr - Base64-encoded XDR of the signed transaction
  * @param network - Stellar network name
+ * @param sorobanRpcUrl - Optional override Soroban RPC endpoint (e.g. a keyed
+ *   Alchemy URL); becomes the primary with the SDK's public endpoints kept as
+ *   failover. Omit to use the public endpoints.
  * @returns The transaction hash once the network confirms it as successful
  * @throws {@link AugustTimeoutError} when the transaction is not confirmed
  *   within the poll budget (`MAX_POLL_ATTEMPTS`).
@@ -72,9 +75,10 @@ function safeStringify(value) {
  * }
  * ```
  */
-async function submitStellarTransaction(signedXdr, network) {
-    const { rpcUrl, passphrase } = (0, soroban_1.resolveNetworkConfig)(network);
-    const server = (0, soroban_1.createServer)(rpcUrl);
+async function submitStellarTransaction(signedXdr, network, sorobanRpcUrl) {
+    const config = (0, soroban_1.resolveNetworkConfig)(network, sorobanRpcUrl);
+    const { passphrase } = config;
+    const server = await (0, soroban_1.getHealthyServer)(config);
     const tx = stellar_sdk_1.TransactionBuilder.fromXDR(signedXdr, passphrase);
     const sendResult = await server.sendTransaction(tx);
     if (sendResult.status === 'ERROR') {

package/lib/adapters/stellar/types.d.ts

@@ -9,6 +9,12 @@ export interface IStellarDepositParams {
     amount: string;
     senderAddress: string;
     network: IStellarNetwork;
+    /**
+     * Optional override Soroban RPC endpoint (e.g. a keyed Alchemy URL). When set
+     * it is the primary, with the SDK's public endpoints kept behind it as
+     * failover.
+     */
+    sorobanRpcUrl?: string;
 }
 /** Parameters for building an unsigned Stellar vault redeem transaction. */
 export interface IStellarRedeemParams {
@@ -16,6 +22,12 @@ export interface IStellarRedeemParams {
     shares: string;
     receiverAddress: string;
     network: IStellarNetwork;
+    /**
+     * Optional override Soroban RPC endpoint (e.g. a keyed Alchemy URL). When set
+     * it is the primary, with the SDK's public endpoints kept behind it as
+     * failover.
+     */
+    sorobanRpcUrl?: string;
 }
 /**
  * User vault position returned by on-chain balance queries.

package/lib/core/analytics/method-taxonomy.js

@@ -39,6 +39,7 @@ exports.METHOD_CATEGORIES = {
     getVaultBorrowerHealthFactor: 'read.vault',
     getYieldLastRealizedOn: 'read.vault',
     getVaultActivity: 'read.vault',
+    getSwapRouterDepositResult: 'read.vault',
     getVaultPositions: 'read.position',
     getVaultUserHistory: 'read.position',
     getUserHistory: 'read.position',