@augustdigital/sdk 8.3.2 → 8.5.0

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

@@ -1,12 +1,29 @@
 "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',
@@ -16,9 +33,11 @@ function decodeWithdrawalProcessing(txData, iface) {
                 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',
@@ -28,6 +47,7 @@ function decodeWithdrawalProcessing(txData, iface) {
                 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 {
@@ -67,6 +87,7 @@ function decodeWithdrawalProcessing(txData, iface) {
                 receiverAddr: receiverAddr.toString(),
             };
         }
+        // Unknown function that decoded successfully
         return {
             functionName: 'unknown',
             year,
@@ -85,6 +106,21 @@ function decodeWithdrawalProcessing(txData, iface) {
         };
     }
 }
+/**
+ * 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 {
@@ -95,6 +131,7 @@ async function decodeFromReceiptLogs(receipt, vaultAddress, iface) {
             error: 'No receipt available',
         };
     }
+    // Look for WithdrawalProcessed events in the logs
     for (const log of receipt.logs) {
         if (log.address.toLowerCase() !== vaultAddress.toLowerCase()) {
             continue;
@@ -102,6 +139,8 @@ async function decodeFromReceiptLogs(receipt, vaultAddress, iface) {
         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,
@@ -112,6 +151,7 @@ async function decodeFromReceiptLogs(receipt, vaultAddress, iface) {
             }
         }
         catch (e) {
+            // Not a matching event, continue
         }
     }
     return {
@@ -122,6 +162,16 @@ async function decodeFromReceiptLogs(receipt, vaultAddress, iface) {
         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',
@@ -132,6 +182,12 @@ function isMulticall(functionName) {
     ];
     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';
 }

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

@@ -1,11 +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

@@ -1,4 +1,10 @@
 "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;
@@ -6,20 +12,53 @@ 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;
+    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 ||
@@ -29,9 +68,16 @@ function isValidClaimableDate(date) {
         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();
 }

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

@@ -1,8 +1,25 @@
 import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault } 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
+ * @param tokenizedVault - The tokenized vault
+ * @returns The rewards
+ */
 export declare function getVaultRewards(tokenizedVault: ITokenizedVault): {
     points: string;
     multiplier: number;
@@ -12,9 +29,24 @@ export declare function getVaultRewards(tokenizedVault: ITokenizedVault): {
     }[];
     additionalPoints: string[];
 };
+/**
+ * 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 strategists from backend subaccounts or hardcoded list.
+ * Shared across all chain adapters.
+ */
 export declare function mapStrategists(tokenizedVault: ITokenizedVault): {
     address: IAddress;
     logo: string;
@@ -22,9 +54,30 @@ export declare function mapStrategists(tokenizedVault: ITokenizedVault): {
     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 {
@@ -33,5 +86,21 @@ export interface PermitSignature {
     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;