@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/modules/sub-accounts/utils.d.ts

@@ -0,0 +1,106 @@
+import type { IWSSubaccountSummary } from '../../types';
+/**
+ * Transform the raw API response to camelCase
+ */
+export declare const transformSubaccountSummary: (response: IWSSubaccountSummary) => {
+    address: `0x${string}`;
+    name: string;
+    type: "eoa" | "subaccount";
+    portfolio: {
+        tokens: {
+            value: number;
+            balance: number;
+            token: {
+                type: string;
+                name: string;
+                address: string;
+                chain: number;
+                symbol: string;
+                decimals: number;
+                imgUrl: string;
+            };
+        }[];
+        marginBalances: unknown[];
+        collateralBalances: unknown[];
+        cefiPositions: unknown[];
+        defiPositions: unknown[];
+        trsPositions: unknown[];
+        strategyContractPositions: unknown[];
+        legacyHedgerPositions: unknown[];
+        otcPositions: unknown[];
+        totalValue: number;
+        discountedValue: number;
+    };
+    loanbook: {
+        loans: {
+            subaccountAddress: `0x${string}`;
+            book: {
+                address: `0x${string}`;
+                lender: `0x${string}`;
+                borrower: `0x${string}`;
+                state: string;
+                totalRepaid: number;
+                principalToken: {
+                    type: string;
+                    name: string;
+                    address: string;
+                    chain: number;
+                    symbol: string;
+                    decimals: number;
+                    imgUrl: string;
+                    tokenType: number;
+                    discountFactor: number;
+                    price: number;
+                };
+                principalAmount: number;
+                interestAmount: number;
+                upcomingPayment: {
+                    amount: number;
+                    dueDate: string;
+                };
+                apr: number;
+                initialPrincipalAmount: number;
+                deployedDate: string;
+                paymentInterval: number;
+                totalInterestPaymentFees: number;
+            };
+            isBorrow: boolean;
+            debtInfo: {
+                interestOwed: number;
+                principalDebtOwed: number;
+                interestRepaid: number;
+            };
+            creditInfo: {
+                netInterestOwed: number;
+                principalDebtOwed: number;
+                netInterestRepaid: number;
+            };
+        }[];
+        totalDebt: number;
+        totalCredit: number;
+        aggregatesByToken: unknown[];
+    };
+    chains: {
+        name: string;
+        chainId: number;
+    }[];
+    tokens: {
+        type: string;
+        name: string;
+        address: string;
+        chain: number;
+        symbol: string;
+        decimals: number;
+        imgUrl: string;
+        price: number;
+        rawBalance: number;
+        balance: number;
+        value: number;
+    }[];
+    totalAccountValue: number;
+    totalCollateralValue: number;
+    totalLoanValue: number;
+    healthFactor: number;
+    netAccountValue: number;
+    totalEquityValue: number;
+};

package/lib/modules/sub-accounts/utils.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformSubaccountSummary = void 0;
+/**
+ * Transform the raw API response to camelCase
+ */
+const transformSubaccountSummary = (response) => {
+    return {
+        address: response.address,
+        name: response.name,
+        type: response.type,
+        portfolio: {
+            tokens: response.portfolio.tokens.map((t) => ({
+                value: t.value,
+                balance: t.balance,
+                token: {
+                    type: t.token.type,
+                    name: t.token.name,
+                    address: t.token.address,
+                    chain: t.token.chain,
+                    symbol: t.token.symbol,
+                    decimals: t.token.decimals,
+                    imgUrl: t.token.img_url,
+                },
+            })),
+            marginBalances: response.portfolio.margin_balances,
+            collateralBalances: response.portfolio.collateral_balances,
+            cefiPositions: response.portfolio.cefi_positions,
+            defiPositions: response.portfolio.defi_positions,
+            trsPositions: response.portfolio.trs_positions,
+            strategyContractPositions: response.portfolio.strategy_contract_positions,
+            legacyHedgerPositions: response.portfolio.legacy_hedger_positions,
+            otcPositions: response.portfolio.otc_positions,
+            totalValue: response.portfolio.total_value,
+            discountedValue: response.portfolio.discounted_value,
+        },
+        loanbook: {
+            loans: response.loanbook.loans.map((loan) => ({
+                subaccountAddress: loan.subaccount_address,
+                book: {
+                    address: loan.book.address,
+                    lender: loan.book.lender,
+                    borrower: loan.book.borrower,
+                    state: loan.book.state,
+                    totalRepaid: loan.book.total_repaid,
+                    principalToken: {
+                        type: loan.book.principal_token.type,
+                        name: loan.book.principal_token.name,
+                        address: loan.book.principal_token.address,
+                        chain: loan.book.principal_token.chain,
+                        symbol: loan.book.principal_token.symbol,
+                        decimals: loan.book.principal_token.decimals,
+                        imgUrl: loan.book.principal_token.img_url,
+                        tokenType: loan.book.principal_token.token_type,
+                        discountFactor: loan.book.principal_token.discount_factor,
+                        price: loan.book.principal_token.price,
+                    },
+                    principalAmount: loan.book.principal_amount,
+                    interestAmount: loan.book.interest_amount,
+                    upcomingPayment: {
+                        amount: loan.book.upcoming_payment.amount,
+                        dueDate: loan.book.upcoming_payment.due_date,
+                    },
+                    apr: loan.book.apr,
+                    initialPrincipalAmount: loan.book.initial_principal_amount,
+                    deployedDate: loan.book.deployed_date,
+                    paymentInterval: loan.book.payment_interval,
+                    totalInterestPaymentFees: loan.book.total_interest_payment_fees,
+                },
+                isBorrow: loan.is_borrow,
+                debtInfo: {
+                    interestOwed: loan.debt_info.interest_owed,
+                    principalDebtOwed: loan.debt_info.principal_debt_owed,
+                    interestRepaid: loan.debt_info.interest_repaid,
+                },
+                creditInfo: {
+                    netInterestOwed: loan.credit_info.net_interest_owed,
+                    principalDebtOwed: loan.credit_info.principal_debt_owed,
+                    netInterestRepaid: loan.credit_info.net_interest_repaid,
+                },
+            })),
+            totalDebt: response.loanbook.total_debt,
+            totalCredit: response.loanbook.total_credit,
+            aggregatesByToken: response.loanbook.aggregates_by_token,
+        },
+        chains: response.chains.map((c) => ({
+            name: c.name,
+            chainId: c.chain_id,
+        })),
+        tokens: response.tokens.map((t) => ({
+            type: t.type,
+            name: t.name,
+            address: t.address,
+            chain: t.chain,
+            symbol: t.symbol,
+            decimals: t.decimals,
+            imgUrl: t.img_url,
+            price: t.price,
+            rawBalance: t.raw_balance,
+            balance: t.balance,
+            value: t.value,
+        })),
+        totalAccountValue: response.total_account_value,
+        totalCollateralValue: response.total_collateral_value,
+        totalLoanValue: response.total_loan_value,
+        healthFactor: response.health_factor,
+        netAccountValue: response.net_account_value,
+        totalEquityValue: response.total_equity_value,
+    };
+};
+exports.transformSubaccountSummary = transformSubaccountSummary;
+//# sourceMappingURL=utils.js.map

package/lib/modules/vaults/adapter.helpers.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Adapter Helper Functions
+ *
+ * Functions to support deposits with alternative tokens through swap adapters,
+ * wrapper contracts, and Paraswap integration.
+ */
+import type { BaseContract, Signer, Wallet } from 'ethers';
+import type { IAddress } from '../../types';
+import type { IVaultAdapterConfig } from '../../types/vaults';
+/**
+ * Get quote from Paraswap for token swap
+ */
+export declare function getParaswapQuote({ srcToken, destToken, amount, network, srcDecimals, destDecimals, }: {
+    srcToken: string;
+    destToken: string;
+    amount: string;
+    network: string;
+    srcDecimals: number;
+    destDecimals: number;
+}): Promise<any>;
+/**
+ * Fetch a Paraswap price quote and return the pool-adapter contract for a
+ * Paraswap-bridge (`bridgeId === 2`) vault.
+ *
+ * @deprecated No longer used by the SDK. It never built the Paraswap swap
+ *   calldata (the quote is fetched and discarded, and the returned contract
+ *   carries no transaction data), so it cannot produce a valid
+ *   `swapAndDeposit` call. `vaultDeposit` now rejects the Paraswap adapter
+ *   route up front; use `swapRouterDeposit` for any-token deposits. Kept
+ *   exported for back-compat only and will be removed in the next major.
+ *
+ * @param params.signer - Signer used to bind the returned contract.
+ * @param params.srcToken - Token being deposited.
+ * @param params.srcDecimals - Decimals of `srcToken`.
+ * @param params.destToken - Vault underlying asset.
+ * @param params.destDecimals - Decimals of `destToken`.
+ * @param params.amount - Raw (wei-style) amount of `srcToken`.
+ * @param params.network - Chain id as a string, for the Paraswap API.
+ * @param params.adapterConfig - Adapter config carrying `wrapperAddress`.
+ * @param params.userAddress - Depositor address (unused).
+ * @returns The pool-adapter contract bound to `signer`.
+ * @throws Error when Paraswap returns no price route.
+ */
+export declare function buildSwapAndDepositTransaction({ signer, srcToken, srcDecimals, destToken, destDecimals, amount, network, adapterConfig, userAddress, }: {
+    signer: Signer | Wallet;
+    srcToken: IAddress;
+    srcDecimals: number;
+    destToken: IAddress;
+    destDecimals: number;
+    amount: string;
+    network: string;
+    adapterConfig: IVaultAdapterConfig;
+    userAddress: IAddress;
+}): Promise<BaseContract>;
+/**
+ * Build native/wrapped token deposit transaction
+ */
+export declare function buildNativeDepositTransaction({ signer, srcToken, amount, poolName, adapterConfig, userAddress, }: {
+    signer: Signer | Wallet;
+    srcToken: IAddress;
+    amount: string;
+    poolName?: string;
+    adapterConfig: IVaultAdapterConfig;
+    userAddress: IAddress;
+}): Promise<{
+    contract: BaseContract;
+    functionName: string;
+    args: any[];
+    value?: bigint;
+}>;
+/**
+ * Preview adapter deposit output
+ */
+export declare function previewAdapterDeposit({ signer, vaultAddress, srcToken, srcAmount, srcDecimals, destToken, destDecimals, adapterConfig, chainId, }: {
+    signer: Signer | Wallet;
+    vaultAddress: IAddress;
+    srcToken: IAddress;
+    srcAmount: string;
+    srcDecimals: number;
+    destToken: IAddress;
+    destDecimals: number;
+    adapterConfig: IVaultAdapterConfig;
+    chainId: number;
+}): Promise<bigint>;

package/lib/modules/vaults/adapter.helpers.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * Adapter Helper Functions
+ *
+ * Functions to support deposits with alternative tokens through swap adapters,
+ * wrapper contracts, and Paraswap integration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getParaswapQuote = getParaswapQuote;
+exports.buildSwapAndDepositTransaction = buildSwapAndDepositTransaction;
+exports.buildNativeDepositTransaction = buildNativeDepositTransaction;
+exports.previewAdapterDeposit = previewAdapterDeposit;
+const adapters_1 = require("../../core/constants/adapters");
+const abis_1 = require("../../abis");
+const core_1 = require("../../core");
+/**
+ * Paraswap API endpoints
+ */
+const PARASWAP_PRICES_API = 'https://api.paraswap.io/prices';
+/**
+ * Paraswap partner configuration
+ */
+const PARASWAP_PARTNER = 'upshift';
+const PARASWAP_PARTNER_ADDRESS = '0xb60ee0FA5B6bA917255A03e744967E0Bda531dD0';
+const PARASWAP_VERSION = '6.2';
+/**
+ * Get quote from Paraswap for token swap
+ */
+async function getParaswapQuote({ srcToken, destToken, amount, network, srcDecimals, destDecimals, }) {
+    const params = new URLSearchParams();
+    params.append('network', network);
+    params.append('srcToken', srcToken);
+    params.append('srcDecimals', srcDecimals.toString());
+    params.append('destToken', destToken);
+    params.append('destDecimals', destDecimals.toString());
+    params.append('amount', amount);
+    params.append('partner', PARASWAP_PARTNER);
+    params.append('partnerAddress', PARASWAP_PARTNER_ADDRESS);
+    params.append('version', PARASWAP_VERSION);
+    const priceUrl = `${PARASWAP_PRICES_API}?${params.toString()}`;
+    const response = await fetch(priceUrl, {
+        method: 'GET',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+    });
+    const data = await response.json();
+    return data?.priceRoute || {};
+}
+/**
+ * Fetch a Paraswap price quote and return the pool-adapter contract for a
+ * Paraswap-bridge (`bridgeId === 2`) vault.
+ *
+ * @deprecated No longer used by the SDK. It never built the Paraswap swap
+ *   calldata (the quote is fetched and discarded, and the returned contract
+ *   carries no transaction data), so it cannot produce a valid
+ *   `swapAndDeposit` call. `vaultDeposit` now rejects the Paraswap adapter
+ *   route up front; use `swapRouterDeposit` for any-token deposits. Kept
+ *   exported for back-compat only and will be removed in the next major.
+ *
+ * @param params.signer - Signer used to bind the returned contract.
+ * @param params.srcToken - Token being deposited.
+ * @param params.srcDecimals - Decimals of `srcToken`.
+ * @param params.destToken - Vault underlying asset.
+ * @param params.destDecimals - Decimals of `destToken`.
+ * @param params.amount - Raw (wei-style) amount of `srcToken`.
+ * @param params.network - Chain id as a string, for the Paraswap API.
+ * @param params.adapterConfig - Adapter config carrying `wrapperAddress`.
+ * @param params.userAddress - Depositor address (unused).
+ * @returns The pool-adapter contract bound to `signer`.
+ * @throws Error when Paraswap returns no price route.
+ */
+async function buildSwapAndDepositTransaction({ signer, srcToken, srcDecimals, destToken, destDecimals, amount, network, adapterConfig, userAddress, }) {
+    // Get price quote from Paraswap
+    const priceRoute = await getParaswapQuote({
+        srcToken,
+        destToken,
+        amount,
+        network,
+        srcDecimals,
+        destDecimals,
+    });
+    if (!priceRoute || !priceRoute.destAmount) {
+        throw new Error('No price route found from Paraswap');
+    }
+    // Create adapter contract
+    // Note: Transaction data will be built in the calling code
+    const adapterContract = (0, core_1.createContract)({
+        address: adapterConfig.wrapperAddress,
+        provider: signer,
+        abi: abis_1.ABI_POOL_ADAPTER,
+    });
+    return adapterContract;
+}
+/**
+ * Build native/wrapped token deposit transaction
+ */
+async function buildNativeDepositTransaction({ signer, srcToken, amount, poolName, adapterConfig, userAddress, }) {
+    const isNative = srcToken === '0x0000000000000000000000000000000000000000';
+    const wrapperContract = (0, core_1.createContract)({
+        address: adapterConfig.wrapperAddress,
+        provider: signer,
+        abi: (adapterConfig.abi ||
+            abis_1.ABI_WRAPPER_ADAPTER),
+    });
+    // Handle different pool types
+    if (poolName === adapters_1.POOL_NAMES.ETH_TREEHOUSE_GROWTH) {
+        if (isNative) {
+            return {
+                contract: wrapperContract,
+                functionName: 'depositETH',
+                args: [adapterConfig.referralId],
+                value: BigInt(amount),
+            };
+        }
+        return {
+            contract: wrapperContract,
+            functionName: 'depositWETH',
+            args: [BigInt(amount), adapterConfig.referralId],
+        };
+    }
+    if (poolName === adapters_1.POOL_NAMES.AVAX_AVAX) {
+        return {
+            contract: wrapperContract,
+            functionName: 'depositETH',
+            args: [],
+            value: BigInt(amount),
+        };
+    }
+    if (poolName === adapters_1.POOL_NAMES.ETH_KELP_TAC_RSETH) {
+        if (isNative) {
+            return {
+                contract: wrapperContract,
+                functionName: 'getRSETHWithETH',
+                args: [adapterConfig.referralId],
+                value: BigInt(amount),
+            };
+        }
+        return {
+            contract: wrapperContract,
+            functionName: 'getRSETHWithERC20',
+            args: [
+                adapterConfig.wrappedTokenAddress,
+                BigInt(amount),
+                adapterConfig.referralId,
+            ],
+        };
+    }
+    // Default native deposit
+    if (isNative && adapterConfig.isNativeTokenDeposit) {
+        return {
+            contract: wrapperContract,
+            functionName: 'depositETH',
+            args: adapterConfig.referralId ? [adapterConfig.referralId] : [],
+            value: BigInt(amount),
+        };
+    }
+    throw new Error('Unsupported deposit configuration');
+}
+/**
+ * Preview adapter deposit output
+ */
+async function previewAdapterDeposit({ signer, vaultAddress, srcToken, srcAmount, srcDecimals, destToken, destDecimals, adapterConfig, chainId, }) {
+    // If using Paraswap bridge, get quote
+    if (adapterConfig.bridgeId === 2) {
+        const quote = await getParaswapQuote({
+            srcToken,
+            destToken,
+            amount: srcAmount,
+            network: chainId.toString(),
+            srcDecimals,
+            destDecimals,
+        });
+        return BigInt(quote.destAmount || 0);
+    }
+    // If view adapter is available, use it
+    if (adapterConfig.viewAdapter) {
+        const viewContract = (0, core_1.createContract)({
+            address: adapterConfig.viewAdapter,
+            provider: signer,
+            abi: [
+                {
+                    inputs: [
+                        { internalType: 'address', name: 'asset', type: 'address' },
+                        { internalType: 'uint256', name: 'depositAmount', type: 'uint256' },
+                    ],
+                    name: 'getRsETHAmountToMint',
+                    outputs: [
+                        { internalType: 'uint256', name: 'rsETHAmount', type: 'uint256' },
+                    ],
+                    stateMutability: 'view',
+                    type: 'function',
+                },
+            ],
+        });
+        const output = await viewContract.getRsETHAmountToMint(srcToken, BigInt(srcAmount));
+        return BigInt(output);
+    }
+    // Default: assume 1:1 ratio
+    return BigInt(srcAmount);
+}
+//# sourceMappingURL=adapter.helpers.js.map

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

@@ -0,0 +1,147 @@
+import type { IAddress } from '../../types';
+/**
+ * Fetch the set of vaults whose deposit/withdraw history is served from the
+ * backend Mongo snapshot (`/upshift/vault_history`) rather than their (retired)
+ * Goldsky subgraph.
+ *
+ * This is the routing source of truth: a vault appears here only once its
+ * history has been backfilled, so the SDK can never reroute a vault to empty
+ * snapshot data ahead of its backfill. Result is cached for 10 minutes.
+ *
+ * Side effects: one HTTP GET to the public API (cached).
+ *
+ * @returns A set of lowercased vault addresses. Empty on any error — callers
+ *   then fall back to the subgraph path, which is the safe default while
+ *   subgraphs still exist.
+ */
+export declare function fetchArchivedVaults(): Promise<Set<string>>;
+/**
+ * Whether a vault's history should be served from the backend snapshot rather
+ * than its subgraph. Backed by {@link fetchArchivedVaults} (cached).
+ *
+ * @param vaultAddress - The vault contract address (any casing).
+ * @returns `true` if the vault has a backfilled history snapshot.
+ */
+export declare function isArchivedVault(vaultAddress: IAddress): Promise<boolean>;
+/**
+ * Specialized vault fetching with enhanced retry logic and fallback strategies
+ * This function attempts to fetch vault data with multiple fallback approaches
+ *
+ * The return shape is "success flag wins": when `success === true`, `data` is
+ * the resolved value (which may legitimately be falsy — `0`, `''`, `0n`,
+ * `null`); when `success === false`, `error` is populated. Callers must branch
+ * on `success`, not on the truthiness of `data`.
+ */
+export declare function fetchVaultWithFallback<T>(vaultAddress: string, fetchFn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelay?: number;
+    fallbackStrategies?: Array<() => Promise<T>>;
+    timeout?: number;
+}): Promise<{
+    success: boolean;
+    data?: T;
+    error?: Error;
+    strategy: string;
+}>;
+/**
+ * Batch vault fetching with intelligent retry and fallback
+ * Ensures maximum vault coverage by trying multiple strategies
+ */
+export declare function fetchVaultsBatch<T>(vaults: Array<{
+    address: string;
+    fetchFn: () => Promise<T>;
+}>, options?: {
+    maxRetries?: number;
+    baseDelay?: number;
+    batchSize?: number;
+    parallelLimit?: number;
+}): Promise<{
+    successful: Array<{
+        index: number;
+        data: T;
+        strategy: string;
+    }>;
+    failed: Array<{
+        index: number;
+        error: Error;
+        address: string;
+    }>;
+    totalAttempted: number;
+    successRate: number;
+}>;
+/**
+ * Comprehensive vault fetching that handles all failure points
+ * This function ensures maximum vault coverage by implementing multiple strategies
+ */
+export declare function fetchVaultsComprehensive<T>(vaults: Array<{
+    address: string;
+    chain: number;
+}>, fetchFn: (vault: {
+    address: string;
+    chain: number;
+    fallbackRpc?: string;
+    minimal?: boolean;
+}) => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelay?: number;
+    batchSize?: number;
+    parallelLimit?: number;
+    includeClosed?: boolean;
+    includeInvisible?: boolean;
+    fallbackRpcUrls?: Record<number, string[]>;
+    timeout?: number;
+}): Promise<{
+    successful: Array<{
+        index: number;
+        data: T;
+        strategy: string;
+        attempts: number;
+    }>;
+    failed: Array<{
+        index: number;
+        error: Error;
+        address: string;
+        chain: number;
+        attempts: number;
+    }>;
+    totalAttempted: number;
+    successRate: number;
+    coverageReport: {
+        totalVaults: number;
+        successfulVaults: number;
+        failedVaults: number;
+        closedVaults: number;
+        invisibleVaults: number;
+        rpcFailures: Record<number, number>;
+    };
+}>;
+/**
+ * Enhanced vault filtering that preserves more vaults while maintaining quality
+ */
+export declare function filterVaultsIntelligently<T extends {
+    status?: string;
+    isVisible?: boolean;
+    is_visible?: boolean;
+}>(vaults: (T | null)[], options?: {
+    includeClosed?: boolean;
+    includeInvisible?: boolean;
+    includeNull?: boolean;
+    minStatus?: string[];
+}): {
+    active: T[];
+    closed: T[];
+    invisible: T[];
+    failed: Array<{
+        index: number;
+        reason: string;
+    }>;
+    summary: {
+        total: number;
+        active: number;
+        closed: number;
+        invisible: number;
+        failed: number;
+        successRate: number;
+    };
+};
+export { fetchVaultMetadata } from '../../core/vault-metadata';