@upshiftfinance/sdk 0.3.0 → 0.5.0

package/lib/core/analytics/method-taxonomy.d.ts

@@ -3,7 +3,7 @@
  * Sentry tag so the partner-usage dashboard can roll calls up into
  * `read.*` / `write.*` / `network` / `bridge` buckets.
  */
-export type MethodCategory = 'read.vault' | 'read.position' | 'read.redemption' | 'read.price' | 'read.points' | 'read.subaccount' | 'read.staking' | 'read.layerzero' | 'read.solana' | 'read.stellar' | 'read.sui' | 'read.evm' | 'write.deposit' | 'write.redeem' | 'write.approve' | 'write.points' | 'write.stellar' | 'network' | 'bridge' | 'unknown';
+export type MethodCategory = 'read.vault' | 'read.position' | 'read.redemption' | 'read.price' | 'read.points' | 'read.subaccount' | 'read.staking' | 'read.layerzero' | 'read.solana' | 'read.stellar' | 'read.sui' | 'read.evm' | 'write.deposit' | 'write.redeem' | 'write.approve' | 'write.points' | 'write.stellar' | 'write.sui' | 'read.kyc' | 'write.kyc' | 'network' | 'bridge' | 'unknown';
 /**
  * Map of public SDK method names to their {@link MethodCategory}.
  *

package/lib/core/analytics/method-taxonomy.js

@@ -65,6 +65,8 @@ exports.METHOD_CATEGORIES = {
     getVaultPendingRedemptions: 'read.redemption',
     getVaultWithdrawals: 'read.redemption',
     getWithdrawalRequestsWithStatus: 'read.redemption',
+    // Sui withdrawal queue: a wallet's pending requests on a vault.
+    getWithdrawalRequests: 'read.redemption',
     previewRedemption: 'read.redemption',
     previewRwaRedemption: 'read.redemption',
     getBurnableAmountByReceiver: 'read.redemption',
@@ -113,9 +115,16 @@ exports.METHOD_CATEGORIES = {
     getExplorerLink: 'read.stellar',
     isSuiAddress: 'read.sui',
     isSuiVault: 'read.sui',
+    // Broadcasts a signed Sui transaction, like Stellar's submitTransaction.
+    executeTransaction: 'write.sui',
     vaultAllowance: 'read.evm',
     sendersWhitelistAddress: 'read.evm',
     isWhitelisted: 'read.evm',
+    getKycStatus: 'read.evm',
+    getKycRecord: 'read.evm',
+    getKycChallenge: 'read.kyc',
+    createKycSession: 'write.kyc',
+    refreshKycSession: 'write.kyc',
     getDeposited: 'read.evm',
     getRemainingAllocations: 'read.evm',
     previewDeposit: 'read.vault',

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated at build time from package.json version
  * This file is gitignored and regenerated by every build
  */
-export declare const SDK_VERSION = "0.3.0";
+export declare const SDK_VERSION = "0.5.0";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated at build time from package.json version
  * This file is gitignored and regenerated by every build
  */
-exports.SDK_VERSION = '0.3.0';
+exports.SDK_VERSION = '0.5.0';
 //# sourceMappingURL=version.js.map

package/lib/core/constants/core.d.ts

@@ -101,6 +101,11 @@ export declare const WEBSERVER_ENDPOINTS: {
         }) => string;
     };
     public: {
+        kyc: {
+            challenge: (wallet: IAddress, chainId: number) => string;
+            session: string;
+            sessionRefresh: string;
+        };
         integrations: {
             morpho: {
                 apy: (subaccount: IAddress, vaultAddress: IAddress) => string;

package/lib/core/constants/core.js

@@ -168,6 +168,11 @@ exports.WEBSERVER_ENDPOINTS = {
         },
     },
     public: {
+        kyc: {
+            challenge: (wallet, chainId) => `/kyc/challenge?${new URLSearchParams({ wallet, chain_id: String(chainId) }).toString()}`,
+            session: '/kyc/session',
+            sessionRefresh: '/kyc/session/refresh',
+        },
         integrations: {
             morpho: {
                 apy: (subaccount, vaultAddress) => `/integrations/morpho/apy?subaccount_address=${subaccountSegment(subaccount)}&vault_address=${(0, ethers_1.getAddress)(vaultAddress)}`,

package/lib/core/constants/kyc.d.ts

@@ -0,0 +1,9 @@
+import type { IAddress } from '../../types';
+/**
+ * Address of the `KycRegistry` proxy on each chain.
+ *
+ * Missing keys mean no registry is deployed on that chain, so no vault there
+ * can gate on KYC and the KYC reads reject the chain. Empty until the first
+ * KYC vault launches.
+ */
+export declare const KYC_REGISTRY_ADDRESSES: Readonly<Record<number, IAddress>>;

package/lib/core/constants/kyc.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KYC_REGISTRY_ADDRESSES = void 0;
+/**
+ * Address of the `KycRegistry` proxy on each chain.
+ *
+ * Missing keys mean no registry is deployed on that chain, so no vault there
+ * can gate on KYC and the KYC reads reject the chain. Empty until the first
+ * KYC vault launches.
+ */
+exports.KYC_REGISTRY_ADDRESSES = {};
+//# sourceMappingURL=kyc.js.map

package/lib/core/constants/web3.d.ts

@@ -46,7 +46,7 @@ export declare const NATIVE_ADDRESS = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEe
  * Decimal precision of the native gas token on every EVM chain this SDK
  * supports (ETH, Base, Arbitrum, Avalanche, Polygon, BNB, HyperEVM, Unichain,
  * Mezo, Monad, Plasma, Ink, Flare, Katana, Citrea, Fluent, Tempo, X Layer —
- * whose native OKB is also 18 decimals).
+ * whose native OKB is also 18 decimals — and RISE).
  *
  * All of them use 18-decimal native tokens, so this is a single constant rather
  * than a per-chain map. It exists because the native token has no ERC-20
@@ -88,7 +88,7 @@ export declare const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a17397
  * Chains where the canonical Multicall3 deployment was **verified on-chain**
  * (`eth_getCode` returned the 3808-byte runtime at {@link MULTICALL3_ADDRESS};
  * checked per chain on 2026-07-14, Tempo checked separately on 2026-07-15,
- * X Layer on 2026-08-11) —
+ * X Layer on 2026-08-11, RISE on 2026-11-02) —
  * deterministic-deployer presence is NOT assumed. Chains outside this set
  * keep the per-call read path.
  *

package/lib/core/constants/web3.js

@@ -54,7 +54,7 @@ exports.NATIVE_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
  * Decimal precision of the native gas token on every EVM chain this SDK
  * supports (ETH, Base, Arbitrum, Avalanche, Polygon, BNB, HyperEVM, Unichain,
  * Mezo, Monad, Plasma, Ink, Flare, Katana, Citrea, Fluent, Tempo, X Layer —
- * whose native OKB is also 18 decimals).
+ * whose native OKB is also 18 decimals — and RISE).
  *
  * All of them use 18-decimal native tokens, so this is a single constant rather
  * than a per-chain map. It exists because the native token has no ERC-20
@@ -179,6 +179,11 @@ exports.NETWORKS = {
         chainId: 196,
         explorer: 'https://xlayerscan.com',
     },
+    4153: {
+        name: 'RISE',
+        chainId: 4153,
+        explorer: 'https://explorer.risechain.com',
+    },
 };
 exports.AVAILABLE_CHAINS = Object.keys(exports.NETWORKS).map((c) => Number(c));
 /**
@@ -191,7 +196,7 @@ exports.MULTICALL3_ADDRESS = '0xcA11bde05977b3631167028862bE2a173976CA11';
  * Chains where the canonical Multicall3 deployment was **verified on-chain**
  * (`eth_getCode` returned the 3808-byte runtime at {@link MULTICALL3_ADDRESS};
  * checked per chain on 2026-07-14, Tempo checked separately on 2026-07-15,
- * X Layer on 2026-08-11) —
+ * X Layer on 2026-08-11, RISE on 2026-11-02) —
  * deterministic-deployer presence is NOT assumed. Chains outside this set
  * keep the per-call read path.
  *
@@ -218,6 +223,7 @@ exports.MULTICALL3_VERIFIED_CHAINS = new Set([
     25363, // Fluent
     4217, // Tempo
     196, // X Layer
+    4153, // RISE
 ]);
 /**
  * Fallbacks
@@ -247,5 +253,6 @@ exports.FALLBACK_RPC_URLS = {
     25363: ['https://rpc.fluent.xyz'],
     4217: ['https://rpc.mainnet.tempo.xyz'],
     196: ['https://rpc.xlayer.tech'],
+    4153: ['https://rpc.risechain.com'],
 };
 //# sourceMappingURL=web3.js.map

package/lib/core/errors/index.d.ts

@@ -15,7 +15,7 @@
  * ```
  */
 /** Stable error codes attached to SDK errors. */
-export type UpshiftErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NO_SIGNER' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'TRANSACTION_UNCONFIRMED' | 'HISTORY_UNAVAILABLE' | 'PRICE_UNAVAILABLE' | 'UNKNOWN';
+export type UpshiftErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NO_SIGNER' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'TRANSACTION_UNCONFIRMED' | 'VAULT_ABORTED' | 'HISTORY_UNAVAILABLE' | 'PRICE_UNAVAILABLE' | 'UNKNOWN';
 /** Options accepted by every SDK error constructor. */
 export interface UpshiftErrorOptions {
     /** Original error preserved for stack-trace chaining. */
@@ -72,6 +72,29 @@ export declare class UpshiftServerError extends UpshiftSDKError {
     constructor(status: number, message: string, options?: UpshiftErrorOptions);
     toJSON(): Record<string, unknown>;
 }
+/** Why a KYC API call failed, parsed from the backend's fixed `detail` sentence. */
+export type UpshiftKycErrorReason = 'challenge_expired' | 'challenge_used' | 'invalid_signature' | 'session_expired' | 'identity_blocked' | 'wallet_bound' | 'wallet_limit' | 'other_chain' | 'other_provider' | 'not_verified_for_chain' | 'enrolment_in_progress' | 'registry_write_in_progress' | 'enrolment_timed_out' | 'no_registry' | 'rate_limited' | 'invalid_request' | 'unavailable' | 'unknown';
+/**
+ * A KYC API call (`/kyc/challenge`, `/kyc/session`, `/kyc/session/refresh`)
+ * returned a non-2xx status.
+ *
+ * `retryable` means the same action may succeed shortly, but only with a new
+ * challenge: a session nonce is single use.
+ */
+export declare class UpshiftKycError extends UpshiftSDKError {
+    /** HTTP status code returned by the backend. */
+    readonly status: number;
+    /** The backend's `detail` sentence, or `''` when the body had none. */
+    readonly detail: string;
+    readonly reason: UpshiftKycErrorReason;
+    readonly retryable: boolean;
+    /** From `Retry-After` on a 429. */
+    readonly retryAfterMs?: number;
+    constructor(status: number, detail: string, reason: UpshiftKycErrorReason, options?: UpshiftErrorOptions & {
+        retryAfterMs?: number;
+    });
+    toJSON(): Record<string, unknown>;
+}
 /**
  * Transaction/position history required to compute a value could not be
  * retrieved or was empty, so the computed result would be wrong rather than
@@ -173,5 +196,71 @@ export declare class UpshiftTransactionError extends UpshiftSDKError {
     constructor(message: string, signature: string, options?: UpshiftErrorOptions);
     toJSON(): Record<string, unknown>;
 }
+/**
+ * Why a vault contract rejected a transaction.
+ *
+ * - `paused` — the vault is paused.
+ * - `below_min_deposit` / `above_max_deposit` — the deposit is outside the
+ *   vault's per-call bounds.
+ * - `deposit_cap_exceeded` — the deposit would take total assets past the cap.
+ * - `above_max_withdrawal` — the redemption's gross assets exceed the per-call
+ *   maximum.
+ * - `insufficient_liquidity` — the vault's idle assets cannot pay it now.
+ * - `queue_attached` — instant redemption is off; the vault uses a
+ *   withdrawal queue.
+ * - `slippage` — the output is below the minimum the transaction set.
+ * - `zero_output` — the amount is too small to mint shares or pay assets.
+ * - `version_retired` — the transaction targets a retired package version;
+ *   point it at the current `upshift_vault` package (`sui.packageId`).
+ * - `queue_not_attached` — withdrawal requests are off; the vault has no
+ *   withdrawal queue (redeem instantly instead).
+ * - `invalid_payout` — the request's payout address could never receive the
+ *   assets (the zero, vault, Registry or request address).
+ * - `request_id_in_use` — the wallet already used this request ID on the
+ *   vault; build the request again to pick the next one.
+ * - `not_request_owner` — only the wallet that made the request may cancel it.
+ * - `not_finalizer` — this wallet may not claim the request yet: only its
+ *   owner or named finalizer may, until one day after it became eligible.
+ * - `not_eligible_yet` — the request's cooldown has not run out.
+ * - `request_expired` — the request's fulfillment window has passed; cancel it
+ *   to get the shares back.
+ * - `other` — any other abort; see `module` and `constant`.
+ */
+export type UpshiftVaultAbortReason = 'paused' | 'below_min_deposit' | 'above_max_deposit' | 'deposit_cap_exceeded' | 'above_max_withdrawal' | 'insufficient_liquidity' | 'queue_attached' | 'slippage' | 'zero_output' | 'version_retired' | 'queue_not_attached' | 'invalid_payout' | 'request_id_in_use' | 'not_request_owner' | 'not_finalizer' | 'not_eligible_yet' | 'request_expired' | 'other';
+/**
+ * A vault contract rejected a transaction, in a dry run before signing or on
+ * chain. `reason` is stable to branch on; `module` and `constant` name the
+ * contract error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.sui.vaultRedeem(params);
+ * } catch (err) {
+ *   if (err instanceof UpshiftVaultAbortError && err.reason === 'queue_attached') {
+ *     // offer a withdrawal request instead
+ *   }
+ * }
+ * ```
+ */
+export declare class UpshiftVaultAbortError extends UpshiftSDKError {
+    /** Why the contract rejected the transaction. */
+    readonly reason: UpshiftVaultAbortReason;
+    /** Contract module that aborted, e.g. `vault`. */
+    readonly module?: string;
+    /** Contract error constant, e.g. `EPaused`. */
+    readonly constant?: string;
+    /**
+     * @param reason - Why the contract rejected the transaction.
+     * @param message - Human-readable description.
+     * @param abort - The aborting module and error constant, when known.
+     * @param options - Standard SDK error options.
+     */
+    constructor(reason: UpshiftVaultAbortReason, message: string, abort?: {
+        module?: string;
+        constant?: string;
+    }, options?: UpshiftErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 export declare function isUpshiftSDKError(err: unknown): err is UpshiftSDKError;

package/lib/core/errors/index.js

@@ -16,7 +16,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UpshiftTransactionError = exports.UpshiftPriceUnavailableError = exports.UpshiftHistoryUnavailableError = exports.UpshiftServerError = exports.UpshiftRateLimitError = exports.UpshiftValidationError = exports.UpshiftTimeoutError = exports.UpshiftNetworkError = exports.UpshiftAuthError = exports.UpshiftSDKError = void 0;
+exports.UpshiftVaultAbortError = exports.UpshiftTransactionError = exports.UpshiftPriceUnavailableError = exports.UpshiftHistoryUnavailableError = exports.UpshiftKycError = exports.UpshiftServerError = exports.UpshiftRateLimitError = exports.UpshiftValidationError = exports.UpshiftTimeoutError = exports.UpshiftNetworkError = exports.UpshiftAuthError = exports.UpshiftSDKError = void 0;
 exports.isUpshiftSDKError = isUpshiftSDKError;
 /** Base class for all SDK errors. */
 class UpshiftSDKError extends Error {
@@ -131,6 +131,53 @@ class UpshiftServerError extends UpshiftSDKError {
     }
 }
 exports.UpshiftServerError = UpshiftServerError;
+/**
+ * A KYC API call (`/kyc/challenge`, `/kyc/session`, `/kyc/session/refresh`)
+ * returned a non-2xx status.
+ *
+ * `retryable` means the same action may succeed shortly, but only with a new
+ * challenge: a session nonce is single use.
+ */
+class UpshiftKycError extends UpshiftSDKError {
+    /** HTTP status code returned by the backend. */
+    status;
+    /** The backend's `detail` sentence, or `''` when the body had none. */
+    detail;
+    reason;
+    retryable;
+    /** From `Retry-After` on a 429. */
+    retryAfterMs;
+    constructor(status, detail, reason, options = {}) {
+        super(status === 401
+            ? 'AUTH_UNAUTHORIZED'
+            : status === 403
+                ? 'AUTH_FORBIDDEN'
+                : status === 429
+                    ? 'RATE_LIMITED'
+                    : status >= 500
+                        ? 'SERVER_ERROR'
+                        : 'INVALID_INPUT', `KYC request failed (${status}): ${detail || reason}`, options);
+        this.name = 'UpshiftKycError';
+        this.status = status;
+        this.detail = detail;
+        this.reason = reason;
+        this.retryable =
+            reason === 'enrolment_in_progress' ||
+                reason === 'registry_write_in_progress' ||
+                reason === 'enrolment_timed_out';
+        this.retryAfterMs = options.retryAfterMs;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            status: this.status,
+            detail: this.detail,
+            reason: this.reason,
+            retryable: this.retryable,
+        };
+    }
+}
+exports.UpshiftKycError = UpshiftKycError;
 /**
  * Transaction/position history required to compute a value could not be
  * retrieved or was empty, so the computed result would be wrong rather than
@@ -247,6 +294,52 @@ class UpshiftTransactionError extends UpshiftSDKError {
     }
 }
 exports.UpshiftTransactionError = UpshiftTransactionError;
+/**
+ * A vault contract rejected a transaction, in a dry run before signing or on
+ * chain. `reason` is stable to branch on; `module` and `constant` name the
+ * contract error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.sui.vaultRedeem(params);
+ * } catch (err) {
+ *   if (err instanceof UpshiftVaultAbortError && err.reason === 'queue_attached') {
+ *     // offer a withdrawal request instead
+ *   }
+ * }
+ * ```
+ */
+class UpshiftVaultAbortError extends UpshiftSDKError {
+    /** Why the contract rejected the transaction. */
+    reason;
+    /** Contract module that aborted, e.g. `vault`. */
+    module;
+    /** Contract error constant, e.g. `EPaused`. */
+    constant;
+    /**
+     * @param reason - Why the contract rejected the transaction.
+     * @param message - Human-readable description.
+     * @param abort - The aborting module and error constant, when known.
+     * @param options - Standard SDK error options.
+     */
+    constructor(reason, message, abort = {}, options) {
+        super('VAULT_ABORTED', message, options);
+        this.name = 'UpshiftVaultAbortError';
+        this.reason = reason;
+        this.module = abort.module;
+        this.constant = abort.constant;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            reason: this.reason,
+            module: this.module,
+            constant: this.constant,
+        };
+    }
+}
+exports.UpshiftVaultAbortError = UpshiftVaultAbortError;
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 function isUpshiftSDKError(err) {
     return (err instanceof UpshiftSDKError ||

package/lib/core/fetcher.d.ts

@@ -20,6 +20,11 @@ export type IFetchUpshiftOptions = {
     signal?: AbortSignal;
     /** Per-request timeout in ms. Defaults to `REQUEST_TIMEOUT_MS`. */
     timeoutMs?: number;
+    /**
+     * `fetchUpshiftPublic` only: return a non-2xx response instead of throwing,
+     * so the caller can read the error body.
+     */
+    returnErrorResponse?: boolean;
     /**
      * @deprecated No longer has any effect: an absent `apiKey` already sends an
      * anonymous request. Will be removed in a future major version; drop it.

package/lib/core/fetcher.js

@@ -529,7 +529,7 @@ async function fetchUpshiftPublic(relativeUrl, options) {
         tracked = true;
         const correlationId = readResponseHeader(res.headers, 'x-correlation-id');
         const logger = logger_1.Logger.getLogger();
-        if (!res.ok) {
+        if (!res.ok && !options?.returnErrorResponse) {
             if (correlationId && logger) {
                 logger.setTag('correlation_id', correlationId);
             }

package/lib/core/helpers/chain-support.d.ts

@@ -79,8 +79,8 @@ export declare function assertKnownChainId(chainId: number | undefined, provider
  */
 export declare function assertEvmProviderConfigured(chainId: number | undefined, providers: Partial<Record<number, string>> | undefined, method: string): void;
 /**
- * Throw when a vault read targets Sui, whose vault reads this SDK does not
- * implement yet: either `chainId` is Sui's (`-2`) or `vault` is a Sui object ID
+ * Throw when a read that Sui vaults do not support (loans, allocations)
+ * targets Sui: either `chainId` is Sui's (`-2`) or `vault` is a Sui object ID
  * (`0x` + 64 hex chars), with or without a `chainId`.
  *
  * Call it before any EVM address check. Sui (`-2`) is a known chain, so it

package/lib/core/helpers/chain-support.js

@@ -115,8 +115,8 @@ function assertEvmProviderConfigured(chainId, providers, method) {
         `new UpshiftSDK({ providers: { ${chainId}: '<rpc-url>' } }).`, { context: { method, chainId } });
 }
 /**
- * Throw when a vault read targets Sui, whose vault reads this SDK does not
- * implement yet: either `chainId` is Sui's (`-2`) or `vault` is a Sui object ID
+ * Throw when a read that Sui vaults do not support (loans, allocations)
+ * targets Sui: either `chainId` is Sui's (`-2`) or `vault` is a Sui object ID
  * (`0x` + 64 hex chars), with or without a `chainId`.
  *
  * Call it before any EVM address check. Sui (`-2`) is a known chain, so it
@@ -134,6 +134,6 @@ function assertEvmProviderConfigured(chainId, providers, method) {
 function assertSuiReadsSupported(chainId, vault, method) {
     if (chainId !== web3_1.SUI_CHAIN_ID && !(vault && (0, chain_address_1.isSuiAddress)(vault)))
         return;
-    throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: Sui vault reads are not supported yet (chainId ${web3_1.SUI_CHAIN_ID}).`, { context: { method, chainId } });
+    throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method} is not supported for Sui vaults (chainId ${web3_1.SUI_CHAIN_ID}).`, { context: { method, chainId } });
 }
 //# sourceMappingURL=chain-support.js.map

package/lib/core/helpers/kyc.d.ts

@@ -0,0 +1,47 @@
+import type { IKycRecord, IKycStatus, IKycWalletOptions } from '../../types';
+/**
+ * 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();
+ * ```
+ */
+export declare function getKycStatus({ chainId, wallet, rpcUrl, }: IKycWalletOptions): Promise<IKycStatus>;
+/**
+ * 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);
+ * ```
+ */
+export declare function getKycRecord({ chainId, wallet, rpcUrl, }: IKycWalletOptions): Promise<IKycRecord>;

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