upshift-finance 1.0.0

package/lib/modules/vaults/prefetch.d.ts

@@ -0,0 +1,65 @@
+import type { IAddress, ITokenizedVault } from '../../types';
+/**
+ * Per-vault on-chain reads resolved ahead of the positions fan-out, so
+ * `getVaultPositions` / `getVaultAvailableRedemptions` can skip their own
+ * `balanceOf` / `lagDuration` RPCs. A missing field means the read was not
+ * (or could not be) prefetched — the getter falls back to its own call.
+ * @internal
+ */
+export interface IPrefetchedVaultReads {
+    /** Raw share/receipt-token balance of the wallet (`balanceOf`). */
+    balance?: bigint;
+    /** Vault redemption lag in seconds (`lagDuration`). */
+    lagDuration?: number;
+}
+/**
+ * Minimal shape of a backend tokenized-vault row the prefetch needs. The
+ * full backend response type is looser than this; only these fields are read.
+ * @internal
+ */
+interface IPrefetchableVault {
+    address: string;
+    chain: number;
+    chain_type?: string;
+    /**
+     * Backend vault kind. `getVaultVersionV2` reads this to classify evm-2
+     * (`multiAssetVault`) vaults whose address isn't in the hardcoded
+     * `MULTI_ASSET_VAULTS` list; without it such a vault would be misclassified
+     * as evm-1 and the batch would target the vault itself for `balanceOf`
+     * instead of its receipt token.
+     */
+    internal_type?: ITokenizedVault['internal_type'];
+}
+/**
+ * Batch the two non-cacheable per-vault reads (`balanceOf`, `lagDuration`)
+ * for a vault list via Multicall3, grouped by chain, ahead of the per-vault
+ * positions fan-out.
+ *
+ * Scope and fallback rules (task 52):
+ * - Only EVM vaults on chains with a configured provider AND a verified
+ *   Multicall3 deployment are batched. Solana/Stellar vaults, unverified
+ *   chains (e.g. Citrea 4114), and provider-less chains are skipped — they
+ *   keep today's exact per-vault read path.
+ * - `balanceOf` targets the receipt token for evm-2 vaults (resolved through
+ *   the same cached `getReceiptTokenAddress` the getters use) and the vault
+ *   itself for evm-1. Without an EVM wallet only `lagDuration` is batched.
+ * - Failures never propagate: a reverting vault call is simply absent from
+ *   the result map, and a whole-chain error drops that chain's entries. The
+ *   worst case is always "no prefetch → per-vault fallback", never wrong data.
+ *
+ * RPC cost: per batched chain, `ceil(reads / 10)` `eth_call`s (+1 cold
+ * `lpTokenAddress` per evm-2 vault) instead of ~2 `eth_call`s per vault.
+ *
+ * @param vaults Backend tokenized-vault rows about to be fanned out over.
+ * @param wallet Optional EVM wallet for `balanceOf` reads.
+ * @param providers Chain-id → RPC-url map (the module's `this.providers`).
+ * @returns Map keyed by lowercased vault address; vaults with no batched
+ *   reads have no entry.
+ * @internal
+ */
+export declare function prefetchVaultPositionReads({ vaults, wallet, providers, }: {
+    vaults: IPrefetchableVault[];
+    wallet?: IAddress;
+    providers?: Partial<Record<number, string>>;
+}): Promise<Map<string, IPrefetchedVaultReads>>;
+export {};

package/lib/modules/vaults/prefetch.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prefetchVaultPositionReads = prefetchVaultPositionReads;
+const ethers_1 = require("ethers");
+const abis_1 = require("../../abis");
+const TokenizedVaultV2Receipt_1 = require("../../abis/TokenizedVaultV2Receipt");
+const core_1 = require("../../core");
+/**
+ * Batch the two non-cacheable per-vault reads (`balanceOf`, `lagDuration`)
+ * for a vault list via Multicall3, grouped by chain, ahead of the per-vault
+ * positions fan-out.
+ *
+ * Scope and fallback rules (task 52):
+ * - Only EVM vaults on chains with a configured provider AND a verified
+ *   Multicall3 deployment are batched. Solana/Stellar vaults, unverified
+ *   chains (e.g. Citrea 4114), and provider-less chains are skipped — they
+ *   keep today's exact per-vault read path.
+ * - `balanceOf` targets the receipt token for evm-2 vaults (resolved through
+ *   the same cached `getReceiptTokenAddress` the getters use) and the vault
+ *   itself for evm-1. Without an EVM wallet only `lagDuration` is batched.
+ * - Failures never propagate: a reverting vault call is simply absent from
+ *   the result map, and a whole-chain error drops that chain's entries. The
+ *   worst case is always "no prefetch → per-vault fallback", never wrong data.
+ *
+ * RPC cost: per batched chain, `ceil(reads / 10)` `eth_call`s (+1 cold
+ * `lpTokenAddress` per evm-2 vault) instead of ~2 `eth_call`s per vault.
+ *
+ * @param vaults Backend tokenized-vault rows about to be fanned out over.
+ * @param wallet Optional EVM wallet for `balanceOf` reads.
+ * @param providers Chain-id → RPC-url map (the module's `this.providers`).
+ * @returns Map keyed by lowercased vault address; vaults with no batched
+ *   reads have no entry.
+ * @internal
+ */
+async function prefetchVaultPositionReads({ vaults, wallet, providers, }) {
+    const reads = new Map();
+    const hasWallet = !!(wallet && (0, ethers_1.isAddress)(wallet));
+    const byChain = new Map();
+    for (const v of vaults) {
+        if (!v?.address || !(0, ethers_1.isAddress)(v.address))
+            continue;
+        if (!(0, core_1.isMulticall3Supported)(v.chain))
+            continue;
+        if (!providers?.[v.chain])
+            continue;
+        const group = byChain.get(v.chain) ?? [];
+        group.push(v);
+        byChain.set(v.chain, group);
+    }
+    await Promise.all(Array.from(byChain.entries()).map(async ([chain, chainVaults]) => {
+        try {
+            // Same cache key as the getters (`createProvider(rpcUrl)` without a
+            // chainId) so the receipt-token/decimals caches stay shared.
+            const provider = (0, core_1.createProvider)(providers[chain]);
+            // Resolve each vault's `balanceOf` target — the receipt token for
+            // evm-2 vaults (one `lpTokenAddress` read each on a cold cache),
+            // the vault itself otherwise. Bound the fan-out to
+            // `MULTICALL3_BATCH_SIZE` concurrent reads (CLAUDE.md §4.1): a wallet
+            // with many uncached evm-2 vaults on one chain would otherwise burst
+            // N simultaneous reads before the aggregate3 batch even fires.
+            const balanceTargets = [];
+            for (let i = 0; i < chainVaults.length; i += core_1.MULTICALL3_BATCH_SIZE) {
+                const slice = chainVaults.slice(i, i + core_1.MULTICALL3_BATCH_SIZE);
+                const resolved = await Promise.all(slice.map(async (v) => {
+                    if (!hasWallet)
+                        return undefined;
+                    if ((0, core_1.getVaultVersionV2)(v) === 'evm-2') {
+                        // Cached + in-flight-deduped; a cold miss costs the same
+                        // `lpTokenAddress` read the getter itself would make.
+                        return (0, core_1.getReceiptTokenAddress)(provider, v.address);
+                    }
+                    return v.address;
+                }));
+                balanceTargets.push(...resolved);
+            }
+            const calls = [];
+            const slots = [];
+            chainVaults.forEach((v, i) => {
+                calls.push({
+                    target: v.address,
+                    abi: abis_1.ABI_LENDING_POOL_V2,
+                    functionName: 'lagDuration',
+                });
+                slots.push({ address: v.address, field: 'lagDuration' });
+                const target = balanceTargets[i];
+                if (hasWallet && target && (0, ethers_1.isAddress)(target)) {
+                    calls.push({
+                        target: target,
+                        abi: target === v.address
+                            ? abis_1.ABI_LENDING_POOL_V2
+                            : TokenizedVaultV2Receipt_1.ABI_TOKENIZED_VAULT_V2_RECEIPT,
+                        functionName: 'balanceOf',
+                        args: [wallet],
+                    });
+                    slots.push({ address: v.address, field: 'balance' });
+                }
+            });
+            const results = await (0, core_1.multicall3Aggregate)(provider, chain, calls);
+            results.forEach((r, i) => {
+                if (!r.success)
+                    return;
+                const slot = slots[i];
+                const key = slot.address.toLowerCase();
+                const entry = reads.get(key) ?? {};
+                if (slot.field === 'lagDuration') {
+                    entry.lagDuration = Number(r.value);
+                }
+                else {
+                    entry.balance = BigInt(r.value);
+                }
+                reads.set(key, entry);
+            });
+        }
+        catch (e) {
+            core_1.Logger.log.warn('prefetchVaultPositionReads', `chain ${chain} prefetch failed — falling back to per-vault reads`, e);
+        }
+    }));
+    return reads;
+}
+//# sourceMappingURL=prefetch.js.map

package/lib/modules/vaults/read.actions.d.ts

@@ -0,0 +1,225 @@
+import type { IAddress, IContractRunner, INormalizedNumber } from '../../types';
+import type { IContractWriteOptions } from './write.actions';
+/**
+ * Function to fetch instant redemption fee
+ * @param signer - signer / provider object
+ * @param options - object including pool contract address, user wallet address
+ * @returns normalized number object of the instant redemption fee
+ */
+export declare function fetchInstantRedemptionFee(signer: IContractRunner, options: IContractWriteOptions): Promise<INormalizedNumber>;
+/**
+ * allowance checks user's current allowance per pool
+ * @param signer - signer / provider object
+ * @param options - object including pool contract address, user wallet address
+ * @returns normalized number object of the user's current allowance
+ */
+export declare function vaultAllowance(signer: IContractRunner, options: IContractWriteOptions): Promise<INormalizedNumber>;
+/**
+ * Fetches the senders whitelist contract address from a whitelisted allocation vault
+ * @param signer - signer / provider object
+ * @param options - object including vault contract address
+ * @returns the senders whitelist contract address
+ */
+export declare function sendersWhitelistAddress(signer: IContractRunner, options: {
+    vault: IAddress;
+}): Promise<IAddress | undefined>;
+/**
+ * Checks if an address is whitelisted on a whitelist contract
+ * @param signer - signer / provider object
+ * @param options - object including whitelist contract address and wallet address to check
+ * @returns boolean indicating if the address is whitelisted
+ */
+export declare function isWhitelisted(signer: IContractRunner, options: {
+    whitelist: IAddress;
+    wallet: IAddress;
+}): Promise<boolean | undefined>;
+/**
+ * Fetches the total amount deposited by an address on a whitelist contract
+ * @param signer - signer / provider object
+ * @param options - object including whitelist contract address, wallet address, and vault address
+ * @returns normalized number of the deposited amount
+ */
+export declare function getDeposited(signer: IContractRunner, options: {
+    whitelist: IAddress;
+    wallet: IAddress;
+    vault: IAddress;
+}): Promise<INormalizedNumber | undefined>;
+/**
+ * Fetches the remaining allocation for an address on a whitelist contract
+ * @param signer - signer / provider object
+ * @param options - object including whitelist contract address, wallet address, vault address, and optional deposit cap amount
+ * @returns the remaining allocation as normalized number
+ */
+export declare function getRemainingAllocations(signer: IContractRunner, options: {
+    whitelist: IAddress;
+    wallet: IAddress;
+    vault: IAddress;
+    depositCapAmount?: bigint;
+}): Promise<INormalizedNumber | undefined>;
+export type IPreviewRwaRedemptionOptions = {
+    /** RwaRedeemSubaccount contract address */
+    target: IAddress;
+    /** Redeemable asset address (e.g. USDC, USDT) */
+    asset: IAddress;
+    /** Amount of vault shares to preview */
+    amount: string | bigint | number;
+    /** Decimals of the vault share token */
+    decimals: number;
+    /** Decimals of the output/redeemable asset */
+    outputDecimals: number;
+};
+/**
+ * Preview the output amount for an RWA instant redemption via the RwaRedeemSubaccount contract.
+ * @param signer - signer / provider object
+ * @param options - object including subaccount address, asset, amount, decimals, and outputDecimals
+ * @returns normalized number of the expected output amount (in output asset decimals)
+ */
+export declare function previewRwaRedemption(signer: IContractRunner, options: IPreviewRwaRedemptionOptions): Promise<INormalizedNumber | undefined>;
+/** Options for {@link previewDeposit}. */
+export type IPreviewDepositOptions = {
+    /** Vault contract address. */
+    vault: IAddress;
+    /** Deposit amount in the deposit asset's smallest unit (raw bigint-shaped). */
+    amount: string | bigint | number;
+    /**
+     * Optional deposit asset. Required for multi-asset vaults (EVM-2); ignored
+     * for single-asset vaults where the underlying is implicit.
+     */
+    asset?: IAddress;
+};
+/** Options for {@link previewRedeem}. */
+export type IPreviewRedeemOptions = {
+    /** Vault contract address. */
+    vault: IAddress;
+    /** Share amount in the vault share token's smallest unit (raw bigint-shaped). */
+    shares: string | bigint | number;
+};
+/** Options for {@link allowance}. */
+export type IAllowanceOptions = {
+    /** Spender contract — usually the vault address. */
+    vault: IAddress;
+    /** Owner whose ERC-20 allowance is being queried. */
+    owner: IAddress;
+    /**
+     * Token whose allowance is queried. Defaults to the vault's underlying
+     * asset, resolved via `IERC4626.asset()`.
+     */
+    asset?: IAddress;
+};
+/** Options for {@link balanceOf}. */
+export type IBalanceOfOptions = {
+    /** ERC-20 token address. */
+    asset: IAddress;
+    /** Owner whose balance is queried. */
+    owner: IAddress;
+};
+/** Options for {@link maxDeposit}. */
+export type IMaxDepositOptions = {
+    /** Vault contract address. */
+    vault: IAddress;
+    /**
+     * Receiver address — passed to ERC-4626 `maxDeposit(address)` on single-
+     * asset vaults. Ignored by EVM-2 multi-asset vaults which expose a vault-
+     * level `maxDepositAmount()` without a receiver argument.
+     */
+    receiver?: IAddress;
+};
+/**
+ * Preview the number of shares that would be minted for a deposit, without
+ * touching on-chain state. Routes between single-asset ERC-4626 and EVM-2
+ * multi-asset vaults using the vault version detected from backend metadata.
+ *
+ * @returns The number of shares (raw on-chain units, share-token decimals).
+ * @throws AugustValidationError on invalid vault address or amount.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const shares = await augustSdk.evm.previewDeposit({
+ *   vault: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+ *   amount: 1_000_000n,           // 1 USDC (6 decimals)
+ * });
+ * ```
+ */
+export declare function previewDeposit(signer: IContractRunner, options: IPreviewDepositOptions): Promise<bigint>;
+/**
+ * Preview the number of underlying assets returned by redeeming a given
+ * number of shares, without touching on-chain state. Routes between single-
+ * asset ERC-4626 (`previewRedeem`) and EVM-2 multi-asset
+ * (`previewRedemption(shares, isInstant=false)`) using the vault version.
+ *
+ * @returns The assets that would be redeemed (raw on-chain units, asset
+ *   decimals).
+ * @throws AugustValidationError on invalid vault or share input.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const assets = await augustSdk.evm.previewRedeem({
+ *   vault: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+ *   shares: 1_000_000_000_000_000_000n, // 1 share (18 decimals)
+ * });
+ * ```
+ */
+export declare function previewRedeem(signer: IContractRunner, options: IPreviewRedeemOptions): Promise<bigint>;
+/**
+ * Read the ERC-20 allowance an `owner` has granted to a vault (the spender).
+ * If `asset` is omitted, the vault's underlying asset is resolved via
+ * `IERC4626.asset()` and used as the token.
+ *
+ * Returns a raw `bigint` to keep BigInt math precise — call
+ * {@link toNormalizedBn} if you need a UI-shaped {@link INormalizedNumber}.
+ *
+ * @returns Allowance in raw on-chain units of `asset`.
+ * @throws AugustValidationError on invalid addresses.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const raw = await augustSdk.evm.allowance({
+ *   vault: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+ *   owner: walletAddress,
+ * });
+ * if (raw < requiredAmount) {
+ *   await augustSdk.evm.vaultApprove({
+ *     target: vault,
+ *     wallet: walletAddress,
+ *     amount: requiredAmount.toString(),
+ *   });
+ * }
+ * ```
+ */
+export declare function allowance(signer: IContractRunner, options: IAllowanceOptions): Promise<bigint>;
+/**
+ * Read an ERC-20 balance directly. Returns the raw on-chain value as
+ * `bigint`; call {@link toNormalizedBn} if you need a {@link INormalizedNumber}.
+ *
+ * @returns Balance in raw on-chain units of `asset`.
+ * @throws AugustValidationError on invalid asset / owner addresses.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const raw = await augustSdk.evm.balanceOf({
+ *   asset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+ *   owner: walletAddress,
+ * });
+ * ```
+ */
+export declare function balanceOf(signer: IContractRunner, options: IBalanceOfOptions): Promise<bigint>;
+/**
+ * Read the maximum deposit currently accepted by a vault. Routes between
+ * single-asset ERC-4626 (`maxDeposit(receiver)`) and EVM-2 multi-asset
+ * (`maxDepositAmount()`, vault-level cap, no receiver dependence).
+ *
+ * @returns Max deposit in raw on-chain units of the deposit asset.
+ * @throws AugustValidationError on invalid vault address.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const cap = await augustSdk.evm.maxDeposit({ vault });
+ * if (cap === 0n) showVaultIsFullToast();
+ * ```
+ */
+export declare function maxDeposit(signer: IContractRunner, options: IMaxDepositOptions): Promise<bigint>;