@upshiftfinance/sdk 0.3.0 → 0.5.0

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

@@ -43,7 +43,7 @@ export declare function suiEndpointHost(url: string): string;
  *
  * @param err - What the call rejected with.
  * @returns `true` for transport failures, gRPC statuses in
- *   {@link RETRYABLE_GRPC_CODES}, a bare `NOT_FOUND` (the endpoint has no Sui
+ *   `RETRYABLE_GRPC_CODES`, a bare `NOT_FOUND` (the endpoint has no Sui
  *   gRPC service at that path) and the SDK's own call timeout.
  * @internal
  */
@@ -58,8 +58,8 @@ export declare function setSuiClientFactoryForTests(factory: SuiClientFactory |
  * Run a Sui call against the first endpoint that answers.
  *
  * Endpoints are tried in order, starting with the one that last worked (for
- * {@link PREFERRED_ENDPOINT_TTL_MS}). An endpoint failure — see
- * {@link isRetryableSuiError} — moves on to the next endpoint; any other error
+ * `PREFERRED_ENDPOINT_TTL_MS`). An endpoint failure — see
+ * `isRetryableSuiError` — moves on to the next endpoint; any other error
  * is thrown at once. Each attempt is bounded by a 15 s timeout.
  *
  * Worst case: one attempt per endpoint (two with a consumer `rpcUrl`).

package/lib/adapters/sui/client.js

@@ -99,7 +99,7 @@ function suiEndpointHost(url) {
  *
  * @param err - What the call rejected with.
  * @returns `true` for transport failures, gRPC statuses in
- *   {@link RETRYABLE_GRPC_CODES}, a bare `NOT_FOUND` (the endpoint has no Sui
+ *   `RETRYABLE_GRPC_CODES`, a bare `NOT_FOUND` (the endpoint has no Sui
  *   gRPC service at that path) and the SDK's own call timeout.
  * @internal
  */
@@ -115,14 +115,29 @@ function isRetryableSuiError(err) {
         return false;
     if (RETRYABLE_GRPC_CODES.has(code))
         return true;
-    // A path with no gRPC service answers HTTP 404, which the transport reports
-    // as NOT_FOUND with no message; a missing object is a different error type.
-    return code === 'NOT_FOUND' && err.message === '';
+    // An endpoint with no Sui gRPC service at that path answers a bare HTTP 404
+    // or 400. The transport reports those as NOT_FOUND / INVALID_ARGUMENT whose
+    // message is the HTTP status text ('' over HTTP/2, the reason phrase over
+    // HTTP/1.1). Errors from the Sui service itself carry their own message.
+    return ((code === 'NOT_FOUND' &&
+        (err.message === '' || err.message === 'Not Found')) ||
+        (code === 'INVALID_ARGUMENT' && err.message === 'Bad Request'));
 }
-/** Default factory: loads `@mysten/sui/grpc` on first use. */
+/**
+ * Default factory: loads `@mysten/sui/grpc` on first use. A failure to load
+ * the module is about the runtime, not the endpoint, so it is thrown as an
+ * SDK error that {@link withSuiClient} does not retry: in Node.js, requiring
+ * the ESM-only package needs `^20.19 || >=22.12`.
+ */
 const defaultClientFactory = async (baseUrl, network) => {
-    const { SuiGrpcClient } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/grpc')));
-    return new SuiGrpcClient({ baseUrl, network });
+    let grpc;
+    try {
+        grpc = await Promise.resolve().then(() => __importStar(require('@mysten/sui/grpc')));
+    }
+    catch (err) {
+        throw new errors_1.UpshiftSDKError('UNKNOWN', `Sui support could not load @mysten/sui — in Node.js it needs version ^20.19 or >=22.12: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    return new grpc.SuiGrpcClient({ baseUrl, network });
 };
 let clientFactory = defaultClientFactory;
 const clientCache = new Map();
@@ -151,8 +166,8 @@ function clientFor(url, network) {
  * Run a Sui call against the first endpoint that answers.
  *
  * Endpoints are tried in order, starting with the one that last worked (for
- * {@link PREFERRED_ENDPOINT_TTL_MS}). An endpoint failure — see
- * {@link isRetryableSuiError} — moves on to the next endpoint; any other error
+ * `PREFERRED_ENDPOINT_TTL_MS`). An endpoint failure — see
+ * `isRetryableSuiError` — moves on to the next endpoint; any other error
  * is thrown at once. Each attempt is bounded by a 15 s timeout.
  *
  * Worst case: one attempt per endpoint (two with a consumer `rpcUrl`).
@@ -185,6 +200,9 @@ async function withSuiClient(config, call) {
             client = await clientFor(url, config.network);
         }
         catch (err) {
+            // The SDK could not load its Sui client at all: no endpoint can help.
+            if (err instanceof errors_1.UpshiftSDKError)
+                throw err;
             // A malformed endpoint (e.g. a typo'd consumer rpcUrl) must not disable
             // the endpoints behind it.
             lastError = err;

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

@@ -0,0 +1,268 @@
+import { type ISuiConfig, type ISuiNetwork, type ITokenizedVault, type IVault, type IVaultAvailableRedemption } from '../../types';
+import type { IVaultBaseOptions } from '../../modules/vaults/types';
+/** The vault a read is for: its object ID, coin types and network. */
+export interface ISuiVaultRef {
+    /** Vault object ID (`0x` + 64 hex chars). */
+    vaultId: string;
+    /** Move type of the deposit coin. */
+    assetCoinType: string;
+    /** Move type of the vault's share coin. */
+    shareCoinType: string;
+    /** Network the vault lives on. */
+    network: ISuiNetwork;
+}
+/**
+ * A vault's on-chain state. Amounts are raw base units: assets in the deposit
+ * coin's decimals, shares in {@link ISuiVaultState.decimals} (the contract
+ * requires the share coin to use the deposit coin's decimals).
+ */
+export interface ISuiVaultState {
+    /** Net assets: idle + deployed AUM − collectable fees, floored at 0. */
+    totalAssets: bigint;
+    /** Minted shares, including shares escrowed in withdrawal requests. */
+    totalSupply: bigint;
+    /** Asset base units per `10^decimals` shares. */
+    sharePrice: bigint;
+    /** Share (and deposit coin) decimals. */
+    decimals: number;
+    /** Deposits, redemptions and new requests abort while paused. */
+    paused: boolean;
+    /** Whether a withdrawal queue is attached; instant `redeem` is off when it is. */
+    queueAttached: boolean;
+    /** Smallest accepted deposit, in asset base units. */
+    minDeposit: bigint;
+    /** Ceiling on total assets after a deposit, in asset base units. */
+    depositCap: bigint;
+    /** Largest single deposit, in asset base units. */
+    maxDepositAmount: bigint;
+    /** Largest single gross withdrawal, in asset base units. */
+    maxWithdrawalAmount: bigint;
+    /** Fee charged by instant `redeem`, in basis points of the gross amount. */
+    instantRedemptionFeeBps: number;
+}
+/**
+ * Decode a little-endian BCS unsigned integer of `size` bytes.
+ * @internal
+ */
+export declare function decodeSuiUint(bytes: Uint8Array, size: number): bigint;
+/**
+ * Decode a BCS `bool`.
+ * @internal
+ */
+export declare function decodeSuiBool(bytes: Uint8Array): boolean;
+/**
+ * Read the instant-redemption fee from the vault object's JSON fields: the fee
+ * sits in a nested struct that a transaction cannot return.
+ * @internal
+ */
+export declare function parseInstantRedemptionFeeBps(json: unknown): number;
+/**
+ * The `sui` config to use for a vault on `network`: the consumer's config when
+ * it is for that network, else the network alone (built-in endpoint and
+ * contract IDs). A testnet override must never serve a mainnet vault.
+ * @internal
+ */
+export declare function suiConfigForNetwork(network: ISuiNetwork, sui?: ISuiConfig): ISuiConfig;
+/**
+ * Read a vault's on-chain state.
+ *
+ * RPC cost: two requests, run in parallel: one transaction simulation and one
+ * object read. `getVaults` makes these two per Sui vault.
+ *
+ * @param ref - The vault and its coin types and network.
+ * @param sui - The SDK's `sui` config; applied only when its network matches
+ *   `ref.network`.
+ * @returns The vault's state; see {@link ISuiVaultState} for units.
+ * @throws {@link UpshiftValidationError} (`INVALID_ADDRESS`) for a malformed
+ *   vault ID, (`INVALID_INPUT`) when the contract IDs for the network are not
+ *   known or the simulation aborts (wrong vault, coin types or package).
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ * @example
+ * ```ts
+ * const state = await readSuiVaultState(
+ *   { vaultId, assetCoinType, shareCoinType, network: 'testnet' },
+ *   { network: 'testnet', packageId, originalPackageId, registryId },
+ * );
+ * ```
+ */
+export declare function readSuiVaultState(ref: ISuiVaultRef, sui?: ISuiConfig): Promise<ISuiVaultState>;
+/**
+ * Shares a deposit would mint at the current price. Limits are not checked.
+ *
+ * RPC cost: one transaction simulation.
+ *
+ * @param ref - The vault and its coin types and network.
+ * @param assets - Deposit amount in asset base units.
+ * @param sui - The SDK's `sui` config; applied only for `ref.network`.
+ * @returns Shares in share base units.
+ * @throws {@link UpshiftValidationError} for a malformed vault ID, a negative
+ *   or out-of-range amount, unknown contract IDs or an aborted simulation.
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+export declare function previewSuiDeposit(ref: ISuiVaultRef, assets: bigint, sui?: ISuiConfig): Promise<bigint>;
+/**
+ * Assets a redemption of `shares` would pay at the current price.
+ *
+ * RPC cost: one transaction simulation.
+ *
+ * @param ref - The vault and its coin types and network.
+ * @param shares - Shares to redeem, in share base units.
+ * @param isInstant - `true` for instant `redeem` (charges the instant fee),
+ *   `false` for a queued withdrawal (no fee).
+ * @param sui - The SDK's `sui` config; applied only for `ref.network`.
+ * @returns `gross` and `net` (after the instant fee) in asset base units.
+ * @throws {@link UpshiftValidationError} for a malformed vault ID, a negative
+ *   or out-of-range amount, unknown contract IDs or an aborted simulation.
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+export declare function previewSuiRedemption(ref: ISuiVaultRef, shares: bigint, isInstant: boolean, sui?: ISuiConfig): Promise<{
+    gross: bigint;
+    net: bigint;
+}>;
+/**
+ * A wallet's balance of a share coin: coin objects plus the address balance.
+ *
+ * RPC cost: one balance read.
+ *
+ * @param owner - Wallet address (`0x` + 64 hex chars).
+ * @param shareCoinType - Move type of the vault's share coin.
+ * @param network - Network to read.
+ * @param sui - The SDK's `sui` config; applied only for `network`.
+ * @returns Shares in share base units.
+ * @throws {@link UpshiftValidationError} (`INVALID_ADDRESS`) for a malformed
+ *   owner.
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+export declare function getSuiShareBalance(owner: string, shareCoinType: string, network: ISuiNetwork, sui?: ISuiConfig): Promise<bigint>;
+/**
+ * A pending withdrawal request: shares escrowed in a queued vault, waiting to
+ * be claimed or cancelled. Times are Unix milliseconds from the chain's clock.
+ */
+export interface ISuiWithdrawalRequest {
+    /** Request object ID; pass it as `request` to claim or cancel. */
+    request: string;
+    /** The wallet's numeric ID for the request on this vault (`0, 1, 2, …`). */
+    requestId: bigint;
+    /** Wallet that made the request; the only one that may cancel it. */
+    owner: string;
+    /** Escrowed shares, in share base units. Priced when the request is claimed. */
+    shares: bigint;
+    /** Address the claim pays, into its address balance. */
+    payout: string;
+    /**
+     * The one address besides the owner that may claim, or `null` when anyone
+     * may. From one day after `eligibleAtMs` anyone may claim either way.
+     */
+    finalizer: string | null;
+    /** When the request was made. */
+    requestedAtMs: number;
+    /** When the cooldown ends and the request can be claimed. */
+    eligibleAtMs: number;
+    /**
+     * When the request stops being claimable (it can still be cancelled), or
+     * `null` when it never expires.
+     */
+    expiresAtMs: number | null;
+}
+/**
+ * A wallet's pending withdrawal requests on a vault, oldest first.
+ *
+ * Finds the requests the SDK made (see `buildSuiRequestRedeemTransaction`),
+ * however old: requests made outside the SDK with non-sequential IDs are not
+ * listed. Claimed and cancelled requests no longer exist and are left out.
+ *
+ * RPC cost: one object read for a wallet that has made up to 23 requests on
+ * the vault (most wallets), one more per further 25.
+ *
+ * @param ref - The vault and its coin types and network.
+ * @param owner - Wallet that made the requests (`0x` + 64 hex chars).
+ * @param sui - The SDK's `sui` config; applied only for `ref.network`.
+ * @returns The pending requests; empty when there are none.
+ * @throws {@link UpshiftValidationError} (`INVALID_ADDRESS`) for a malformed
+ *   vault ID or owner, (`INVALID_INPUT`) for unknown contract IDs, or a vault
+ *   ID that is not a vault of the configured `sui.originalPackageId`.
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails, or the
+ *   node cannot answer for one of the objects.
+ * @example
+ * ```ts
+ * const pending = await getSuiWithdrawalRequests(ref, account.address, sdkSuiConfig);
+ * const now = Date.now();
+ * const claimable = pending.filter(
+ *   (r) => r.eligibleAtMs <= now && (r.expiresAtMs === null || now < r.expiresAtMs),
+ * );
+ * ```
+ */
+export declare function getSuiWithdrawalRequests(ref: ISuiVaultRef, owner: string, sui?: ISuiConfig): Promise<ISuiWithdrawalRequest[]>;
+/**
+ * Split a wallet's withdrawal requests into position redemptions, the way
+ * the EVM and Solana paths do: `availableRedemptions` holds requests still in
+ * their cooldown or past their window (cancel-only), `pendingRedemptions` the
+ * ones claimable now. Each entry's `amount` is the escrowed shares; `date` is
+ * when it becomes claimable, `timestamp` when it was made (Unix seconds).
+ * @internal
+ */
+export declare function suiPositionRedemptions(requests: readonly ISuiWithdrawalRequest[], vault: string, decimals: number, nowMs: number): {
+    availableRedemptions: IVaultAvailableRedemption[];
+    pendingRedemptions: IVaultAvailableRedemption[];
+};
+/**
+ * A wallet's withdrawal requests on a vault as position redemptions (see
+ * {@link suiPositionRedemptions}). Empty when the SDK has no contract IDs for
+ * the network: the share balance can still be read without them, so a
+ * position should not fail for that.
+ *
+ * RPC cost: as {@link getSuiWithdrawalRequests}; none without contract IDs.
+ * @internal
+ */
+export declare function getSuiPositionRedemptions(ref: ISuiVaultRef, owner: string, decimals: number, sui?: ISuiConfig): Promise<ReturnType<typeof suiPositionRedemptions>>;
+/**
+ * The request ID a wallet's next withdrawal request on a vault takes: the
+ * lowest it has never used.
+ *
+ * RPC cost: as {@link getSuiWithdrawalRequests}.
+ * @internal
+ */
+export declare function nextSuiWithdrawalRequestId(ref: ISuiVaultRef, owner: string, sui?: ISuiConfig): Promise<bigint>;
+/**
+ * The object ID of a wallet's withdrawal request: derived from the vault, the
+ * owner and the request ID, as the contract derives it.
+ *
+ * @param vaultId - Vault object ID.
+ * @param owner - Wallet that made the request.
+ * @param requestId - The wallet's numeric request ID on the vault.
+ * @param originalPackageId - The original `upshift_vault` package, which
+ *   names the derivation key type.
+ * @returns The request object ID.
+ * @internal
+ */
+export declare function deriveSuiWithdrawalRequestId(vaultId: string, owner: string, requestId: bigint, originalPackageId: string): Promise<string>;
+/**
+ * The vault reference for a backend row, or `null` when the row has no usable
+ * `sui_vault_metadata`.
+ * @internal
+ */
+export declare function suiVaultRefFromRow(row: ITokenizedVault): ISuiVaultRef | null;
+/**
+ * Build the SDK's `IVault` for a Sui vault from its backend row and, when the
+ * read succeeded, its on-chain state. Without state, total assets fall back
+ * to the backend's `latest_reported_tvl`, supply to zero, and the vault is
+ * marked deposit-paused so no deposit is offered on unread state.
+ * @internal
+ */
+export declare function buildSuiVault(row: ITokenizedVault, state: ISuiVaultState | null): IVault;
+/**
+ * Build a Sui vault's `IVault` from its backend row plus on-chain state.
+ *
+ * A failed read (unknown contract IDs, every endpoint down, an aborted
+ * simulation) does not fail the call: the vault is built from the backend row
+ * alone (see `buildSuiVault`) and a warning is logged.
+ *
+ * RPC cost: as {@link readSuiVaultState}.
+ *
+ * @param row - Backend `tokenized_vault` row with `sui_vault_metadata`.
+ * @param options - Vault options; `options.sui` carries the SDK's `sui` config.
+ * @returns The vault.
+ * @throws {@link UpshiftValidationError} (`INVALID_INPUT`) when the row has no
+ *   usable `sui_vault_metadata` (e.g. a legacy Ember/Gamma Sui vault).
+ */
+export declare function getSuiVault(row: ITokenizedVault, options?: IVaultBaseOptions): Promise<IVault>;