@upshiftfinance/sdk 0.4.0 → 0.5.0

package/lib/adapters/sui/getters.js

@@ -41,15 +41,32 @@ exports.readSuiVaultState = readSuiVaultState;
 exports.previewSuiDeposit = previewSuiDeposit;
 exports.previewSuiRedemption = previewSuiRedemption;
 exports.getSuiShareBalance = getSuiShareBalance;
+exports.getSuiWithdrawalRequests = getSuiWithdrawalRequests;
+exports.suiPositionRedemptions = suiPositionRedemptions;
+exports.getSuiPositionRedemptions = getSuiPositionRedemptions;
+exports.nextSuiWithdrawalRequestId = nextSuiWithdrawalRequestId;
+exports.deriveSuiWithdrawalRequestId = deriveSuiWithdrawalRequestId;
 exports.suiVaultRefFromRow = suiVaultRefFromRow;
 exports.buildSuiVault = buildSuiVault;
 exports.getSuiVault = getSuiVault;
+const types_1 = require("../../types");
 const core_1 = require("../../core");
+const errors_1 = require("../../core/errors");
 const chain_address_1 = require("../../core/helpers/chain-address");
 const utils_1 = require("../../modules/vaults/utils");
 const client_1 = require("./client");
 const constants_1 = require("./constants");
 const targets_1 = require("./targets");
+/**
+ * Re-throw a failed read as a typed SDK error: SDK errors pass through, and
+ * anything else (an object that does not exist, a malformed coin type, a
+ * package that is not the vault package) becomes `INVALID_INPUT`.
+ */
+function asReadError(err, network) {
+    if (err instanceof core_1.UpshiftSDKError)
+        throw err;
+    throw new core_1.UpshiftValidationError('INVALID_INPUT', `Sui read failed — check the vault ID, its coin types and the contract IDs for this network: ${err instanceof Error ? err.message : String(err)}`, { cause: err, context: { network } });
+}
 /** Simulations need a sender; no signature or gas is involved. */
 const SIMULATION_SENDER = `0x${'0'.repeat(64)}`;
 /** The contract's "no limit" value for `u64` caps. */
@@ -136,6 +153,17 @@ async function simulateVaultReads(ref, sui, calls) {
         // Built per attempt: building resolves object versions against this client.
         const tx = new SuiTransaction();
         tx.setSender(SIMULATION_SENDER);
+        // Charge the management fee accrued since the last charge first, so every
+        // read sees the current NAV. A simulation persists nothing.
+        tx.moveCall({
+            target: (0, targets_1.suiMoveCallTarget)(contracts, 'chargeManagementFee'),
+            typeArguments,
+            arguments: [
+                tx.object(ref.vaultId),
+                tx.object(contracts.registryId),
+                tx.object(constants_1.SUI_CLOCK_ID),
+            ],
+        });
         for (const call of calls) {
             tx.moveCall({
                 target: (0, targets_1.suiMoveCallTarget)(contracts, call.target),
@@ -159,8 +187,11 @@ async function simulateVaultReads(ref, sui, calls) {
                 },
             });
         }
-        return result.commandResults.map((c) => c.returnValues.map((v) => v.bcs));
-    });
+        // Drop the fee charge's (empty) result so indexes match `calls`.
+        return result.commandResults
+            .slice(1)
+            .map((c) => c.returnValues.map((v) => v.bcs));
+    }).catch((err) => asReadError(err, ref.network));
 }
 /**
  * Read a vault's on-chain state.
@@ -192,7 +223,7 @@ async function readSuiVaultState(ref, sui) {
             target,
             registry: NEEDS_REGISTRY.has(target),
         }))),
-        (0, client_1.withSuiClient)((0, client_1.resolveSuiNetworkConfig)(config), (client) => client.core.getObject({ objectId: ref.vaultId, include: { json: true } })),
+        (0, client_1.withSuiClient)((0, client_1.resolveSuiNetworkConfig)(config), (client) => client.core.getObject({ objectId: ref.vaultId, include: { json: true } })).catch((err) => asReadError(err, ref.network)),
     ]);
     const at = (i) => {
         const bytes = values[i]?.[0];
@@ -294,9 +325,256 @@ async function getSuiShareBalance(owner, shareCoinType, network, sui) {
         throw new core_1.UpshiftValidationError('INVALID_ADDRESS', 'getSuiShareBalance: owner must be a Sui address (0x + 64 hex chars).');
     }
     const config = suiConfigForNetwork(network, sui);
-    const { balance } = await (0, client_1.withSuiClient)((0, client_1.resolveSuiNetworkConfig)(config), (client) => client.core.getBalance({ owner, coinType: shareCoinType }));
+    const { balance } = await (0, client_1.withSuiClient)((0, client_1.resolveSuiNetworkConfig)(config), (client) => client.core.getBalance({ owner, coinType: shareCoinType })).catch((err) => asReadError(err, network));
     return BigInt(balance.balance);
 }
+/**
+ * IDs checked per object read: each needs its claim marker and its request,
+ * and the gRPC client sends at most 50 objects per request. The first page
+ * also carries the vault object, so it checks one ID fewer.
+ */
+const REQUEST_SCAN_PAGE = 25;
+/**
+ * Walk a wallet's request IDs on a vault, `0, 1, 2, …`, and read each one.
+ *
+ * The contract derives a request's object ID from (vault, owner, request ID)
+ * and leaves a permanent claim marker on the vault for every ID ever used,
+ * also after the request is claimed or cancelled. The SDK numbers requests
+ * sequentially, so the first ID without a marker is the next one to use, and
+ * every request below it that still exists is pending. This needs neither an
+ * event index (public fullnodes keep about two weeks of events) nor an
+ * indexer.
+ *
+ * Requests made outside the SDK with other IDs are not found.
+ *
+ * The first read also checks that `ref.vaultId` is a vault of the configured
+ * original package, so a wrong vault ID or `sui.originalPackageId` (which
+ * names the request IDs) fails loudly instead of finding nothing.
+ *
+ * RPC cost: one object read for up to 23 used IDs, one more per further 25.
+ */
+async function scanSuiWithdrawalRequests(ref, owner, sui) {
+    const config = suiConfigForNetwork(ref.network, sui);
+    const contracts = (0, targets_1.resolveSuiVaultContracts)(config);
+    const [{ bcs }, { deriveDynamicFieldID }] = await Promise.all([
+        Promise.resolve().then(() => __importStar(require('@mysten/sui/bcs'))),
+        Promise.resolve().then(() => __importStar(require('@mysten/sui/utils'))),
+    ]);
+    const WithdrawalRequest = bcs.struct('WithdrawalRequest', {
+        id: bcs.Address,
+        vaultId: bcs.Address,
+        owner: bcs.Address,
+        requestId: bcs.u64(),
+        shares: bcs.u64(),
+        payout: bcs.Address,
+        finalizer: bcs.option(bcs.Address),
+        requestedAtMs: bcs.u64(),
+        eligibleAtMs: bcs.u64(),
+        expiresAtMs: bcs.option(bcs.u64()),
+    });
+    const requests = [];
+    for (let start = 0n;;) {
+        const first = start === 0n;
+        const size = first ? REQUEST_SCAN_PAGE - 1 : REQUEST_SCAN_PAGE;
+        const ids = Array.from({ length: size }, (_, i) => start + BigInt(i));
+        start += BigInt(size);
+        const requestIds = await Promise.all(ids.map((requestId) => deriveSuiWithdrawalRequestId(ref.vaultId, owner, requestId, contracts.originalPackageId)));
+        // The marker is a dynamic field on the vault keyed by the request ID.
+        const markerIds = requestIds.map((id) => deriveDynamicFieldID(ref.vaultId, '0x2::derived_object::Claimed', bcs.Address.serialize(id).toBytes()));
+        const { objects } = await (0, client_1.withSuiClient)((0, client_1.resolveSuiNetworkConfig)(config), (client) => client.core.getObjects({
+            objectIds: [
+                ...markerIds,
+                ...requestIds,
+                ...(first ? [ref.vaultId] : []),
+            ],
+            include: { content: true },
+        })).catch((err) => asReadError(err, ref.network));
+        const missing = (o) => {
+            if (!(o instanceof Error))
+                return false;
+            const reason = o.reason;
+            if (reason === 'notFound' || reason === 'deleted')
+                return true;
+            // Any other per-object error means the node did not answer for it.
+            throw new errors_1.UpshiftNetworkError(`Sui read: withdrawal request lookup failed: ${o.message}`, { cause: o, context: { network: ref.network } });
+        };
+        if (first) {
+            const vault = objects[2 * size];
+            // A missing vault is a wrong ID; any other per-object error is the node.
+            assertVaultOfPackage(missing(vault) ? undefined : vault, ref, contracts);
+        }
+        for (let i = 0; i < size; i += 1) {
+            if (missing(objects[i])) {
+                return { nextRequestId: ids[i], requests };
+            }
+            const object = objects[size + i];
+            // Claimed but gone: the request was claimed or cancelled.
+            if (missing(object) || object instanceof Error)
+                continue;
+            const parsed = WithdrawalRequest.parse(object.content);
+            requests.push({
+                request: requestIds[i],
+                requestId: BigInt(parsed.requestId),
+                owner: parsed.owner,
+                shares: BigInt(parsed.shares),
+                payout: parsed.payout,
+                finalizer: parsed.finalizer ?? null,
+                requestedAtMs: Number(parsed.requestedAtMs),
+                eligibleAtMs: Number(parsed.eligibleAtMs),
+                expiresAtMs: parsed.expiresAtMs == null ? null : Number(parsed.expiresAtMs),
+            });
+        }
+    }
+}
+/**
+ * Throw unless `object` is the vault `ref` names, typed by the configured
+ * original package: request IDs are derived from that package, so a wrong one
+ * would make every request invisible.
+ */
+function assertVaultOfPackage(object, ref, contracts) {
+    const type = object instanceof Error ? undefined : object?.type;
+    const expected = `${contracts.originalPackageId}::vault::Vault<`.toLowerCase();
+    if (!type) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Sui read: the vault object was not found — check the vault ID for this network.', { context: { network: ref.network } });
+    }
+    if (!type.toLowerCase().startsWith(expected)) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `Sui read: ${ref.vaultId} is not a vault of the configured original package (its type is ${type}) — check the vault ID and sui.originalPackageId.`, { context: { network: ref.network } });
+    }
+}
+function assertOwner(owner, method) {
+    if (!(0, chain_address_1.isSuiAddress)(owner)) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: owner must be a Sui address (0x + 64 hex chars).`);
+    }
+}
+/**
+ * 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),
+ * );
+ * ```
+ */
+async function getSuiWithdrawalRequests(ref, owner, sui) {
+    assertVaultRef(ref, 'getSuiWithdrawalRequests');
+    assertOwner(owner, 'getSuiWithdrawalRequests');
+    return (await scanSuiWithdrawalRequests(ref, owner, sui)).requests;
+}
+/**
+ * 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
+ */
+function suiPositionRedemptions(requests, vault, decimals, nowMs) {
+    const availableRedemptions = [];
+    const pendingRedemptions = [];
+    for (const r of requests) {
+        const status = r.expiresAtMs !== null && nowMs >= r.expiresAtMs
+            ? types_1.VaultRedemptionStatus.EXPIRED
+            : nowMs >= r.eligibleAtMs
+                ? types_1.VaultRedemptionStatus.READY_TO_CLAIM
+                : types_1.VaultRedemptionStatus.AWAITING_COOLDOWN;
+        const date = new Date(r.eligibleAtMs);
+        const entry = {
+            id: r.request,
+            hash: r.request,
+            timestamp: Math.floor(r.requestedAtMs / 1000),
+            receiver: r.payout,
+            day: (0, core_1.toNormalizedBn)(date.getUTCDate(), 0),
+            month: (0, core_1.toNormalizedBn)(date.getUTCMonth() + 1, 0),
+            year: (0, core_1.toNormalizedBn)(date.getUTCFullYear(), 0),
+            amount: (0, core_1.toNormalizedBn)(r.shares, decimals),
+            date,
+            vault: vault,
+            status,
+        };
+        if (status === types_1.VaultRedemptionStatus.READY_TO_CLAIM) {
+            pendingRedemptions.push(entry);
+        }
+        else {
+            availableRedemptions.push(entry);
+        }
+    }
+    return { availableRedemptions, pendingRedemptions };
+}
+/**
+ * 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
+ */
+async function getSuiPositionRedemptions(ref, owner, decimals, sui) {
+    const config = suiConfigForNetwork(ref.network, sui);
+    const defaults = constants_1.SUI_VAULT_CONTRACTS[ref.network];
+    const configured = (config.packageId ?? defaults.packageId) &&
+        (config.originalPackageId ?? defaults.originalPackageId) &&
+        (config.registryId ?? defaults.registryId);
+    if (!configured) {
+        return suiPositionRedemptions([], ref.vaultId, decimals, Date.now());
+    }
+    const requests = await getSuiWithdrawalRequests(ref, owner, sui);
+    return suiPositionRedemptions(requests, ref.vaultId, decimals, Date.now());
+}
+/**
+ * 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
+ */
+async function nextSuiWithdrawalRequestId(ref, owner, sui) {
+    assertVaultRef(ref, 'nextSuiWithdrawalRequestId');
+    assertOwner(owner, 'nextSuiWithdrawalRequestId');
+    return (await scanSuiWithdrawalRequests(ref, owner, sui)).nextRequestId;
+}
+/**
+ * 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
+ */
+async function deriveSuiWithdrawalRequestId(vaultId, owner, requestId, originalPackageId) {
+    const [{ bcs }, { deriveObjectID, normalizeSuiAddress }] = await Promise.all([
+        Promise.resolve().then(() => __importStar(require('@mysten/sui/bcs'))),
+        Promise.resolve().then(() => __importStar(require('@mysten/sui/utils'))),
+    ]);
+    const key = bcs
+        .struct('RequestKey', { owner: bcs.Address, requestId: bcs.u64() })
+        .serialize({ owner: normalizeSuiAddress(owner), requestId })
+        .toBytes();
+    return deriveObjectID(normalizeSuiAddress(vaultId), `${originalPackageId}::withdrawal::RequestKey`, key);
+}
 /**
  * The vault reference for a backend row, or `null` when the row has no usable
  * `sui_vault_metadata`.
@@ -360,7 +638,7 @@ function buildSuiVault(row, 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 {@link buildSuiVault}) and a warning is logged.
+ * alone (see `buildSuiVault`) and a warning is logged.
  *
  * RPC cost: as {@link readSuiVaultState}.
  *

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

@@ -10,6 +10,11 @@ import * as SuiConstants from './constants';
 import * as SuiGetters from './getters';
 import * as SuiTargets from './targets';
 import * as SuiUtils from './utils';
+/**
+ * Sui helpers by area: chain identity (`utils`), constants, the gRPC client
+ * with failover (`client`), move-call targets (`targets`), vault reads
+ * (`getters`) and deposit / instant-redeem builders (`actions`).
+ */
 export declare const Sui: {
     utils: typeof SuiUtils;
     constants: typeof SuiConstants;
@@ -45,7 +50,7 @@ export interface ISuiAdapterVault {
  * sdk.sui.isSuiAddress(vault.address);
  * ```
  */
-declare class SuiAdapter {
+export declare class SuiAdapter {
     private readonly _config;
     /**
      * @param config - Optional Sui settings; omit to target Sui mainnet.
@@ -79,7 +84,8 @@ declare class SuiAdapter {
      * RPC cost: one dry run (plus the coin lookup it needs).
      *
      * @param params - The vault, `amount` in asset base units, the `sender`, and
-     *   an optional `minSharesOut` (defaults to the dry run's exact preview).
+     *   optionally `minSharesOut` or `slippageBps` (the minimum defaults to the
+     *   dry run's preview less 0.1%).
      * @returns The unsigned transaction for the sender's wallet, the shares the
      *   dry run minted, and the minimum it enforces.
      * @throws {@link UpshiftValidationError} for malformed input, unknown
@@ -95,17 +101,21 @@ declare class SuiAdapter {
      *   amount: 1_000_000n,
      *   sender: account.address,
      * });
-     * await dAppKit.signAndExecuteTransaction({ transaction });
+     * const digest = await sdk.sui.executeTransaction(
+     *   await dAppKit.signTransaction({ transaction }),
+     * );
      * ```
      */
     vaultDeposit(params: ISuiAdapterVault & {
         amount: bigint;
         sender: string;
         minSharesOut?: bigint;
+        slippageBps?: number;
     }): Promise<SuiActions.ISuiDepositTransaction>;
     /**
-     * Build an unsigned instant redemption on the configured network: redeem
-     * shares with a minimum net asset amount, send the assets to the sender.
+     * Build an unsigned instant redemption on the configured network: charge
+     * the management fee, redeem shares with a minimum net asset amount, send
+     * the assets to the sender.
      * Dry-runs it first; a vault with a withdrawal queue attached fails with
      * `queue_attached`.
      *
@@ -115,8 +125,8 @@ declare class SuiAdapter {
      * RPC cost: one dry run (plus the coin lookup it needs).
      *
      * @param params - The vault, `shares` in share base units, the `sender`, and
-     *   an optional `minAssetsOut` net of the instant fee (defaults to the dry
-     *   run's exact preview).
+     *   optionally `minAssetsOut` (net of the instant fee) or `slippageBps` (the
+     *   minimum defaults to the dry run's preview less 0.1%).
      * @returns The unsigned transaction, the dry run's gross and net assets, and
      *   the minimum it enforces.
      * @throws {@link UpshiftValidationError} for malformed input, unknown
@@ -128,7 +138,144 @@ declare class SuiAdapter {
         shares: bigint;
         sender: string;
         minAssetsOut?: bigint;
+        slippageBps?: number;
     }): Promise<SuiActions.ISuiRedeemTransaction>;
+    /**
+     * Build an unsigned withdrawal request on the configured network, for a
+     * vault with a withdrawal queue attached (where instant redemption is off).
+     * Escrows the shares in a new request; dry-runs it first, so a vault that
+     * would reject it fails here.
+     *
+     * The request is priced when it is claimed. Once the vault's cooldown has
+     * run, claim it with {@link SuiAdapter.claimWithdrawal}; cancel it at any
+     * time with {@link SuiAdapter.vaultCancelRedeemRequest}. List a wallet's
+     * requests with {@link SuiAdapter.getWithdrawalRequests}.
+     *
+     * RPC cost: one object read for a wallet with up to 23 earlier requests on
+     * the vault (one more per further 25), then one dry run.
+     *
+     * @param params - The vault, `shares` in share base units, the `sender`, and
+     *   optionally `payout` (defaults to the sender) and `finalizer`: who besides
+     *   the owner may claim during the first day the request is claimable
+     *   (anyone may after). Defaults to the owner alone; pass a keeper address,
+     *   or `null` to let anyone claim as soon as the cooldown ends.
+     * @returns The unsigned transaction, the request ID, the request's object ID
+     *   (`request`) for claiming or cancelling, and `expectedAssets` at today's
+     *   price.
+     * @throws {@link UpshiftValidationError} for malformed input, unknown
+     *   contract IDs, or a transaction that cannot be built.
+     * @throws {@link UpshiftVaultAbortError} when the vault would reject it,
+     *   e.g. `queue_not_attached` (redeem instantly instead) or `paused`.
+     * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+     * @example
+     * ```ts
+     * const { transaction, request } = await sdk.sui.vaultRequestRedeem({
+     *   vaultId: vault.address,
+     *   assetCoinType: vault.depositAssets[0].address,
+     *   shareCoinType: vault.receipt.address,
+     *   shares: 1_000_000n,
+     *   sender: account.address,
+     * });
+     * await sdk.sui.executeTransaction(await dAppKit.signTransaction({ transaction }));
+     * ```
+     */
+    vaultRequestRedeem(params: ISuiAdapterVault & {
+        shares: bigint;
+        sender: string;
+        payout?: string;
+        finalizer?: string | null;
+    }): Promise<SuiActions.ISuiRequestRedeemTransaction>;
+    /**
+     * Build an unsigned cancellation of a pending withdrawal request on the
+     * configured network; the escrowed shares go back to the sender. Allowed at
+     * any time while the request exists, also while the vault is paused. Only
+     * the wallet that made the request may cancel it.
+     *
+     * RPC cost: one dry run.
+     *
+     * @param params - The vault, the `request` object ID and the `sender`.
+     * @returns The unsigned transaction and the shares it returns.
+     * @throws {@link UpshiftValidationError} for malformed input, unknown
+     *   contract IDs, or a request that no longer exists.
+     * @throws {@link UpshiftVaultAbortError} when the vault would reject it,
+     *   e.g. `not_request_owner`.
+     * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+     * @example
+     * ```ts
+     * const { transaction } = await sdk.sui.vaultCancelRedeemRequest({
+     *   vaultId, assetCoinType, shareCoinType, request, sender: account.address,
+     * });
+     * ```
+     */
+    vaultCancelRedeemRequest(params: ISuiAdapterVault & {
+        request: string;
+        sender: string;
+    }): Promise<SuiActions.ISuiCancelRedeemRequestTransaction>;
+    /**
+     * Build an unsigned claim of a withdrawal request on the configured
+     * network: burns the escrowed shares and pays their current value, with no
+     * instant fee, to the request's payout.
+     *
+     * The payout lands in the payout address's address balance, not as a coin
+     * object. A request can be claimed from `eligibleAtMs` until `expiresAtMs`
+     * by its owner or finalizer (anyone when it names none), and by anyone from
+     * one day after it became eligible.
+     *
+     * RPC cost: one dry run.
+     *
+     * @param params - The vault, the `request` object ID, the `sender`, and
+     *   optionally `minAssetsOut` or `slippageBps` (the minimum defaults to the
+     *   dry run's payout less 0.1%).
+     * @returns The unsigned transaction, the shares it burns, the dry run's
+     *   payout, and the minimum it enforces.
+     * @throws {@link UpshiftValidationError} for malformed input, unknown
+     *   contract IDs, or a request that no longer exists.
+     * @throws {@link UpshiftVaultAbortError} when the vault would reject it,
+     *   e.g. `not_eligible_yet`, `request_expired` or `insufficient_liquidity`.
+     * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+     * @example
+     * ```ts
+     * const [pending] = await sdk.sui.getWithdrawalRequests({ ...vault, owner: account.address });
+     * const { transaction } = await sdk.sui.claimWithdrawal({
+     *   ...vault, request: pending.request, sender: account.address,
+     * });
+     * ```
+     */
+    claimWithdrawal(params: ISuiAdapterVault & {
+        request: string;
+        sender: string;
+        minAssetsOut?: bigint;
+        slippageBps?: number;
+    }): Promise<SuiActions.ISuiClaimWithdrawalTransaction>;
+    /**
+     * A wallet's pending withdrawal requests on a vault, on the configured
+     * network, oldest first. Finds every request made through the SDK however
+     * old; claimed and cancelled requests 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 params - The vault and the `owner` wallet.
+     * @returns The pending requests, with shares, payout, and the times they
+     *   become claimable and expire; empty when there are none.
+     * @throws {@link UpshiftValidationError} for malformed input, 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.
+     * @example
+     * ```ts
+     * const pending = await sdk.sui.getWithdrawalRequests({
+     *   vaultId, assetCoinType, shareCoinType, owner: account.address,
+     * });
+     * const now = Date.now();
+     * const claimable = pending.filter(
+     *   (r) => r.eligibleAtMs <= now && (r.expiresAtMs === null || now < r.expiresAtMs),
+     * );
+     * ```
+     */
+    getWithdrawalRequests(params: ISuiAdapterVault & {
+        owner: string;
+    }): Promise<SuiGetters.ISuiWithdrawalRequest[]>;
     /**
      * Execute a wallet-signed transaction on the configured network and wait
      * until it is indexed. Not needed when the wallet executes the transaction