@switchxfi/alm-sdk 1.1.0

package/README.md

@@ -0,0 +1,138 @@
+# SwitchX ALM SDK
+This SDK provides utilities for interacting with SwitchX ALM vaults, designed to simplify integration into your project.
+
+## 📦 Installation
+Using npm:
+```bash
+npm install @switchxfi/alm-sdk
+```
+or yarn:
+```bash
+yarn add @switchxfi/alm-sdk
+```
+
+## 📚 Vault GET Methods
+
+- `getVaultsByPool`
+
+Get a list of vault addresses associated with a specific pool
+```ts
+const vaultAddresses: string[] = await getVaultsByPool(poolAddress, chainId);
+```
+
+- `getTotalAmounts`
+
+Returns the total number of both tokens stored in the vault
+```ts
+const [totalAmount0, totalAmount1] = await getTotalAmounts(
+    vaultAddress,
+    provider,
+    true,
+    token0.decimals,
+    token1.decimals
+);
+```
+
+- `getTotalSupply`
+  
+Returns the total number of vault shares
+```ts
+const totalSupply = await getTotalSupply(vaultAddress, provider)
+```
+
+## 👤 User Data in Vaults
+
+- `getUserAmounts`
+
+Returns the user's token balances and share count in the vault. If the `raw` flag is set, values are returned as BigNumbers
+```ts
+const [userAmount0, userAmount1, shares] = await getUserAmounts(
+    account,
+    vaultAddress,
+    provider,
+    token0.decimals,
+    token1.decimals,
+    true
+);
+```
+
+- `calculateUserDepositTokenPNL`
+
+Calculates the user’s PNL and ROI in terms of the deposit token
+```ts
+const { pnl, roi } = await calculateUserDepositTokenPNL(
+    account,
+    vaultAddress,
+    userAmount0.toString(),
+    userAmount1.toString(),
+    token0.decimals,
+    token1.decimals,
+    provider
+);
+```
+
+## 🚀 Transactions
+
+- `approveDepositToken` 
+
+Approves a token for deposit. Must be called before using the `deposit()` method. The amount can be a string or number in major units.
+```ts
+const tx = await approveDepositToken(
+    accountAddress,
+    0, // token idx can be 0 or 1
+    vaultAddress,
+    provider,
+    amount // (optional)
+);
+```
+
+- `deposit` / `depositNativeToken`
+
+Performs a deposit into the vault. The `amount0` and `amount1` parameters represent the amounts of each token in major units.
+```ts
+if (useNativeToken) {
+    const tx = await depositNativeToken(
+        account,
+        vault.allowTokenA ? amount : "0",
+        vault.allowTokenB ? amount : "0",
+        vaultAddress,
+        provider
+    );
+} else {
+    const tx = await deposit(
+        account,
+        vault.allowTokenA ? amount : "0",
+        vault.allowTokenB ? amount : "0",
+        vaultAddress,
+        provider
+    );
+}
+```
+
+- `withdraw` / `withdrawNativeToken`
+
+Withdraws a specified number of shares from the vault, returning both underlying tokens to the user. The share amount should be a string or number in major units.
+```ts
+const percentMultiplier = 1; // 100%
+const shareToWithdraw = Number(userShare) * percentMultiplier;
+const slippage = 1 // 1%
+
+if (useNativeToken) {
+   const tx = await withdrawNativeToken(
+        account,
+        shareToWithdraw,
+        vaultAddress,
+        provider,
+        slippage
+    );
+} else {
+   const tx = await withdrawWithSlippage(
+        account,
+        shareToWithdraw,
+        vaultAddress,
+        provider,
+        slippage
+    );
+}
+```
+

package/dist/index.d.mts

@@ -0,0 +1,325 @@
+import { Provider, JsonRpcProvider, Web3Provider } from '@ethersproject/providers';
+import { BigNumber, Overrides as Overrides$1, ContractTransaction as ContractTransaction$1 } from 'ethers';
+import { Signer } from '@ethersproject/abstract-signer';
+import { Overrides, ContractTransaction } from '@ethersproject/contracts';
+import { BigNumber as BigNumber$1 } from '@ethersproject/bignumber';
+
+type SignerOrProvider = Signer | Provider;
+declare enum SupportedChainId {
+    Base = 8453,
+    PulseChain = 369,
+    BaseSepolia = 84532
+}
+declare const algebraVaultDecimals = 18;
+type TotalAmountsBN = [BigNumber, BigNumber] & {
+    total0: BigNumber;
+    total1: BigNumber;
+};
+type UserAmountsBN = [BigNumber, BigNumber, BigNumber];
+type TotalAmounts = [string, string, string] & {
+    total0: string;
+    total1: string;
+};
+type UserAmounts = [string, string, string];
+type UserAmountsInVault = {
+    poolAddress: string;
+    vaultAddress: string;
+    userAmounts: UserAmounts;
+};
+type UserAmountsInVaultBN = {
+    poolAddress: string;
+    vaultAddress: string;
+    userAmounts: UserAmountsBN;
+};
+interface AlgebraVault {
+    id: string;
+    tokenA: string;
+    tokenB: string;
+    allowTokenA: boolean;
+    allowTokenB: boolean;
+    holdersCount?: string;
+    fee?: string;
+}
+type VaultShares = {
+    vault: {
+        id: string;
+        tokenA: string;
+        tokenB: string;
+        pool: string;
+    };
+    vaultShareBalance: string;
+    vaultShareStaked: string;
+};
+type UserBalances = {
+    vaultShares: VaultShares[];
+};
+interface VaultState {
+    totalAmount0: string;
+    totalAmount1: string;
+    createdAtTimestamp: string;
+    vault: string;
+    sqrtPrice: string;
+    totalSupply: string;
+}
+interface Fees extends VaultState {
+    feeAmount0: string;
+    feeAmount1: string;
+    totalAmount0: string;
+    totalAmount1: string;
+    createdAtTimestamp: string;
+    vault: string;
+    sqrtPrice: string;
+    totalSupply: string;
+}
+interface VaultTransactionEvent extends VaultState {
+    amount0: string;
+    amount1: string;
+    totalAmount0: string;
+    totalAmount1: string;
+    totalAmount0BeforeEvent: string;
+    totalAmount1BeforeEvent: string;
+    createdAtTimestamp: string;
+    vault: string;
+    sqrtPrice: string;
+    totalSupply: string;
+    shares: string;
+}
+type FeesInfo = {
+    timePeriod: number;
+    feeAmount0: string;
+    feeAmount1: string;
+    pctAPR: number;
+};
+type DepositTokenRatio = {
+    atTimestamp: string;
+    percent: number;
+};
+type AverageDepositTokenRatio = {
+    timePeriod: number;
+    percent: number;
+};
+type VaultApr = {
+    timeInterval: number;
+    apr: number | null;
+};
+type FeeAprData = {
+    feeApr_1d: number | null;
+    feeApr_3d: number | null;
+    feeApr_7d: number | null;
+    feeApr_30d: number | null;
+};
+type PriceChange = {
+    timeInterval: number;
+    priceChange: number | null;
+};
+type UserBalanceInVault = {
+    vaultAddress: string;
+    poolAddress: string;
+    shares: string;
+    stakedShares: string;
+};
+type UserBalanceInVaultBN = {
+    vaultAddress: string;
+    poolAddress: string;
+    shares: BigNumber;
+    stakedShares: BigNumber;
+};
+type VaultMetrics = {
+    timeInterval: number;
+    lpPriceChange: number | null;
+    lpApr: number | null;
+    avgDtr: number;
+    feeApr: number;
+};
+
+declare function getTotalAmounts(vaultAddress: string, jsonProvider: JsonRpcProvider, raw: false, token0Decimals: number, token1Decimals: number): Promise<TotalAmounts>;
+declare function getTotalAmounts(vaultAddress: string, jsonProvider: JsonRpcProvider, raw: true, token0Decimals: number, token1Decimals: number): Promise<TotalAmountsBN>;
+declare function getTotalSupply(vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<string>;
+declare function getTotalSupply(vaultAddress: string, jsonProvider: JsonRpcProvider, raw: true): Promise<BigNumber>;
+
+declare function getUserBalance(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<string>;
+declare function getUserBalance(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider, raw: true): Promise<BigNumber>;
+declare function sendUserBalancesQueryRequest(url: string, accountAddress: string, query: string): Promise<VaultShares[]>;
+declare function getAllUserBalances(accountAddress: string, jsonProvider: JsonRpcProvider): Promise<UserBalanceInVault[]>;
+declare function getAllUserBalances(accountAddress: string, jsonProvider: JsonRpcProvider, raw: true): Promise<UserBalanceInVaultBN[]>;
+declare function getUserAmounts(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider, token0Decimals: number, token1Decimals: number, raw: false): Promise<UserAmounts>;
+declare function getUserAmounts(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider, token0Decimals: number, token1Decimals: number, raw: true): Promise<UserAmountsBN>;
+declare function getAllUserAmounts(accountAddress: string, jsonProvider: Web3Provider): Promise<UserAmountsInVault[]>;
+declare function getAllUserAmounts(accountAddress: string, jsonProvider: Web3Provider, raw: true): Promise<UserAmountsInVaultBN[]>;
+
+declare function isTokenAllowed(tokenIdx: 0 | 1, vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<boolean>;
+declare function isDepositTokenApproved(accountAddress: string, tokenIdx: 0 | 1, amount: string | number | BigNumber, vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<boolean>;
+declare function approveDepositToken(accountAddress: string, tokenIdx: 0 | 1, vaultAddress: string, jsonProvider: JsonRpcProvider, amount?: string | number | BigNumber, overrides?: Overrides): Promise<ContractTransaction>;
+declare function _getMaxDepositAmount(tokenIdx: 0 | 1, vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<BigNumber>;
+declare function getMaxDepositAmount(tokenIdx: 0 | 1, vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<BigNumber>;
+declare function deposit(accountAddress: string, amount0: string | number | BigNumber, amount1: string | number | BigNumber, vaultAddress: string, jsonProvider: JsonRpcProvider, percentSlippage?: number, overrides?: Overrides): Promise<ContractTransaction>;
+declare function depositNativeToken(accountAddress: string, amount0: string | number | BigNumber, amount1: string | number | BigNumber, vaultAddress: string, jsonProvider: JsonRpcProvider, percentSlippage?: number, overrides?: Overrides): Promise<ContractTransaction>;
+
+declare function approveVaultToken(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider, shares?: string | number | BigNumber, overrides?: Overrides): Promise<ContractTransaction>;
+declare function isVaultTokenApproved(accountAddress: string, shares: string | number | BigNumber, vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<boolean>;
+declare function withdraw(accountAddress: string, shares: string | number | BigNumber, vaultAddress: string, jsonProvider: JsonRpcProvider, overrides?: Overrides): Promise<ContractTransaction>;
+declare function withdrawWithSlippage(accountAddress: string, shares: string | number | BigNumber, vaultAddress: string, jsonProvider: JsonRpcProvider, percentSlippage?: number, overrides?: Overrides): Promise<ContractTransaction>;
+declare function withdrawNativeToken(accountAddress: string, shares: string | number | BigNumber, vaultAddress: string, jsonProvider: JsonRpcProvider, percentSlippage?: number, overrides?: Overrides): Promise<ContractTransaction>;
+
+interface VaultQueryData {
+    almVault: AlgebraVault;
+}
+interface VaultWithPoolQueryData extends VaultQueryData {
+    pool: string;
+}
+interface VaultsByTokensQueryData {
+    almVaults: AlgebraVault[];
+}
+
+declare function getAlgebraVaultInfo(chainId: SupportedChainId, vaultAddress: string, jsonProvider?: JsonRpcProvider): Promise<AlgebraVault>;
+interface ExtendedAlgebraVault extends AlgebraVault {
+    apr: number;
+    amount0: bigint;
+    amount1: bigint;
+}
+declare function getExtendedAlgebraVault(vaultAddress: string, chainId: SupportedChainId, jsonProvider: JsonRpcProvider, token0Decimals: number, token1Decimals: number): Promise<ExtendedAlgebraVault>;
+declare function getVaultsByTokens(chainId: SupportedChainId, depositTokenAddress: string, pairedTokenAddress: string): Promise<VaultsByTokensQueryData['almVaults']>;
+declare function getVaultsByPool(poolAddress: string, chainId: SupportedChainId): Promise<string[]>;
+declare function getAllVaults(chainId: SupportedChainId): Promise<VaultWithPoolQueryData[]>;
+declare function validateVaultData(vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<{
+    chainId: SupportedChainId;
+    vault: AlgebraVault;
+}>;
+declare function getChainByProvider(jsonProvider: JsonRpcProvider): Promise<{
+    chainId: SupportedChainId;
+}>;
+
+declare function getTotalAmountsAtFeeCollectionEvent(objFees: VaultState, isVaultInverted: boolean, token0Decimals: number, token1Decimals: number): [number, number];
+declare function getFeesAmountInBaseTokens(objFees: Fees, isVaultInverted: boolean, token0Decimals: number, token1Decimals: number): number;
+declare function getTotalFeesAmountInBaseTokens(feesDataset: Fees[], t0decimals: number, t1decimals: number, isInverted: boolean): number;
+declare function getFeesCollected(vaultAddress: string, jsonProvider: JsonRpcProvider, days?: number): Promise<TotalAmounts>;
+declare function getFeesCollected(vaultAddress: string, jsonProvider: JsonRpcProvider, raw: true, days?: number): Promise<TotalAmountsBN>;
+declare function getFeesCollectedInfo(vaultAddress: string, jsonProvider: JsonRpcProvider, forDays?: number[]): Promise<FeesInfo[]>;
+interface UserFees {
+    totalUserFees0: BigNumber$1;
+    totalUserFees1: BigNumber$1;
+    sinceTimestamp: number | null;
+}
+declare function getUserFeesCollected(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<UserFees>;
+
+declare function getAmountsInDepositToken(sqrtPrice: BigNumber$1, amount0: BigNumber$1, amount1: BigNumber$1, token0Decimals: number, token1Decimals: number, depositToken: 0 | 1): BigNumber$1;
+declare function getDtrAtTransactionEvent(objTransactionEvent: VaultTransactionEvent, isVaultInverted: boolean, token0Decimals: number, token1Decimals: number, beforeEvent?: boolean): DepositTokenRatio;
+declare function getDtrAtFeeCollectionEvent(objFeeCollectionEvent: VaultState, isVaultInverted: boolean, token0Decimals: number, token1Decimals: number): DepositTokenRatio;
+declare function getAllDtrsForTimeInterval(vaultAddress: string, jsonProvider: JsonRpcProvider, timeInterval: number): Promise<DepositTokenRatio[]>;
+declare function getAverageDtr(allDtrs: DepositTokenRatio[]): number;
+declare function getAverageDepositTokenRatios(vaultAddress: string, jsonProvider: JsonRpcProvider, timeIntervals?: number[]): Promise<AverageDepositTokenRatio[]>;
+
+declare function getLpPriceAt(vaultEvents: VaultState[], daysAgo: number, isVaultInverted: boolean, token0decimals: number, token1decimals: number): PriceChange | null;
+declare function getLpApr(vaultAddress: string, jsonProvider: JsonRpcProvider, vault: AlgebraVault, token0Decimals: number, token1Decimals: number): Promise<{
+    aprs: (VaultApr | null)[];
+    vault: AlgebraVault;
+    tvl: number;
+    totalAmounts: TotalAmountsBN;
+}>;
+declare function getLpPriceChange(vaultAddress: string, jsonProvider: JsonRpcProvider, timeIntervals?: number[]): Promise<(PriceChange | null)[]>;
+
+declare function getVaultMetrics(vaultAddress: string, jsonProvider: JsonRpcProvider, timeIntervals?: number[]): Promise<(VaultMetrics | null)[]>;
+
+type VaultEvent = {
+    atTimestamp: string;
+    dtr: number;
+    tvl: number;
+    feeAmount: number;
+    lpPrice: number;
+    poolPrice: number;
+};
+declare function getTvlAtTransactionEvent(objTransactionEvent: VaultTransactionEvent, vault: AlgebraVault, token0decimals: number, token1decimals: number): number;
+declare function getTvlAtFeeCollectionEvent(objFeeCollectionEvent: VaultState, vault: AlgebraVault, token0decimals: number, token1decimals: number): number;
+declare function getVaultEventsForTimeInterval(vaultAddress: string, jsonProvider: JsonRpcProvider, timeInterval: number): Promise<VaultEvent[]>;
+
+type VaultPositionsInfo = {
+    currentTick: number;
+    currentPrice: number;
+    positions: {
+        tickLower: number;
+        tickUpper: number;
+        priceLower: number;
+        priceUpper: number;
+        liquidity: string;
+        amountToken0: string;
+        amountToken1: string;
+        positionTvl: number;
+    }[];
+};
+declare function getVaultPositions(vaultAddress: string, jsonProvider: JsonRpcProvider, decimals0?: number, decimals1?: number): Promise<VaultPositionsInfo>;
+type VaultRanges = {
+    baseLower: number;
+    baseUpper: number;
+    limitLower: number;
+    limitUpper: number;
+};
+declare function getVaultRanges(vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<VaultRanges>;
+type VaultRangePercents = {
+    currentTick: number;
+    currentPrice: number;
+    base?: {
+        tickLower: number;
+        tickUpper: number;
+        priceLower: number;
+        priceUpper: number;
+        widthPct: number;
+        widthPctTick: number;
+        distancePct: [number, number];
+        edgeGapTicks: number;
+        edgeGapPctOfSpacing: number;
+        side: 'above' | 'below';
+        inRange: boolean;
+    };
+    limit?: {
+        tickLower: number;
+        tickUpper: number;
+        priceLower: number;
+        priceUpper: number;
+        widthPct: number;
+        widthPctTick: number;
+        distancePct: [number, number];
+        edgeGapTicks: number;
+        edgeGapPctOfSpacing: number;
+        side: 'above' | 'below';
+        inRange: boolean;
+    };
+};
+declare function getVaultRangePercents(vaultAddress: string, jsonProvider: JsonRpcProvider, decimals0?: number, decimals1?: number): Promise<VaultRangePercents>;
+
+/**
+ * Get fee APR values for a vault from a V2 subgraph
+ * @param vaultAddress The address of the vault
+ * @param jsonProvider A JsonRpcProvider
+ * @param dex The DEX identifier
+ * @returns Fee APR data for different time periods or null if data not available
+ */
+declare function getFeeAprs(vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<FeeAprData | null>;
+
+declare function stake(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider, shares: string | number | BigNumber, overrides?: Overrides$1): Promise<ContractTransaction$1>;
+declare function unstake(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider, shares: string | number | BigNumber, overrides?: Overrides$1): Promise<ContractTransaction$1>;
+declare function harvest(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider, overrides?: Overrides$1): Promise<ContractTransaction$1>;
+declare function addRewardTokenToDistributor(accountAddress: string, vaultAddress: string, rewardToken: string, jsonProvider: JsonRpcProvider, overrides?: Overrides$1): Promise<ContractTransaction$1>;
+declare function getTokenRewardAddresses(vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<string[]>;
+
+declare function getUserAmountsStaked(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider, token0Decimals: number, token1Decimals: number, raw: false): Promise<UserAmounts>;
+declare function getUserAmountsStaked(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider, token0Decimals: number, token1Decimals: number, raw: true): Promise<UserAmountsBN>;
+declare function getUserFarmingRewards(accountAddress: string, vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<Map<string, BigNumber>>;
+
+declare const VAULT_DEPOSIT_GUARD: Record<SupportedChainId, string>;
+
+interface UserPnl {
+    totalDepositAmountBN: BigNumber;
+    totalWithdrawAmountBN: BigNumber;
+    pnlBN: BigNumber;
+    pnl: string;
+    roi: number;
+}
+/** calculates the PNL/ROI of a user in price of the deposit token */
+declare function calculateUserDepositTokenPNL(accountAddress: string, vaultAddress: string, currentAmount0: string, currentAmount1: string, decimals0: number, decimals1: number, jsonProvider: JsonRpcProvider): Promise<UserPnl>;
+
+declare function getUserDeposits(accountAddress: string, vaultAddress: string, chainId: SupportedChainId): Promise<VaultTransactionEvent[]>;
+declare function getUserWithdraws(accountAddress: string, vaultAddress: string, chainId: SupportedChainId): Promise<VaultTransactionEvent[]>;
+
+declare function getFarmingRewardsDistributorAddress(vaultAddress: string, jsonProvider: JsonRpcProvider): Promise<string>;
+
+export { type AlgebraVault, type AverageDepositTokenRatio, type DepositTokenRatio, type ExtendedAlgebraVault, type FeeAprData, type Fees, type FeesInfo, type PriceChange, type SignerOrProvider, SupportedChainId, type TotalAmounts, type TotalAmountsBN, type UserAmounts, type UserAmountsBN, type UserAmountsInVault, type UserAmountsInVaultBN, type UserBalanceInVault, type UserBalanceInVaultBN, type UserBalances, VAULT_DEPOSIT_GUARD, type VaultApr, type VaultEvent, type VaultMetrics, type VaultPositionsInfo, type VaultRangePercents, type VaultRanges, type VaultShares, type VaultState, type VaultTransactionEvent, _getMaxDepositAmount, addRewardTokenToDistributor, algebraVaultDecimals, approveDepositToken, approveVaultToken, calculateUserDepositTokenPNL, deposit, depositNativeToken, getAlgebraVaultInfo, getAllDtrsForTimeInterval, getAllUserAmounts, getAllUserBalances, getAllVaults, getAmountsInDepositToken, getAverageDepositTokenRatios, getAverageDtr, getChainByProvider, getDtrAtFeeCollectionEvent, getDtrAtTransactionEvent, getExtendedAlgebraVault, getFarmingRewardsDistributorAddress, getFeeAprs, getFeesAmountInBaseTokens, getFeesCollected, getFeesCollectedInfo, getLpApr, getLpPriceAt, getLpPriceChange, getMaxDepositAmount, getTokenRewardAddresses, getTotalAmounts, getTotalAmountsAtFeeCollectionEvent, getTotalFeesAmountInBaseTokens, getTotalSupply, getTvlAtFeeCollectionEvent, getTvlAtTransactionEvent, getUserAmounts, getUserAmountsStaked, getUserBalance, getUserDeposits, getUserFarmingRewards, getUserFeesCollected, getUserWithdraws, getVaultEventsForTimeInterval, getVaultMetrics, getVaultPositions, getVaultRangePercents, getVaultRanges, getVaultsByPool, getVaultsByTokens, harvest, isDepositTokenApproved, isTokenAllowed, isVaultTokenApproved, sendUserBalancesQueryRequest, stake, unstake, validateVaultData, withdraw, withdrawNativeToken, withdrawWithSlippage };