@upshiftfinance/sdk 0.2.0 → 0.4.0

package/lib/core/helpers/kyc.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKycStatus = getKycStatus;
+exports.getKycRecord = getKycRecord;
+const ethers_1 = require("ethers");
+const abis_1 = require("../../abis");
+const kyc_1 = require("../constants/kyc");
+const errors_1 = require("../errors");
+const web3_1 = require("./web3");
+const KYC_STATUSES = [
+    'none',
+    'active',
+    'expired',
+    'blocked',
+];
+function toKycStatus(raw, chainId) {
+    const status = KYC_STATUSES[Number(raw)];
+    if (!status) {
+        throw new errors_1.UpshiftSDKError('UNKNOWN', `KycRegistry on chain ${chainId} returned unknown status ${raw}`, { context: { chainId } });
+    }
+    return status;
+}
+function contractAt(method, chainId, address, abi, provider) {
+    const contract = (0, web3_1.createContract)({ address, abi, provider });
+    if (!contract) {
+        throw new errors_1.UpshiftSDKError('UNKNOWN', `${method}: could not create a contract at ${address} on chain ${chainId}`, { context: { method, chainId } });
+    }
+    return contract;
+}
+function connect(method, chainId, rpcUrl, wallets) {
+    const registryAddress = kyc_1.KYC_REGISTRY_ADDRESSES[chainId];
+    if (!registryAddress) {
+        throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: no KycRegistry is deployed on chain ${chainId}`, { context: { method, chainId } });
+    }
+    for (const [field, value] of Object.entries(wallets)) {
+        if (!(0, ethers_1.isAddress)(value)) {
+            throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: ${field} is not a valid EVM address`, { context: { method, chainId, field } });
+        }
+    }
+    return contractAt(method, chainId, registryAddress, abis_1.ABI_KYC_REGISTRY, (0, web3_1.createProvider)(rpcUrl, chainId));
+}
+async function wrapRead(method, chainId, read) {
+    try {
+        return await read();
+    }
+    catch (e) {
+        if (e instanceof errors_1.UpshiftSDKError)
+            throw e;
+        throw new errors_1.UpshiftSDKError('UNKNOWN', `${method} failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { chainId } });
+    }
+}
+/**
+ * Read a wallet's KYC status from the chain's `KycRegistry` (`statusOf`).
+ *
+ * The registry decides whether a KYC vault accepts a deposit, so read it
+ * on-chain rather than trusting a cached backend status. `expired` covers both
+ * a lapsed and a revoked record; tell them apart with {@link getKycRecord}.
+ * Not cached: an approval lands when the registry writer sends it, and callers
+ * poll for it.
+ *
+ * @param options - {@link IKycWalletOptions}.
+ * @returns The wallet's {@link IKycStatus}.
+ * @throws {@link UpshiftValidationError} `INVALID_CHAIN` when no registry is
+ *   deployed on `chainId` (see {@link KYC_REGISTRY_ADDRESSES}),
+ *   `INVALID_ADDRESS` when `wallet` is not an EVM address.
+ * @throws {@link UpshiftSDKError} when the `statusOf` read fails or returns a
+ *   status this SDK version does not know.
+ * @worstCaseRpcCalls 1 — one `statusOf(address)` call.
+ * @example
+ * ```ts
+ * const status = await getKycStatus({ chainId: 1, wallet, rpcUrl });
+ * if (status !== 'active') showVerifyPrompt();
+ * ```
+ */
+async function getKycStatus({ chainId, wallet, rpcUrl, }) {
+    const registry = connect('getKycStatus', chainId, rpcUrl, { wallet });
+    const raw = await wrapRead('getKycStatus', chainId, () => registry.statusOf(wallet));
+    return toKycStatus(raw, chainId);
+}
+/**
+ * Read a wallet's raw record from the chain's `KycRegistry` (`getRecord`).
+ *
+ * Use it with {@link getKycStatus} to show when access ends (`expiresAt`) and
+ * to tell a lapsed record (`expiresAt` in the past) from a revoked one. Not
+ * cached, for the same reason as {@link getKycStatus}.
+ *
+ * @param options - {@link IKycWalletOptions}.
+ * @returns The wallet's {@link IKycRecord}. A never-approved wallet returns
+ *   all-zero timestamps and `blocked: false`.
+ * @throws {@link UpshiftValidationError} `INVALID_CHAIN` when no registry is
+ *   deployed on `chainId`, `INVALID_ADDRESS` when `wallet` is not an EVM
+ *   address.
+ * @throws {@link UpshiftSDKError} when the `getRecord` read fails.
+ * @worstCaseRpcCalls 1 — one `getRecord(address)` call.
+ * @example
+ * ```ts
+ * const { expiresAt } = await getKycRecord({ chainId: 1, wallet, rpcUrl });
+ * const verifiedUntil = new Date(expiresAt * 1000);
+ * ```
+ */
+async function getKycRecord({ chainId, wallet, rpcUrl, }) {
+    const registry = connect('getKycRecord', chainId, rpcUrl, { wallet });
+    const record = await wrapRead('getKycRecord', chainId, () => registry.getRecord(wallet));
+    return {
+        blocked: record.blocked,
+        verifiedAt: Number(record.verifiedAt),
+        expiresAt: Number(record.expiresAt),
+        revokedAt: Number(record.revokedAt),
+    };
+}
+//# sourceMappingURL=kyc.js.map

package/lib/core/helpers/revert-decode.js

@@ -99,8 +99,8 @@ const STANDARD_ERROR_SIGNATURES = [
  * ABIs already shipped by the SDK whose `error` fragments join the corpus.
  * Covers the Upshift vault estate: tokenized vaults (plus their
  * receipt / permit / whitelist companions), the SwapRouter, lending pools,
- * the fee oracle, the native-deposit wrapper, Multicall3, and the RWA redeem
- * subaccount.
+ * the fee oracle, the native-deposit wrapper, Multicall3, the RWA redeem
+ * subaccount, and the KYC registry.
  */
 const CORPUS_ABIS = [
     STANDARD_ERROR_SIGNATURES,
@@ -112,6 +112,7 @@ const CORPUS_ABIS = [
     abis_1.ABI_TOKENIZED_VAULT_V2_SENDER_ALLOCATION_WHITELIST,
     abis_1.ABI_MULTI_ASSET_NATIVE_DEPOSIT_WRAPPER,
     abis_1.ABI_SWAP_ROUTER,
+    abis_1.ABI_KYC_REGISTRY,
     abis_1.ABI_LENDING_POOL_V3,
     abis_1.ABI_FEE_ORACLE,
     abis_1.ABI_MULTICALL3,

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