@upshiftfinance/sdk 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,149 @@
+import type { Connection } from '@solana/web3.js';
+import type { IAddress, IEnv, ISolanaNetwork, IStellarNetwork, IWSMonitorHeaders } from '../../types';
+/**
+ * Structural interface for the Solana adapter surface used by vault operations.
+ * Avoids importing the concrete SolanaAdapter class to prevent circular dependencies.
+ */
+export interface ISolanaService {
+    connection: Connection;
+    getVaultState: (vaultProgramId: any, idl: any, vaultAddress?: any) => Promise<any>;
+    fetchUserShareBalance: (publicKey: any, shareMint: any) => Promise<any>;
+    /**
+     * Raw (BigInt-safe) variant. Required — `fetchUserShareBalance` alone
+     * returns a JS-number `uiAmount` which is lossy and silently encodes
+     * against 18 decimals when fed back through `toNormalizedBn` without an
+     * explicit decimals argument. Every consumer that needs a correct
+     * `walletBalance.raw` (positions, redemptions, max actions) MUST use this
+     * entry point.
+     *
+     * Returns `{ amount, decimals }`:
+     *   - `amount` is the on-chain u64 as a base-units string (always set;
+     *     `'0'` when no balance / no account / no args / RPC failure).
+     *   - `decimals` matches the mint when a parsed `tokenAmount` is
+     *     available; otherwise **`null`**. `decimals === null` is the
+     *     "scale unknown" signal — callers must substitute a known decimals
+     *     value (typically the deposit mint's decimals from backend metadata)
+     *     before constructing an `INormalizedNumber`. Never throws.
+     */
+    fetchUserShareBalanceRaw: (publicKey: any, shareMint: any) => Promise<{
+        amount: string;
+        decimals: number | null;
+    }>;
+    /**
+     * Canonical program id for this service's network, as
+     * `SolanaAdapter.getProgramId`. Optional so a hand-built service keeps
+     * working: without it the withdrawal-queue reads are skipped, and vaults and
+     * positions come back without queue data.
+     */
+    getProgramId?: (type: 'vault' | 'withdrawalQueue') => string;
+    /**
+     * This service's network, as `SolanaAdapter.network`. When present, the
+     * withdrawal-queue reads look the queue program up in `programIds` directly
+     * instead of calling `getProgramId`.
+     */
+    network?: ISolanaNetwork;
+}
+/**
+ * Base configuration for vault operations.
+ */
+export interface IVaultBaseOptions {
+    rpcUrl: string;
+    env?: IEnv;
+    upshiftKey?: string;
+    subgraphKey?: string;
+    chainId?: number;
+    solanaService?: ISolanaService;
+    /**
+     * Optional Soroban RPC override (e.g. a keyed Alchemy URL) for Stellar vault
+     * reads, threaded from the SDK's `stellar` config. Carries the network it was
+     * configured for so it is only applied to matching-network vaults — a testnet
+     * override must not be used for a mainnet read. Unset → built-in endpoints.
+     */
+    stellarRpc?: {
+        rpcUrl: string;
+        network: IStellarNetwork;
+    };
+    headers?: IWSMonitorHeaders;
+    /**
+     * Portfolio mode: when true, the per-vault EVM getter does NOT null out a
+     * closed + invisible vault. Needed so a user's position in a closed,
+     * invisible vault can still resolve its metadata. Defaults to undefined
+     * (false) so marketplace/discovery reads keep hiding closed staging vaults.
+     */
+    includeClosed?: boolean;
+}
+/**
+ * Optional enrichment options for vault queries.
+ */
+export interface IVaultCustomOptions {
+    loans?: boolean;
+    allocations?: boolean;
+    wallet?: IAddress;
+    solanaWallet?: string;
+    stellarWallet?: string;
+    /**
+     * Portfolio mode for a SINGLE vault read: when true, a `closed` +
+     * `is_visible: false` vault resolves normally instead of coming back as
+     * null. Needed by any caller reading ONE vault by address on behalf of a
+     * holder — a position in a closed vault must still resolve its metadata, or
+     * the holder is left with no way to act on it.
+     *
+     * The plural counterpart is {@link IGetVaultsOptions.includeClosed}; this is
+     * the same flag on the per-address path.
+     *
+     * @default false
+     */
+    includeClosed?: boolean;
+}
+/**
+ * Options accepted by `getVaults` — on both the `UpshiftSDK` facade and the
+ * underlying `UpshiftVaults` module. Defined once so the two signatures cannot
+ * drift (the facade previously declared a narrower inline type that rejected
+ * documented options like `includeClosed` at compile time).
+ */
+export interface IGetVaultsOptions extends IVaultCustomOptions {
+    chainIds?: number[];
+    headers?: IWSMonitorHeaders;
+    loadSubaccounts?: boolean;
+    loadSnapshots?: boolean;
+    /**
+     * Portfolio mode: include closed vaults in the result.
+     *
+     * By default (`false`) closed vaults are excluded, so marketplace /
+     * discovery callers never receive a `status: 'closed'` vault. When set,
+     * closed vaults are returned regardless of `is_visible` (closed +
+     * invisible vaults bucket as closed), so a consumer joining user
+     * positions can render a position held in a closed vault on the
+     * portfolio page.
+     *
+     * In this mode, loans/allocations enrichment is also skipped for closed
+     * vaults: they have none, and the per-vault enrichment
+     * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
+     * vault has no live strategy/debank data or no subaccounts, which would
+     * land the vault in the `failed` bucket and silently drop it before it
+     * reaches the filter. Skipping enrichment lets the vault survive on its
+     * backend metadata + base on-chain read.
+     *
+     * @default false
+     */
+    includeClosed?: boolean;
+    /**
+     * Maximum primary-fetch attempts per vault before the fallback
+     * strategies (fallback RPCs, minimal fetch, extended retry) run.
+     * Attempt `n` waits `baseDelay * 2^(n-1)` ms before retrying, so the
+     * default (5 attempts, 2000 ms base) can spend up to 30s of backoff on
+     * a single persistently-failing vault. Callers racing this method
+     * against their own timeout should lower it (e.g. `2`) so one flaky
+     * vault cannot exhaust the whole budget.
+     *
+     * @default 5
+     */
+    maxRetries?: number;
+    /**
+     * Base backoff delay in **milliseconds** for the per-vault retry
+     * schedule (see `maxRetries`).
+     *
+     * @default 2000
+     */
+    baseDelay?: number;
+}

package/lib/modules/vaults/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

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