@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/adapters/stellar/submit.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * Stellar Transaction Submission
+ *
+ * Submits signed Soroban transactions and polls for confirmation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.submitStellarTransaction = submitStellarTransaction;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const core_1 = require("../../core");
+const curator_alert_1 = require("../../core/logger/curator-alert");
+const soroban_1 = require("./soroban");
+const invocation_1 = require("./invocation");
+const constants_1 = require("./constants");
+/**
+ * Best-effort decode of the transaction-level result code (the XDR union
+ * discriminant, e.g. `"txBadSeq"`, `"txTooLate"`) from a Soroban
+ * `TransactionResult`. Typed `unknown` and probed structurally so it stays
+ * robust to RPC/SDK shape drift; returns `undefined` for anything that isn't a
+ * decoded union, so callers fall back to the stringified XDR in the message.
+ */
+function extractTxResultCode(result) {
+    try {
+        const decoded = result;
+        if (typeof decoded?.result !== 'function')
+            return undefined;
+        // `|| undefined`: an empty discriminant shares the clean "no code" path.
+        return decoded.result().switch().name || undefined;
+    }
+    catch (e) {
+        // Only reached on a malformed / shape-drifted union (the non-union case
+        // already returned above). Breadcrumb it so decoder rot stays detectable;
+        // the caller still throws with the stringified XDR in the message.
+        core_1.Logger.log.warn('extractTxResultCode', { decodeError: String(e) });
+        return undefined;
+    }
+}
+/**
+ * `JSON.stringify` that never throws. A real `xdr.TransactionResult` can hold
+ * `bigint` fields (e.g. `feeCharged`), which make `JSON.stringify` throw a
+ * `TypeError` — that would escape and replace the `UpshiftSDKError` this detail
+ * is only meant to enrich. Returns `''` on failure so the caller falls back to
+ * the status; the decoded `resultCode` still carries the precise reason.
+ */
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+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') {
+        const errorResult = 'errorResult' in sendResult ? sendResult.errorResult : undefined;
+        const resultCode = extractTxResultCode(errorResult);
+        const detail = errorResult ? safeStringify(errorResult) : '';
+        const msg = `Transaction submission failed: ${detail || sendResult.status}`;
+        core_1.Logger.log.error('submitStellarTransaction', msg, { network, resultCode });
+        throw new core_1.UpshiftSDKError('UNKNOWN', msg, {
+            context: { network, status: sendResult.status, resultCode },
+        });
+    }
+    // Only PENDING (and DUPLICATE) mean the tx was accepted by the RPC.
+    // DUPLICATE means this exact transaction was already submitted — it may
+    // already be confirmed or still pending from a prior submission.
+    // TRY_AGAIN_LATER and any other status should be surfaced immediately
+    // so callers can retry submission instead of waiting for a poll timeout.
+    if (sendResult.status !== 'PENDING' && sendResult.status !== 'DUPLICATE') {
+        const msg = `Transaction not accepted by RPC (status: ${sendResult.status}). ` +
+            'This may be retryable — the RPC node could be overloaded.';
+        core_1.Logger.log.error('submitStellarTransaction', msg, { network });
+        throw new core_1.UpshiftSDKError('UNKNOWN', msg, {
+            context: { network, status: sendResult.status },
+        });
+    }
+    // Geometric backoff (start POLL_INTERVAL_MS, ×POLL_INTERVAL_BACKOFF up to
+    // POLL_INTERVAL_MAX_MS) — fast on the happy path, gentler on slow ledgers.
+    let getResult = await server.getTransaction(sendResult.hash);
+    let polls = 0;
+    let nextDelay = constants_1.POLL_INTERVAL_MS;
+    while (getResult.status === 'NOT_FOUND') {
+        if (++polls >= constants_1.MAX_POLL_ATTEMPTS) {
+            const msg = `Transaction ${sendResult.hash} not confirmed after ${constants_1.MAX_POLL_ATTEMPTS} poll attempts`;
+            core_1.Logger.log.error('submitStellarTransaction', msg, {
+                hash: sendResult.hash,
+                network,
+            });
+            throw new core_1.UpshiftTimeoutError(msg, constants_1.POLL_INTERVAL_MAX_MS * polls, {
+                context: { hash: sendResult.hash, network },
+            });
+        }
+        await new Promise((r) => setTimeout(r, nextDelay));
+        nextDelay = Math.min(Math.round(nextDelay * constants_1.POLL_INTERVAL_BACKOFF), constants_1.POLL_INTERVAL_MAX_MS);
+        getResult = await server.getTransaction(sendResult.hash);
+    }
+    if (getResult.status === 'SUCCESS') {
+        return sendResult.hash;
+    }
+    const resultXdr = 'resultXdr' in getResult ? getResult.resultXdr : undefined;
+    const resultCode = extractTxResultCode(resultXdr);
+    const detail = resultXdr ? safeStringify(resultXdr) : '';
+    const failDetail = detail ? ` (${detail})` : '';
+    const msg = `Transaction failed: ${getResult.status}${failDetail}`;
+    core_1.Logger.log.error('submitStellarTransaction', msg, {
+        hash: sendResult.hash,
+        network,
+        resultCode,
+    });
+    // A redemption that executed and failed is the strongest form of the signal
+    // the curator needs — and the only one carrying a hash the relay can verify
+    // on chain. Two gates, because a FAILED confirmation is not by itself a vault
+    // failure:
+    //   - `txFailed` is the only result code meaning the operations were applied
+    //     and one of them failed. Everything else at this layer is
+    //     transaction-level — `txBadSeq`, `txInsufficientBalance`,
+    //     `txTooLate`, resource-limit overruns — where the redeem never ran, and
+    //     which the caller resolves by retrying. An undecodable code is treated
+    //     the same way: without it we cannot tell the two apart, and silence
+    //     beats paging a curator over a sequence-number race.
+    //   - the envelope must actually be a redeem: this function is handed an
+    //     opaque XDR and would otherwise misattribute deposits.
+    const invocation = resultCode === 'txFailed' ? (0, invocation_1.describeVaultInvocation)(tx) : undefined;
+    // A partially-decoded envelope is not reported at all: an alert naming no
+    // wallet or no amount is one a curator cannot act on, and the reporting
+    // endpoint rejects it anyway.
+    const redeemer = invocation?.owner ?? invocation?.receiver;
+    if (invocation?.functionName === 'redeem' &&
+        redeemer &&
+        invocation.amountRaw) {
+        (0, curator_alert_1.reportRedeemFailure)({
+            phase: 'submission',
+            chain: 'stellar',
+            network,
+            contractId: invocation.contractId,
+            // `owner` is the account whose shares burn; `receiver` only receives the
+            // assets. They are the same for a self-redeem, and owner is the right one
+            // to name when they differ.
+            eoa: redeemer,
+            sharesRaw: invocation.amountRaw,
+            txHash: sendResult.hash,
+            resultCode,
+            error: msg,
+        });
+    }
+    throw new core_1.UpshiftSDKError('UNKNOWN', msg, {
+        context: {
+            hash: sendResult.hash,
+            network,
+            status: getResult.status,
+            resultCode,
+        },
+    });
+}
+//# sourceMappingURL=submit.js.map

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

@@ -0,0 +1,57 @@
+/**
+ * Stellar Vault Types
+ */
+import type { IStellarNetwork } from '../../types/web3';
+export type { IStellarNetwork };
+/** Parameters for building an unsigned Stellar vault deposit transaction. */
+export interface IStellarDepositParams {
+    contractId: string;
+    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 {
+    contractId: string;
+    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.
+ *
+ * `decimals` carries the share-token scale used to interpret `shares`. When the
+ * on-chain `decimals()` read fails, it falls back to STELLAR_FALLBACK_DECIMALS
+ * (7) and `decimalsFromFallback` is set to `true`. Callers that size a redeem
+ * from this position MUST check `decimalsFromFallback` and refuse to settle
+ * when it is `true` — trusting a fabricated 7 against an ERC4626 offset vault
+ * (share decimals = asset + offset) under-redeems by `10^offset`.
+ */
+export interface IStellarUserPosition {
+    /** Raw share balance in smallest unit, as a non-negative integer string */
+    shares: string;
+    /** Share-token decimals; may be the fallback — see `decimalsFromFallback`. */
+    decimals: number;
+    /**
+     * `true` when `decimals` is the fallback (the on-chain `decimals()` read
+     * failed), `false` when it is the authoritative on-chain value. Treat `true`
+     * as a decimals read failure: do not trust `decimals` to scale or redeem.
+     *
+     * Optional for source back-compat (a consumer's existing object literal still
+     * compiles), but `getStellarUserPosition` always populates it — so a position
+     * obtained from the SDK never omits it.
+     */
+    decimalsFromFallback?: boolean;
+}

package/lib/adapters/stellar/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Stellar Vault Types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Stellar Utilities
+ */
+import type { IStellarNetwork } from './types';
+import { isStellarAddress } from '../../core/helpers/chain-address';
+export { isStellarAddress };
+/**
+ * Get the Stellar explorer URL for a given address or transaction.
+ */
+export declare function getExplorerLink({ id, type, network, }: {
+    id: string;
+    type?: 'contract' | 'account' | 'tx';
+    network?: IStellarNetwork;
+}): string;
+/**
+ * Throw if the given address is a Stellar address.
+ * Used as a guard in vault operations that don't yet support Stellar.
+ */
+export declare function assertNotStellar(address: string, operation: string): void;
+export declare const StellarUtils: {
+    isStellarAddress: typeof isStellarAddress;
+    getExplorerLink: typeof getExplorerLink;
+    assertNotStellar: typeof assertNotStellar;
+};

package/lib/adapters/stellar/utils.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Stellar Utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StellarUtils = exports.isStellarAddress = void 0;
+exports.getExplorerLink = getExplorerLink;
+exports.assertNotStellar = assertNotStellar;
+const core_1 = require("../../core");
+const chain_address_1 = require("../../core/helpers/chain-address");
+Object.defineProperty(exports, "isStellarAddress", { enumerable: true, get: function () { return chain_address_1.isStellarAddress; } });
+/**
+ * Get the Stellar explorer URL for a given address or transaction.
+ */
+function getExplorerLink({ id, type = 'contract', network = 'mainnet', }) {
+    const baseUrl = 'https://stellar.expert/explorer';
+    const net = network === 'mainnet' ? 'public' : 'testnet';
+    return `${baseUrl}/${net}/${type}/${id}`;
+}
+/**
+ * Throw if the given address is a Stellar address.
+ * Used as a guard in vault operations that don't yet support Stellar.
+ */
+function assertNotStellar(address, operation) {
+    if ((0, chain_address_1.isStellarAddress)(address)) {
+        throw new core_1.UpshiftValidationError('INVALID_CHAIN', `${operation} is not yet supported for Stellar vaults: ${address}`);
+    }
+}
+exports.StellarUtils = {
+    isStellarAddress: chain_address_1.isStellarAddress,
+    getExplorerLink,
+    assertNotStellar,
+};
+//# sourceMappingURL=utils.js.map

package/lib/adapters/sui/client.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Sui gRPC client factory with endpoint failover.
+ *
+ * Sui removed JSON-RPC (Sui v1.82), so the SDK talks to fullnodes over gRPC.
+ * It uses gRPC-web — `@mysten/sui`'s `SuiGrpcClient` — so one code path works
+ * in browsers and Node.js.
+ *
+ * `@mysten/sui` is ESM-only and this SDK is published as CommonJS. The module
+ * is loaded on first use, not when the SDK is imported, so importing the SDK
+ * never requires it. That keeps Jest (which cannot `require` an ES module) and
+ * other CommonJS test runners working for integrators that never call Sui.
+ *
+ * @module SuiClient
+ */
+import type { SuiGrpcClient } from '@mysten/sui/grpc';
+import type { ISuiConfig, ISuiNetwork } from '../../types';
+/** Network and ordered endpoints for Sui calls: primary first, failover after. */
+export interface ISuiNetworkConfig {
+    network: ISuiNetwork;
+    /** gRPC-web endpoints in priority order. */
+    rpcUrls: readonly string[];
+}
+/**
+ * Resolve the network and ordered endpoints for a Sui config.
+ *
+ * A consumer `rpcUrl` becomes the primary, with the public fullnode kept behind
+ * it as failover, so a premium provider still degrades to the public network
+ * instead of becoming a single point of failure.
+ *
+ * @param config - The `sui` config passed to `new UpshiftSDK({ sui })`.
+ * @returns The network (`'mainnet'` by default) and its endpoints.
+ */
+export declare function resolveSuiNetworkConfig(config?: ISuiConfig): ISuiNetworkConfig;
+/**
+ * Host-only view of an endpoint, safe for logs and errors: keyed provider URLs
+ * carry their key in the path.
+ * @internal
+ */
+export declare function suiEndpointHost(url: string): string;
+/**
+ * Whether an error from a Sui call means the endpoint failed and the next one
+ * should be tried.
+ *
+ * @param err - What the call rejected with.
+ * @returns `true` for transport failures, gRPC statuses in
+ *   {@link RETRYABLE_GRPC_CODES}, a bare `NOT_FOUND` (the endpoint has no Sui
+ *   gRPC service at that path) and the SDK's own call timeout.
+ * @internal
+ */
+export declare function isRetryableSuiError(err: unknown): boolean;
+type SuiClientFactory = (baseUrl: string, network: ISuiNetwork) => Promise<SuiGrpcClient>;
+/**
+ * Replace the client factory and clear the caches. Test-only seam.
+ * @internal
+ */
+export declare function setSuiClientFactoryForTests(factory: SuiClientFactory | undefined): void;
+/**
+ * Run a Sui call against the first endpoint that answers.
+ *
+ * Endpoints are tried in order, starting with the one that last worked (for
+ * {@link PREFERRED_ENDPOINT_TTL_MS}). An endpoint failure — see
+ * {@link isRetryableSuiError} — moves on to the next endpoint; any other error
+ * is thrown at once. Each attempt is bounded by a 15 s timeout.
+ *
+ * Worst case: one attempt per endpoint (two with a consumer `rpcUrl`).
+ *
+ * @param config - Network and endpoints from {@link resolveSuiNetworkConfig}.
+ * @param call - The call to make with a client; it may run more than once, so
+ *   it must not have side effects before its RPC completes.
+ * @returns What `call` resolves to.
+ * @throws {@link UpshiftNetworkError} when every endpoint fails, naming their
+ *   hosts (never their full URLs); the last failure is the `cause`.
+ * @throws Whatever `call` throws for a non-endpoint error.
+ * @example
+ * ```ts
+ * const config = resolveSuiNetworkConfig({ network: 'testnet' });
+ * const { object } = await withSuiClient(config, (client) =>
+ *   client.core.getObject({ objectId: vaultId }),
+ * );
+ * ```
+ */
+export declare function withSuiClient<T>(config: ISuiNetworkConfig, call: (client: SuiGrpcClient) => Promise<T>): Promise<T>;
+export {};

package/lib/adapters/sui/client.js

@@ -0,0 +1,216 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSuiNetworkConfig = resolveSuiNetworkConfig;
+exports.suiEndpointHost = suiEndpointHost;
+exports.isRetryableSuiError = isRetryableSuiError;
+exports.setSuiClientFactoryForTests = setSuiClientFactoryForTests;
+exports.withSuiClient = withSuiClient;
+const logger_1 = require("../../core/logger");
+const errors_1 = require("../../core/errors");
+const concurrency_1 = require("../../core/helpers/concurrency");
+const constants_1 = require("./constants");
+/** Bound on one Sui call, so a hung endpoint fails over instead of blocking. */
+const SUI_CALL_TIMEOUT_MS = 15_000;
+/** How long a working endpoint is tried first before the order resets. */
+const PREFERRED_ENDPOINT_TTL_MS = 30_000;
+/**
+ * gRPC status codes that mean the endpoint, not the request, failed: the next
+ * endpoint may succeed. `fetch failed` (refused connection, DNS) arrives as
+ * `INTERNAL`; a provider that does not serve gRPC-web answers `UNAUTHENTICATED`
+ * or similar. Request errors such as `INVALID_ARGUMENT` would fail the same way
+ * everywhere, so they are thrown at once.
+ */
+const RETRYABLE_GRPC_CODES = new Set([
+    'INTERNAL',
+    'UNAVAILABLE',
+    'UNKNOWN',
+    'DEADLINE_EXCEEDED',
+    'RESOURCE_EXHAUSTED',
+    'UNAUTHENTICATED',
+    'PERMISSION_DENIED',
+    'UNIMPLEMENTED',
+]);
+/**
+ * Resolve the network and ordered endpoints for a Sui config.
+ *
+ * A consumer `rpcUrl` becomes the primary, with the public fullnode kept behind
+ * it as failover, so a premium provider still degrades to the public network
+ * instead of becoming a single point of failure.
+ *
+ * @param config - The `sui` config passed to `new UpshiftSDK({ sui })`.
+ * @returns The network (`'mainnet'` by default) and its endpoints.
+ */
+function resolveSuiNetworkConfig(config = {}) {
+    const network = config.network ?? 'mainnet';
+    const publicUrl = constants_1.SUI_GRPC_URLS[network];
+    const override = config.rpcUrl?.trim();
+    const rpcUrls = override && override !== publicUrl ? [override, publicUrl] : [publicUrl];
+    return { network, rpcUrls };
+}
+/**
+ * Host-only view of an endpoint, safe for logs and errors: keyed provider URLs
+ * carry their key in the path.
+ * @internal
+ */
+function suiEndpointHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return '<invalid url>';
+    }
+}
+/**
+ * Whether an error from a Sui call means the endpoint failed and the next one
+ * should be tried.
+ *
+ * @param err - What the call rejected with.
+ * @returns `true` for transport failures, gRPC statuses in
+ *   {@link RETRYABLE_GRPC_CODES}, a bare `NOT_FOUND` (the endpoint has no Sui
+ *   gRPC service at that path) and the SDK's own call timeout.
+ * @internal
+ */
+function isRetryableSuiError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.message.startsWith('sui call timed out'))
+        return true;
+    if (err.name !== 'RpcError')
+        return false;
+    const code = err.code;
+    if (typeof code !== 'string')
+        return false;
+    if (RETRYABLE_GRPC_CODES.has(code))
+        return true;
+    // A path with no gRPC service answers HTTP 404, which the transport reports
+    // as NOT_FOUND with no message; a missing object is a different error type.
+    return code === 'NOT_FOUND' && err.message === '';
+}
+/** Default factory: loads `@mysten/sui/grpc` on first use. */
+const defaultClientFactory = async (baseUrl, network) => {
+    const { SuiGrpcClient } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/grpc')));
+    return new SuiGrpcClient({ baseUrl, network });
+};
+let clientFactory = defaultClientFactory;
+const clientCache = new Map();
+const preferredEndpoint = new Map();
+/**
+ * Replace the client factory and clear the caches. Test-only seam.
+ * @internal
+ */
+function setSuiClientFactoryForTests(factory) {
+    clientFactory = factory ?? defaultClientFactory;
+    clientCache.clear();
+    preferredEndpoint.clear();
+}
+function clientFor(url, network) {
+    const key = `${network}|${url}`;
+    let client = clientCache.get(key);
+    if (!client) {
+        client = clientFactory(url, network);
+        clientCache.set(key, client);
+        // A failed construction must not be cached forever.
+        client.catch(() => clientCache.delete(key));
+    }
+    return client;
+}
+/**
+ * Run a Sui call against the first endpoint that answers.
+ *
+ * Endpoints are tried in order, starting with the one that last worked (for
+ * {@link PREFERRED_ENDPOINT_TTL_MS}). An endpoint failure — see
+ * {@link isRetryableSuiError} — moves on to the next endpoint; any other error
+ * is thrown at once. Each attempt is bounded by a 15 s timeout.
+ *
+ * Worst case: one attempt per endpoint (two with a consumer `rpcUrl`).
+ *
+ * @param config - Network and endpoints from {@link resolveSuiNetworkConfig}.
+ * @param call - The call to make with a client; it may run more than once, so
+ *   it must not have side effects before its RPC completes.
+ * @returns What `call` resolves to.
+ * @throws {@link UpshiftNetworkError} when every endpoint fails, naming their
+ *   hosts (never their full URLs); the last failure is the `cause`.
+ * @throws Whatever `call` throws for a non-endpoint error.
+ * @example
+ * ```ts
+ * const config = resolveSuiNetworkConfig({ network: 'testnet' });
+ * const { object } = await withSuiClient(config, (client) =>
+ *   client.core.getObject({ objectId: vaultId }),
+ * );
+ * ```
+ */
+async function withSuiClient(config, call) {
+    const cacheKey = `${config.network}|${config.rpcUrls.join('|')}`;
+    const preferred = preferredEndpoint.get(cacheKey);
+    const order = preferred && Date.now() - preferred.at < PREFERRED_ENDPOINT_TTL_MS
+        ? [preferred.url, ...config.rpcUrls.filter((u) => u !== preferred.url)]
+        : [...config.rpcUrls];
+    let lastError;
+    for (const url of order) {
+        let client;
+        try {
+            client = await clientFor(url, config.network);
+        }
+        catch (err) {
+            // A malformed endpoint (e.g. a typo'd consumer rpcUrl) must not disable
+            // the endpoints behind it.
+            lastError = err;
+            logger_1.Logger.log.warn('withSuiClient', 'Invalid Sui endpoint; trying next', {
+                host: suiEndpointHost(url),
+            });
+            continue;
+        }
+        try {
+            const result = await (0, concurrency_1.withTimeout)(call(client), SUI_CALL_TIMEOUT_MS, 'sui call');
+            preferredEndpoint.set(cacheKey, { url, at: Date.now() });
+            return result;
+        }
+        catch (err) {
+            if (!isRetryableSuiError(err))
+                throw err;
+            lastError = err;
+            logger_1.Logger.log.warn('withSuiClient', 'Sui endpoint failed; trying next', {
+                host: suiEndpointHost(url),
+                code: err.code,
+            });
+        }
+    }
+    preferredEndpoint.delete(cacheKey);
+    throw new errors_1.UpshiftNetworkError(`Every Sui ${config.network} endpoint failed: ${order
+        .map(suiEndpointHost)
+        .join(', ')}`, { cause: lastError, context: { network: config.network } });
+}
+//# sourceMappingURL=client.js.map

package/lib/adapters/sui/constants.d.ts

@@ -0,0 +1,33 @@
+import type { ISuiNetwork } from '../../types';
+export { SUI_CHAIN_ID } from '../../core/constants/web3';
+/** Sui's shared `Clock` system object, passed to time-dependent vault calls. */
+export declare const SUI_CLOCK_ID = "0x6";
+/** Sui's shared `CoinRegistry` system object (coin metadata / currencies). */
+export declare const SUI_COIN_REGISTRY_ID = "0xc";
+/**
+ * Mysten's public fullnodes, which serve gRPC-web. The SDK talks gRPC-web so
+ * the same code runs in browsers; a consumer `rpcUrl` goes in front of these as
+ * the primary (see `resolveSuiNetworkConfig`).
+ */
+export declare const SUI_GRPC_URLS: Record<ISuiNetwork, string>;
+/**
+ * IDs of the deployed Upshift vault contracts on one Sui network.
+ *
+ * `packageId` is the latest published package (what move calls target);
+ * `originalPackageId` is the first published one, which Move keeps in type
+ * names across upgrades, so it names the vault's on-chain type.
+ */
+export interface ISuiVaultContracts {
+    /** Latest `upshift_vault` package ID; move-call targets use it. */
+    packageId: string;
+    /** Original `upshift_vault` package ID; vault and key types use it. */
+    originalPackageId: string;
+    /** Shared `upshift_vault::registry::Registry` object ID. */
+    registryId: string;
+}
+/**
+ * Built-in contract IDs per network. Empty until the contracts are published
+ * there: until then callers pass `packageId`, `originalPackageId` and
+ * `registryId` through `new UpshiftSDK({ sui })`.
+ */
+export declare const SUI_VAULT_CONTRACTS: Record<ISuiNetwork, Partial<ISuiVaultContracts>>;