augustdigital-sdk 8.20.1

package/lib/modules/vaults/utils/call-data-decoder.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Withdrawal Processing Transaction Decoder
+ *
+ * Decodes transaction calldata to extract which (year, month, day) cluster
+ * was processed when a WithdrawalProcessed event was emitted.
+ */
+import type { ContractTransactionReceipt, Interface } from 'ethers';
+export interface ProcessingCallData {
+    functionName: 'processAllClaimsByDate' | 'claim' | 'unknown';
+    year: number;
+    month: number;
+    day: number;
+    maxLimit?: number;
+    receiverAddr?: string;
+    error?: string;
+}
+/**
+ * Decode withdrawal processing transaction calldata.
+ * Handles both processAllClaimsByDate() and claim() functions.
+ *
+ * Both functions have the same first 3 parameters: (year, month, day)
+ *
+ * @param txData - Raw transaction data (tx.data from provider.getTransaction())
+ * @param iface - ethers Interface initialized with vault ABI
+ * @returns Decoded parameters or error
+ */
+export declare function decodeWithdrawalProcessing(txData: string, iface: Interface): ProcessingCallData;
+/**
+ * Fallback: Parse receipt logs if calldata decoding fails.
+ *
+ * This handles the multicall wrapper case where the outer tx.data
+ * is the multicall wrapper, not the vault function. By parsing logs,
+ * we can infer what happened on-chain.
+ *
+ * Note: This is a best-effort fallback. Ideal solution is Option 2
+ * (subgraph indexing) to avoid RPC calls altogether.
+ *
+ * @param receipt - Transaction receipt from provider
+ * @param vaultAddress - Expected vault address
+ * @param iface - ethers Interface with vault ABI
+ * @returns Decoded parameters from logs, or error
+ */
+export declare function decodeFromReceiptLogs(receipt: ContractTransactionReceipt | null, vaultAddress: string, iface: Interface): Promise<ProcessingCallData>;
+/**
+ * Detect if this is a multicall/batch transaction.
+ * Common patterns:
+ * - Uniswap Multicall: 0x1f0464f6
+ * - Gnosis Safe: 0x6a761202
+ * - 1inch Aggregator: 0x7c025200
+ *
+ * @param functionName - Function name from parsed decoded tx
+ * @returns true if this appears to be a batch/multicall
+ */
+export declare function isMulticall(functionName: string): boolean;
+/**
+ * Detect if the decoded function is one we care about for withdrawal processing.
+ *
+ * @param functionName - Function name from decoding
+ * @returns true if this is a withdrawal processing function
+ */
+export declare function isWithdrawalProcessingFunction(functionName: string): boolean;

package/lib/modules/vaults/utils/call-data-decoder.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Withdrawal Processing Transaction Decoder
+ *
+ * Decodes transaction calldata to extract which (year, month, day) cluster
+ * was processed when a WithdrawalProcessed event was emitted.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeWithdrawalProcessing = decodeWithdrawalProcessing;
+exports.decodeFromReceiptLogs = decodeFromReceiptLogs;
+exports.isMulticall = isMulticall;
+exports.isWithdrawalProcessingFunction = isWithdrawalProcessingFunction;
+/**
+ * Decode withdrawal processing transaction calldata.
+ * Handles both processAllClaimsByDate() and claim() functions.
+ *
+ * Both functions have the same first 3 parameters: (year, month, day)
+ *
+ * @param txData - Raw transaction data (tx.data from provider.getTransaction())
+ * @param iface - ethers Interface initialized with vault ABI
+ * @returns Decoded parameters or error
+ */
+function decodeWithdrawalProcessing(txData, iface) {
+    try {
+        const decoded = iface.parseTransaction({ data: txData });
+        // Validation
+        if (!decoded || !decoded.args || decoded.args.length < 3) {
+            return {
+                functionName: 'unknown',
+                year: 0,
+                month: 0,
+                day: 0,
+                error: 'Invalid calldata: insufficient args',
+            };
+        }
+        // Extract first 3 parameters (shared by both functions)
+        const year = Number(decoded.args[0]);
+        const month = Number(decoded.args[1]);
+        const day = Number(decoded.args[2]);
+        // Validate date parameters are reasonable
+        if (year < 2000 || year > 2100 || month < 1 || month > 12 || day < 1) {
+            return {
+                functionName: 'unknown',
+                year,
+                month,
+                day,
+                error: 'Invalid date parameters',
+            };
+        }
+        // Validate day is valid for the month
+        const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
+        if (day > daysInMonth) {
+            return {
+                functionName: 'unknown',
+                year,
+                month,
+                day,
+                error: `Invalid day for month: ${day} > ${daysInMonth}`,
+            };
+        }
+        if (decoded.name === 'processAllClaimsByDate') {
+            const maxLimit = decoded.args[3] ? Number(decoded.args[3]) : undefined;
+            return {
+                functionName: 'processAllClaimsByDate',
+                year,
+                month,
+                day,
+                maxLimit,
+            };
+        }
+        else if (decoded.name === 'claim') {
+            const receiverAddr = decoded.args[3];
+            if (!receiverAddr) {
+                return {
+                    functionName: 'unknown',
+                    year,
+                    month,
+                    day,
+                    error: 'Missing receiver address in claim()',
+                };
+            }
+            return {
+                functionName: 'claim',
+                year,
+                month,
+                day,
+                receiverAddr: receiverAddr.toString(),
+            };
+        }
+        // Unknown function that decoded successfully
+        return {
+            functionName: 'unknown',
+            year,
+            month,
+            day,
+            error: `Unknown withdrawal function: ${decoded.name}`,
+        };
+    }
+    catch (error) {
+        return {
+            functionName: 'unknown',
+            year: 0,
+            month: 0,
+            day: 0,
+            error: error instanceof Error ? error.message : 'Unknown decoding error',
+        };
+    }
+}
+/**
+ * Fallback: Parse receipt logs if calldata decoding fails.
+ *
+ * This handles the multicall wrapper case where the outer tx.data
+ * is the multicall wrapper, not the vault function. By parsing logs,
+ * we can infer what happened on-chain.
+ *
+ * Note: This is a best-effort fallback. Ideal solution is Option 2
+ * (subgraph indexing) to avoid RPC calls altogether.
+ *
+ * @param receipt - Transaction receipt from provider
+ * @param vaultAddress - Expected vault address
+ * @param iface - ethers Interface with vault ABI
+ * @returns Decoded parameters from logs, or error
+ */
+async function decodeFromReceiptLogs(receipt, vaultAddress, iface) {
+    if (!receipt) {
+        return {
+            functionName: 'unknown',
+            year: 0,
+            month: 0,
+            day: 0,
+            error: 'No receipt available',
+        };
+    }
+    // Look for WithdrawalProcessed events in the logs
+    for (const log of receipt.logs) {
+        if (log.address.toLowerCase() !== vaultAddress.toLowerCase()) {
+            continue;
+        }
+        try {
+            const parsed = iface.parseLog(log);
+            if (parsed && parsed.name === 'WithdrawalProcessed') {
+                // Event found but date cannot be extracted from the current event schema.
+                // Return with year/month/day = 0 to signal caller should use fallback.
+                return {
+                    functionName: 'processAllClaimsByDate',
+                    year: 0,
+                    month: 0,
+                    day: 0,
+                    error: 'Event found but date not available in event schema',
+                };
+            }
+        }
+        catch (e) {
+            // Not a matching event, continue
+        }
+    }
+    return {
+        functionName: 'unknown',
+        year: 0,
+        month: 0,
+        day: 0,
+        error: 'No WithdrawalProcessed logs found',
+    };
+}
+/**
+ * Detect if this is a multicall/batch transaction.
+ * Common patterns:
+ * - Uniswap Multicall: 0x1f0464f6
+ * - Gnosis Safe: 0x6a761202
+ * - 1inch Aggregator: 0x7c025200
+ *
+ * @param functionName - Function name from parsed decoded tx
+ * @returns true if this appears to be a batch/multicall
+ */
+function isMulticall(functionName) {
+    const multicallNames = [
+        'multicall',
+        'aggregate',
+        'aggregate3',
+        'batchcall',
+        'batch',
+    ];
+    return multicallNames.includes(functionName.toLowerCase());
+}
+/**
+ * Detect if the decoded function is one we care about for withdrawal processing.
+ *
+ * @param functionName - Function name from decoding
+ * @returns true if this is a withdrawal processing function
+ */
+function isWithdrawalProcessingFunction(functionName) {
+    return functionName === 'processAllClaimsByDate' || functionName === 'claim';
+}
+//# sourceMappingURL=call-data-decoder.js.map

package/lib/modules/vaults/utils/date-utils.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Withdrawal Date Utilities
+ *
+ * Mirrors TimelockedVault.sol's DateUtils logic for computing claimable dates.
+ * All operations are in UTC to match contract behavior.
+ */
+export interface ClaimableDate {
+    year: number;
+    month: number;
+    day: number;
+    epoch: number;
+}
+/**
+ * Compute the claimable date for a withdrawal request.
+ * Replicates TimelockedVault.requestRedeem() logic exactly.
+ *
+ * The contract does:
+ *   (year, month, day) = DateUtils.timestampToDate(block.timestamp + 300 + lagDuration)
+ *
+ * @param requestTimestamp - Block timestamp of the request (in seconds, UTC)
+ * @param lagDuration - Lag duration in seconds (e.g., 86400 for 1 day)
+ * @returns The date when the withdrawal becomes claimable (UTC)
+ */
+export declare function computeClaimableDate(requestTimestamp: number, lagDuration: number): ClaimableDate;
+/**
+ * Check if a withdrawal request is ready to claim.
+ * The contract allows claiming when: block.timestamp + 300 >= claimableEpoch
+ *
+ * @param claimableEpoch - The epoch when this request became claimable
+ * @param currentEpoch - Current timestamp (usually block.timestamp or now)
+ * @returns true if claimable now
+ */
+export declare function isClaimableNow(claimableEpoch: number, currentEpoch: number): boolean;
+/**
+ * Format date for use as a lookup key (e.g., "2024-03-16")
+ * Ensures consistent formatting across the codebase.
+ */
+export declare function formatDateKey(year: number, month: number, day: number): string;
+/**
+ * Verify that computed date matches expected format.
+ * Used for debugging and validation.
+ */
+export declare function isValidClaimableDate(date: ClaimableDate): boolean;
+/**
+ * Get the number of days in a given month.
+ * @param year - Year (4-digit)
+ * @param month - Month (1-12)
+ * @returns Number of days in that month
+ */
+export declare function getDaysInMonth(year: number, month: number): number;

package/lib/modules/vaults/utils/date-utils.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Withdrawal Date Utilities
+ *
+ * Mirrors TimelockedVault.sol's DateUtils logic for computing claimable dates.
+ * All operations are in UTC to match contract behavior.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeClaimableDate = computeClaimableDate;
+exports.isClaimableNow = isClaimableNow;
+exports.formatDateKey = formatDateKey;
+exports.isValidClaimableDate = isValidClaimableDate;
+exports.getDaysInMonth = getDaysInMonth;
+const TIMESTAMP_MANIPULATION_WINDOW = 300;
+/**
+ * Compute the claimable date for a withdrawal request.
+ * Replicates TimelockedVault.requestRedeem() logic exactly.
+ *
+ * The contract does:
+ *   (year, month, day) = DateUtils.timestampToDate(block.timestamp + 300 + lagDuration)
+ *
+ * @param requestTimestamp - Block timestamp of the request (in seconds, UTC)
+ * @param lagDuration - Lag duration in seconds (e.g., 86400 for 1 day)
+ * @returns The date when the withdrawal becomes claimable (UTC)
+ */
+function computeClaimableDate(requestTimestamp, lagDuration) {
+    // Add 300s + lagDuration to the request timestamp
+    // This must be done BEFORE converting to date, not after
+    const claimableEpoch = requestTimestamp + TIMESTAMP_MANIPULATION_WINDOW + lagDuration;
+    // Convert to UTC date
+    // CRITICAL: Use getUTC* methods, not local timezone methods
+    const date = new Date(claimableEpoch * 1000);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + 1; // getUTCMonth() returns 0-11
+    const day = date.getUTCDate();
+    return { year, month, day, epoch: claimableEpoch };
+}
+/**
+ * Check if a withdrawal request is ready to claim.
+ * The contract allows claiming when: block.timestamp + 300 >= claimableEpoch
+ *
+ * @param claimableEpoch - The epoch when this request became claimable
+ * @param currentEpoch - Current timestamp (usually block.timestamp or now)
+ * @returns true if claimable now
+ */
+function isClaimableNow(claimableEpoch, currentEpoch) {
+    // Ready to claim when: currentEpoch + 300 >= claimableEpoch
+    // Which means: currentEpoch >= claimableEpoch - 300
+    return currentEpoch >= claimableEpoch - TIMESTAMP_MANIPULATION_WINDOW;
+}
+/**
+ * Format date for use as a lookup key (e.g., "2024-03-16")
+ * Ensures consistent formatting across the codebase.
+ */
+function formatDateKey(year, month, day) {
+    return `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+/**
+ * Verify that computed date matches expected format.
+ * Used for debugging and validation.
+ */
+function isValidClaimableDate(date) {
+    if (date.year < 2000 ||
+        date.year > 2100 ||
+        date.month < 1 ||
+        date.month > 12 ||
+        date.day < 1 ||
+        date.epoch <= 0) {
+        return false;
+    }
+    // Validate day is valid for the month (use Date.UTC to avoid local timezone issues)
+    const daysInMonth = new Date(Date.UTC(date.year, date.month, 0)).getUTCDate();
+    return date.day <= daysInMonth;
+}
+/**
+ * Get the number of days in a given month.
+ * @param year - Year (4-digit)
+ * @param month - Month (1-12)
+ * @returns Number of days in that month
+ */
+function getDaysInMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+//# sourceMappingURL=date-utils.js.map

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

@@ -0,0 +1,140 @@
+import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault, IVaultFreshness } from '../../types';
+import { ethers } from 'ethers';
+import type { WalletClient } from 'viem';
+/**
+ * @param walletClient a wagmi-derived client (from useWalletClient)
+ * @returns An ethers JsonRpcSigner object used in sdk.evm.setSigner
+ */
+export declare function walletClientToSigner(walletClient: WalletClient): Promise<ethers.JsonRpcSigner>;
+/**
+ * Calculates the reward multiplier based on the vault and optional timestamp.
+ * Returns the applicable multiplier for a given vault at a specific timestamp,
+ * or the latest multiplier if no timestamp is provided.
+ * @param foundPool The vault to get the multiplier for
+ * @param timestamp Optional timestamp to get historical multiplier
+ * @returns The reward multiplier value
+ */
+export declare const getRewardMultiplierByTimestamp: (foundPool: IVault, timestamp?: number) => number;
+/**
+ * Get the rewards for the vault.
+ *
+ * Builds the display-facing rewards summary from the raw tokenized-vault
+ * rewards array. In addition to the legacy `additionalPoints` string list, it
+ * emits `additionalPointsDetailed`, which pairs each label with its
+ * backend-provided `img_url`. Consumers (e.g. the Upshift app) resolve a
+ * reward's logo from this `imgUrl` first, falling back to a bundled asset only
+ * when it is absent — so a newly-added reward with a backend logo (e.g.
+ * "Cores") renders its icon without any client-side keyword mapping.
+ *
+ * @param tokenizedVault - The tokenized vault.
+ * @returns The rewards summary, including `additionalPointsDetailed`.
+ */
+export declare function getVaultRewards(tokenizedVault: ITokenizedVault): {
+    points: string;
+    multiplier: number;
+    multipliers: {
+        timestamp: number;
+        value: number;
+    }[];
+    additionalPoints: string[];
+    additionalPointsDetailed: {
+        id: string;
+        label: string;
+        text: string;
+        imgUrl: string;
+        multiplier: number;
+    }[];
+};
+/**
+ * Get the idle assets for the vault
+ * @param provider - The provider
+ * @param vaultAddress - The vault address
+ * @param totalAssets - The total assets of the vault
+ * @returns The idle assets
+ */
+export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber): Promise<bigint>;
+export declare function getYieldLastRealizedOn(provider: IContractRunner, vaultAddress: IAddress): Promise<number>;
+/**
+ * Format APY data from backend tokenized vault into the unified IVaultApy shape.
+ * Shared across all chain adapters (EVM, Solana, Stellar).
+ */
+export declare function formatVaultApy(tokenizedVault: ITokenizedVault): IVault['apy'];
+/**
+ * Map the backend `freshness` object onto the camelCased {@link IVaultFreshness}
+ * shape carried on `IVault`. Shared across all chain adapters (EVM, Solana,
+ * Stellar) so every surface reports provenance identically.
+ *
+ * Each of the three stamps is passed through independently: a missing member
+ * becomes `null` and is never defaulted from one of the others. That is the point
+ * of the object — `apy_computed_at` and `share_ratio_snapshot_at` describe two
+ * different pipelines, and collapsing them would erase the very staleness signal
+ * (snapshot newer than APY) the field exists to expose.
+ *
+ * @param tokenizedVault - Backend tokenized-vault payload. `freshness` is absent on
+ *   responses predating the backend change, and may be explicitly null.
+ * @returns The mapped freshness object, or `null` when the backend reported none.
+ *   Values are the backend's RFC 3339 UTC strings verbatim — no reformatting, so
+ *   the trailing `Z` is preserved.
+ */
+export declare function mapVaultFreshness(tokenizedVault: ITokenizedVault | undefined | null): IVaultFreshness | null;
+/**
+ * Map strategists from backend subaccounts or hardcoded list.
+ * Shared across all chain adapters.
+ */
+export declare function mapStrategists(tokenizedVault: ITokenizedVault): {
+    address: IAddress;
+    logo: string;
+    name: string;
+    type: string;
+    website_url: string;
+}[];
+/**
+ * Map composability integrations from backend format to vault format.
+ * Shared across all chain adapters.
+ */
+export declare function mapComposabilityIntegrations(tokenizedVault: ITokenizedVault): IVault['composabilityIntegrations'];
+/**
+ * Convert a backend-reported TVL (whole token units) to a NormalizedBn.
+ * Handles null, undefined, and non-finite values (NaN, Infinity) safely, defaulting to 0.
+ * Shared between non-EVM adapters (Solana, Stellar) and the module-level getVaultTvl handler.
+ */
+export declare function backendTvlToNormalizedBn(tvl: number | null | undefined, decimals: number): INormalizedNumber;
+/**
+ * Build a base IVault from backend data, shared across non-EVM adapters (Solana, Stellar).
+ * Chain-specific fields (chainId, version, name, totalAssets, totalSupply, depositAssets, receipt)
+ * must be provided via the overrides parameter.
+ */
+export declare function buildBackendVault(tokenizedVault: ITokenizedVault, overrides: Pick<IVault, 'chainId' | 'version' | 'name' | 'totalAssets' | 'totalSupply' | 'depositAssets' | 'receipt'> & Pick<Partial<IVault>, 'programId' | 'enabled_historical_price_horizons' | 'defaultApyHorizon' | 'latest_reported_tvl' | 'isDepositPaused' | 'isWithdrawalPaused'>): IVault;
+/**
+ * Build the formatted vault
+ * @param provider - The provider
+ * @param tokenizedVault - The tokenized vault
+ * @param contractCalls - The contract calls
+ * @returns The formatted vault
+ */
+export declare function buildFormattedVault(provider: IContractRunner, tokenizedVault: ITokenizedVault, contractCalls: Record<IPoolFunctions, string | number | INormalizedNumber | boolean | IAddress[]>): Promise<IVault>;
+export declare const ERC_20_PERMIT_HASH = "0x6e71edae12b1b97f4d1f60370fef10105fa2faae0126114a169c64845d6126c9";
+export interface PermitSignature {
+    r: string;
+    s: string;
+    v: number;
+    deadline: number;
+}
+/**
+ * Generate an ERC2612 permit signature
+ * @param token - The ERC20 token contract address
+ * @param owner - The token owner's address (signer)
+ * @param spender - The address that will be approved to spend (your pool contract)
+ * @param value - The amount to approve
+ * @param deadline - Unix timestamp for when the permit expires
+ * @param signer - The ethers.js Signer (wallet)
+ * @param provider - The ethers.js Provider
+ * @returns The signature components (v, r, s) and deadline
+ */
+export declare function generatePermitSignature(token: string, owner: string, spender: string, value: string | bigint, deadline: number, signer: ethers.Signer, chainId: number): Promise<PermitSignature>;
+/**
+ * Helper to create a deadline (current time + offset in seconds)
+ * @param offsetSeconds - Number of seconds from now (default: 20 minutes)
+ * @returns Unix timestamp
+ */
+export declare function createDeadline(offsetSeconds?: number): number;