@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/adapters/stellar/soroban.js

@@ -0,0 +1,617 @@
+"use strict";
+/**
+ * Shared Soroban RPC utilities
+ *
+ * Common transaction building and read-only query helpers used by
+ * actions, submit, and getters modules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = createServer;
+exports.resolveNetworkConfig = resolveNetworkConfig;
+exports.resetHealthyServerCache = resetHealthyServerCache;
+exports.redactRpcUrl = redactRpcUrl;
+exports.getHealthyServer = getHealthyServer;
+exports.isRetryableSorobanRpcError = isRetryableSorobanRpcError;
+exports.isRetryableSimulationError = isRetryableSimulationError;
+exports.withEndpointFailover = withEndpointFailover;
+exports.toBigIntAmount = toBigIntAmount;
+exports.queryContract = queryContract;
+exports.buildSorobanTx = buildSorobanTx;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const core_1 = require("../../core");
+const concurrency_1 = require("../../core/helpers/concurrency");
+const constants_1 = require("./constants");
+function createServer(rpcUrl) {
+    return new stellar_sdk_1.rpc.Server(rpcUrl, {
+        allowHttp: rpcUrl.startsWith('http://'),
+    });
+}
+/**
+ * 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, overrideRpcUrl) {
+    const defaults = SOROBAN_FALLBACK_RPC_URLS[network];
+    const rpcUrls = overrideRpcUrl
+        ? [overrideRpcUrl, ...defaults]
+        : [...defaults];
+    return {
+        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
+ * `UpshiftSDKError.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;
+}
+/**
+ * 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 (0, concurrency_1.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.UpshiftSDKError('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.
+ *
+ * Named distinctly from `core/helpers/chain-error`'s `isRetryableRpcError`
+ * (the EVM transport classifier, deliberately public) — the internal-dts
+ * leak check matches `@internal` tags by name across the whole `src.ts` tree,
+ * so a same-named pair would make it flag the public EVM one as a leak.
+ * @internal
+ */
+function isRetryableSorobanRpcError(err) {
+    return !(err instanceof core_1.UpshiftValidationError || err instanceof core_1.UpshiftSDKError);
+}
+/**
+ * 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 isRetryableSorobanRpcError}); 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 ?? isRetryableSorobanRpcError;
+    const timeoutMs = options.timeoutMs ?? RPC_OPERATION_TIMEOUT_MS;
+    const rpcUrls = config.rpcUrls && config.rpcUrls.length > 0
+        ? config.rpcUrls
+        : [config.rpcUrl];
+    const runOn = (server) => (0, concurrency_1.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.UpshiftSDKError('UNKNOWN', `Soroban ${method} failed on all endpoints: ${scrub(String(lastError))}`, {
+        cause: scrubErrorUrls(lastError, scrub),
+        context: { method, stage: 'rpc-failover' },
+    });
+    // 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.
+ */
+function toBigIntAmount(value, label) {
+    if (value === '') {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `Invalid ${label}: value must not be empty`);
+    }
+    let result;
+    try {
+        result = BigInt(value);
+    }
+    catch {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `Invalid ${label}: "${value}" is not a valid integer string`);
+    }
+    if (result < 0n) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `Invalid ${label}: value must be non-negative, got "${value}"`);
+    }
+    return result;
+}
+/**
+ * Query a read-only Soroban contract function via simulation.
+ * Uses a throwaway source account — simulation is off-chain and has no on-chain side effects.
+ * Returns the ScVal result, or null if the call fails.
+ */
+function extractSimulationError(simulated) {
+    return 'error' in simulated
+        ? String(simulated.error)
+        : 'Unknown simulation error';
+}
+async function queryContract(config, contractId, method, args = []) {
+    try {
+        // 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');
+        // Minimal fee — simulation is off-chain; these values don't affect execution cost.
+        // Short timeout to avoid blocking vault listing if Soroban RPC is slow.
+        const tx = new stellar_sdk_1.TransactionBuilder(account, {
+            fee: '100',
+            networkPassphrase: config.passphrase,
+        })
+            .addOperation(contract.call(method, ...args))
+            .setTimeout(constants_1.QUERY_TIMEOUT_SECONDS)
+            .build();
+        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;
+        });
+    }
+    catch (err) {
+        core_1.Logger.log.warn('queryContract', `Soroban query failed: ${method}`, {
+            contractId,
+            error: String(err),
+        });
+        return null;
+    }
+}
+/**
+ * Read the network's wall-clock time (unix seconds) from the latest closed
+ * ledger, or null if the RPC can't report it.
+ *
+ * Soroban validators reject a transaction whose `maxTime` precedes the ledger
+ * close time (`txTOO_LATE`). Anchoring `maxTime` to the *network* clock instead
+ * of the signer's `Date.now()` immunises the deadline against a skewed device
+ * clock — a machine lagging behind real time was silently building
+ * already-expired transactions. Best-effort: on any RPC failure the caller
+ * falls back to the local clock, so this never regresses the prior behaviour.
+ */
+async function getNetworkCloseTime(server) {
+    try {
+        const { sequence } = await server.getLatestLedger();
+        // `latestLedgerCloseTime` on the response envelope is the freshest network
+        // time; the single-ledger page is just the cheapest valid request shape.
+        const page = await server.getLedgers({
+            startLedger: sequence,
+            pagination: { limit: 1 },
+        });
+        return typeof page.latestLedgerCloseTime === 'number'
+            ? page.latestLedgerCloseTime
+            : null;
+    }
+    catch (err) {
+        core_1.Logger.log.warn('getNetworkCloseTime', `Network clock unavailable; falling back to local clock for tx timebounds: ${String(err)}`);
+        return null;
+    }
+}
+/**
+ * Build an unsigned Soroban contract invocation transaction.
+ * Fetches the real source account from the network (the account must exist and be funded).
+ * Simulates via Soroban RPC to attach resource footprint and auth entries,
+ * using MAX_FEE_STROOPS as the fee ceiling and incorporating the simulated resource fee.
+ *
+ * Thrown errors carry `context.stage` naming where the build broke:
+ * `'simulation'` (the contract itself rejected the call), `'restore-required'`,
+ * `'assembly'`, or `'rpc-failover'` (no endpoint answered). Callers use it to
+ * separate a vault-level rejection from a transport problem — see the curator
+ * alerting in `handleStellarRedeem`. Validation errors (e.g.
+ * `ACCOUNT_NOT_FUNDED`) carry no stage, so treat a missing one as "not a
+ * vault-level failure" rather than assuming the field is always present.
+ */
+async function buildSorobanTx(config, sourceAddress, contractId, method, args) {
+    const contract = new stellar_sdk_1.Contract(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.UpshiftValidationError('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.UpshiftSDKError('UNKNOWN', `Soroban simulation failed: ${errorText}`, { context: { method, contractId, stage: 'simulation' } });
+        }
+        if ('restorePreamble' in simulated && simulated.restorePreamble) {
+            throw new core_1.UpshiftSDKError('UNKNOWN', `Contract ledger state needs restoration before invoking ${method}. ` +
+                'Submit a restore footprint transaction first.', { context: { method, contractId, stage: 'restore-required' } });
+        }
+        try {
+            const assembled = stellar_sdk_1.rpc.assembleTransaction(tx, simulated).build();
+            return assembled.toXDR();
+        }
+        catch (assemblyErr) {
+            throw new core_1.UpshiftSDKError('UNKNOWN', `Failed to assemble Soroban transaction for ${method}: ${String(assemblyErr)}`, {
+                cause: assemblyErr,
+                context: { method, contractId, stage: 'assembly' },
+            });
+        }
+    });
+}
+//# sourceMappingURL=soroban.js.map

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

@@ -0,0 +1,42 @@
+/**
+ * Stellar Transaction Submission
+ *
+ * Submits signed Soroban transactions and polls for confirmation.
+ */
+import type { IStellarNetwork } from './types';
+/**
+ * Submit a signed Soroban transaction and poll until confirmed.
+ *
+ * @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 UpshiftTimeoutError} when the transaction is not confirmed
+ *   within the poll budget (`MAX_POLL_ATTEMPTS`).
+ * @throws {@link UpshiftSDKError} when the RPC rejects the submission or the
+ *   transaction confirms as failed. Its `context` carries `{ network, status }`
+ *   plus, when the result XDR decodes, a `resultCode` string holding the
+ *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
+ *   is `undefined` when the code cannot be decoded.
+ *
+ * Side effect: a transaction whose `resultCode` is `txFailed` — the operation
+ * itself ran and failed — and whose envelope shows a vault `redeem` is relayed
+ * to that vault's curator (fire-and-forget, deduped — see
+ * {@link reportRedeemFailure}). Nothing else alerts: an RPC-rejected
+ * broadcast is a retryable race, a poll timeout is indeterminate (the
+ * transaction may yet succeed), and any other result code means the redeem
+ * never executed.
+ * @example
+ * ```ts
+ * try {
+ *   const hash = await submitStellarTransaction(signedXdr, 'mainnet');
+ * } catch (err) {
+ *   if (err instanceof UpshiftSDKError && err.context?.resultCode === 'txBadSeq') {
+ *     // stale sequence number — rebuild the transaction and resubmit
+ *   }
+ * }
+ * ```
+ */
+export declare function submitStellarTransaction(signedXdr: string, network: IStellarNetwork, sorobanRpcUrl?: string): Promise<string>;