@upshiftfinance/sdk 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,539 @@
+import { type IContractWriteOptions, type INativeDepositOptions, type ApproveResult, type IClaimWithdrawalOptions, type IGetDepositRouteOptions } from '../../modules/vaults/write.actions';
+import type { ISwapAndDepositOptions, ISwapRouterDirectDepositOptions, ISwapRouterNativeDepositOptions, ISwapRouterDepositOptions, ISwapRouterDepositResultOptions } from '../../types';
+import { type IPreviewDepositOptions, type IPreviewRedeemOptions, type IAllowanceOptions, type IBalanceOfOptions, type IMaxDepositOptions, type IGetIdleLiquidityOptions, type ILagDurationOptions, type IGetWithdrawalEpochOptions, type IWithdrawalEpoch, type IGetBurnableAmountByReceiverOptions, type IGetRequirementByDateOptions, type IGetScheduledTransactionsByDateOptions, type IScheduledTransactionsByDate } from '../../modules/vaults/read.actions';
+import { type CompatibleSigner } from '../../core/helpers/signer';
+import type { IAddress, IContractRunner } from '../../types';
+export * from './getters';
+/**
+ * EVM Adapter for Upshift SDK
+ * Supports both ethers Signer/Wallet and wagmi/viem WalletClient
+ *
+ * @example
+ * To access the EVM adapter instance
+ * ```
+ * const sdk = new UpshiftSDK()
+ * sdk.evm.vaultRedeem()
+ * ```
+ */
+declare class EVMAdapter {
+    private signer?;
+    private rawSigner?;
+    private getReadProvider?;
+    /**
+     * @param signer - Optional ethers Signer/Wallet or viem WalletClient. Required
+     *   for writes; reads fall back to `getReadProvider` when absent.
+     * @param getReadProvider - Optional thunk returning a read-only provider for
+     *   the SDK's active network. Called on every signerless read so it tracks
+     *   `switchNetwork`. `UpshiftSDK` wires this to its configured `providers`.
+     */
+    constructor(signer?: CompatibleSigner, getReadProvider?: () => IContractRunner | undefined);
+    /**
+     * Set a new signer (supports both ethers and viem/wagmi)
+     * @param signer - Either an ethers Signer/Wallet or viem WalletClient
+     */
+    setSigner(signer: CompatibleSigner): void;
+    /**
+     * Get the normalized ethers-compatible signer
+     * Converts viem WalletClient to ethers Signer if needed
+     */
+    private _getSigner;
+    /**
+     * Resolve the contract runner for a read-only call. Prefers the signer when
+     * one is set (preserving the signer's chain), otherwise falls back to the
+     * read provider for the SDK's active network, so reads such as `balanceOf`
+     * or `previewDeposit` work before `setSigner` is called.
+     *
+     * No extra RPC calls: the provider comes from the `createProvider` cache.
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when neither a signer nor a read
+     *   provider (configured `providers` entry) is available.
+     */
+    private _getReadRunner;
+    vaultApprove(options: IContractWriteOptions): Promise<string>;
+    /**
+     * Approve a vault to spend a deposit token, returning a discriminated
+     * {@link ApproveResult} so callers can tell `sent` from `sufficient`
+     * (existing allowance covers) and `native` (no allowance applies).
+     * Prefer this over {@link vaultApprove} for new integrations.
+     *
+     * @example
+     * ```ts
+     * const r = await upshiftSdk.evm.approve({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   amount: '100',
+     *   wait: true,
+     * });
+     * if (r.kind === 'sent') console.log('approve tx', r.hash);
+     * ```
+     */
+    approve(options: IContractWriteOptions): Promise<ApproveResult>;
+    /**
+     * Read the ERC-20 allowance the wallet has granted the vault to spend its
+     * underlying asset, returned as a normalized number. For the newer typed
+     * read that returns a raw `bigint` and accepts an explicit `asset` override,
+     * use {@link EVMAdapter.allowance}.
+     *
+     * Only `target` (vault address) and `wallet` are read from `options`; the
+     * remaining {@link IContractWriteOptions} fields are ignored.
+     *
+     * @param options - `{ target, wallet }` (other fields ignored).
+     * @returns Normalized allowance (`{ raw, normalized }`), or `undefined` when
+     *   `target` / `wallet` fail address validation.
+     *
+     * @example
+     * ```ts
+     * const a = await upshiftSdk.evm.vaultAllowance({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     * });
+     * console.log(a?.normalized);
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    vaultAllowance(options: IContractWriteOptions): Promise<import("../../types").INormalizedNumber>;
+    /**
+     * Deposit into an Upshift vault. Routes automatically: V1 single-asset vaults
+     * deposit the underlying directly; V2 multi-asset vaults route through the
+     * adapter for non-underlying `depositAsset`. With `attribution.originCode`
+     * configured, eligible deposits go through the SwapRouter instead (see
+     * {@link EVMAdapter.getDepositRoute}). If allowance is insufficient
+     * the method submits an approve transaction first (the approve step always
+     * waits for confirmation to close a race window, regardless of `wait`).
+     *
+     * @param options - {@link IContractWriteOptions}. `target` and `wallet` are
+     *   required; pass `amount`, `depositAsset` (defaults to the vault's
+     *   underlying), `chainId`, `poolName`, `wait`, and `isDepositWithPermit`
+     *   as needed.
+     * @returns The deposit `TransactionResponse`, or `undefined` if an
+     *   approval-only path was taken and no deposit transaction was sent.
+     * @throws UpshiftValidationError on invalid inputs (bad address, bad amount).
+     * @throws UpshiftSDKError on RPC / contract revert during the deposit.
+     *
+     * @example
+     * ```ts
+     * const tx = await upshiftSdk.evm.vaultDeposit({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   amount: '100',
+     *   wait: true,
+     * });
+     * ```
+     */
+    vaultDeposit(options: IContractWriteOptions): Promise<string>;
+    /**
+     * Resolve whether a deposit goes through the SwapRouter with the instance
+     * origin code or takes the vault's native path, and the address to approve
+     * (`route.spender`, not necessarily the vault). See {@link getDepositRoute}.
+     *
+     * @param options - {@link IGetDepositRouteOptions}.
+     * @returns `{ via, spender, reason? }` — `reason` explains a native route
+     *   (`router-paused` while the SwapRouter is paused).
+     * @throws UpshiftValidationError on an invalid target, or an unregistered
+     *   code under `attribution.strictOrigin` while the router is not paused.
+     * @throws UpshiftSDKError when a backend, vault or router read fails.
+     * @example
+     * ```ts
+     * const { via, spender } = await upshiftSdk.evm.getDepositRoute({ target: vault });
+     * ```
+     */
+    getDepositRoute(options: IGetDepositRouteOptions): Promise<import("../../modules/vaults/write.actions").IDepositRoute>;
+    /**
+     * Submit a redemption request against a vault. Shares are escrowed and the
+     * underlying assets are released asynchronously by the protocol; callers
+     * collect the matured assets via {@link EVMAdapter.vaultRedeem}, or use the
+     * instant-redeem variant by setting `isInstantRedeem: true`.
+     *
+     * @param options - {@link IContractWriteOptions}. `target`, `wallet`, and
+     *   `amount` (in shares) are required. Set `isInstantRedeem: true` to take
+     *   the instant-redeem path when the vault supports it.
+     * @returns The request `TransactionResponse`, or `undefined` if the request
+     *   could not be built (validation failure).
+     * @throws UpshiftValidationError on invalid inputs.
+     * @throws UpshiftSDKError on RPC / contract revert.
+     *
+     * @example
+     * ```ts
+     * const tx = await upshiftSdk.evm.vaultRequestRedeem({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   amount: shareAmount,
+     *   wait: true,
+     * });
+     * ```
+     */
+    vaultRequestRedeem(options: IContractWriteOptions): Promise<string>;
+    /**
+     * Deposit the chain's native asset (ETH / AVAX / etc.) into a vault by
+     * routing through the `MultiAssetNativeDepositWrapper`. The wrapper handles
+     * native-to-wrapped conversion and the subsequent vault deposit in a single
+     * transaction.
+     *
+     * @param options - {@link INativeDepositOptions}: `wrapperAddress`, `amount`
+     *   (native, scaled by the chain's native decimals), optional `receiver`
+     *   (defaults to the signer), and optional `wait`.
+     * @returns The deposit `TransactionResponse`.
+     * @throws UpshiftValidationError on invalid inputs.
+     * @throws UpshiftSDKError on RPC / contract revert.
+     *
+     * @example
+     * ```ts
+     * const tx = await upshiftSdk.evm.depositNative({
+     *   wrapperAddress: nativeWrapperAddress,
+     *   amount: parseEther('1'),
+     *   wait: true,
+     * });
+     * ```
+     */
+    depositNative(options: INativeDepositOptions): Promise<string>;
+    /**
+     * Swap one or more whitelisted ERC-20s into a vault's reference asset via
+     * the on-chain `SwapRouter` and deposit the proceeds. The router handles
+     * fee accrual, slippage protection, and the v1/v3 vs v2 deposit-interface
+     * branching. Approval is sent automatically for each `swaps[i].tokenIn`
+     * when the caller's allowance against the SwapRouter is below `amountIn`.
+     *
+     * @param options - {@link ISwapAndDepositOptions}.
+     * @returns The transaction hash of the `swapAndDeposit` call.
+     * @throws UpshiftValidationError on invalid inputs (bad chain, empty swaps).
+     * @throws UpshiftSDKError while the SwapRouter is paused (checked before any
+     *   approval), or on RPC / contract revert.
+     *
+     * @example
+     * ```ts
+     * const quote = await fetchSwapQuote({
+     *   chainId: 1, srcToken: WBTC, srcDecimals: 8,
+     *   destToken: USDC, destDecimals: 6, amount: 100_000_000n,
+     *   receiver: SWAP_ROUTER_ADDRESSES[1]!,
+     * });
+     * const hash = await upshiftSdk.evm.swapAndDeposit({
+     *   chainId: 1, vault, receiver: wallet,
+     *   swaps: [{ tokenIn: WBTC, tokenOut: USDC, amountIn: 100_000_000n,
+     *     minAmountOut: quote.minAmountOut, router: quote.router, payload: quote.payload }],
+     * });
+     * ```
+     */
+    swapAndDeposit(options: ISwapAndDepositOptions): Promise<string>;
+    /**
+     * Deposit a vault's reference asset through the SwapRouter — no swap.
+     * Use this when the caller already holds the reference asset but wants
+     * the origin/referral fee accounting that the SwapRouter path provides.
+     *
+     * @param options - {@link ISwapRouterDirectDepositOptions}.
+     * @returns The transaction hash of the `deposit` call.
+     * @throws UpshiftSDKError while the SwapRouter is paused (checked before any
+     *   approval), or on RPC / contract revert.
+     */
+    depositViaSwapRouter(options: ISwapRouterDirectDepositOptions): Promise<string>;
+    /**
+     * Deposit native ETH (or chain-native equivalent) into a vault via the
+     * SwapRouter. Only valid when the vault's reference asset is the chain's
+     * wrapped-native token — the SwapRouter wraps `amount` and deposits.
+     *
+     * @param options - {@link ISwapRouterNativeDepositOptions}.
+     * @returns The transaction hash of the `depositNativeToken` call.
+     * @throws UpshiftSDKError while the SwapRouter is paused (checked before any
+     *   approval), or on RPC / contract revert.
+     */
+    depositNativeViaSwapRouter(options: ISwapRouterNativeDepositOptions): Promise<string>;
+    /**
+     * Deposit into a vault through the on-chain `SwapRouter`, choosing the router
+     * path from `depositAsset` (direct deposit, native wrap, or a swap to the
+     * reference asset). The explicit, opt-in swap entry point —
+     * {@link vaultDeposit} never swaps — so a native-deposit vault is never
+     * accidentally swapped.
+     *
+     * Reads the vault's reference asset + decimals on-chain, resolves the swap
+     * quote and fail-closes on aggregator/whitelist drift, and sends the ERC-20
+     * approval to the SwapRouter when allowance is short.
+     *
+     * @param options - {@link ISwapRouterDepositOptions}.
+     * @returns The transaction hash of the router deposit call.
+     * @throws UpshiftValidationError on unsupported chain, invalid address, zero
+     *   amount, a native deposit into a non-wrapped-native vault, or quote drift.
+     * @throws UpshiftSDKError while the SwapRouter is paused (checked before any
+     *   approval), or on RPC / contract revert.
+     * @example
+     * ```ts
+     * const hash = await upshiftSdk.evm.swapRouterDeposit({
+     *   chainId: 1, vault, depositAsset: USDT, amount: '100', slippageBps: 50,
+     * });
+     * ```
+     */
+    swapRouterDeposit(options: ISwapRouterDepositOptions): Promise<string>;
+    /**
+     * Resolves the real, post-execution outcome of a SwapRouter deposit from
+     * its mined receipt — the actual amount that reached the vault (and shares
+     * minted), decoded from the vault's own `Deposit` event, rather than the
+     * pre-trade quote shown before submission.
+     *
+     * @param options - {@link ISwapRouterDepositResultOptions}.
+     * @returns The decoded {@link ISwapRouterDepositResult}, or `null` if the
+     *   receipt isn't found yet or carries no matching `Deposit` log.
+     * @example
+     * ```ts
+     * const hash = await upshiftSdk.evm.swapRouterDeposit({ ... });
+     * const result = await upshiftSdk.evm.getSwapRouterDepositResult({ txHash: hash, vault });
+     * ```
+     */
+    getSwapRouterDepositResult(options: ISwapRouterDepositResultOptions): Promise<import("../../types").ISwapRouterDepositResult>;
+    /**
+     * Claim assets from a matured redemption request on a dated-redemption
+     * (RWA-style) vault. The `year`, `month`, `day`, and `receiverIndex` tuple
+     * identifies which batch of the user's matured requests to redeem from —
+     * these are emitted at request-time and indexed by the subgraph.
+     *
+     * For non-dated vaults that complete their redemption via `instantRedeem`,
+     * see {@link EVMAdapter.vaultRequestRedeem} with `isInstantRedeem: true`.
+     *
+     * @param options - {@link IContractWriteOptions} plus `year` / `month` /
+     *   `day` / `receiverIndex` identifying the matured batch to claim.
+     * @returns The redeem `TransactionResponse`.
+     * @throws UpshiftValidationError on invalid inputs.
+     * @throws UpshiftSDKError on RPC / contract revert.
+     *
+     * @example
+     * ```ts
+     * const tx = await upshiftSdk.evm.vaultRedeem({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   amount: shareAmount,
+     *   year: '2026',
+     *   month: '06',
+     *   day: '02',
+     *   receiverIndex: '0',
+     *   wait: true,
+     * });
+     * ```
+     */
+    vaultRedeem(options: IContractWriteOptions & {
+        year: string;
+        month: string;
+        day: string;
+        receiverIndex: string;
+    }): Promise<string>;
+    /**
+     * Claim a previously-requested queued withdrawal on an EVM-2 (Tokenized
+     * Vault V2) vault, once its withdrawal epoch has passed. EVM-2 only — v1/v0
+     * vaults use {@link EVMAdapter.vaultRedeem} instead.
+     *
+     * @param options - {@link IClaimWithdrawalOptions}: `target` / `wallet`
+     *   plus the `year` / `month` / `day` tuple returned by
+     *   `vaultRequestRedeem`.
+     * @returns Claim transaction hash.
+     * @throws UpshiftValidationError on invalid inputs or a non-EVM-2 vault.
+     * @throws UpshiftSDKError on RPC / contract revert.
+     *
+     * @example
+     * ```ts
+     * const { year, month, day } = await upshiftSdk.evm.vaultRequestRedeem({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   amount: '10',
+     * });
+     * await upshiftSdk.evm.claimWithdrawal({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   year,
+     *   month,
+     *   day,
+     *   wait: true,
+     * });
+     * ```
+     */
+    claimWithdrawal(options: IClaimWithdrawalOptions): Promise<string>;
+    sendersWhitelistAddress(options: {
+        vault: IAddress;
+    }): Promise<`0x${string}`>;
+    isWhitelisted(options: {
+        whitelist: IAddress;
+        wallet: IAddress;
+    }): Promise<boolean>;
+    getDeposited(options: {
+        whitelist: IAddress;
+        wallet: IAddress;
+        vault: IAddress;
+    }): Promise<import("../../types").INormalizedNumber>;
+    getRemainingAllocations(options: {
+        whitelist: IAddress;
+        wallet: IAddress;
+        vault: IAddress;
+        depositCapAmount?: bigint;
+    }): Promise<import("../../types").INormalizedNumber>;
+    /**
+     * Preview the share output of a deposit without broadcasting a transaction.
+     * See {@link readPreviewDeposit} for the routing details (EVM-1 vs EVM-2
+     * multi-asset vaults).
+     *
+     * @returns Shares minted in raw on-chain units (share-token decimals).
+     *
+     * @example
+     * ```ts
+     * const shares = await upshiftSdk.evm.previewDeposit({
+     *   vault: '0x...',
+     *   amount: 1_000_000n,
+     * });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    previewDeposit(options: IPreviewDepositOptions): Promise<bigint>;
+    /**
+     * Preview the assets returned by redeeming a number of shares, without
+     * broadcasting a transaction.
+     *
+     * @returns Assets returned in raw on-chain units (asset decimals).
+     *
+     * @example
+     * ```ts
+     * const assets = await upshiftSdk.evm.previewRedeem({
+     *   vault: '0x...',
+     *   shares: 1_000_000_000_000_000_000n,
+     * });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    previewRedeem(options: IPreviewRedeemOptions): Promise<bigint>;
+    /**
+     * Read the ERC-20 allowance an owner has granted the vault. Defaults to the
+     * vault's underlying asset; pass `asset` to override.
+     *
+     * @returns Allowance as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const raw = await upshiftSdk.evm.allowance({ vault, owner });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    allowance(options: IAllowanceOptions): Promise<bigint>;
+    /**
+     * Read an ERC-20 token balance.
+     *
+     * @returns Balance as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const raw = await upshiftSdk.evm.balanceOf({ asset: usdcAddress, owner });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    balanceOf(options: IBalanceOfOptions): Promise<bigint>;
+    /**
+     * Read the maximum deposit accepted by the vault for the supplied
+     * receiver. Useful for "vault is full" gates.
+     *
+     * @returns Max deposit as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const cap = await upshiftSdk.evm.maxDeposit({ vault });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    maxDeposit(options: IMaxDepositOptions): Promise<bigint>;
+    /**
+     * Read an EVM-2 vault's idle liquidity (`getTotalAssets() -
+     * externalAssets()`) — the balance available to an instant redemption
+     * without a synchronous recall from the settlement module.
+     *
+     * @returns Idle liquidity as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const idle = await upshiftSdk.evm.getIdleLiquidity({ vault });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    getIdleLiquidity(options: IGetIdleLiquidityOptions): Promise<bigint>;
+    /**
+     * Read an EVM-2 vault's queued-withdrawal lag, in seconds.
+     *
+     * @returns Lag duration as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const seconds = await upshiftSdk.evm.lagDuration({ vault });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    lagDuration(options: ILagDurationOptions): Promise<bigint>;
+    /**
+     * Read an EVM-2 vault's current withdrawal epoch by named field
+     * (`year`/`month`/`day`/`claimableEpoch`).
+     *
+     * @returns {@link IWithdrawalEpoch}.
+     *
+     * @example
+     * ```ts
+     * const epoch = await upshiftSdk.evm.getWithdrawalEpoch({ vault });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    getWithdrawalEpoch(options: IGetWithdrawalEpochOptions): Promise<IWithdrawalEpoch>;
+    /**
+     * Read how much of a withdrawal-epoch date's queue a receiver can
+     * currently claim, before calling {@link EVMAdapter.claimWithdrawal}.
+     *
+     * @returns Claimable amount as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const claimable = await upshiftSdk.evm.getBurnableAmountByReceiver({
+     *   vault, receiver, year, month, day,
+     * });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    getBurnableAmountByReceiver(options: IGetBurnableAmountByReceiverOptions): Promise<bigint>;
+    /**
+     * Read the total shares required to settle a withdrawal-epoch date's
+     * entire queue.
+     *
+     * @returns Required shares as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const shares = await upshiftSdk.evm.getRequirementByDate({ vault, year, month, day });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    getRequirementByDate(options: IGetRequirementByDateOptions): Promise<bigint>;
+    /**
+     * Read the scheduled queued-withdrawal volume for a withdrawal-epoch date.
+     *
+     * @returns {@link IScheduledTransactionsByDate}.
+     *
+     * @example
+     * ```ts
+     * const { totalTransactions, executionEpoch } =
+     *   await upshiftSdk.evm.getScheduledTransactionsByDate({ vault, year, month, day });
+     * ```
+     *
+     * @throws {@link UpshiftSDKError} `NO_SIGNER` when the SDK has no signer and no
+     *   configured provider for the active network.
+     */
+    getScheduledTransactionsByDate(options: IGetScheduledTransactionsByDateOptions): Promise<IScheduledTransactionsByDate>;
+}
+export default EVMAdapter;