@upshiftfinance/sdk 0.4.0 → 0.5.0

package/README.md

@@ -154,7 +154,7 @@ src.ts/
 │   ├── evm/             # EVM adapter (approve, deposit, redeem, read helpers)
 │   ├── solana/          # Solana program adapters
 │   ├── stellar/         # Stellar vault adapters
-│   └── sui/             # Sui config and chain-identity helpers
+│   └── sui/             # Sui client, contract targets, vault reads and actions
 ├── evm/                 # EVM cross-chain (LayerZero OVault)
 ├── modules/             # Feature modules
 │   ├── vaults/          # Vault read operations
@@ -183,6 +183,7 @@ src.ts/
 - `evm-2`: Current EVM vault architecture (separate receipt tokens)
 - `sol-0`: Solana program-based vaults
 - `stellar-0`: Stellar-based vaults
+- `sui-0`: Sui Move vaults
 
 ### Data Enrichment
 
@@ -337,6 +338,9 @@ if (walletClient) sdk.evm.setSigner(walletClient);
 
 | Method | Description |
 | --- | --- |
+| `vaultDeposit(options)` | Build an unsigned deposit (dry-run first) |
+| `vaultRedeem(options)` | Build an unsigned instant redemption (dry-run first) |
+| `executeTransaction({ bytes, signature })` | Execute a wallet-signed transaction and wait for it |
 | `isSuiAddress(address)` | Whether a string is a Sui address / object ID (`0x` + 64 hex) |
 | `isSuiVault(chainId)` | Whether a chain ID is Sui's (`-2`) |
 | `network`, `rpcUrl` | The `sui` config passed to `new UpshiftSDK({ sui })` |

package/esm/index.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Type entry for ESM consumers of `@upshiftfinance/sdk` (paired with
+ * `esm/index.mjs`).
+ *
+ * The declaration rollup `lib/sdk.d.ts` describes a CommonJS module. Under
+ * ESM-mode TypeScript (`module: node16 | nodenext`), a default import of a CJS
+ * declaration resolves to the whole `module.exports`, so
+ * `new UpshiftSDK()` failed to typecheck ("This expression is not
+ * constructable"). `import = require` reads the CJS module as-is, letting us
+ * re-export its `default` (the `UpshiftSDK` class) as the ESM default.
+ */
+import sdk = require('../lib/sdk.js');
+
+export * from '../lib/sdk.js';
+export default sdk.default;

package/esm/index.mjs

@@ -0,0 +1,18 @@
+/**
+ * ESM entry point for `@upshiftfinance/sdk`.
+ *
+ * The SDK is compiled to CommonJS (`lib/index.js`), where the default export
+ * lives on `exports.default`. Node's ESM loader (and tools that follow it:
+ * Vite SSR, vitest, tsx, plain `node` with `"type": "module"`) maps a default
+ * import of a CJS module to the whole `module.exports` object, so
+ * `import UpshiftSDK from '@upshiftfinance/sdk'` returned a namespace object
+ * and `new UpshiftSDK()` threw "UpshiftSDK is not a constructor".
+ *
+ * This wrapper re-exports the same CJS module instance (no dual-package
+ * hazard: one copy of every class, cache, and `instanceof` check) and binds
+ * its `default` to the `UpshiftSDK` class.
+ */
+import cjs from '../lib/index.js';
+
+export * from '../lib/index.js';
+export default cjs.default;

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

@@ -1,5 +1,6 @@
 /**
- * Sui vault actions: deposit and instant redeem.
+ * 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
@@ -23,10 +24,16 @@ export interface ISuiDepositParams {
     /** Wallet that pays the deposit and receives the shares. */
     sender: string;
     /**
-     * Smallest share amount to accept. Defaults to the dry run's exact preview,
-     * so any price move between building and executing aborts with `slippage`.
+     * 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 {
@@ -37,10 +44,16 @@ export interface ISuiRedeemParams {
     /** Wallet that holds the shares and receives the assets. */
     sender: string;
     /**
-     * Smallest asset amount to accept, net of the instant fee. Defaults to the
-     * dry run's exact preview.
+     * 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 {
@@ -69,8 +82,28 @@ export interface ISuiSignedTransaction {
     /** The sender's signature, base64. */
     signature: string;
 }
-/** The parts of a Sui execution error the mapping reads. */
-interface ISuiExecutionError {
+/**
+ * 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;
@@ -87,10 +120,23 @@ interface ISuiExecutionError {
  * {@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;
+ * }
+ * ```
  */
 export declare function suiExecutionErrorToSdkError(executionError: ISuiExecutionError | undefined, context?: Record<string, unknown>): UpshiftSDKError;
 /**
@@ -103,7 +149,11 @@ export declare function suiExecutionErrorToSdkError(executionError: ISuiExecutio
  *
  * 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.
@@ -120,13 +170,18 @@ export declare function suiExecutionErrorToSdkError(executionError: ISuiExecutio
  *   { 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,
+ * );
  * ```
  */
 export declare function buildSuiDepositTransaction(params: ISuiDepositParams, sui?: ISuiConfig): Promise<ISuiDepositTransaction>;
 /**
- * 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`.
@@ -137,7 +192,11 @@ export declare function buildSuiDepositTransaction(params: ISuiDepositParams, su
  *
  * 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.
@@ -150,6 +209,194 @@ export declare function buildSuiDepositTransaction(params: ISuiDepositParams, su
  * @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.
  *
@@ -171,4 +418,3 @@ export declare function buildSuiRedeemTransaction(params: ISuiRedeemParams, sui?
  * @throws {@link UpshiftNetworkError} when every Sui endpoint fails.
  */
 export declare function submitSuiTransaction(signed: ISuiSignedTransaction, network: ISuiNetwork, sui?: ISuiConfig): Promise<string>;
-export {};