@upshiftfinance/sdk 0.3.0 → 0.5.0

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

@@ -0,0 +1,420 @@
+/**
+ * Sui vault actions: deposit, instant redeem, and the withdrawal queue
+ * (request, cancel, claim).
+ *
+ * Each builder dry-runs the exact transaction with the sender's own coins, so
+ * a vault that would reject it (paused, queue attached, limits) fails here
+ * with a typed {@link UpshiftVaultAbortError} instead of in the wallet, and the
+ * dry run's preview sets the transaction's minimum output. The result is an
+ * unsigned `Transaction` for the wallet to sign; {@link submitSuiTransaction}
+ * executes a signed one and waits for it.
+ *
+ * @module SuiActions
+ */
+import type { Transaction } from '@mysten/sui/transactions';
+import type { ISuiConfig, ISuiNetwork } from '../../types';
+import { UpshiftSDKError } from '../../core/errors';
+import { type ISuiVaultRef } from './getters';
+/** Parameters for {@link buildSuiDepositTransaction}. */
+export interface ISuiDepositParams {
+    /** The vault and its coin types and network. */
+    vault: ISuiVaultRef;
+    /** Deposit amount in asset base units. */
+    amount: bigint;
+    /** Wallet that pays the deposit and receives the shares. */
+    sender: string;
+    /**
+     * Smallest share amount to accept. Wins over `slippageBps`. Defaults to the
+     * dry run's preview less `slippageBps`.
+     */
+    minSharesOut?: bigint;
+    /**
+     * Tolerance below the dry run's preview, in basis points (0–10000), used
+     * when `minSharesOut` is not set. Defaults to {@link DEFAULT_SUI_SLIPPAGE_BPS}.
+     * `0` demands exactly the preview.
+     */
+    slippageBps?: number;
+}
+/** Parameters for {@link buildSuiRedeemTransaction}. */
+export interface ISuiRedeemParams {
+    /** The vault and its coin types and network. */
+    vault: ISuiVaultRef;
+    /** Shares to redeem, in share base units. */
+    shares: bigint;
+    /** Wallet that holds the shares and receives the assets. */
+    sender: string;
+    /**
+     * Smallest asset amount to accept, net of the instant fee. Wins over
+     * `slippageBps`. Defaults to the dry run's preview less `slippageBps`.
+     */
+    minAssetsOut?: bigint;
+    /**
+     * Tolerance below the dry run's preview, in basis points (0–10000), used
+     * when `minAssetsOut` is not set. Defaults to {@link DEFAULT_SUI_SLIPPAGE_BPS}.
+     * `0` demands exactly the preview.
+     */
+    slippageBps?: number;
+}
+/** An unsigned deposit transaction and the minimum it enforces. */
+export interface ISuiDepositTransaction {
+    /** Unsigned transaction, sender set; sign it with the sender's wallet. */
+    transaction: Transaction;
+    /** Shares the dry run minted. */
+    expectedShares: bigint;
+    /** Minimum shares the transaction accepts. */
+    minSharesOut: bigint;
+}
+/** An unsigned instant-redeem transaction and the minimum it enforces. */
+export interface ISuiRedeemTransaction {
+    /** Unsigned transaction, sender set; sign it with the sender's wallet. */
+    transaction: Transaction;
+    /** Gross assets before the instant fee. */
+    expectedGrossAssets: bigint;
+    /** Assets the dry run paid, net of the instant fee. */
+    expectedAssets: bigint;
+    /** Minimum net assets the transaction accepts. */
+    minAssetsOut: bigint;
+}
+/** A transaction signed by the sender's wallet. */
+export interface ISuiSignedTransaction {
+    /** Transaction bytes, base64, as the wallet returns them. */
+    bytes: string;
+    /** The sender's signature, base64. */
+    signature: string;
+}
+/**
+ * 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.
+ */
+export declare const DEFAULT_SUI_SLIPPAGE_BPS = 10;
+/**
+ * The minimum output for a previewed amount: `expected` less `slippageBps`,
+ * rounded down.
+ * @internal
+ */
+export declare function suiMinOut(expected: bigint, slippageBps: number): bigint;
+/**
+ * A failed Sui execution: `effects.status.error` of a failed transaction, or
+ * the `executionError` of a `SimulationError` a wallet's build throws. Only
+ * the fields the mapping reads.
+ */
+export interface ISuiExecutionError {
+    message?: string;
+    MoveAbort?: {
+        abortCode?: string;
+        location?: {
+            module?: string;
+        };
+        cleverError?: {
+            constantName?: string;
+        };
+    };
+}
+/**
+ * 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;
+ * }
+ * ```
+ */
+export declare function suiExecutionErrorToSdkError(executionError: ISuiExecutionError | undefined, context?: Record<string, unknown>): UpshiftSDKError;
+/**
+ * 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,
+ * );
+ * ```
+ */
+export declare function buildSuiDepositTransaction(params: ISuiDepositParams, sui?: ISuiConfig): Promise<ISuiDepositTransaction>;
+/**
+ * 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.
+ */
+export declare function buildSuiRedeemTransaction(params: ISuiRedeemParams, sui?: ISuiConfig): Promise<ISuiRedeemTransaction>;
+/** Parameters for {@link buildSuiRequestRedeemTransaction}. */
+export interface ISuiRequestRedeemParams {
+    /** The vault and its coin types and network. */
+    vault: ISuiVaultRef;
+    /** Shares to escrow, in share base units. */
+    shares: bigint;
+    /** Wallet that holds the shares and owns the request. */
+    sender: string;
+    /** Address the claim pays, into its address balance. Defaults to `sender`. */
+    payout?: string;
+    /**
+     * Who besides the owner may claim the request during the first day after it
+     * becomes claimable; from then on anyone may. Defaults to the owner alone,
+     * so nobody else can choose the moment the holder leaves (the claim is
+     * priced then). Pass a keeper's address to let it settle at once, or `null`
+     * to let anyone claim as soon as the cooldown ends. The payout goes to
+     * `payout` whoever claims.
+     */
+    finalizer?: string | null;
+}
+/** An unsigned withdrawal request and the request it creates. */
+export interface ISuiRequestRedeemTransaction {
+    /** Unsigned transaction, sender set; sign it with the sender's wallet. */
+    transaction: Transaction;
+    /** The wallet's numeric ID for the request on this vault. */
+    requestId: bigint;
+    /** Object ID the request will have; pass it as `request` to claim or cancel. */
+    request: string;
+    /**
+     * What the shares would pay at today's price, in asset base units. The claim
+     * is priced when it happens, so this is an estimate.
+     */
+    expectedAssets: bigint;
+}
+/** Parameters for {@link buildSuiCancelRedeemRequestTransaction}. */
+export interface ISuiCancelRedeemRequestParams {
+    /** The vault and its coin types and network. */
+    vault: ISuiVaultRef;
+    /** Request object ID, from `getSuiWithdrawalRequests` or the request build. */
+    request: string;
+    /** Wallet that made the request; it gets the shares back. */
+    sender: string;
+}
+/** An unsigned cancellation and the shares it returns. */
+export interface ISuiCancelRedeemRequestTransaction {
+    /** Unsigned transaction, sender set; sign it with the sender's wallet. */
+    transaction: Transaction;
+    /** Shares the dry run returned to the sender. */
+    shares: bigint;
+}
+/** Parameters for {@link buildSuiClaimWithdrawalTransaction}. */
+export interface ISuiClaimWithdrawalParams {
+    /** The vault and its coin types and network. */
+    vault: ISuiVaultRef;
+    /** Request object ID, from `getSuiWithdrawalRequests` or the request build. */
+    request: string;
+    /**
+     * Wallet that signs and pays gas: the owner, the request's finalizer, or
+     * anyone the request permits. The assets go to the request's payout.
+     */
+    sender: string;
+    /**
+     * Smallest asset amount to accept. Wins over `slippageBps`. Defaults to the
+     * dry run's preview less `slippageBps`.
+     */
+    minAssetsOut?: bigint;
+    /**
+     * Tolerance below the dry run's preview, in basis points (0–10000), used
+     * when `minAssetsOut` is not set. Defaults to {@link DEFAULT_SUI_SLIPPAGE_BPS}.
+     */
+    slippageBps?: number;
+}
+/** An unsigned claim and what it pays. */
+export interface ISuiClaimWithdrawalTransaction {
+    /** Unsigned transaction, sender set; sign it with the sender's wallet. */
+    transaction: Transaction;
+    /** Escrowed shares the claim burns. */
+    shares: bigint;
+    /** Previewed payout, in asset base units (no fee on queued withdrawals). */
+    expectedAssets: bigint;
+    /** Minimum assets the transaction accepts. */
+    minAssetsOut: bigint;
+}
+/**
+ * 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,
+ * );
+ * ```
+ */
+export declare function buildSuiRequestRedeemTransaction(params: ISuiRequestRedeemParams, sui?: ISuiConfig): Promise<ISuiRequestRedeemTransaction>;
+/**
+ * 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,
+ * );
+ * ```
+ */
+export declare function buildSuiCancelRedeemRequestTransaction(params: ISuiCancelRedeemRequestParams, sui?: ISuiConfig): Promise<ISuiCancelRedeemRequestTransaction>;
+/**
+ * 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,
+ * );
+ * ```
+ */
+export declare function buildSuiClaimWithdrawalTransaction(params: ISuiClaimWithdrawalParams, sui?: ISuiConfig): Promise<ISuiClaimWithdrawalTransaction>;
+/**
+ * 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.
+ */
+export declare function submitSuiTransaction(signed: ISuiSignedTransaction, network: ISuiNetwork, sui?: ISuiConfig): Promise<string>;