@strkfarm/sdk 1.0.15 → 1.0.17

package/dist/index.d.ts

@@ -1,28 +1,9 @@
-import { RpcProvider, BlockIdentifier, Contract, Account } from 'starknet';
 import BigNumber from 'bignumber.js';
+import * as starknet from 'starknet';
+import { RpcProvider, BlockIdentifier, Contract, Account } from 'starknet';
 import * as util from 'util';
 import TelegramBot from 'node-telegram-bot-api';
 
-interface TokenInfo {
-    name: string;
-    symbol: string;
-    address: string;
-    decimals: number;
-    coingeckId?: string;
-}
-declare enum Network {
-    mainnet = "mainnet",
-    sepolia = "sepolia",
-    devnet = "devnet"
-}
-interface IConfig {
-    provider: RpcProvider;
-    network: Network;
-    stage: 'production' | 'staging';
-    heartbeatUrl?: string;
-}
-declare function getMainnetConfig(rpcUrl?: string, blockIdentifier?: BlockIdentifier): IConfig;
-
 declare class Web3Number extends BigNumber {
     decimals: number;
     constructor(value: string | number, decimals: number);
@@ -49,43 +30,66 @@ declare class ContractAddr {
     static eqString(a: string, b: string): boolean;
 }
 
-interface PriceInfo {
-    price: number;
-    timestamp: Date;
+declare enum RiskType {
+    MARKET_RISK = "MARKET_RISK",
+    IMPERMANENT_LOSS = "IMPERMANENT_LOSS",
+    LIQUIDITY_RISK = "LIQUIDITY_RISK",
+    SMART_CONTRACT_RISK = "SMART_CONTRACT_RISK",
+    TECHNICAL_RISK = "TECHNICAL_RISK",
+    COUNTERPARTY_RISK = "COUNTERPARTY_RISK"
 }
-declare class Pricer {
-    readonly config: IConfig;
-    readonly tokens: TokenInfo[];
-    protected prices: {
-        [key: string]: PriceInfo;
+interface RiskFactor {
+    type: RiskType;
+    value: number;
+    weight: number;
+}
+interface TokenInfo {
+    name: string;
+    symbol: string;
+    address: string;
+    decimals: number;
+    logo: string;
+    coingeckId?: string;
+}
+declare enum Network {
+    mainnet = "mainnet",
+    sepolia = "sepolia",
+    devnet = "devnet"
+}
+interface IConfig {
+    provider: RpcProvider;
+    network: Network;
+    stage: 'production' | 'staging';
+    heartbeatUrl?: string;
+}
+interface IProtocol {
+    name: string;
+    logo: string;
+}
+/**
+ * @property risk.riskFactor.factor - The risk factors that are considered for the strategy.
+ * @property risk.riskFactor.factor - The value of the risk factor from 0 to 10, 0 being the lowest and 10 being the highest.
+ */
+interface IStrategyMetadata {
+    name: string;
+    description: string;
+    address: ContractAddr;
+    type: 'ERC4626' | 'ERC721' | 'Other';
+    depositTokens: TokenInfo[];
+    protocols: IProtocol[];
+    auditUrl?: string;
+    maxTVL: Web3Number;
+    risk: {
+        riskFactor: RiskFactor[];
+        netRisk: number;
     };
-    private methodToUse;
-    /**
-     * TOKENA and TOKENB are the two token names to get price of TokenA in terms of TokenB
-     */
-    protected PRICE_API: string;
-    protected EKUBO_API: string;
-    protected client: any;
-    constructor(config: IConfig, tokens: TokenInfo[]);
-    isReady(): boolean;
-    waitTillReady(): Promise<void>;
-    start(): void;
-    isStale(timestamp: Date, tokenName: string): boolean;
-    assertNotStale(timestamp: Date, tokenName: string): void;
-    getPrice(tokenName: string): Promise<PriceInfo>;
-    protected _loadPrices(onUpdate?: (tokenSymbol: string) => void): void;
-    _getPrice(token: TokenInfo, defaultMethod?: string): Promise<number>;
-    _getPriceCoinbase(token: TokenInfo): Promise<number>;
-    _getPriceCoinMarketCap(token: TokenInfo): Promise<number>;
-    _getPriceEkubo(token: TokenInfo, amountIn?: Web3Number, retry?: number): Promise<number>;
 }
-
-declare class Pragma {
-    contractAddr: string;
-    readonly contract: Contract;
-    constructor(provider: RpcProvider);
-    getPrice(tokenAddr: string): Promise<number>;
+interface IInvestmentFlow {
+    title: string;
+    subItems: string[];
+    linkedFlows: IInvestmentFlow[];
 }
+declare function getMainnetConfig(rpcUrl?: string, blockIdentifier?: BlockIdentifier): IConfig;
 
 interface ILendingMetadata {
     name: string;
@@ -139,6 +143,48 @@ declare abstract class Initializable {
     waitForInitilisation(): Promise<void>;
 }
 
+declare abstract class PricerBase {
+    readonly config: IConfig;
+    readonly tokens: TokenInfo[];
+    constructor(config: IConfig, tokens: TokenInfo[]);
+    getPrice(tokenSymbol: string): Promise<PriceInfo>;
+}
+
+interface PriceInfo {
+    price: number;
+    timestamp: Date;
+}
+declare class Pricer extends PricerBase {
+    protected prices: {
+        [key: string]: PriceInfo;
+    };
+    private methodToUse;
+    /**
+     * TOKENA and TOKENB are the two token names to get price of TokenA in terms of TokenB
+     */
+    protected PRICE_API: string;
+    protected EKUBO_API: string;
+    constructor(config: IConfig, tokens: TokenInfo[]);
+    isReady(): boolean;
+    waitTillReady(): Promise<void>;
+    start(): void;
+    isStale(timestamp: Date, tokenName: string): boolean;
+    assertNotStale(timestamp: Date, tokenName: string): void;
+    getPrice(tokenSymbol: string): Promise<PriceInfo>;
+    protected _loadPrices(onUpdate?: (tokenSymbol: string) => void): void;
+    _getPrice(token: TokenInfo, defaultMethod?: string): Promise<number>;
+    _getPriceCoinbase(token: TokenInfo): Promise<number>;
+    _getPriceCoinMarketCap(token: TokenInfo): Promise<number>;
+    _getPriceEkubo(token: TokenInfo, amountIn?: Web3Number, retry?: number): Promise<number>;
+}
+
+declare class Pragma {
+    contractAddr: string;
+    readonly contract: Contract;
+    constructor(provider: RpcProvider);
+    getPrice(tokenAddr: string): Promise<number>;
+}
+
 declare class ZkLend extends ILending implements ILending {
     readonly pricer: Pricer;
     static readonly POOLS_URL = "https://app.zklend.com/api/pools";
@@ -170,6 +216,15 @@ declare class ZkLend extends ILending implements ILending {
     getPositions(user: ContractAddr): Promise<ILendingPosition[]>;
 }
 
+declare class PricerFromApi extends PricerBase {
+    constructor(config: IConfig, tokens: TokenInfo[]);
+    getPrice(tokenSymbol: string): Promise<PriceInfo>;
+    getPriceFromMyAPI(tokenSymbol: string): Promise<{
+        price: number;
+        timestamp: Date;
+    }>;
+}
+
 declare const logger: {
     verbose(message: string): void;
     assert(condition?: boolean, ...data: any[]): void;
@@ -225,6 +280,7 @@ declare class FatalError extends Error {
 declare class Global {
     static fatalError(message: string, err?: Error): void;
     static httpError(url: string, err: Error, message?: string): void;
+    static getDefaultTokens(): TokenInfo[];
     static getTokens(): Promise<TokenInfo[]>;
     static assert(condition: any, message: string): void;
 }
@@ -258,6 +314,179 @@ declare class AutoCompounderSTRK {
     }>;
 }
 
+interface Change {
+    pool_id: ContractAddr;
+    changeAmt: Web3Number;
+    finalAmt: Web3Number;
+    isDeposit: boolean;
+}
+interface PoolInfoFull {
+    pool_id: ContractAddr;
+    pool_name: string | undefined;
+    max_weight: number;
+    current_weight: number;
+    v_token: ContractAddr;
+    amount: Web3Number;
+    usdValue: Web3Number;
+    APY: {
+        baseApy: number;
+        defiSpringApy: number;
+        netApy: number;
+    };
+    currentUtilization: number;
+    maxUtilization: number;
+}
+/**
+ * Represents a VesuRebalance strategy.
+ * This class implements an automated rebalancing strategy for Vesu pools,
+ * managing deposits and withdrawals while optimizing yield through STRK rewards.
+ */
+declare class VesuRebalance {
+    /** Configuration object for the strategy */
+    readonly config: IConfig;
+    /** Contract address of the strategy */
+    readonly address: ContractAddr;
+    /** Pricer instance for token price calculations */
+    readonly pricer: PricerBase;
+    /** Metadata containing strategy information */
+    readonly metadata: IStrategyMetadata;
+    /** Contract instance for interacting with the strategy */
+    readonly contract: Contract;
+    readonly BASE_WEIGHT = 10000;
+    /**
+     * Creates a new VesuRebalance strategy instance.
+     * @param config - Configuration object containing provider and other settings
+     * @param pricer - Pricer instance for token price calculations
+     * @param metadata - Strategy metadata including deposit tokens and address
+     * @throws {Error} If more than one deposit token is specified
+     */
+    constructor(config: IConfig, pricer: PricerBase, metadata: IStrategyMetadata);
+    /**
+     * Creates a deposit call to the strategy contract.
+     * @param assets - Amount of assets to deposit
+     * @param receiver - Address that will receive the strategy tokens
+     * @returns Populated contract call for deposit
+     */
+    depositCall(assets: Web3Number, receiver: ContractAddr): starknet.Call[];
+    /**
+     * Creates a withdrawal call to the strategy contract.
+     * @param assets - Amount of assets to withdraw
+     * @param receiver - Address that will receive the withdrawn assets
+     * @param owner - Address that owns the strategy tokens
+     * @returns Populated contract call for withdrawal
+     */
+    withdrawCall(assets: Web3Number, receiver: ContractAddr, owner: ContractAddr): starknet.Call[];
+    /**
+     * Returns the underlying asset token of the strategy.
+     * @returns The deposit token supported by this strategy
+     */
+    asset(): TokenInfo;
+    /**
+     * Returns the number of decimals used by the strategy token.
+     * @returns Number of decimals (same as the underlying token)
+     */
+    decimals(): number;
+    /**
+     * Calculates the Total Value Locked (TVL) for a specific user.
+     * @param user - Address of the user
+     * @returns Object containing the amount in token units and USD value
+     */
+    getUserTVL(user: ContractAddr): Promise<{
+        amount: Web3Number;
+        usdValue: number;
+    }>;
+    /**
+     * Calculates the total TVL of the strategy.
+     * @returns Object containing the total amount in token units and USD value
+     */
+    getTVL(): Promise<{
+        amount: Web3Number;
+        usdValue: number;
+    }>;
+    /**
+     * Retrieves the list of allowed pools and their detailed information from multiple sources:
+     * 1. Contract's allowed pools
+     * 2. Vesu positions API for current positions
+     * 3. Vesu pools API for APY and utilization data
+     *
+     * @returns {Promise<{
+     *   data: Array<PoolInfoFull>,
+     *   isErrorPositionsAPI: boolean
+     * }>} Object containing:
+     *   - data: Array of pool information including IDs, weights, amounts, APYs and utilization
+     *   - isErrorPositionsAPI: Boolean indicating if there was an error fetching position data
+     */
+    getPools(): Promise<{
+        data: {
+            pool_id: ContractAddr;
+            pool_name: any;
+            max_weight: number;
+            current_weight: number;
+            v_token: ContractAddr;
+            amount: Web3Number;
+            usdValue: Web3Number;
+            APY: {
+                baseApy: number;
+                defiSpringApy: number;
+                netApy: number;
+            };
+            currentUtilization: number;
+            maxUtilization: number;
+        }[];
+        isErrorPositionsAPI: boolean;
+        isErrorPoolsAPI: boolean;
+        isError: boolean;
+    }>;
+    /**
+     * Calculates the weighted average APY across all pools based on USD value.
+     * @returns {Promise<number>} The weighted average APY across all pools
+     */
+    netAPY(): Promise<number>;
+    /**
+     * Calculates the weighted average APY across all pools based on USD value.
+     * @returns {Promise<number>} The weighted average APY across all pools
+     */
+    netAPYGivenPools(pools: PoolInfoFull[]): number;
+    /**
+     * Calculates optimal position changes to maximize APY while respecting max weights.
+     * The algorithm:
+     * 1. Sorts pools by APY (highest first)
+     * 2. Calculates target amounts based on max weights
+     * 3. For each pool that needs more funds:
+     *    - Takes funds from lowest APY pools that are over their target
+     * 4. Validates that total assets remain constant
+     *
+     * @returns {Promise<{
+     *   changes: Change[],
+     *   finalPools: PoolInfoFull[],
+     *   isAnyPoolOverMaxWeight: boolean
+     * }>} Object containing:
+     *   - changes: Array of position changes
+     *   - finalPools: Array of pool information after rebalance
+     * @throws Error if rebalance is not possible while maintaining constraints
+     */
+    getRebalancedPositions(): Promise<{
+        changes: never[];
+        finalPools: never[];
+        isAnyPoolOverMaxWeight?: undefined;
+    } | {
+        changes: Change[];
+        finalPools: PoolInfoFull[];
+        isAnyPoolOverMaxWeight: boolean;
+    }>;
+    /**
+     * Creates a rebalance Call object for the strategy contract
+     * @param pools - Array of pool information including IDs, weights, amounts, APYs and utilization
+     * @returns Populated contract call for rebalance
+     */
+    getRebalanceCall(pools: Awaited<ReturnType<typeof this.getRebalancedPositions>>['changes'], isOverWeightAdjustment: boolean): Promise<starknet.Call | null>;
+    getInvestmentFlows(pools: PoolInfoFull[]): Promise<IInvestmentFlow[]>;
+}
+/**
+ * Represents the Vesu Rebalance Strategies.
+ */
+declare const VesuRebalanceStrategies: IStrategyMetadata[];
+
 declare class TelegramNotif {
     private subscribers;
     readonly bot: TelegramBot;
@@ -266,6 +495,27 @@ declare class TelegramNotif {
     sendMessage(msg: string): void;
 }
 
+type RequiredFields<T> = {
+    [K in keyof T]-?: T[K];
+};
+type RequiredKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+declare function assert(condition: boolean, message: string): void;
+
+declare class PricerRedis extends Pricer {
+    private redisClient;
+    constructor(config: IConfig, tokens: TokenInfo[]);
+    /** Reads prices from Pricer._loadPrices and uses a callback to set prices in redis */
+    startWithRedis(redisUrl: string): Promise<void>;
+    close(): Promise<void>;
+    initRedis(redisUrl: string): Promise<void>;
+    /** sets current local price in redis */
+    private _setRedisPrices;
+    /** Returns price from redis */
+    getPrice(tokenSymbol: string): Promise<PriceInfo>;
+}
+
 /**
  * @description Config to manage storage of files on disk
  * @param SECRET_FILE_FOLDER - Folder to store secret files (default: ~/.starknet-store)
@@ -344,24 +594,4 @@ declare class PasswordJsonCryptoUtil {
     decrypt(encryptedData: string, password: string): any;
 }
 
-type RequiredFields<T> = {
-    [K in keyof T]-?: T[K];
-};
-type RequiredKeys<T> = {
-    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
-}[keyof T];
-
-declare class PricerRedis extends Pricer {
-    private redisClient;
-    constructor(config: IConfig, tokens: TokenInfo[]);
-    /** Reads prices from Pricer._loadPrices and uses a callback to set prices in redis */
-    startWithRedis(redisUrl: string): Promise<void>;
-    close(): Promise<void>;
-    initRedis(redisUrl: string): Promise<void>;
-    /** sets current local price in redis */
-    private _setRedisPrices;
-    /** Returns price from redis */
-    getPrice(tokenSymbol: string): Promise<PriceInfo>;
-}
-
-export { type AccountInfo, type AllAccountsStore, AutoCompounderSTRK, ContractAddr, FatalError, Global, type IConfig, ILending, type ILendingMetadata, type ILendingPosition, Initializable, type LendingToken, MarginType, Network, PasswordJsonCryptoUtil, Pragma, type PriceInfo, Pricer, PricerRedis, type RequiredFields, type RequiredKeys, type RequiredStoreConfig, Store, type StoreConfig, TelegramNotif, type TokenInfo, Web3Number, ZkLend, getDefaultStoreConfig, getMainnetConfig, logger };
+export { type AccountInfo, type AllAccountsStore, AutoCompounderSTRK, ContractAddr, FatalError, Global, type IConfig, type IInvestmentFlow, ILending, type ILendingMetadata, type ILendingPosition, type IProtocol, type IStrategyMetadata, Initializable, type LendingToken, MarginType, Network, PasswordJsonCryptoUtil, Pragma, type PriceInfo, Pricer, PricerFromApi, PricerRedis, type RequiredFields, type RequiredKeys, type RequiredStoreConfig, type RiskFactor, RiskType, Store, type StoreConfig, TelegramNotif, type TokenInfo, VesuRebalance, VesuRebalanceStrategies, Web3Number, ZkLend, assert, getDefaultStoreConfig, getMainnetConfig, logger };