@upshiftfinance/sdk 0.4.0 → 0.5.0

package/lib/adapters/sui/actions.js

@@ -33,9 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SUI_SLIPPAGE_BPS = void 0;
+exports.suiMinOut = suiMinOut;
 exports.suiExecutionErrorToSdkError = suiExecutionErrorToSdkError;
 exports.buildSuiDepositTransaction = buildSuiDepositTransaction;
 exports.buildSuiRedeemTransaction = buildSuiRedeemTransaction;
+exports.buildSuiRequestRedeemTransaction = buildSuiRequestRedeemTransaction;
+exports.buildSuiCancelRedeemRequestTransaction = buildSuiCancelRedeemRequestTransaction;
+exports.buildSuiClaimWithdrawalTransaction = buildSuiClaimWithdrawalTransaction;
 exports.submitSuiTransaction = submitSuiTransaction;
 const errors_1 = require("../../core/errors");
 const chain_address_1 = require("../../core/helpers/chain-address");
@@ -45,6 +50,31 @@ const constants_1 = require("./constants");
 const getters_1 = require("./getters");
 const targets_1 = require("./targets");
 const U64_MAX = 2n ** 64n - 1n;
+/**
+ * Default tolerance below the previewed output: 10 basis points (0.1%).
+ *
+ * Between the dry run and execution the price moves only by rounding (a unit
+ * as other deposits and redemptions land) and by management fee accruing for
+ * a few seconds; 0.1% absorbs both. An operator AUM report can move it by up
+ * to the vault's report bound (percent-level), which this still rejects with
+ * `slippage` rather than fill at a price the user did not see.
+ */
+exports.DEFAULT_SUI_SLIPPAGE_BPS = 10;
+/**
+ * The minimum output for a previewed amount: `expected` less `slippageBps`,
+ * rounded down.
+ * @internal
+ */
+function suiMinOut(expected, slippageBps) {
+    return (expected * BigInt(10_000 - slippageBps)) / 10000n;
+}
+function assertSlippage(bps, method) {
+    if (bps === undefined)
+        return;
+    if (!Number.isInteger(bps) || bps < 0 || bps > 10_000) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: slippageBps must be an integer from 0 to 10000.`);
+    }
+}
 /** Contract errors with a stable SDK reason, keyed `module::constant`. */
 const ABORT_REASONS = {
     'vault::EPaused': 'paused',
@@ -58,16 +88,37 @@ const ABORT_REASONS = {
     'vault::EZeroShares': 'zero_output',
     'vault::EZeroAssets': 'zero_output',
     'versioning::EVersionRetired': 'version_retired',
+    'vault::EQueueNotAttached': 'queue_not_attached',
+    'vault::EInvalidPayout': 'invalid_payout',
+    'vault::ENotRequestOwner': 'not_request_owner',
+    'vault::ENotFinalizer': 'not_finalizer',
+    'vault::ENotEligibleYet': 'not_eligible_yet',
+    'vault::ERequestExpired': 'request_expired',
+    // The request ID was used before: its derived object ID is already claimed.
+    'derived_object::EObjectAlreadyExists': 'request_id_in_use',
 };
 /**
  * Map a failed Sui execution to an SDK error: a contract abort becomes an
  * {@link UpshiftVaultAbortError} with a stable reason, anything else an
  * {@link UpshiftSDKError} (`UNKNOWN`).
  *
+ * The SDK applies this itself to its dry runs and to `executeTransaction`.
+ * Use it when the wallet builds, signs or executes a transaction and fails,
+ * e.g. because the vault changed after the SDK built it.
+ *
  * @param executionError - `effects.status.error` of a failed transaction, or
  *   the `executionError` of a `SimulationError`.
  * @param context - Structured context for the error (e.g. network, digest).
- * @internal
+ * @returns The typed error; throw it or branch on its `reason`.
+ * @example
+ * ```ts
+ * try {
+ *   await dAppKit.signTransaction({ transaction });
+ * } catch (err) {
+ *   if (err?.executionError) throw Sui.actions.suiExecutionErrorToSdkError(err.executionError);
+ *   throw err;
+ * }
+ * ```
  */
 function suiExecutionErrorToSdkError(executionError, context = {}) {
     const abort = executionError?.MoveAbort;
@@ -146,7 +197,11 @@ async function dryRun(config, build, method, onAbort) {
  *
  * RPC cost: one dry run (plus the coin lookup it needs).
  *
- * @param params - Vault, amount, sender and optional minimum shares.
+ * The minimum is the dry run's preview less `slippageBps` (default 0.1%),
+ * unless `minSharesOut` is given.
+ *
+ * @param params - Vault, amount, sender, and optional `minSharesOut` or
+ *   `slippageBps`.
  * @param sui - The SDK's `sui` config; applied only for `params.vault.network`.
  * @returns The unsigned transaction, the shares the dry run minted and the
  *   minimum it enforces.
@@ -163,18 +218,23 @@ async function dryRun(config, build, method, onAbort) {
  *   { vault: ref, amount: 1_000_000n, sender: account.address },
  *   sdkSuiConfig,
  * );
- * const { digest } = await dAppKit.signAndExecuteTransaction({ transaction });
+ * const digest = await submitSuiTransaction(
+ *   await dAppKit.signTransaction({ transaction }),
+ *   'testnet',
+ *   sdkSuiConfig,
+ * );
  * ```
  */
 async function buildSuiDepositTransaction(params, sui) {
     const method = 'buildSuiDepositTransaction';
-    const { vault: ref, amount, sender, minSharesOut } = params;
+    const { vault: ref, amount, sender, minSharesOut, slippageBps } = params;
     assertSender(sender, method);
     if (!(0, chain_address_1.isSuiAddress)(ref?.vaultId)) {
         throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: vault.vaultId must be a Sui object ID.`);
     }
     assertAmount(amount, method, 'amount', true);
     assertAmount(minSharesOut, method, 'minSharesOut', false);
+    assertSlippage(slippageBps, method);
     const config = (0, getters_1.suiConfigForNetwork)(ref.network, sui);
     const contracts = (0, targets_1.resolveSuiVaultContracts)(config);
     const { Transaction: SuiTransaction, coinWithBalance } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/transactions')));
@@ -193,7 +253,8 @@ async function buildSuiDepositTransaction(params, sui) {
     // The preview runs after the fee charge, so it matches the deposit exactly.
     const results = await dryRun(config, async () => compose(0n, true), method);
     const expectedShares = (0, getters_1.decodeSuiUint)(results[1][0], 8);
-    const min = minSharesOut ?? expectedShares;
+    const min = minSharesOut ??
+        suiMinOut(expectedShares, slippageBps ?? exports.DEFAULT_SUI_SLIPPAGE_BPS);
     return {
         transaction: compose(min, false),
         expectedShares,
@@ -201,8 +262,9 @@ async function buildSuiDepositTransaction(params, sui) {
     };
 }
 /**
- * Build an unsigned instant redemption: redeem shares with a minimum net
- * asset amount and send the assets to the sender — one transaction.
+ * Build an unsigned instant redemption: charge the management fee, redeem
+ * shares with a minimum net asset amount and send the assets to the sender —
+ * one transaction.
  *
  * The shares are `coinWithBalance(Share)`. A vault with a withdrawal queue
  * attached has instant redemption off; that fails here with `queue_attached`.
@@ -213,7 +275,11 @@ async function buildSuiDepositTransaction(params, sui) {
  *
  * RPC cost: one dry run (plus the coin lookup it needs).
  *
- * @param params - Vault, shares, sender and optional minimum assets.
+ * The minimum is the dry run's net preview less `slippageBps` (default 0.1%),
+ * unless `minAssetsOut` is given.
+ *
+ * @param params - Vault, shares, sender, and optional `minAssetsOut` or
+ *   `slippageBps`.
  * @param sui - The SDK's `sui` config; applied only for `params.vault.network`.
  * @returns The unsigned transaction, the dry run's gross and net assets and
  *   the minimum it enforces.
@@ -227,13 +293,14 @@ async function buildSuiDepositTransaction(params, sui) {
  */
 async function buildSuiRedeemTransaction(params, sui) {
     const method = 'buildSuiRedeemTransaction';
-    const { vault: ref, shares, sender, minAssetsOut } = params;
+    const { vault: ref, shares, sender, minAssetsOut, slippageBps } = params;
     assertSender(sender, method);
     if (!(0, chain_address_1.isSuiAddress)(ref?.vaultId)) {
         throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: vault.vaultId must be a Sui object ID.`);
     }
     assertAmount(shares, method, 'shares', true);
     assertAmount(minAssetsOut, method, 'minAssetsOut', false);
+    assertSlippage(slippageBps, method);
     const config = (0, getters_1.suiConfigForNetwork)(ref.network, sui);
     const contracts = (0, targets_1.resolveSuiVaultContracts)(config);
     const { Transaction: SuiTransaction, coinWithBalance } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/transactions')));
@@ -241,6 +308,9 @@ async function buildSuiRedeemTransaction(params, sui) {
         const tx = new SuiTransaction();
         tx.setSender(sender);
         const call = vaultCalls(tx, ref, contracts);
+        // As on deposit: charge the accrued management fee first, so the redeemer
+        // pays their share of it instead of leaving it to the remaining holders.
+        call('chargeManagementFee', [tx.object(constants_1.SUI_CLOCK_ID)]);
         if (withPreview) {
             call('previewRedemption', [tx.pure.u64(shares), tx.pure.bool(true)]);
         }
@@ -258,9 +328,11 @@ async function buildSuiRedeemTransaction(params, sui) {
         sharesRaw: shares.toString(),
         error: err.message,
     }));
-    const expectedGrossAssets = (0, getters_1.decodeSuiUint)(results[0][0], 8);
-    const expectedAssets = (0, getters_1.decodeSuiUint)(results[0][1], 8);
-    const min = minAssetsOut ?? expectedAssets;
+    // results[0] is the fee charge; the preview runs after it.
+    const expectedGrossAssets = (0, getters_1.decodeSuiUint)(results[1][0], 8);
+    const expectedAssets = (0, getters_1.decodeSuiUint)(results[1][1], 8);
+    const min = minAssetsOut ??
+        suiMinOut(expectedAssets, slippageBps ?? exports.DEFAULT_SUI_SLIPPAGE_BPS);
     return {
         transaction: compose(min, false),
         expectedGrossAssets,
@@ -268,6 +340,247 @@ async function buildSuiRedeemTransaction(params, sui) {
         minAssetsOut: min,
     };
 }
+function assertVaultId(ref, method) {
+    if (!(0, chain_address_1.isSuiAddress)(ref?.vaultId)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: vault.vaultId must be a Sui object ID.`);
+    }
+}
+function assertAddress(value, method, name) {
+    if (value !== undefined && value !== null && !(0, chain_address_1.isSuiAddress)(value)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: ${name} must be a Sui address (0x + 64 hex chars).`);
+    }
+}
+/**
+ * Build an unsigned withdrawal request for a vault with a withdrawal queue:
+ * escrow the shares in a new request object and share it — one transaction.
+ *
+ * The request is priced when it is claimed, not now. Once the vault's cooldown
+ * has run, claim it with {@link buildSuiClaimWithdrawalTransaction}; it can be
+ * cancelled at any time with {@link buildSuiCancelRedeemRequestTransaction}.
+ *
+ * The request ID is the lowest the wallet has never used on this vault
+ * (`0, 1, 2, …`), which is how `getSuiWithdrawalRequests` finds requests
+ * without an event index. Two requests built before either lands get the same
+ * ID; the second then fails (the node refuses its stale coins, or it aborts
+ * with `request_id_in_use`) — build it again.
+ *
+ * The finalizer defaults to the owner: only the owner can claim during the
+ * first day the request is claimable, then anyone can (e.g. a keeper).
+ *
+ * RPC cost: one object read for the next ID (more after 23 earlier requests),
+ * then one dry run (plus the coin lookup it needs).
+ *
+ * @param params - Vault, shares, sender, and optional `payout` and `finalizer`.
+ * @param sui - The SDK's `sui` config; applied only for `params.vault.network`.
+ * @returns The unsigned transaction, the request ID and the request's object ID.
+ * @throws {@link UpshiftValidationError} for a malformed address, an
+ *   out-of-range amount, unknown contract IDs, or a transaction that cannot be
+ *   built (e.g. the sender lacks the shares).
+ * @throws {@link UpshiftVaultAbortError} when the vault would reject it
+ *   (`queue_not_attached`, `paused`, `above_max_withdrawal`, `invalid_payout`,
+ *   `request_id_in_use`, `version_retired`), or the shares would pay nothing
+ *   (`zero_output`).
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ * @example
+ * ```ts
+ * const { transaction, request } = await buildSuiRequestRedeemTransaction(
+ *   { vault: ref, shares: 1_000_000n, sender: account.address },
+ *   sdkSuiConfig,
+ * );
+ * ```
+ */
+async function buildSuiRequestRedeemTransaction(params, sui) {
+    const method = 'buildSuiRequestRedeemTransaction';
+    const { vault: ref, shares, sender, payout, finalizer } = params;
+    assertSender(sender, method);
+    assertVaultId(ref, method);
+    assertAmount(shares, method, 'shares', true);
+    assertAddress(payout, method, 'payout');
+    assertAddress(finalizer, method, 'finalizer');
+    const config = (0, getters_1.suiConfigForNetwork)(ref.network, sui);
+    const contracts = (0, targets_1.resolveSuiVaultContracts)(config);
+    const { Transaction: SuiTransaction, coinWithBalance } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/transactions')));
+    const requestId = await (0, getters_1.nextSuiWithdrawalRequestId)(ref, sender, sui);
+    const compose = (withPreview) => {
+        const tx = new SuiTransaction();
+        tx.setSender(sender);
+        const call = vaultCalls(tx, ref, contracts);
+        // Priced on a current NAV (fee charged first, in the dry run only).
+        // Queued withdrawals pay no instant fee, so gross is what a claim pays.
+        if (withPreview) {
+            call('chargeManagementFee', [tx.object(constants_1.SUI_CLOCK_ID)]);
+            call('previewRedemption', [tx.pure.u64(shares), tx.pure.bool(false)]);
+        }
+        const escrow = tx.add(coinWithBalance({ type: ref.shareCoinType, balance: shares }));
+        const request = call('requestWithdrawal', [
+            escrow,
+            tx.pure.u64(requestId),
+            tx.pure.address(payout ?? sender),
+            tx.pure.option('address', finalizer === undefined ? sender : finalizer),
+            tx.object(constants_1.SUI_CLOCK_ID),
+        ]);
+        // The contract returns the request unshared; it must be shared in the
+        // same transaction.
+        tx.moveCall({
+            target: (0, targets_1.suiMoveCallTarget)(contracts, 'shareWithdrawalRequest'),
+            typeArguments: [ref.shareCoinType],
+            arguments: [request],
+        });
+        return tx;
+    };
+    const results = await dryRun(config, async () => compose(true), method);
+    // results[0] is the fee charge.
+    const expectedAssets = (0, getters_1.decodeSuiUint)(results[1][0], 8);
+    // The contract accepts a request whose claim would pay nothing (shares worth
+    // less than one asset unit); it could then only be cancelled.
+    if (expectedAssets === 0n) {
+        throw new errors_1.UpshiftVaultAbortError('zero_output', `${method}: ${shares} shares pay no assets at the current price; request more.`, {}, { context: { network: ref.network, method } });
+    }
+    return {
+        transaction: compose(false),
+        requestId,
+        expectedAssets,
+        request: await (0, getters_1.deriveSuiWithdrawalRequestId)(ref.vaultId, sender, requestId, contracts.originalPackageId),
+    };
+}
+/**
+ * Build an unsigned cancellation of a pending withdrawal request: the escrowed
+ * shares go back to the sender — one transaction.
+ *
+ * Allowed at any time while the request exists, also while the vault is
+ * paused or after the request expired. Only the wallet that made it may.
+ *
+ * RPC cost: one dry run.
+ *
+ * @param params - Vault, request object ID and sender.
+ * @param sui - The SDK's `sui` config; applied only for `params.vault.network`.
+ * @returns The unsigned transaction and the shares it returns.
+ * @throws {@link UpshiftValidationError} for a malformed address, unknown
+ *   contract IDs, or a transaction that cannot be built (e.g. the request no
+ *   longer exists).
+ * @throws {@link UpshiftVaultAbortError} when the vault would reject it
+ *   (`not_request_owner`, `version_retired`).
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ * @example
+ * ```ts
+ * const { transaction } = await buildSuiCancelRedeemRequestTransaction(
+ *   { vault: ref, request, sender: account.address },
+ *   sdkSuiConfig,
+ * );
+ * ```
+ */
+async function buildSuiCancelRedeemRequestTransaction(params, sui) {
+    const method = 'buildSuiCancelRedeemRequestTransaction';
+    const { vault: ref, request, sender } = params;
+    assertSender(sender, method);
+    assertVaultId(ref, method);
+    if (!(0, chain_address_1.isSuiAddress)(request)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: request must be a Sui object ID.`);
+    }
+    const config = (0, getters_1.suiConfigForNetwork)(ref.network, sui);
+    const contracts = (0, targets_1.resolveSuiVaultContracts)(config);
+    const { Transaction: SuiTransaction } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/transactions')));
+    const compose = () => {
+        const tx = new SuiTransaction();
+        tx.setSender(sender);
+        const call = vaultCalls(tx, ref, contracts);
+        const shares = call('cancelWithdrawal', [tx.object(request)]);
+        tx.transferObjects([shares], sender);
+        return tx;
+    };
+    const results = await dryRun(config, async () => compose(), method);
+    // The returned Coin<Share> is a 32-byte UID followed by its u64 balance.
+    const coin = results[0][0];
+    return {
+        transaction: compose(),
+        shares: (0, getters_1.decodeSuiUint)(coin.subarray(32), 8),
+    };
+}
+/**
+ * Build an unsigned claim of a withdrawal request: charge the management fee,
+ * then burn the escrowed shares and pay their current value to the request's
+ * payout, with a minimum — one transaction.
+ *
+ * The payout lands in the payout address's **address balance**, not as a
+ * coin object. Balance reads (`getBalance`) include it; wallets that only
+ * list coin objects may not show it.
+ *
+ * The request is priced now, at the vault's current share price, without the
+ * instant-redemption fee. It can be claimed from `eligibleAtMs` until
+ * `expiresAtMs`, by its owner, its finalizer (anyone when it names none), and
+ * by anyone from one day after it became eligible.
+ *
+ * RPC cost: one dry run.
+ *
+ * @param params - Vault, request object ID, sender, and optional
+ *   `minAssetsOut` or `slippageBps`.
+ * @param sui - The SDK's `sui` config; applied only for `params.vault.network`.
+ * @returns The unsigned transaction, the shares it burns, the dry run's
+ *   payout and the minimum it enforces.
+ * @throws {@link UpshiftValidationError} for a malformed address, an
+ *   out-of-range minimum, unknown contract IDs, or a transaction that cannot
+ *   be built (e.g. the request no longer exists).
+ * @throws {@link UpshiftVaultAbortError} when the vault would reject it
+ *   (`not_eligible_yet`, `request_expired`, `not_finalizer`, `paused`,
+ *   `above_max_withdrawal`, `insufficient_liquidity`, `zero_output`,
+ *   `slippage`, `version_retired`).
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ * @example
+ * ```ts
+ * const { transaction, expectedAssets } = await buildSuiClaimWithdrawalTransaction(
+ *   { vault: ref, request, sender: account.address },
+ *   sdkSuiConfig,
+ * );
+ * ```
+ */
+async function buildSuiClaimWithdrawalTransaction(params, sui) {
+    const method = 'buildSuiClaimWithdrawalTransaction';
+    const { vault: ref, request, sender, minAssetsOut, slippageBps } = params;
+    assertSender(sender, method);
+    assertVaultId(ref, method);
+    if (!(0, chain_address_1.isSuiAddress)(request)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: request must be a Sui object ID.`);
+    }
+    assertAmount(minAssetsOut, method, 'minAssetsOut', false);
+    assertSlippage(slippageBps, method);
+    const config = (0, getters_1.suiConfigForNetwork)(ref.network, sui);
+    const contracts = (0, targets_1.resolveSuiVaultContracts)(config);
+    const { Transaction: SuiTransaction } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/transactions')));
+    const compose = (min, withPreview) => {
+        const tx = new SuiTransaction();
+        tx.setSender(sender);
+        const call = vaultCalls(tx, ref, contracts);
+        // Charge the accrued management fee first, as on deposit and redeem, so
+        // the claim is priced on the current NAV.
+        call('chargeManagementFee', [tx.object(constants_1.SUI_CLOCK_ID)]);
+        if (withPreview) {
+            const shares = tx.moveCall({
+                target: (0, targets_1.suiMoveCallTarget)(contracts, 'withdrawalRequestShares'),
+                typeArguments: [ref.shareCoinType],
+                arguments: [tx.object(request)],
+            });
+            call('previewRedemption', [shares, tx.pure.bool(false)]);
+        }
+        call('finalizeWithdrawalChecked', [
+            tx.object(request),
+            tx.pure.u64(min),
+            tx.object(constants_1.SUI_CLOCK_ID),
+        ]);
+        return tx;
+    };
+    // results[0] is the fee charge, [1] the escrowed shares, [2] the preview.
+    const results = await dryRun(config, async () => compose(0n, true), method);
+    const shares = (0, getters_1.decodeSuiUint)(results[1][0], 8);
+    const expectedAssets = (0, getters_1.decodeSuiUint)(results[2][1], 8);
+    const min = minAssetsOut ??
+        suiMinOut(expectedAssets, slippageBps ?? exports.DEFAULT_SUI_SLIPPAGE_BPS);
+    return {
+        transaction: compose(min, false),
+        shares,
+        expectedAssets,
+        minAssetsOut: min,
+    };
+}
 /**
  * The vault, sender and share amount of an instant redemption in a built
  * transaction, for the curator alert; `null` when it is not one.
@@ -331,7 +644,13 @@ async function submitSuiTransaction(signed, network, sui) {
     const networkConfig = (0, client_1.resolveSuiNetworkConfig)(config);
     const { Transaction: SuiTransaction } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/transactions')));
     const { fromBase64 } = await Promise.resolve().then(() => __importStar(require('@mysten/sui/utils')));
-    const bytes = fromBase64(signed.bytes);
+    let bytes;
+    try {
+        bytes = fromBase64(signed.bytes);
+    }
+    catch (err) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', 'submitSuiTransaction: bytes is not valid base64.', { cause: err });
+    }
     // Executing the same signed bytes twice is idempotent, so endpoint failover is safe.
     const result = await (0, client_1.withSuiClient)(networkConfig, (client) => client.core.executeTransaction({
         transaction: bytes,

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

@@ -1,4 +1,4 @@
-import type { ISuiConfig, ISuiNetwork, ITokenizedVault, IVault } from '../../types';
+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 {
@@ -134,6 +134,108 @@ export declare function previewSuiRedemption(ref: ISuiVaultRef, shares: bigint,
  * @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`.
@@ -153,7 +255,7 @@ export declare function buildSuiVault(row: ITokenizedVault, state: ISuiVaultStat
  *
  * A failed read (unknown contract IDs, every endpoint down, an aborted
  * simulation) does not fail the call: the vault is built from the backend row
- * alone (see {@link buildSuiVault}) and a warning is logged.
+ * alone (see `buildSuiVault`) and a warning is logged.
  *
  * RPC cost: as {@link readSuiVaultState}.
  *