@upshiftfinance/sdk 0.3.0 → 0.5.0

package/lib/adapters/sui/actions.js

@@ -0,0 +1,701 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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");
+const curator_alert_1 = require("../../core/logger/curator-alert");
+const client_1 = require("./client");
+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',
+    'vault::EBelowMinDeposit': 'below_min_deposit',
+    'vault::EAboveMaxDeposit': 'above_max_deposit',
+    'vault::EDepositCapExceeded': 'deposit_cap_exceeded',
+    'vault::EAboveMaxWithdrawal': 'above_max_withdrawal',
+    'vault::EInsufficientLiquidity': 'insufficient_liquidity',
+    'vault::EQueueAttached': 'queue_attached',
+    'vault::ESlippageExceeded': 'slippage',
+    '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).
+ * @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;
+    if (abort) {
+        const module = abort.location?.module;
+        const constant = abort.cleverError?.constantName;
+        const reason = ABORT_REASONS[`${module}::${constant}`] ?? 'other';
+        return new errors_1.UpshiftVaultAbortError(reason, `Sui vault rejected the transaction: ${reason}${constant ? ` (${module}::${constant})` : ` (abort ${abort.abortCode})`}.`, { module, constant }, { context: { ...context, abortCode: abort.abortCode } });
+    }
+    return new errors_1.UpshiftSDKError('UNKNOWN', `Sui transaction failed: ${executionError?.message ?? 'unknown error'}`, { context });
+}
+function assertSender(sender, method) {
+    if (!(0, chain_address_1.isSuiAddress)(sender)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: sender must be a Sui address (0x + 64 hex chars).`);
+    }
+}
+function assertAmount(value, method, name, positive) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'bigint' ||
+        value < (positive ? 1n : 0n) ||
+        value > U64_MAX) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: ${name} must be a bigint between ${positive ? 1 : 0} and 2^64 - 1.`);
+    }
+}
+/** Move-call helper bound to one vault and its contracts. */
+function vaultCalls(tx, ref, contracts) {
+    const typeArguments = (0, targets_1.suiVaultTypeArguments)(ref.assetCoinType, ref.shareCoinType);
+    return (target, args) => tx.moveCall({
+        target: (0, targets_1.suiMoveCallTarget)(contracts, target),
+        typeArguments,
+        arguments: [
+            tx.object(ref.vaultId),
+            tx.object(contracts.registryId),
+            ...args,
+        ],
+    });
+}
+/**
+ * Dry-run `tx` against the network and return each command's return values.
+ * An abort, at build (gas estimation) or in the simulation, becomes a typed
+ * SDK error; `onAbort` sees it first.
+ */
+async function dryRun(config, build, method, onAbort) {
+    const context = { network: config.network, method };
+    try {
+        return await (0, client_1.withSuiClient)((0, client_1.resolveSuiNetworkConfig)(config), async (client) => {
+            const result = await client.core.simulateTransaction({
+                transaction: await build(),
+                include: { commandResults: true, effects: true },
+            });
+            if (result.$kind !== 'Transaction') {
+                throw suiExecutionErrorToSdkError(result.FailedTransaction.effects?.status.error ?? undefined, context);
+            }
+            return result.commandResults.map((c) => c.returnValues.map((v) => v.bcs));
+        });
+    }
+    catch (err) {
+        const sdkError = err instanceof errors_1.UpshiftSDKError
+            ? err
+            : err?.executionError
+                ? suiExecutionErrorToSdkError(err.executionError, context)
+                : new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: could not build the transaction: ${err instanceof Error ? err.message : String(err)}`, { cause: err, context });
+        if (sdkError instanceof errors_1.UpshiftVaultAbortError)
+            onAbort?.(sdkError);
+        throw sdkError;
+    }
+}
+/**
+ * Build an unsigned deposit: charge the management fee, deposit with a minimum
+ * share amount, and send the shares to the sender — one transaction.
+ *
+ * The payment is `coinWithBalance(Asset)`: the wallet selects and merges the
+ * sender's coins when it signs. The fee is charged first so the deposit is
+ * priced on a current NAV.
+ *
+ * RPC cost: one dry run (plus the coin lookup it needs).
+ *
+ * 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.
+ * @throws {@link UpshiftValidationError} for a malformed sender or vault, an
+ *   out-of-range amount, unknown contract IDs, or a transaction that cannot be
+ *   built (e.g. the sender lacks the asset).
+ * @throws {@link UpshiftVaultAbortError} when the vault would reject the
+ *   deposit (`paused`, `below_min_deposit`, `above_max_deposit`,
+ *   `deposit_cap_exceeded`, `zero_output`, `slippage`, `version_retired`).
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ * @example
+ * ```ts
+ * const { transaction } = await buildSuiDepositTransaction(
+ *   { vault: ref, amount: 1_000_000n, sender: account.address },
+ *   sdkSuiConfig,
+ * );
+ * const digest = await submitSuiTransaction(
+ *   await dAppKit.signTransaction({ transaction }),
+ *   'testnet',
+ *   sdkSuiConfig,
+ * );
+ * ```
+ */
+async function buildSuiDepositTransaction(params, sui) {
+    const method = 'buildSuiDepositTransaction';
+    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')));
+    const compose = (min, withPreview) => {
+        const tx = new SuiTransaction();
+        tx.setSender(sender);
+        const call = vaultCalls(tx, ref, contracts);
+        call('chargeManagementFee', [tx.object(constants_1.SUI_CLOCK_ID)]);
+        if (withPreview)
+            call('previewDeposit', [tx.pure.u64(amount)]);
+        const payment = tx.add(coinWithBalance({ type: ref.assetCoinType, balance: amount }));
+        const shares = call('depositChecked', [payment, tx.pure.u64(min)]);
+        tx.transferObjects([shares], sender);
+        return tx;
+    };
+    // 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 ??
+        suiMinOut(expectedShares, slippageBps ?? exports.DEFAULT_SUI_SLIPPAGE_BPS);
+    return {
+        transaction: compose(min, false),
+        expectedShares,
+        minSharesOut: min,
+    };
+}
+/**
+ * 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`.
+ *
+ * Side effect on failure: when the vault rejects the dry run, the failure is
+ * reported to that vault's curator (fire-and-forget; see
+ * `monitoring.curatorAlerts`).
+ *
+ * RPC cost: one dry run (plus the coin lookup it needs).
+ *
+ * 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.
+ * @throws {@link UpshiftValidationError} for a malformed sender or vault, 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 the
+ *   redemption (`queue_attached`, `paused`, `above_max_withdrawal`,
+ *   `insufficient_liquidity`, `zero_output`, `slippage`, `version_retired`).
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+async function buildSuiRedeemTransaction(params, sui) {
+    const method = 'buildSuiRedeemTransaction';
+    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')));
+    const compose = (min, withPreview) => {
+        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)]);
+        }
+        const payment = tx.add(coinWithBalance({ type: ref.shareCoinType, balance: shares }));
+        const assets = call('redeemChecked', [payment, tx.pure.u64(min)]);
+        tx.transferObjects([assets], sender);
+        return tx;
+    };
+    const results = await dryRun(config, async () => compose(0n, true), method, (err) => (0, curator_alert_1.reportRedeemFailure)({
+        phase: 'simulation',
+        chain: 'sui',
+        network: ref.network,
+        contractId: ref.vaultId,
+        eoa: sender,
+        sharesRaw: shares.toString(),
+        error: err.message,
+    }));
+    // 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,
+        expectedAssets,
+        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.
+ */
+function redemptionOf(data, fromBase64) {
+    for (const command of data.commands) {
+        const call = command.MoveCall;
+        if (call?.module !== 'coin_entry' || call.function !== 'redeem_checked')
+            continue;
+        const vaultArg = call.arguments[0];
+        const vaultInput = vaultArg?.$kind === 'Input' ? data.inputs[vaultArg.Input] : undefined;
+        const vaultId = vaultInput?.Object?.SharedObject?.objectId;
+        if (!vaultId)
+            return null;
+        // The shares are usually split off the sender's coins; read that amount.
+        let sharesRaw = '0';
+        const coinArg = call.arguments[2];
+        const source = coinArg?.$kind === 'NestedResult' || coinArg?.$kind === 'Result'
+            ? data.commands[coinArg.$kind === 'Result'
+                ? coinArg.Result
+                : coinArg.NestedResult[0]]
+            : undefined;
+        const amountArg = source?.SplitCoins?.amounts[0];
+        const amountInput = amountArg?.$kind === 'Input' ? data.inputs[amountArg.Input] : undefined;
+        const bytes = amountInput?.Pure?.bytes;
+        if (bytes) {
+            const raw = fromBase64(bytes);
+            if (raw.length === 8)
+                sharesRaw = (0, getters_1.decodeSuiUint)(raw, 8).toString();
+        }
+        return { vaultId, sharesRaw };
+    }
+    return null;
+}
+/**
+ * Execute a signed transaction and wait until the network has indexed it.
+ *
+ * Side effect on failure: a failed instant redemption is reported to that
+ * vault's curator with its digest (fire-and-forget; see
+ * `monitoring.curatorAlerts`).
+ *
+ * RPC cost: one execution plus the confirmation poll.
+ *
+ * @param signed - Bytes and signature from the wallet's `signTransaction`.
+ * @param network - Network the transaction was built for.
+ * @param sui - The SDK's `sui` config; applied only for `network`.
+ * @returns The transaction digest once it succeeded and is indexed.
+ * @throws {@link UpshiftVaultAbortError} when the vault aborted it on chain.
+ * @throws {@link UpshiftSDKError} (`UNKNOWN`) when it failed for another
+ *   reason; `context.digest` names it.
+ * @throws {@link UpshiftTransactionError} when it executed but was not
+ *   indexed in time; check `signature` (the digest) before retrying.
+ * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
+ */
+async function submitSuiTransaction(signed, network, sui) {
+    if (typeof signed?.bytes !== 'string' ||
+        typeof signed.signature !== 'string') {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', 'submitSuiTransaction: pass { bytes, signature } from the wallet, both base64.');
+    }
+    const config = (0, getters_1.suiConfigForNetwork)(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')));
+    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,
+        signatures: [signed.signature],
+        include: { effects: true },
+    })).catch((err) => {
+        if (err instanceof errors_1.UpshiftSDKError)
+            throw err;
+        // The node refused it before execution: a bad signature, or inputs that
+        // changed since signing (rebuild and sign again).
+        throw new errors_1.UpshiftSDKError('UNKNOWN', `submitSuiTransaction: the network rejected the transaction: ${err instanceof Error ? err.message : String(err)}`, { cause: err, context: { network } });
+    });
+    if (result.$kind !== 'Transaction') {
+        const failed = result.FailedTransaction;
+        const digest = failed.digest;
+        const error = suiExecutionErrorToSdkError(failed.effects?.status.error ?? undefined, { network, digest });
+        // Gas was still spent: wait (best effort) until the failure is indexed, so
+        // a retry built right after this sees the sender's new coin versions.
+        await (0, client_1.withSuiClient)(networkConfig, (client) => client.core.waitForTransaction({ result, timeout: 12_000 })).catch(() => undefined);
+        const data = SuiTransaction.from(bytes).getData();
+        const redemption = redemptionOf(data, fromBase64);
+        if (redemption && data.sender) {
+            (0, curator_alert_1.reportRedeemFailure)({
+                phase: 'submission',
+                chain: 'sui',
+                network,
+                contractId: redemption.vaultId,
+                eoa: data.sender,
+                sharesRaw: redemption.sharesRaw,
+                txHash: digest,
+                error: error.message,
+            });
+        }
+        throw error;
+    }
+    const digest = result.Transaction.digest;
+    try {
+        await (0, client_1.withSuiClient)(networkConfig, (client) => 
+        // Under the client's 15 s per-call bound, so a slow index is not mistaken
+        // for a dead endpoint.
+        client.core.waitForTransaction({ result, timeout: 12_000 }));
+    }
+    catch (err) {
+        throw new errors_1.UpshiftTransactionError(`Sui transaction ${digest} executed but was not confirmed in time.`, digest, { cause: err, context: { network } });
+    }
+    return digest;
+}
+//# sourceMappingURL=actions.js.map