@upshiftfinance/sdk 0.3.0 → 0.4.0

package/lib/adapters/sui/actions.js

@@ -0,0 +1,382 @@
+"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.suiExecutionErrorToSdkError = suiExecutionErrorToSdkError;
+exports.buildSuiDepositTransaction = buildSuiDepositTransaction;
+exports.buildSuiRedeemTransaction = buildSuiRedeemTransaction;
+exports.submitSuiTransaction = submitSuiTransaction;
+const errors_1 = require("../../core/errors");
+const chain_address_1 = require("../../core/helpers/chain-address");
+const curator_alert_1 = require("../../core/logger/curator-alert");
+const client_1 = require("./client");
+const constants_1 = require("./constants");
+const getters_1 = require("./getters");
+const targets_1 = require("./targets");
+const U64_MAX = 2n ** 64n - 1n;
+/** Contract errors with a stable SDK reason, keyed `module::constant`. */
+const ABORT_REASONS = {
+    'vault::EPaused': 'paused',
+    'vault::EBelowMinDeposit': 'below_min_deposit',
+    'vault::EAboveMaxDeposit': 'above_max_deposit',
+    'vault::EDepositCapExceeded': 'deposit_cap_exceeded',
+    'vault::EAboveMaxWithdrawal': 'above_max_withdrawal',
+    'vault::EInsufficientLiquidity': 'insufficient_liquidity',
+    'vault::EQueueAttached': 'queue_attached',
+    'vault::ESlippageExceeded': 'slippage',
+    'vault::EZeroShares': 'zero_output',
+    'vault::EZeroAssets': 'zero_output',
+    'versioning::EVersionRetired': 'version_retired',
+};
+/**
+ * Map a failed Sui execution to an SDK error: a contract abort becomes an
+ * {@link UpshiftVaultAbortError} with a stable reason, anything else an
+ * {@link UpshiftSDKError} (`UNKNOWN`).
+ *
+ * @param executionError - `effects.status.error` of a failed transaction, or
+ *   the `executionError` of a `SimulationError`.
+ * @param context - Structured context for the error (e.g. network, digest).
+ * @internal
+ */
+function suiExecutionErrorToSdkError(executionError, context = {}) {
+    const abort = executionError?.MoveAbort;
+    if (abort) {
+        const module = abort.location?.module;
+        const constant = abort.cleverError?.constantName;
+        const reason = ABORT_REASONS[`${module}::${constant}`] ?? 'other';
+        return new errors_1.UpshiftVaultAbortError(reason, `Sui vault rejected the transaction: ${reason}${constant ? ` (${module}::${constant})` : ` (abort ${abort.abortCode})`}.`, { module, constant }, { context: { ...context, abortCode: abort.abortCode } });
+    }
+    return new errors_1.UpshiftSDKError('UNKNOWN', `Sui transaction failed: ${executionError?.message ?? 'unknown error'}`, { context });
+}
+function assertSender(sender, method) {
+    if (!(0, chain_address_1.isSuiAddress)(sender)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: sender must be a Sui address (0x + 64 hex chars).`);
+    }
+}
+function assertAmount(value, method, name, positive) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'bigint' ||
+        value < (positive ? 1n : 0n) ||
+        value > U64_MAX) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: ${name} must be a bigint between ${positive ? 1 : 0} and 2^64 - 1.`);
+    }
+}
+/** Move-call helper bound to one vault and its contracts. */
+function vaultCalls(tx, ref, contracts) {
+    const typeArguments = (0, targets_1.suiVaultTypeArguments)(ref.assetCoinType, ref.shareCoinType);
+    return (target, args) => tx.moveCall({
+        target: (0, targets_1.suiMoveCallTarget)(contracts, target),
+        typeArguments,
+        arguments: [
+            tx.object(ref.vaultId),
+            tx.object(contracts.registryId),
+            ...args,
+        ],
+    });
+}
+/**
+ * Dry-run `tx` against the network and return each command's return values.
+ * An abort, at build (gas estimation) or in the simulation, becomes a typed
+ * SDK error; `onAbort` sees it first.
+ */
+async function dryRun(config, build, method, onAbort) {
+    const context = { network: config.network, method };
+    try {
+        return await (0, client_1.withSuiClient)((0, client_1.resolveSuiNetworkConfig)(config), async (client) => {
+            const result = await client.core.simulateTransaction({
+                transaction: await build(),
+                include: { commandResults: true, effects: true },
+            });
+            if (result.$kind !== 'Transaction') {
+                throw suiExecutionErrorToSdkError(result.FailedTransaction.effects?.status.error ?? undefined, context);
+            }
+            return result.commandResults.map((c) => c.returnValues.map((v) => v.bcs));
+        });
+    }
+    catch (err) {
+        const sdkError = err instanceof errors_1.UpshiftSDKError
+            ? err
+            : err?.executionError
+                ? suiExecutionErrorToSdkError(err.executionError, context)
+                : new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: could not build the transaction: ${err instanceof Error ? err.message : String(err)}`, { cause: err, context });
+        if (sdkError instanceof errors_1.UpshiftVaultAbortError)
+            onAbort?.(sdkError);
+        throw sdkError;
+    }
+}
+/**
+ * Build an unsigned deposit: charge the management fee, deposit with a minimum
+ * share amount, and send the shares to the sender — one transaction.
+ *
+ * The payment is `coinWithBalance(Asset)`: the wallet selects and merges the
+ * sender's coins when it signs. The fee is charged first so the deposit is
+ * priced on a current NAV.
+ *
+ * RPC cost: one dry run (plus the coin lookup it needs).
+ *
+ * @param params - Vault, amount, sender and optional minimum shares.
+ * @param sui - The SDK's `sui` config; applied only for `params.vault.network`.
+ * @returns The unsigned transaction, the shares the dry run minted and the
+ *   minimum it enforces.
+ * @throws {@link UpshiftValidationError} for a malformed sender or vault, an
+ *   out-of-range amount, unknown contract IDs, or a transaction that cannot be
+ *   built (e.g. the sender lacks the asset).
+ * @throws {@link UpshiftVaultAbortError} when the vault would reject the
+ *   deposit (`paused`, `below_min_deposit`, `above_max_deposit`,
+ *   `deposit_cap_exceeded`, `zero_output`, `slippage`, `version_retired`).
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ * @example
+ * ```ts
+ * const { transaction } = await buildSuiDepositTransaction(
+ *   { vault: ref, amount: 1_000_000n, sender: account.address },
+ *   sdkSuiConfig,
+ * );
+ * const { digest } = await dAppKit.signAndExecuteTransaction({ transaction });
+ * ```
+ */
+async function buildSuiDepositTransaction(params, sui) {
+    const method = 'buildSuiDepositTransaction';
+    const { vault: ref, amount, sender, minSharesOut } = params;
+    assertSender(sender, method);
+    if (!(0, chain_address_1.isSuiAddress)(ref?.vaultId)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: vault.vaultId must be a Sui object ID.`);
+    }
+    assertAmount(amount, method, 'amount', true);
+    assertAmount(minSharesOut, method, 'minSharesOut', false);
+    const config = (0, getters_1.suiConfigForNetwork)(ref.network, sui);
+    const contracts = (0, targets_1.resolveSuiVaultContracts)(config);
+    const { Transaction: SuiTransaction, coinWithBalance } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/transactions')));
+    const compose = (min, withPreview) => {
+        const tx = new SuiTransaction();
+        tx.setSender(sender);
+        const call = vaultCalls(tx, ref, contracts);
+        call('chargeManagementFee', [tx.object(constants_1.SUI_CLOCK_ID)]);
+        if (withPreview)
+            call('previewDeposit', [tx.pure.u64(amount)]);
+        const payment = tx.add(coinWithBalance({ type: ref.assetCoinType, balance: amount }));
+        const shares = call('depositChecked', [payment, tx.pure.u64(min)]);
+        tx.transferObjects([shares], sender);
+        return tx;
+    };
+    // The preview runs after the fee charge, so it matches the deposit exactly.
+    const results = await dryRun(config, async () => compose(0n, true), method);
+    const expectedShares = (0, getters_1.decodeSuiUint)(results[1][0], 8);
+    const min = minSharesOut ?? expectedShares;
+    return {
+        transaction: compose(min, false),
+        expectedShares,
+        minSharesOut: min,
+    };
+}
+/**
+ * Build an unsigned instant redemption: redeem shares with a minimum net
+ * asset amount and send the assets to the sender — one transaction.
+ *
+ * The shares are `coinWithBalance(Share)`. A vault with a withdrawal queue
+ * attached has instant redemption off; that fails here with `queue_attached`.
+ *
+ * Side effect on failure: when the vault rejects the dry run, the failure is
+ * reported to that vault's curator (fire-and-forget; see
+ * `monitoring.curatorAlerts`).
+ *
+ * RPC cost: one dry run (plus the coin lookup it needs).
+ *
+ * @param params - Vault, shares, sender and optional minimum assets.
+ * @param sui - The SDK's `sui` config; applied only for `params.vault.network`.
+ * @returns The unsigned transaction, the dry run's gross and net assets and
+ *   the minimum it enforces.
+ * @throws {@link UpshiftValidationError} for a malformed sender or vault, an
+ *   out-of-range amount, unknown contract IDs, or a transaction that cannot be
+ *   built (e.g. the sender lacks the shares).
+ * @throws {@link UpshiftVaultAbortError} when the vault would reject the
+ *   redemption (`queue_attached`, `paused`, `above_max_withdrawal`,
+ *   `insufficient_liquidity`, `zero_output`, `slippage`, `version_retired`).
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+async function buildSuiRedeemTransaction(params, sui) {
+    const method = 'buildSuiRedeemTransaction';
+    const { vault: ref, shares, sender, minAssetsOut } = params;
+    assertSender(sender, method);
+    if (!(0, chain_address_1.isSuiAddress)(ref?.vaultId)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: vault.vaultId must be a Sui object ID.`);
+    }
+    assertAmount(shares, method, 'shares', true);
+    assertAmount(minAssetsOut, method, 'minAssetsOut', false);
+    const config = (0, getters_1.suiConfigForNetwork)(ref.network, sui);
+    const contracts = (0, targets_1.resolveSuiVaultContracts)(config);
+    const { Transaction: SuiTransaction, coinWithBalance } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/transactions')));
+    const compose = (min, withPreview) => {
+        const tx = new SuiTransaction();
+        tx.setSender(sender);
+        const call = vaultCalls(tx, ref, contracts);
+        if (withPreview) {
+            call('previewRedemption', [tx.pure.u64(shares), tx.pure.bool(true)]);
+        }
+        const payment = tx.add(coinWithBalance({ type: ref.shareCoinType, balance: shares }));
+        const assets = call('redeemChecked', [payment, tx.pure.u64(min)]);
+        tx.transferObjects([assets], sender);
+        return tx;
+    };
+    const results = await dryRun(config, async () => compose(0n, true), method, (err) => (0, curator_alert_1.reportRedeemFailure)({
+        phase: 'simulation',
+        chain: 'sui',
+        network: ref.network,
+        contractId: ref.vaultId,
+        eoa: sender,
+        sharesRaw: shares.toString(),
+        error: err.message,
+    }));
+    const expectedGrossAssets = (0, getters_1.decodeSuiUint)(results[0][0], 8);
+    const expectedAssets = (0, getters_1.decodeSuiUint)(results[0][1], 8);
+    const min = minAssetsOut ?? expectedAssets;
+    return {
+        transaction: compose(min, false),
+        expectedGrossAssets,
+        expectedAssets,
+        minAssetsOut: min,
+    };
+}
+/**
+ * The vault, sender and share amount of an instant redemption in a built
+ * transaction, for the curator alert; `null` when it is not one.
+ */
+function redemptionOf(data, fromBase64) {
+    for (const command of data.commands) {
+        const call = command.MoveCall;
+        if (call?.module !== 'coin_entry' || call.function !== 'redeem_checked')
+            continue;
+        const vaultArg = call.arguments[0];
+        const vaultInput = vaultArg?.$kind === 'Input' ? data.inputs[vaultArg.Input] : undefined;
+        const vaultId = vaultInput?.Object?.SharedObject?.objectId;
+        if (!vaultId)
+            return null;
+        // The shares are usually split off the sender's coins; read that amount.
+        let sharesRaw = '0';
+        const coinArg = call.arguments[2];
+        const source = coinArg?.$kind === 'NestedResult' || coinArg?.$kind === 'Result'
+            ? data.commands[coinArg.$kind === 'Result'
+                ? coinArg.Result
+                : coinArg.NestedResult[0]]
+            : undefined;
+        const amountArg = source?.SplitCoins?.amounts[0];
+        const amountInput = amountArg?.$kind === 'Input' ? data.inputs[amountArg.Input] : undefined;
+        const bytes = amountInput?.Pure?.bytes;
+        if (bytes) {
+            const raw = fromBase64(bytes);
+            if (raw.length === 8)
+                sharesRaw = (0, getters_1.decodeSuiUint)(raw, 8).toString();
+        }
+        return { vaultId, sharesRaw };
+    }
+    return null;
+}
+/**
+ * Execute a signed transaction and wait until the network has indexed it.
+ *
+ * Side effect on failure: a failed instant redemption is reported to that
+ * vault's curator with its digest (fire-and-forget; see
+ * `monitoring.curatorAlerts`).
+ *
+ * RPC cost: one execution plus the confirmation poll.
+ *
+ * @param signed - Bytes and signature from the wallet's `signTransaction`.
+ * @param network - Network the transaction was built for.
+ * @param sui - The SDK's `sui` config; applied only for `network`.
+ * @returns The transaction digest once it succeeded and is indexed.
+ * @throws {@link UpshiftVaultAbortError} when the vault aborted it on chain.
+ * @throws {@link UpshiftSDKError} (`UNKNOWN`) when it failed for another
+ *   reason; `context.digest` names it.
+ * @throws {@link UpshiftTransactionError} when it executed but was not
+ *   indexed in time; check `signature` (the digest) before retrying.
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+async function submitSuiTransaction(signed, network, sui) {
+    if (typeof signed?.bytes !== 'string' ||
+        typeof signed.signature !== 'string') {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', 'submitSuiTransaction: pass { bytes, signature } from the wallet, both base64.');
+    }
+    const config = (0, getters_1.suiConfigForNetwork)(network, sui);
+    const networkConfig = (0, client_1.resolveSuiNetworkConfig)(config);
+    const { Transaction: SuiTransaction } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/transactions')));
+    const { fromBase64 } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/utils')));
+    const bytes = fromBase64(signed.bytes);
+    // Executing the same signed bytes twice is idempotent, so endpoint failover is safe.
+    const result = await (0, client_1.withSuiClient)(networkConfig, (client) => client.core.executeTransaction({
+        transaction: bytes,
+        signatures: [signed.signature],
+        include: { effects: true },
+    })).catch((err) => {
+        if (err instanceof errors_1.UpshiftSDKError)
+            throw err;
+        // The node refused it before execution: a bad signature, or inputs that
+        // changed since signing (rebuild and sign again).
+        throw new errors_1.UpshiftSDKError('UNKNOWN', `submitSuiTransaction: the network rejected the transaction: ${err instanceof Error ? err.message : String(err)}`, { cause: err, context: { network } });
+    });
+    if (result.$kind !== 'Transaction') {
+        const failed = result.FailedTransaction;
+        const digest = failed.digest;
+        const error = suiExecutionErrorToSdkError(failed.effects?.status.error ?? undefined, { network, digest });
+        // Gas was still spent: wait (best effort) until the failure is indexed, so
+        // a retry built right after this sees the sender's new coin versions.
+        await (0, client_1.withSuiClient)(networkConfig, (client) => client.core.waitForTransaction({ result, timeout: 12_000 })).catch(() => undefined);
+        const data = SuiTransaction.from(bytes).getData();
+        const redemption = redemptionOf(data, fromBase64);
+        if (redemption && data.sender) {
+            (0, curator_alert_1.reportRedeemFailure)({
+                phase: 'submission',
+                chain: 'sui',
+                network,
+                contractId: redemption.vaultId,
+                eoa: data.sender,
+                sharesRaw: redemption.sharesRaw,
+                txHash: digest,
+                error: error.message,
+            });
+        }
+        throw error;
+    }
+    const digest = result.Transaction.digest;
+    try {
+        await (0, client_1.withSuiClient)(networkConfig, (client) => 
+        // Under the client's 15 s per-call bound, so a slow index is not mistaken
+        // for a dead endpoint.
+        client.core.waitForTransaction({ result, timeout: 12_000 }));
+    }
+    catch (err) {
+        throw new errors_1.UpshiftTransactionError(`Sui transaction ${digest} executed but was not confirmed in time.`, digest, { cause: err, context: { network } });
+    }
+    return digest;
+}
+//# sourceMappingURL=actions.js.map

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

@@ -0,0 +1,166 @@
+import type { ISuiConfig, ISuiNetwork, ITokenizedVault, IVault } from '../../types';
+import type { IVaultBaseOptions } from '../../modules/vaults/types';
+/** The vault a read is for: its object ID, coin types and network. */
+export interface ISuiVaultRef {
+    /** Vault object ID (`0x` + 64 hex chars). */
+    vaultId: string;
+    /** Move type of the deposit coin. */
+    assetCoinType: string;
+    /** Move type of the vault's share coin. */
+    shareCoinType: string;
+    /** Network the vault lives on. */
+    network: ISuiNetwork;
+}
+/**
+ * A vault's on-chain state. Amounts are raw base units: assets in the deposit
+ * coin's decimals, shares in {@link ISuiVaultState.decimals} (the contract
+ * requires the share coin to use the deposit coin's decimals).
+ */
+export interface ISuiVaultState {
+    /** Net assets: idle + deployed AUM − collectable fees, floored at 0. */
+    totalAssets: bigint;
+    /** Minted shares, including shares escrowed in withdrawal requests. */
+    totalSupply: bigint;
+    /** Asset base units per `10^decimals` shares. */
+    sharePrice: bigint;
+    /** Share (and deposit coin) decimals. */
+    decimals: number;
+    /** Deposits, redemptions and new requests abort while paused. */
+    paused: boolean;
+    /** Whether a withdrawal queue is attached; instant `redeem` is off when it is. */
+    queueAttached: boolean;
+    /** Smallest accepted deposit, in asset base units. */
+    minDeposit: bigint;
+    /** Ceiling on total assets after a deposit, in asset base units. */
+    depositCap: bigint;
+    /** Largest single deposit, in asset base units. */
+    maxDepositAmount: bigint;
+    /** Largest single gross withdrawal, in asset base units. */
+    maxWithdrawalAmount: bigint;
+    /** Fee charged by instant `redeem`, in basis points of the gross amount. */
+    instantRedemptionFeeBps: number;
+}
+/**
+ * Decode a little-endian BCS unsigned integer of `size` bytes.
+ * @internal
+ */
+export declare function decodeSuiUint(bytes: Uint8Array, size: number): bigint;
+/**
+ * Decode a BCS `bool`.
+ * @internal
+ */
+export declare function decodeSuiBool(bytes: Uint8Array): boolean;
+/**
+ * Read the instant-redemption fee from the vault object's JSON fields: the fee
+ * sits in a nested struct that a transaction cannot return.
+ * @internal
+ */
+export declare function parseInstantRedemptionFeeBps(json: unknown): number;
+/**
+ * The `sui` config to use for a vault on `network`: the consumer's config when
+ * it is for that network, else the network alone (built-in endpoint and
+ * contract IDs). A testnet override must never serve a mainnet vault.
+ * @internal
+ */
+export declare function suiConfigForNetwork(network: ISuiNetwork, sui?: ISuiConfig): ISuiConfig;
+/**
+ * Read a vault's on-chain state.
+ *
+ * RPC cost: two requests, run in parallel: one transaction simulation and one
+ * object read. `getVaults` makes these two per Sui vault.
+ *
+ * @param ref - The vault and its coin types and network.
+ * @param sui - The SDK's `sui` config; applied only when its network matches
+ *   `ref.network`.
+ * @returns The vault's state; see {@link ISuiVaultState} for units.
+ * @throws {@link UpshiftValidationError} (`INVALID_ADDRESS`) for a malformed
+ *   vault ID, (`INVALID_INPUT`) when the contract IDs for the network are not
+ *   known or the simulation aborts (wrong vault, coin types or package).
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ * @example
+ * ```ts
+ * const state = await readSuiVaultState(
+ *   { vaultId, assetCoinType, shareCoinType, network: 'testnet' },
+ *   { network: 'testnet', packageId, originalPackageId, registryId },
+ * );
+ * ```
+ */
+export declare function readSuiVaultState(ref: ISuiVaultRef, sui?: ISuiConfig): Promise<ISuiVaultState>;
+/**
+ * Shares a deposit would mint at the current price. Limits are not checked.
+ *
+ * RPC cost: one transaction simulation.
+ *
+ * @param ref - The vault and its coin types and network.
+ * @param assets - Deposit amount in asset base units.
+ * @param sui - The SDK's `sui` config; applied only for `ref.network`.
+ * @returns Shares in share base units.
+ * @throws {@link UpshiftValidationError} for a malformed vault ID, a negative
+ *   or out-of-range amount, unknown contract IDs or an aborted simulation.
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+export declare function previewSuiDeposit(ref: ISuiVaultRef, assets: bigint, sui?: ISuiConfig): Promise<bigint>;
+/**
+ * Assets a redemption of `shares` would pay at the current price.
+ *
+ * RPC cost: one transaction simulation.
+ *
+ * @param ref - The vault and its coin types and network.
+ * @param shares - Shares to redeem, in share base units.
+ * @param isInstant - `true` for instant `redeem` (charges the instant fee),
+ *   `false` for a queued withdrawal (no fee).
+ * @param sui - The SDK's `sui` config; applied only for `ref.network`.
+ * @returns `gross` and `net` (after the instant fee) in asset base units.
+ * @throws {@link UpshiftValidationError} for a malformed vault ID, a negative
+ *   or out-of-range amount, unknown contract IDs or an aborted simulation.
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+export declare function previewSuiRedemption(ref: ISuiVaultRef, shares: bigint, isInstant: boolean, sui?: ISuiConfig): Promise<{
+    gross: bigint;
+    net: bigint;
+}>;
+/**
+ * A wallet's balance of a share coin: coin objects plus the address balance.
+ *
+ * RPC cost: one balance read.
+ *
+ * @param owner - Wallet address (`0x` + 64 hex chars).
+ * @param shareCoinType - Move type of the vault's share coin.
+ * @param network - Network to read.
+ * @param sui - The SDK's `sui` config; applied only for `network`.
+ * @returns Shares in share base units.
+ * @throws {@link UpshiftValidationError} (`INVALID_ADDRESS`) for a malformed
+ *   owner.
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+export declare function getSuiShareBalance(owner: string, shareCoinType: string, network: ISuiNetwork, sui?: ISuiConfig): Promise<bigint>;
+/**
+ * The vault reference for a backend row, or `null` when the row has no usable
+ * `sui_vault_metadata`.
+ * @internal
+ */
+export declare function suiVaultRefFromRow(row: ITokenizedVault): ISuiVaultRef | null;
+/**
+ * Build the SDK's `IVault` for a Sui vault from its backend row and, when the
+ * read succeeded, its on-chain state. Without state, total assets fall back
+ * to the backend's `latest_reported_tvl`, supply to zero, and the vault is
+ * marked deposit-paused so no deposit is offered on unread state.
+ * @internal
+ */
+export declare function buildSuiVault(row: ITokenizedVault, state: ISuiVaultState | null): IVault;
+/**
+ * Build a Sui vault's `IVault` from its backend row plus on-chain state.
+ *
+ * A failed read (unknown contract IDs, every endpoint down, an aborted
+ * simulation) does not fail the call: the vault is built from the backend row
+ * alone (see {@link buildSuiVault}) and a warning is logged.
+ *
+ * RPC cost: as {@link readSuiVaultState}.
+ *
+ * @param row - Backend `tokenized_vault` row with `sui_vault_metadata`.
+ * @param options - Vault options; `options.sui` carries the SDK's `sui` config.
+ * @returns The vault.
+ * @throws {@link UpshiftValidationError} (`INVALID_INPUT`) when the row has no
+ *   usable `sui_vault_metadata` (e.g. a legacy Ember/Gamma Sui vault).
+ */
+export declare function getSuiVault(row: ITokenizedVault, options?: IVaultBaseOptions): Promise<IVault>;