@upshiftfinance/sdk 0.0.0-stage → 0.1.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/constants.d.ts

@@ -0,0 +1 @@
+export { SUI_CHAIN_ID } from '../../core/constants/web3';

package/lib/adapters/sui/constants.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUI_CHAIN_ID = void 0;
+// Canonical definition lives in `core/constants/web3.ts` so `core/` can
+// recognise the Sui chain ID without importing the adapter layer. Re-exported
+// here to keep `adapters/sui/constants` import sites unchanged.
+var web3_1 = require("../../core/constants/web3");
+Object.defineProperty(exports, "SUI_CHAIN_ID", { enumerable: true, get: function () { return web3_1.SUI_CHAIN_ID; } });
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,24 @@
+import type { IEmberVault, IFetchEmberVaultsOptions } from './types';
+/**
+ * Fetch Ember vaults from API.
+ *
+ * Results are cached for {@link EMBER_CACHE_TTL_MS} (keyed by the full request
+ * URL, so different query options cache independently) and the request is
+ * aborted after {@link EMBER_FETCH_TIMEOUT_MS}. Failures — including timeouts —
+ * are never cached and resolve to `[]`, preserving the long-standing
+ * fail-tolerant contract of this getter.
+ */
+export declare function getEmberVaults(options?: IFetchEmberVaultsOptions): Promise<IEmberVault[]>;
+/**
+ * Fetch the latest Ember TVL (in whole units, i.e. `tvlE9 / 1e9`).
+ *
+ * Shares the timeout and cache of {@link getEmberVaults} via
+ * {@link fetchEmberArray}: the TVL history payload is cached for
+ * {@link EMBER_CACHE_TTL_MS} per `limit`, and a hung request is aborted after
+ * {@link EMBER_FETCH_TIMEOUT_MS}. Failures — including timeouts — are never
+ * cached and resolve to `0`.
+ *
+ * @param limit - Number of history rows to request; only the newest is read.
+ * @returns The latest TVL, or `0` when unavailable.
+ */
+export declare function getEmberTVL(limit?: number): Promise<number>;

package/lib/adapters/sui/getters.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEmberVaults = getEmberVaults;
+exports.getEmberTVL = getEmberTVL;
+const constants_1 = require("./constants");
+const core_1 = require("../../core");
+const cache_1 = require("../../core/cache");
+const logger_1 = require("../../core/logger");
+/**
+ * Hard ceiling on the Ember (Bluefin) vaults request. The endpoint is a
+ * third-party API awaited on the `getVaults` hot path; without a bound, a
+ * hung connection stalls every vault-list consumer indefinitely (the fetch
+ * options carry no signal and no timeout). Measured latency is 0.24–1.02s,
+ * so 5s is ~5× the observed worst case while still failing fast enough for
+ * callers racing `getVaults` against their own budgets.
+ */
+const EMBER_FETCH_TIMEOUT_MS = 5_000;
+/**
+ * TTL for the cached Ember vaults payload. The set of active Ember vaults
+ * changes rarely (the SDK additionally filters it to a hardcoded allowlist),
+ * so 5 minutes matches the freshness of the other list-shaped caches without
+ * letting a stale payload outlive a delisting for long.
+ */
+const EMBER_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * GET an Ember endpoint as a JSON array, with the timeout + cache both Ember
+ * getters share.
+ *
+ * Why: `getEmberVaults` and `getEmberTVL` hit the same third-party API from
+ * the same hot paths, but only the former was bounded and cached — a hung TVL
+ * request stalled callers indefinitely. Centralising the plumbing keeps the
+ * two from drifting again.
+ *
+ * - Cached for {@link EMBER_CACHE_TTL_MS}, keyed by `cacheKey` (callers embed
+ *   the full URL so different query options cache independently). Only
+ *   successful array payloads are cached; failures are never cached.
+ * - Aborted after {@link EMBER_FETCH_TIMEOUT_MS}. AbortController (not
+ *   AbortSignal.timeout) for browser + older-Node parity. The timer stays armed
+ *   through the body read: `fetch` resolves as soon as headers arrive, so
+ *   clearing it there would leave a stalled `json()` unbounded — the exact
+ *   hang the ceiling exists to prevent.
+ *
+ * @param cacheKey - Shared-LRU key for this request.
+ * @param url - Fully-qualified Ember URL (query string included).
+ * @returns The parsed array, or `[]` when the endpoint returns a non-array.
+ * @throws On non-2xx responses, network failure, or timeout (AbortError) —
+ *   callers own the fail-tolerant fallback.
+ */
+async function fetchEmberArray(cacheKey, url) {
+    // The shared LRU is constructed with `allowStale: true`; opt out here so a
+    // payload past its TTL is refetched rather than served one last time —
+    // keeping the 5-minute bound above an exact contract.
+    const cached = cache_1.CACHE.get(cacheKey, { allowStale: false });
+    if (cached)
+        return cached;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), EMBER_FETCH_TIMEOUT_MS);
+    let data;
+    try {
+        const response = await fetch(url, {
+            ...core_1.DEFAULT_FETCH_OPTIONS,
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        data = await response.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const rows = Array.isArray(data) ? data : [];
+    cache_1.CACHE.set(cacheKey, rows, { ttl: EMBER_CACHE_TTL_MS });
+    return rows;
+}
+/**
+ * Fetch Ember vaults from API.
+ *
+ * Results are cached for {@link EMBER_CACHE_TTL_MS} (keyed by the full request
+ * URL, so different query options cache independently) and the request is
+ * aborted after {@link EMBER_FETCH_TIMEOUT_MS}. Failures — including timeouts —
+ * are never cached and resolve to `[]`, preserving the long-standing
+ * fail-tolerant contract of this getter.
+ */
+async function getEmberVaults(options) {
+    try {
+        const params = new URLSearchParams();
+        if (options?.limit)
+            params.append('limit', options.limit.toString());
+        if (options?.offset)
+            params.append('offset', options.offset.toString());
+        if (options?.status)
+            params.append('status', options.status);
+        const queryString = params.toString();
+        const url = `${constants_1.EMBER_API_BASE_URL}${queryString ? `?${queryString}` : ''}`;
+        return await fetchEmberArray(`ember-vaults-${url}`, url);
+    }
+    catch (error) {
+        logger_1.Logger.log.error('getEmberVaults', error);
+        return [];
+    }
+}
+/**
+ * Fetch the latest Ember TVL (in whole units, i.e. `tvlE9 / 1e9`).
+ *
+ * Shares the timeout and cache of {@link getEmberVaults} via
+ * {@link fetchEmberArray}: the TVL history payload is cached for
+ * {@link EMBER_CACHE_TTL_MS} per `limit`, and a hung request is aborted after
+ * {@link EMBER_FETCH_TIMEOUT_MS}. Failures — including timeouts — are never
+ * cached and resolve to `0`.
+ *
+ * @param limit - Number of history rows to request; only the newest is read.
+ * @returns The latest TVL, or `0` when unavailable.
+ */
+async function getEmberTVL(limit = 1) {
+    try {
+        const params = new URLSearchParams();
+        if (limit)
+            params.append('limit', limit.toString());
+        const queryString = params.toString();
+        const url = `${constants_1.EMBER_API_BASE_URL}${constants_1.EMBER_ENDPOINTS.TVL}${queryString ? `?${queryString}` : ''}`;
+        const result = await fetchEmberArray(`ember-tvl-${url}`, url);
+        if (result.length > 0) {
+            const latestEntry = result[0];
+            return Number(latestEntry.tvlE9) / constants_1.EMBER_DEFAULTS.E9_DIVISOR;
+        }
+        return 0;
+    }
+    catch (error) {
+        logger_1.Logger.log.error('getEmberTVL', error);
+        return 0;
+    }
+}
+//# sourceMappingURL=getters.js.map

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

@@ -0,0 +1,53 @@
+/**
+ * Sui Adapter for Upshift SDK
+ *
+ * @module SuiAdapter
+ */
+import type { ISuiConfig, ISuiNetwork } from '../../types';
+import * as SuiConstants from './constants';
+import * as SuiUtils from './utils';
+export declare const Sui: {
+    utils: typeof SuiUtils;
+    constants: typeof SuiConstants;
+};
+/**
+ * Sui Adapter for Upshift SDK.
+ *
+ * Holds the Sui configuration passed to `new UpshiftSDK({ sui })` and the Sui
+ * chain-identity helpers. It makes no network calls.
+ *
+ * @example
+ * ```ts
+ * const sdk = new UpshiftSDK({ appName: 'my-app', sui: { network: 'testnet' } });
+ * sdk.sui.network; // 'testnet'
+ * sdk.sui.isSuiAddress(vault.address);
+ * ```
+ */
+declare class SuiAdapter {
+    private readonly _config;
+    /**
+     * @param config - Optional Sui settings; omit to target Sui mainnet.
+     */
+    constructor(config?: ISuiConfig);
+    /** The SDK's Sui chain ID, `-2` (same as the backend's `chain` for Sui vaults). */
+    get chainId(): number;
+    /** Configured Sui network; `'mainnet'` unless the SDK was built with another. */
+    get network(): ISuiNetwork;
+    /** Configured RPC endpoint override, or `undefined` when none was given. */
+    get rpcUrl(): string | undefined;
+    /**
+     * Check whether a string is a Sui address or object ID (`0x` + 64 hex chars).
+     *
+     * @param address - Candidate address.
+     * @returns `true` for the long, 64-hex-digit form only.
+     */
+    isSuiAddress(address: string): boolean;
+    /**
+     * Check whether a chain ID is Sui's (`-2`).
+     *
+     * @param chainId - Numeric chain ID, e.g. a backend vault row's `chain`.
+     * @returns `true` only for `-2`.
+     */
+    isSuiVault(chainId: number): boolean;
+}
+export default SuiAdapter;

package/lib/adapters/sui/index.js

@@ -0,0 +1,96 @@
+"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.Sui = void 0;
+const SuiConstants = __importStar(require("./constants"));
+const SuiUtils = __importStar(require("./utils"));
+exports.Sui = {
+    utils: SuiUtils,
+    constants: SuiConstants,
+};
+/**
+ * Sui Adapter for Upshift SDK.
+ *
+ * Holds the Sui configuration passed to `new UpshiftSDK({ sui })` and the Sui
+ * chain-identity helpers. It makes no network calls.
+ *
+ * @example
+ * ```ts
+ * const sdk = new UpshiftSDK({ appName: 'my-app', sui: { network: 'testnet' } });
+ * sdk.sui.network; // 'testnet'
+ * sdk.sui.isSuiAddress(vault.address);
+ * ```
+ */
+class SuiAdapter {
+    _config;
+    /**
+     * @param config - Optional Sui settings; omit to target Sui mainnet.
+     */
+    constructor(config = {}) {
+        this._config = { ...config };
+    }
+    /** The SDK's Sui chain ID, `-2` (same as the backend's `chain` for Sui vaults). */
+    get chainId() {
+        return SuiConstants.SUI_CHAIN_ID;
+    }
+    /** Configured Sui network; `'mainnet'` unless the SDK was built with another. */
+    get network() {
+        return this._config.network ?? 'mainnet';
+    }
+    /** Configured RPC endpoint override, or `undefined` when none was given. */
+    get rpcUrl() {
+        return this._config.rpcUrl;
+    }
+    /**
+     * Check whether a string is a Sui address or object ID (`0x` + 64 hex chars).
+     *
+     * @param address - Candidate address.
+     * @returns `true` for the long, 64-hex-digit form only.
+     */
+    isSuiAddress(address) {
+        return SuiUtils.isSuiAddress(address);
+    }
+    /**
+     * Check whether a chain ID is Sui's (`-2`).
+     *
+     * @param chainId - Numeric chain ID, e.g. a backend vault row's `chain`.
+     * @returns `true` only for `-2`.
+     */
+    isSuiVault(chainId) {
+        return SuiUtils.isSuiVault(chainId);
+    }
+}
+exports.default = SuiAdapter;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,10 @@
+import type { IVault } from '../../types';
+import type { IEmberVault } from './types';
+/**
+ * Transform Ember vault to IVault format
+ */
+export declare function transformEmberVaultToIVault(emberVault: IEmberVault): IVault;
+/**
+ * Transform multiple Ember vaults
+ */
+export declare function transformEmberVaultsToIVaults(emberVaults: IEmberVault[]): IVault[];