@augustdigital/sdk 8.11.0 → 8.13.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