@upshiftfinance/sdk 0.3.0 → 0.4.0

package/lib/core/index.d.ts

@@ -11,6 +11,7 @@ export * from './constants/core';
 export * from './constants/web3';
 export * from './constants/vaults';
 export * from './constants/swap-router';
+export * from './constants/kyc';
 export * from './helpers/web3';
 export * from './helpers/multicall';
 export * from './helpers/vaults';
@@ -20,4 +21,5 @@ export * from './helpers/core';
 export * from './helpers/adapters';
 export * from './helpers/signer';
 export * from './helpers/swap-router';
+export * from './helpers/kyc';
 export * from './helpers/revert-decode';

package/lib/core/index.js

@@ -27,6 +27,7 @@ __exportStar(require("./constants/core"), exports);
 __exportStar(require("./constants/web3"), exports);
 __exportStar(require("./constants/vaults"), exports);
 __exportStar(require("./constants/swap-router"), exports);
+__exportStar(require("./constants/kyc"), exports);
 __exportStar(require("./helpers/web3"), exports);
 __exportStar(require("./helpers/multicall"), exports);
 __exportStar(require("./helpers/vaults"), exports);
@@ -36,5 +37,6 @@ __exportStar(require("./helpers/core"), exports);
 __exportStar(require("./helpers/adapters"), exports);
 __exportStar(require("./helpers/signer"), exports);
 __exportStar(require("./helpers/swap-router"), exports);
+__exportStar(require("./helpers/kyc"), exports);
 __exportStar(require("./helpers/revert-decode"), exports);
 //# sourceMappingURL=index.js.map

package/lib/main.d.ts

@@ -7,7 +7,7 @@ import SolanaAdapter from './adapters/solana';
 import SuiAdapter from './adapters/sui';
 import StellarAdapter from './adapters/stellar';
 import EVMAdapter from './adapters/evm';
-import type { IAddress, IChainId, IVaultHistoricalParams } from './types';
+import type { IAddress, IChainId, IKycRecord, IKycStatus, IKycWalletOptions, IVaultHistoricalParams } from './types';
 import { UpshiftBase, type IUpshiftBase } from './core';
 import { UpshiftVaults, type IGetVaultsOptions, type IVaultBaseOptions, type IVaultCustomOptions } from './modules/vaults';
 import type { Signer, Wallet } from 'ethers';
@@ -266,8 +266,8 @@ export declare class UpshiftSDK extends UpshiftBase {
         solanaWallet?: string;
         stellarWallet?: string;
         /**
-         * Sui wallet address (`0x` + 64 hex chars). Validated now; Sui positions
-         * are not read yet, so passing it does not add Sui vaults to the result.
+         * Sui wallet address (`0x` + 64 hex chars). Its share balance is read for
+         * each Sui vault; Sui positions have no redemptions in v1.
          */
         suiWallet?: string;
         options?: IVaultBaseOptions;
@@ -388,6 +388,34 @@ export declare class UpshiftSDK extends UpshiftBase {
         chainId: number;
         originCode: `0x${string}`;
     }): Promise<import("./types").IOriginInfo>;
+    /**
+     * Read a wallet's status in `chainId`'s `KycRegistry`. Delegates to
+     * {@link UpshiftVaults.getKycStatus}.
+     * @param options - `chainId` and `wallet`.
+     * @returns `'none' | 'active' | 'expired' | 'blocked'`.
+     * @throws UpshiftValidationError when no provider is configured or no
+     *   registry is deployed for `chainId`, or `wallet` is malformed.
+     * @throws UpshiftSDKError when the read fails.
+     * @example
+     * ```ts
+     * const status = await upshiftSdk.getKycStatus({ chainId: 1, wallet });
+     * ```
+     */
+    getKycStatus(options: Omit<IKycWalletOptions, 'rpcUrl'>): Promise<IKycStatus>;
+    /**
+     * Read a wallet's raw `KycRegistry` record (blocked flag and Unix-second
+     * timestamps). Delegates to {@link UpshiftVaults.getKycRecord}.
+     * @param options - `chainId` and `wallet`.
+     * @returns {@link IKycRecord}.
+     * @throws UpshiftValidationError when no provider is configured or no
+     *   registry is deployed for `chainId`, or `wallet` is malformed.
+     * @throws UpshiftSDKError when the read fails.
+     * @example
+     * ```ts
+     * const { expiresAt } = await upshiftSdk.getKycRecord({ chainId: 1, wallet });
+     * ```
+     */
+    getKycRecord(options: Omit<IKycWalletOptions, 'rpcUrl'>): Promise<IKycRecord>;
     /**
      * Get lifetime PnL for a user in a specific vault.
      * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.

package/lib/main.js

@@ -463,6 +463,38 @@ class UpshiftSDK extends core_1.UpshiftBase {
     async getOriginInfo(options) {
         return await this.vaults.getOriginInfo(options);
     }
+    /**
+     * Read a wallet's status in `chainId`'s `KycRegistry`. Delegates to
+     * {@link UpshiftVaults.getKycStatus}.
+     * @param options - `chainId` and `wallet`.
+     * @returns `'none' | 'active' | 'expired' | 'blocked'`.
+     * @throws UpshiftValidationError when no provider is configured or no
+     *   registry is deployed for `chainId`, or `wallet` is malformed.
+     * @throws UpshiftSDKError when the read fails.
+     * @example
+     * ```ts
+     * const status = await upshiftSdk.getKycStatus({ chainId: 1, wallet });
+     * ```
+     */
+    async getKycStatus(options) {
+        return await this.vaults.getKycStatus(options);
+    }
+    /**
+     * Read a wallet's raw `KycRegistry` record (blocked flag and Unix-second
+     * timestamps). Delegates to {@link UpshiftVaults.getKycRecord}.
+     * @param options - `chainId` and `wallet`.
+     * @returns {@link IKycRecord}.
+     * @throws UpshiftValidationError when no provider is configured or no
+     *   registry is deployed for `chainId`, or `wallet` is malformed.
+     * @throws UpshiftSDKError when the read fails.
+     * @example
+     * ```ts
+     * const { expiresAt } = await upshiftSdk.getKycRecord({ chainId: 1, wallet });
+     * ```
+     */
+    async getKycRecord(options) {
+        return await this.vaults.getKycRecord(options);
+    }
     /**
      * Get lifetime PnL for a user in a specific vault.
      * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.

package/lib/modules/api/kyc.d.ts

@@ -0,0 +1,4 @@
+import type { IAddress, ICreateKycSessionOptions, IKycChallenge, IKycSession } from '../../types';
+export declare function fetchKycChallenge(wallet: IAddress, chainId: number): Promise<IKycChallenge>;
+export declare function postKycSession(options: ICreateKycSessionOptions): Promise<IKycSession>;
+export declare function postKycSessionRefresh(sessionToken: string): Promise<string>;

package/lib/modules/api/kyc.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchKycChallenge = fetchKycChallenge;
+exports.postKycSession = postKycSession;
+exports.postKycSessionRefresh = postKycSessionRefresh;
+const ethers_1 = require("ethers");
+const core_1 = require("../../core/constants/core");
+const errors_1 = require("../../core/errors");
+const fetcher_1 = require("../../core/fetcher");
+const REASONS = {
+    'challenge expired': 'challenge_expired',
+    'unknown or used challenge': 'challenge_used',
+    'invalid signature': 'invalid_signature',
+    'unknown or expired session': 'session_expired',
+    'session no longer valid': 'session_expired',
+    'identity blocked': 'identity_blocked',
+    'wallet is bound to another identity': 'wallet_bound',
+    'wallet limit reached for this identity': 'wallet_limit',
+    'wallet control was proven on another chain; verify again from there': 'other_chain',
+    'wallet is verified through another provider': 'other_provider',
+    'wallet is not verified for this chain': 'not_verified_for_chain',
+    'enrolment already in progress; retry shortly': 'enrolment_in_progress',
+    'a registry write for this wallet is in progress; retry shortly': 'registry_write_in_progress',
+    'enrolment timed out; retry shortly': 'enrolment_timed_out',
+    'chain has no kyc registry': 'no_registry',
+    'too many requests': 'rate_limited',
+};
+const IDENTITY_STATUSES = [
+    'pending',
+    'approved',
+    'rejected_retry',
+    'rejected_final',
+    'revoked',
+    'blocked',
+];
+function readDetail(body) {
+    const detail = body?.detail;
+    if (typeof detail === 'string')
+        return detail;
+    if (!Array.isArray(detail))
+        return '';
+    return detail
+        .map((d) => d?.msg)
+        .filter((m) => typeof m === 'string')
+        .join('; ');
+}
+function reasonFor(status, detail) {
+    const known = REASONS[detail.toLowerCase()];
+    if (known)
+        return known;
+    if (/has no KYC registry/i.test(detail))
+        return 'no_registry';
+    if (status === 429)
+        return 'rate_limited';
+    if (status >= 500)
+        return 'unavailable';
+    if (status === 422)
+        return 'invalid_request';
+    return 'unknown';
+}
+async function kycRequest(method, path, data) {
+    const res = await (0, fetcher_1.fetchUpshiftPublic)(path, {
+        method: data === undefined ? 'get' : 'post',
+        data,
+        returnErrorResponse: true,
+    });
+    const body = await res.json().catch(() => null);
+    if (res.ok) {
+        if (body && typeof body === 'object')
+            return body;
+        throw new errors_1.UpshiftServerError(res.status, `${method}: empty response body`);
+    }
+    const detail = readDetail(body);
+    const retryAfter = Number(res.headers.get('retry-after'));
+    throw new errors_1.UpshiftKycError(res.status, detail, reasonFor(res.status, detail), {
+        correlationId: res.headers.get('x-correlation-id') ?? undefined,
+        context: { method, status: res.status },
+        retryAfterMs: retryAfter > 0 ? retryAfter * 1000 : undefined,
+    });
+}
+function assertWalletAndChain(method, wallet, chainId) {
+    if (!(0, ethers_1.isAddress)(wallet)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: wallet is not a valid EVM address`);
+    }
+    if (!Number.isInteger(chainId) || chainId < 1) {
+        throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: chainId must be a positive integer, got ${chainId}`);
+    }
+}
+function field(method, body, key, check) {
+    const value = body[key];
+    if (!check(value)) {
+        throw new errors_1.UpshiftServerError(200, `${method}: response field ${key} is malformed`);
+    }
+    return value;
+}
+const isString = (v) => typeof v === 'string' && v.length > 0;
+const isInteger = (v) => Number.isInteger(v);
+const isIdentityStatus = (v) => IDENTITY_STATUSES.includes(v);
+async function fetchKycChallenge(wallet, chainId) {
+    const method = 'getKycChallenge';
+    assertWalletAndChain(method, wallet, chainId);
+    const body = await kycRequest(method, core_1.WEBSERVER_ENDPOINTS.public.kyc.challenge(wallet, chainId));
+    return {
+        wallet: field(method, body, 'wallet', isString),
+        chainId: field(method, body, 'chain_id', isInteger),
+        nonce: field(method, body, 'nonce', isString),
+        issuedAt: field(method, body, 'issued_at', isInteger),
+        expiry: field(method, body, 'expiry', isInteger),
+        message: field(method, body, 'message', isString),
+    };
+}
+async function postKycSession(options) {
+    const method = 'createKycSession';
+    const { wallet, chainId, nonce, issuedAt, expiry, signature } = options;
+    assertWalletAndChain(method, wallet, chainId);
+    if (!/^0x[0-9a-fA-F]+$/.test(signature)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: signature must be 0x-prefixed hex`);
+    }
+    if (!isString(nonce) || !isInteger(issuedAt) || !isInteger(expiry)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: nonce, issuedAt and expiry must come from getKycChallenge`);
+    }
+    const body = await kycRequest(method, core_1.WEBSERVER_ENDPOINTS.public.kyc.session, {
+        wallet,
+        chain_id: chainId,
+        nonce,
+        issued_at: issuedAt,
+        expiry,
+        signature,
+    });
+    return {
+        accessToken: field(method, body, 'access_token', isString),
+        sessionToken: field(method, body, 'session_token', isString),
+        externalUserId: field(method, body, 'external_user_id', isString),
+        levelName: field(method, body, 'level_name', isString),
+        identityStatus: field(method, body, 'identity_status', isIdentityStatus),
+    };
+}
+async function postKycSessionRefresh(sessionToken) {
+    const method = 'refreshKycSession';
+    if (typeof sessionToken !== 'string' ||
+        sessionToken.length < 16 ||
+        sessionToken.length > 128) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: sessionToken must come from createKycSession`);
+    }
+    const body = await kycRequest(method, core_1.WEBSERVER_ENDPOINTS.public.kyc.sessionRefresh, { session_token: sessionToken });
+    return field(method, body, 'access_token', isString);
+}
+//# sourceMappingURL=kyc.js.map

package/lib/modules/api/main.d.ts

@@ -1,5 +1,5 @@
 import { UpshiftBase, type IUpshiftBase } from '../../core/base.class';
-import type { ICollateralExcessOrDeficit, ICollateralSimulationInput, ICollateralSimulationResults, ICuratorWhitelistStatus, IDiscountFactorLadder, ILoanBookInfo, IOracleClassification, IOtcMarginRequirement, IOtcPositionRead, IRevertReason, ITimelockRequest, ITransparencyApySeries, ITransparencyAuditCategory, ITransparencyAuditLog, ITransparencyFees, ITransparencyGovernancePermissions, ITransparencyGovernanceRoles, ITransparencyHistoricalAllocations, ITransparencyPositions, ITransparencyRatioPoint, ITransparencyTimelocks, ITransparencyTimelockStatus, IUnrealizedPnlSnapshot, IVaultPerformanceFees, IWSSubaccountListItem } from '../../types';
+import type { IAddress, ICollateralExcessOrDeficit, ICollateralSimulationInput, ICollateralSimulationResults, ICreateKycSessionOptions, ICuratorWhitelistStatus, IDiscountFactorLadder, IKycChallenge, IKycSession, ILoanBookInfo, IOracleClassification, IOtcMarginRequirement, IOtcPositionRead, IRevertReason, ITimelockRequest, ITransparencyApySeries, ITransparencyAuditCategory, ITransparencyAuditLog, ITransparencyFees, ITransparencyGovernancePermissions, ITransparencyGovernanceRoles, ITransparencyHistoricalAllocations, ITransparencyPositions, ITransparencyRatioPoint, ITransparencyTimelocks, ITransparencyTimelockStatus, IUnrealizedPnlSnapshot, IVaultPerformanceFees, IWSSubaccountListItem } from '../../types';
 /**
  * Read-only client for Upshift backend REST endpoints that have no on-chain
  * equivalent: the unrealized-PnL series, the transparency dashboard
@@ -584,4 +584,66 @@ export declare class UpshiftApi extends UpshiftBase {
      *   const losing = all.filter((s) => s.unrealizedPnl < 0);
      */
     getLatestUnrealizedPnl(): Promise<IUnrealizedPnlSnapshot[]>;
+    /**
+     * Fetch a one-time SIWE challenge that proves the wallet is the user's
+     * before KYC starts (`GET /kyc/challenge`).
+     *
+     * Makes one HTTPS request to the public Upshift API; no RPC calls. Never
+     * cached: the nonce is single use and expires after 600 s.
+     *
+     * @param params - `wallet`, the EVM wallet that will sign `message`, and
+     *   `chainId`, the EVM chain whose `KycRegistry` the session activates.
+     * @returns {@link IKycChallenge}. Sign `message` verbatim with `personal_sign`.
+     * @throws UpshiftValidationError When `wallet` or `chainId` is malformed.
+     * @throws UpshiftKycError When the backend answers non-2xx: `no_registry` (400) or `unavailable` (503).
+     * @throws UpshiftServerError When the response body is malformed.
+     * @example
+     * ```ts
+     * const challenge = await sdk.apiModule.getKycChallenge({ wallet, chainId: 1 });
+     * const signature = await walletClient.signMessage({ message: challenge.message });
+     * ```
+     */
+    getKycChallenge(params: {
+        wallet: IAddress;
+        chainId: number;
+    }): Promise<IKycChallenge>;
+    /**
+     * Open a KYC session with a signed challenge (`POST /kyc/session`). The
+     * first call creates the user's Sumsub applicant; later calls resume it.
+     * Every call activates the identity on `chainId`.
+     *
+     * Makes one HTTPS request and never retries: the nonce is single use. On
+     * any failure, fetch a new challenge before trying again.
+     *
+     * @param options - The challenge fields exactly as returned, plus `signature`.
+     * @returns {@link IKycSession} with the Sumsub WebSDK `accessToken`.
+     * @throws UpshiftValidationError When an input is malformed.
+     * @throws UpshiftKycError When the backend answers non-2xx. `reason` names the
+     *   case; `retryable` is true for the in-progress and timed-out answers.
+     * @throws UpshiftServerError When the response body is malformed.
+     * @example
+     * ```ts
+     * const session = await sdk.apiModule.createKycSession({ ...challenge, signature });
+     * openSumsubWidget(session.accessToken);
+     * ```
+     */
+    createKycSession(options: ICreateKycSessionOptions): Promise<IKycSession>;
+    /**
+     * Get a fresh Sumsub WebSDK access token for an open session without a new
+     * signature (`POST /kyc/session/refresh`). A session lasts 4 h.
+     *
+     * Makes one HTTPS request; no RPC calls.
+     *
+     * @param params - `sessionToken` from {@link UpshiftApi.createKycSession}.
+     * @returns The new Sumsub access token.
+     * @throws UpshiftValidationError When `sessionToken` is malformed.
+     * @throws UpshiftKycError When the backend answers non-2xx: `session_expired` (401) once the session ends or the wallet is unbound.
+     * @example
+     * ```ts
+     * const expirationHandler = () => sdk.apiModule.refreshKycSession({ sessionToken });
+     * ```
+     */
+    refreshKycSession(params: {
+        sessionToken: string;
+    }): Promise<string>;
 }

package/lib/modules/api/main.js

@@ -10,6 +10,7 @@ exports.UpshiftApi = void 0;
  */
 const ethers_1 = require("ethers");
 const fetcher_1 = require("./fetcher");
+const kyc_1 = require("./kyc");
 const base_class_1 = require("../../core/base.class");
 const core_1 = require("../../core/constants/core");
 const errors_1 = require("../../core/errors");
@@ -906,6 +907,69 @@ class UpshiftApi extends base_class_1.UpshiftBase {
         assertSnapshotArray(data, method);
         return data.map(toUnrealizedPnlSnapshot);
     }
+    /**
+     * Fetch a one-time SIWE challenge that proves the wallet is the user's
+     * before KYC starts (`GET /kyc/challenge`).
+     *
+     * Makes one HTTPS request to the public Upshift API; no RPC calls. Never
+     * cached: the nonce is single use and expires after 600 s.
+     *
+     * @param params - `wallet`, the EVM wallet that will sign `message`, and
+     *   `chainId`, the EVM chain whose `KycRegistry` the session activates.
+     * @returns {@link IKycChallenge}. Sign `message` verbatim with `personal_sign`.
+     * @throws UpshiftValidationError When `wallet` or `chainId` is malformed.
+     * @throws UpshiftKycError When the backend answers non-2xx: `no_registry` (400) or `unavailable` (503).
+     * @throws UpshiftServerError When the response body is malformed.
+     * @example
+     * ```ts
+     * const challenge = await sdk.apiModule.getKycChallenge({ wallet, chainId: 1 });
+     * const signature = await walletClient.signMessage({ message: challenge.message });
+     * ```
+     */
+    async getKycChallenge(params) {
+        return (0, kyc_1.fetchKycChallenge)(params.wallet, params.chainId);
+    }
+    /**
+     * Open a KYC session with a signed challenge (`POST /kyc/session`). The
+     * first call creates the user's Sumsub applicant; later calls resume it.
+     * Every call activates the identity on `chainId`.
+     *
+     * Makes one HTTPS request and never retries: the nonce is single use. On
+     * any failure, fetch a new challenge before trying again.
+     *
+     * @param options - The challenge fields exactly as returned, plus `signature`.
+     * @returns {@link IKycSession} with the Sumsub WebSDK `accessToken`.
+     * @throws UpshiftValidationError When an input is malformed.
+     * @throws UpshiftKycError When the backend answers non-2xx. `reason` names the
+     *   case; `retryable` is true for the in-progress and timed-out answers.
+     * @throws UpshiftServerError When the response body is malformed.
+     * @example
+     * ```ts
+     * const session = await sdk.apiModule.createKycSession({ ...challenge, signature });
+     * openSumsubWidget(session.accessToken);
+     * ```
+     */
+    async createKycSession(options) {
+        return (0, kyc_1.postKycSession)(options);
+    }
+    /**
+     * Get a fresh Sumsub WebSDK access token for an open session without a new
+     * signature (`POST /kyc/session/refresh`). A session lasts 4 h.
+     *
+     * Makes one HTTPS request; no RPC calls.
+     *
+     * @param params - `sessionToken` from {@link UpshiftApi.createKycSession}.
+     * @returns The new Sumsub access token.
+     * @throws UpshiftValidationError When `sessionToken` is malformed.
+     * @throws UpshiftKycError When the backend answers non-2xx: `session_expired` (401) once the session ends or the wallet is unbound.
+     * @example
+     * ```ts
+     * const expirationHandler = () => sdk.apiModule.refreshKycSession({ sessionToken });
+     * ```
+     */
+    async refreshKycSession(params) {
+        return (0, kyc_1.postKycSessionRefresh)(params.sessionToken);
+    }
 }
 exports.UpshiftApi = UpshiftApi;
 //# sourceMappingURL=main.js.map

package/lib/modules/vaults/getters.d.ts

@@ -119,11 +119,13 @@ export { getSwapRouterDepositResult } from '../../core/helpers/swap-router';
 /**
  * Vault Positions
  */
-export declare function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, prefetchedReads, }: {
+export declare function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, suiWallet, options, prefetchedReads, }: {
     vault: IAddress;
     wallet?: IAddress;
     solanaWallet?: string;
     stellarWallet?: string;
+    /** Sui wallet whose share balance is read for Sui vaults. */
+    suiWallet?: string;
     options: IVaultBaseOptions;
     /**
      * Per-vault values already read via a Multicall3 batch at the fan-out call

package/lib/modules/vaults/getters.js

@@ -88,6 +88,8 @@ const SolanaConstants = __importStar(require("../../adapters/solana/constants"))
 const withdrawal_queue_1 = require("../../adapters/solana/withdrawal-queue");
 const web3_js_1 = require("@solana/web3.js");
 const StellarGetters = __importStar(require("../../adapters/stellar/getters"));
+const SuiGetters = __importStar(require("../../adapters/sui/getters"));
+const chain_address_1 = require("../../core/helpers/chain-address");
 const utils_3 = require("../../adapters/stellar/utils");
 const constants_1 = require("../../adapters/stellar/constants");
 const EVM = __importStar(require("../../adapters/evm"));
@@ -160,6 +162,10 @@ async function getVault({ vault, loans = false, allocations = false, options, lo
                 returnedVault = await StellarGetters.getStellarVault(tokenizedVault, options);
                 break;
             }
+            case 'sui-0': {
+                returnedVault = await SuiGetters.getSuiVault(tokenizedVault, options);
+                break;
+            }
             case 'evm-2': {
                 returnedVault = await EVM.getEvmVaultV2(tokenizedVault, options);
                 break;
@@ -968,9 +974,9 @@ async function readSolanaRedemptions(input) {
 }
 async function getVaultAvailableRedemptions({ vault, wallet, options, prefetchedReads, }) {
     try {
-        // Stellar vaults don't support on-chain redemptions yet
-        if ((0, utils_3.isStellarAddress)(vault)) {
-            core_1.Logger.log.warn('getVaultAvailableRedemptions', `Available redemptions is not yet supported for Stellar vaults: ${vault}`);
+        // Stellar and Sui vaults don't support on-chain redemptions yet
+        if ((0, utils_3.isStellarAddress)(vault) || (0, chain_address_1.isSuiAddress)(vault)) {
+            core_1.Logger.log.warn('getVaultAvailableRedemptions', `Available redemptions is not yet supported for this vault: ${vault}`);
             return {
                 availableRedemptions: [],
                 pendingRedemptions: [],
@@ -1305,9 +1311,9 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, prefetched
 }
 async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, options, }) {
     try {
-        // Stellar vaults: no on-chain redemption history yet
-        if ((0, utils_3.isStellarAddress)(vault)) {
-            core_1.Logger.log.warn('getVaultRedemptionHistory', `Redemption history is not yet supported for Stellar vaults: ${vault}`);
+        // Stellar and Sui vaults: no on-chain redemption history yet
+        if ((0, utils_3.isStellarAddress)(vault) || (0, chain_address_1.isSuiAddress)(vault)) {
+            core_1.Logger.log.warn('getVaultRedemptionHistory', `Redemption history is not yet supported for this vault: ${vault}`);
             return [];
         }
         // setup
@@ -1481,7 +1487,7 @@ Object.defineProperty(exports, "getSwapRouterDepositResult", { enumerable: true,
 /**
  * Vault Positions
  */
-async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, prefetchedReads, }) {
+async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, suiWallet, options, prefetchedReads, }) {
     try {
         const tokenizedVaults = await (0, core_1.fetchTokenizedVault)(vault ? vault : undefined, options?.headers, false, false);
         if (!tokenizedVaults || tokenizedVaults.length === 0) {
@@ -1594,6 +1600,32 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                         walletBalance: balance,
                     };
                 }
+                if ((0, chain_address_1.isSuiAddress)(v.address)) {
+                    // The contract gives shares the deposit coin's decimals.
+                    const decimals = v.sui_vault_metadata?.deposit_token_decimals;
+                    const shareCoinType = v.sui_vault_metadata?.share_coin_type;
+                    const network = v.sui_vault_metadata?.network_name;
+                    let balance = (0, core_1.toNormalizedBn)(0, decimals ?? 0);
+                    // No metadata at all: a legacy Ember/Gamma vault, nothing to read.
+                    if (suiWallet && (0, chain_address_1.isSuiAddress)(suiWallet) && v.sui_vault_metadata) {
+                        if (decimals == null || !shareCoinType || !network) {
+                            // Without the share type or its decimals there is nothing to
+                            // read or no way to scale it: fail the row, don't show zero.
+                            throw new errors_1.UpshiftValidationError('INVALID_INPUT', 'getVaultPositions: Sui vault is missing sui_vault_metadata share type, decimals or network', { context: { vault: v.address } });
+                        }
+                        const shares = await SuiGetters.getSuiShareBalance(suiWallet, shareCoinType, network, options.sui);
+                        balance = (0, core_1.toNormalizedBn)(shares, decimals);
+                    }
+                    // Sui vaults have no redemption reads in v1.
+                    return {
+                        vault: v.address,
+                        status: renderStatus([], balance),
+                        availableRedemptions: [],
+                        pendingRedemptions: [],
+                        redeemable: (0, core_1.toNormalizedBn)(0),
+                        walletBalance: balance,
+                    };
+                }
                 // create provider
                 const provider = (0, core_1.createProvider)(options.rpcUrl);
                 // version split logic
@@ -1709,6 +1741,7 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
             wallet,
             solanaWallet,
             stellarWallet,
+            suiWallet,
         });
         throw new Error(`#getVaultPositions::${vault}:${e?.message}`);
     }
@@ -1897,6 +1930,14 @@ async function getVaultTvl({ vault, options, historical, }) {
                     },
                 ];
             }
+            if (version === 'sui-0') {
+                return [
+                    {
+                        value: (0, utils_1.backendTvlToNormalizedBn)(_vaultExists?.latest_reported_tvl, _vaultExists?.sui_vault_metadata?.deposit_token_decimals ?? 0),
+                        timestamp: new Date().toISOString(),
+                    },
+                ];
+            }
             if (version === 'stellar-0') {
                 const stellarDecimals = _vaultExists?.stellar_vault_metadata?.deposit_token_decimals ??
                     constants_1.STELLAR_FALLBACK_DECIMALS;
@@ -1957,7 +1998,9 @@ async function getVaultTvl({ vault, options, historical, }) {
             // historical tvl
             // check vault version early to guard non-EVM chains
             const version = (0, core_1.getVaultVersionV2)(_vaultExists);
-            if (version === 'stellar-0' || version === 'sol-0') {
+            if (version === 'stellar-0' ||
+                version === 'sol-0' ||
+                version === 'sui-0') {
                 core_1.Logger.log.warn('getVaultTvl:historical', 'Historical TVL not supported for non-EVM vaults', { vault, version });
                 return [];
             }
@@ -2349,7 +2392,8 @@ async function getYieldLastRealizedOn({ vault, options, }) {
                 break;
             }
             case 'sol-0':
-            case 'stellar-0': {
+            case 'stellar-0':
+            case 'sui-0': {
                 return 0;
             }
             default: {

package/lib/modules/vaults/main.d.ts

@@ -7,7 +7,7 @@
  * Export getters
  */
 export * from './getters';
-import type { IAddress, IChainId, IGetOriginInfoOptions, INormalizedNumber, IOriginInfo, IVaultHistoricalParams, IVaultPosition, IVaultUserHistoryItem } from '../../types';
+import type { IAddress, IChainId, IGetOriginInfoOptions, IKycRecord, IKycStatus, IKycWalletOptions, INormalizedNumber, IOriginInfo, IVaultHistoricalParams, IVaultPosition, IVaultUserHistoryItem } from '../../types';
 import type SolanaAdapter from '../../adapters/solana';
 import { UpshiftBase, type IUpshiftBase } from '../../core';
 import { type IContractWriteOptions, type INativeDepositOptions } from './write.actions';
@@ -27,6 +27,8 @@ export declare class UpshiftVaults extends UpshiftBase {
      * vaults (see `IVaultBaseOptions.stellarRpc`).
      */
     private _stellarRpc?;
+    /** The SDK's `sui` config, for Sui vault reads (see `IVaultBaseOptions.sui`). */
+    private _sui?;
     constructor(baseConfig: IUpshiftBase, solana: SolanaAdapter);
     /**
      * @description deposit underlying token into the specified pool with adapter support. This is for when we cannot pass in a signer in sdk and need to do so as an arg
@@ -240,8 +242,8 @@ export declare class UpshiftVaults extends UpshiftBase {
         solanaWallet?: string;
         stellarWallet?: string;
         /**
-         * Sui wallet address (`0x` + 64 hex chars). Validated now; Sui positions
-         * are not read yet, so passing it does not add Sui vaults to the result.
+         * Sui wallet address (`0x` + 64 hex chars). Its share balance is read for
+         * each Sui vault; Sui positions have no redemptions in v1.
          */
         suiWallet?: string;
         options?: IVaultBaseOptions;
@@ -408,6 +410,40 @@ export declare class UpshiftVaults extends UpshiftBase {
      * ```
      */
     getOriginInfo(options: Omit<IGetOriginInfoOptions, 'rpcUrl'>): Promise<IOriginInfo>;
+    /**
+     * Read a wallet's KYC status through this instance's provider for
+     * `chainId`. See {@link getKycStatus}.
+     *
+     * @param options - `chainId` and `wallet`.
+     * @returns The wallet's {@link IKycStatus}.
+     * @throws UpshiftValidationError (`INVALID_CHAIN`) when no provider is
+     *   configured or no registry is deployed for `chainId`;
+     *   (`INVALID_ADDRESS`) for a malformed wallet.
+     * @throws UpshiftSDKError when the `statusOf` read fails.
+     * @worstCaseRpcCalls 1
+     * @example
+     * ```ts
+     * const status = await upshiftSdk.getKycStatus({ chainId: 1, wallet });
+     * ```
+     */
+    getKycStatus(options: Omit<IKycWalletOptions, 'rpcUrl'>): Promise<IKycStatus>;
+    /**
+     * Read a wallet's raw KYC record through this instance's provider for
+     * `chainId`. See {@link getKycRecord}.
+     *
+     * @param options - `chainId` and `wallet`.
+     * @returns The wallet's {@link IKycRecord}.
+     * @throws UpshiftValidationError (`INVALID_CHAIN`) when no provider is
+     *   configured or no registry is deployed for `chainId`;
+     *   (`INVALID_ADDRESS`) for a malformed wallet.
+     * @throws UpshiftSDKError when the `getRecord` read fails.
+     * @worstCaseRpcCalls 1
+     * @example
+     * ```ts
+     * const record = await upshiftSdk.getKycRecord({ chainId: 1, wallet });
+     * ```
+     */
+    getKycRecord(options: Omit<IKycWalletOptions, 'rpcUrl'>): Promise<IKycRecord>;
     /**
      * @function getStakingPositions gets all available reward staking positions
      * @param wallet optionally passed user wallet address