@strkfarm/sdk 2.0.0-staging.4 → 2.0.0-staging.41

package/src/dataTypes/_bignumber.ts

@@ -1,5 +1,6 @@
 import { logger } from "@/utils/logger";
 import BigNumber from "bignumber.js";
+import { uint256 } from "starknet";
 
 export class _Web3Number<T extends _Web3Number<T>> extends BigNumber {
   decimals: number;
@@ -107,6 +108,10 @@ export class _Web3Number<T extends _Web3Number<T>> extends BigNumber {
       sign: sign,
     }
   }
+
+  toUint256() {
+    return uint256.bnToUint256(this.toWei());
+  }
 }
 
 BigNumber.config({ DECIMAL_PLACES: 18, ROUNDING_MODE: BigNumber.ROUND_DOWN });

package/src/dataTypes/bignumber.browser.ts

@@ -1,3 +1,4 @@
+import { Uint256, uint256 } from "starknet";
 import { _Web3Number } from "./_bignumber";
 
 export class Web3Number extends _Web3Number<Web3Number> {
@@ -5,4 +6,8 @@ export class Web3Number extends _Web3Number<Web3Number> {
         const bn = (new Web3Number(weiNumber, decimals)).dividedBy(10 ** decimals)
         return new Web3Number(bn.toString(), decimals);
     }
+
+    static fromUint256(uint256Value: Uint256): Web3Number {
+        return this.fromWei(uint256.uint256ToBN(uint256Value).toString(), 18);
+    }
 }

package/src/dataTypes/bignumber.node.ts

@@ -1,5 +1,6 @@
 import util from 'util';
 import { _Web3Number } from "./_bignumber";
+import { Uint256, uint256 } from 'starknet';
 
 export class Web3Number extends _Web3Number<Web3Number> {
 
@@ -8,6 +9,10 @@ export class Web3Number extends _Web3Number<Web3Number> {
         return new Web3Number(bn.toString(), decimals);
     }
 
+    static fromUint256(uint256Value: Uint256): Web3Number {
+        return this.fromWei(uint256.uint256ToBN(uint256Value).toString(), 18);
+    }
+
     [util.inspect.custom](depth: any, opts: any): string {
         return this.toString();
     }

package/src/global.ts

@@ -165,6 +165,33 @@ const defaultTokens: TokenInfo[] = [{
     coingeckId: undefined,
     displayDecimals: 2,
     priceCheckAmount: 100,
+}, {
+    name: "fyeWBTC",
+    symbol: "fyeWBTC",
+    logo: 'https://assets.strkfarm.com/integrations/tokens/wbtc.svg',
+    address: ContractAddr.from('0x04dd39de0a588f5e1c7a8377e1bef2c49caaee49a11433429d2c48f587b3a492'),
+    decimals: 8,
+    coingeckId: undefined,
+    displayDecimals: 6,
+    priceCheckAmount: 0.001, // 112000 * 0.0001 = $110.2
+}, {
+    name: "fyETH",
+    symbol: "fyETH",
+    logo: 'https://assets.strkfarm.com/integrations/tokens/eth.svg',
+    address: ContractAddr.from('0x050707bC3b8730022F10530C2c6f6b9467644129C50C2868Ad0036c5e4E9e616'),
+    decimals: 18,
+    coingeckId: undefined,
+    displayDecimals: 4,
+    priceCheckAmount: 0.1,
+}, {
+    name: "fyeUSDC",
+    symbol: "fyeUSDC",
+    logo: 'https://assets.strkfarm.com/integrations/tokens/usdc.svg',
+    address: ContractAddr.from('0x07fdcec0cef01294c9c3d52415215949805c77bae8003702a7928fd6d2c36bc1'),
+    decimals: 6,
+    coingeckId: undefined,
+    displayDecimals: 2,
+    priceCheckAmount: 100,
 }]
 const tokens: TokenInfo[] = defaultTokens;
 

package/src/interfaces/common.tsx

@@ -55,21 +55,24 @@ export interface IProtocol {
   logo: string;
 }
 
-// Strategy-level enums
-export enum StrategyCategory {
-  ALL = "all",
-  BTC = "btc",
-  META_VAULTS = "meta-vaults",
+export interface ICurator {
+  name: string;
+  logo: string;
 }
 
 export enum StrategyTag {
-  EKUBO = "Ekubo",
-  EVERGREEN = "Evergreen",
-  HYPER_LST = "Hyper-LST",
-  VESU = "Vesu",
-  SENSEI = "Sensei",
-  ENDUR = "Endur",
-    BTC = "BTC"
+  META_VAULT = "Meta Vaults",
+  LEVERED = "Maxx",
+  AUTOMATED_LP = "Ekubo",
+  BTC = "BTC"
+}
+
+export enum VaultType {
+  LOOPING = "Looping",
+  META_VAULT = "Meta Vault",
+  DELTA_NEUTRAL = "Delta Neutral",
+  AUTOMATED_LP = "Automated LP",
+  TVA = "Troves Value Averaging",
 }
 
 // Security metadata enums
@@ -86,6 +89,7 @@ export enum SourceCodeType {
 export enum AccessControlType {
   MULTISIG_ACCOUNT = "Multisig Account",
   STANDARD_ACCOUNT = "Standard Account",
+  ROLE_BASED_ACCESS = "Role Based Access",
 }
 
 export enum InstantWithdrawalVault {
@@ -102,7 +106,7 @@ export interface SourceCodeInfo {
 export interface AccessControlInfo {
   type: AccessControlType;
   addresses: ContractAddr[];
-  timeLock: string;
+  timeLock?: string;
 }
 
 export interface SecurityMetadata {
@@ -111,16 +115,13 @@ export interface SecurityMetadata {
   accessControl: AccessControlInfo;
 }
 
-// Redemption metadata interfaces
-export interface RedemptionExpectedTime {
-  upto1M: string;
-  upto10M: string;
-  above10M: string;
-}
-
 export interface RedemptionInfo {
   instantWithdrawalVault: InstantWithdrawalVault;
-  expectedRedemptionTime?: RedemptionExpectedTime;
+  redemptionsInfo: {
+    title: string; // e.g. Upto $1M
+    description: string; // e.g. "1-2 hours"
+  }[],
+  alerts: StrategyAlert[];
 }
 
 export enum FlowChartColors {
@@ -138,7 +139,8 @@ export enum StrategyLiveStatus {
     ACTIVE = "Active",
     NEW = "New",
     COMING_SOON = "Coming Soon",
-    RETIRED = "Retired",
+    DEPRECATED = "Deprecated", // active but not recommended
+    RETIRED = "Retired", // not active anymore
     HOT = "Hot & New 🔥"
 }
 
@@ -165,6 +167,13 @@ export interface StrategySettings {
     tags?: StrategyTag[];
 }
 
+export interface StrategyApyHistoryUIConfig {
+  // Defaults to true in UI if omitted.
+  showApyHistory?: boolean;
+  // Optional message shown when APY history is hidden.
+  noApyHistoryMessage?: 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.
@@ -178,6 +187,10 @@ export interface IStrategyMetadata<T> {
   address: ContractAddr;
   launchBlock: number;
   type: "ERC4626" | "ERC721" | "Other";
+  vaultType: {
+    type: VaultType;
+    description: string;
+  };
   depositTokens: TokenInfo[];
   protocols: IProtocol[];
   auditUrl?: string;
@@ -187,6 +200,7 @@ export interface IStrategyMetadata<T> {
     notARisks: RiskType[];
   };
   apyMethodology?: string;
+  realizedApyMethodology?: string;
   additionalInfo: T;
   contractDetails: {
     address: ContractAddr;
@@ -197,13 +211,20 @@ export interface IStrategyMetadata<T> {
   points?: {multiplier: number, logo: string, toolTip?: string}[];
   docs?: string;
   investmentSteps: string[];
-  curator?: { name: string, logo: string },
+  curator?: ICurator,
   isPreview?: boolean;
-  category: StrategyCategory;
   tags?: StrategyTag[];
   security: SecurityMetadata;
   redemptionInfo: RedemptionInfo;
+  usualTimeToEarnings: null | string; // e.g. "2 weeks" // some strats grow like step functions
+  usualTimeToEarningsDescription: null | string; // e.g. "LSTs price on DEX goes up roughly every 2 weeks"
+  discontinuationInfo?: {
+    date?: Date;
+    reason?: React.ReactNode | string;
+    info?: React.ReactNode | string;
+  };
   settings?: StrategySettings;
+  apyHistoryUIConfig?: StrategyApyHistoryUIConfig;
     // Legacy field for multi-step strategies (deprecated, use investmentFlows instead)
     actions?: Array<{
         name?: string;
@@ -242,6 +263,23 @@ export function getMainnetConfig(
   };
 }
 
+export const getStrategyTagDesciption = (tag: StrategyTag): string => {
+  switch (tag) {
+    case StrategyTag.META_VAULT:
+      return "A meta vault is a vault that auto allocates funds to multiple vaults based on optimal yield opportunities";
+    case StrategyTag.LEVERED:
+      return "Looping vaults on Endur LSTs with leveraged borrowing of STRK or BTC to increase yield (2-4x higher yield than simply staking)";
+    case StrategyTag.AUTOMATED_LP:
+      return "Automated LP vaults on Ekubo that rebalance position automatically, ensuring you earn fees efficiently";
+    case StrategyTag.BTC:
+      return "BTC linked vaults";
+  }
+}
+
+export const getAllStrategyTags = (): StrategyTag[] => {
+  return Object.values(StrategyTag);
+}
+
 export const getRiskExplaination = (riskType: RiskType) => {
   switch (riskType) {
     case RiskType.MARKET_RISK:
@@ -314,7 +352,7 @@ export function highlightTextWithLinks(
       {parts.map((part, i) => {
         const match = highlights.find(m => m.highlight.toLowerCase() === part.toLowerCase());
         return match ? (
-          <a key={i} href={match.link} target="_blank" style={{ color: 'var(--chakra-colors-white)', background: 'var(--chakra-colors-highlight)' }}>
+          <a key={i} href={match.link} target="_blank" style={{ color: 'white', background: 'rgba(255, 255, 255, 0.04)' }}>
             {part}
           </a>
         ) : (
@@ -375,4 +413,9 @@ export const Protocols = {
   VESU: VesuProtocol,
   ENDUR: EndurProtocol,
   EXTENDED: ExtendedProtocol
+}
+
+export const UnwrapLabsCurator: ICurator = {
+  name: "Unwrap Labs",
+  logo: "https://assets.troves.fi/integrations/unwraplabs/white.png"
 }

package/src/modules/avnu.ts

@@ -37,7 +37,7 @@ export class AvnuWrapper {
     excludeSources = ['Haiko(Solvers)']
   ): Promise<Quote> {
     const MAX_RETRY = 5;
-    // logger.verbose(`${AvnuWrapper.name}: getQuotes => Getting quotes for ${fromToken} -> ${toToken}, amount: ${amountWei}, taker: ${taker}, retry: ${retry}`);
+    logger.verbose(`${AvnuWrapper.name}: getQuotes => Getting quotes for ${fromToken} -> ${toToken}, amount: ${amountWei}, taker: ${taker}, retry: ${retry}`);
     const params: any = {
       sellTokenAddress: fromToken,
       buyTokenAddress: toToken,

package/src/modules/erc20.ts

@@ -2,7 +2,7 @@ import { ContractAddr, Web3Number } from "@/dataTypes";
 import { IConfig } from "@/interfaces";
 import { Contract } from "starknet";
 import ERC20Abi from '@/data/erc20.abi.json';
-
+import { uint256 } from "starknet";
 export class ERC20 {
     readonly config: IConfig;
 
@@ -12,7 +12,7 @@ export class ERC20 {
 
     contract(addr: string | ContractAddr) {
         const _addr = typeof addr === 'string' ? addr : addr.address;
-        return new Contract({abi: ERC20Abi, address: _addr, providerOrAccount: this.config.provider});
+        return new Contract({ abi: ERC20Abi, address: _addr, providerOrAccount: this.config.provider });
     }
 
     async balanceOf(token: string | ContractAddr, address: string | ContractAddr, tokenDecimals: number) {
@@ -26,4 +26,20 @@ export class ERC20 {
         const allowance = await contract.call('allowance', [owner.toString(), spender.toString()]);
         return Web3Number.fromWei(allowance.toString(), tokenDecimals);
     }
+
+    approve(
+        token: string | ContractAddr,
+        spender: string | ContractAddr,
+        amount: Web3Number
+    ) {
+        const contract = this.contract(token);
+        const amountUint256 = uint256.bnToUint256(amount.toWei());
+        const approveCall = contract.populate("approve", [
+            spender.toString(),
+            amountUint256.low.toString(),
+            amountUint256.high.toString(),
+        ]);
+        return approveCall;
+    }
+
 }

package/src/strategies/base-strategy.ts

@@ -23,18 +23,76 @@ export interface DualTokenInfo {
     token1: SingleTokenInfo
 }
 
+export type StrategyInputMode = "single" | "dual";
+export type InputModeFromAction<T> = T extends DualActionAmount ? "dual" : "single";
+
+export interface NetAPYSplit {
+  apy: number;
+  id: string;
+}
+
+export interface NetAPYDetails {
+  net: number;
+  splits: NetAPYSplit[];
+}
+
+export type UserPositionCardSubValueColor = "default" | "positive" | "negative" | "info";
+
+export interface UserPositionCard {
+  title: string;
+  value: string;
+  tooltip?: string;
+  subValue?: string;
+  subValueColor?: UserPositionCardSubValueColor;
+  kind?: "metric" | "apy";
+  apyMethod?: string;
+}
+
+export interface UserPositionCardsInput {
+  user: ContractAddr;
+  investmentFlows?: Array<{ amount: string; type: string; timestamp: number; tx_hash: string }>;
+  usualTimeToEarnings?: string | null;
+  usualTimeToEarningsDescription?: string | null;
+  apy?: number | string | null;
+  apyMethod?: string | null;
+}
+
 interface CacheData {
   timestamp: number;
   ttl: number;
   data: any;
 }
-export class BaseStrategy<TVLInfo, ActionInfo> extends CacheClass {
-    readonly config: IConfig;
-    readonly cache: Map<string, CacheData> = new Map();
+export class BaseStrategy<
+  TVLInfo,
+  DepositActionInfo,
+  WithdrawActionInfo = DepositActionInfo,
+> extends CacheClass {
+  readonly config: IConfig;
+  readonly cache: Map<string, CacheData> = new Map();
+  private readonly _depositInputMode: InputModeFromAction<DepositActionInfo>;
+  private readonly _withdrawInputMode: InputModeFromAction<WithdrawActionInfo>;
 
-    constructor(config: IConfig) {
+    constructor(
+      config: IConfig,
+      inputModes?: {
+        depositInputMode?: InputModeFromAction<DepositActionInfo>;
+        withdrawInputMode?: InputModeFromAction<WithdrawActionInfo>;
+      }
+    ) {
         super();
         this.config = config;
+        this._depositInputMode = (inputModes?.depositInputMode ??
+          ("single" as InputModeFromAction<DepositActionInfo>));
+        this._withdrawInputMode = (inputModes?.withdrawInputMode ??
+          ("single" as InputModeFromAction<WithdrawActionInfo>));
+    }
+
+    depositInputMode(): InputModeFromAction<DepositActionInfo> {
+      return this._depositInputMode;
+    }
+
+    withdrawInputMode(): InputModeFromAction<WithdrawActionInfo> {
+      return this._withdrawInputMode;
     }
 
     async getUserTVL(user: ContractAddr, blockIdentifier?: BlockIdentifier): Promise<TVLInfo> {
@@ -45,11 +103,11 @@ export class BaseStrategy<TVLInfo, ActionInfo> extends CacheClass {
         throw new Error("Not implemented");
     }   
 
-    async depositCall(amountInfo: ActionInfo, receiver: ContractAddr): Promise<Call[]> {
+    async depositCall(amountInfo: DepositActionInfo, receiver: ContractAddr): Promise<Call[]> {
         throw new Error("Not implemented");
     }
 
-    async withdrawCall(amountInfo: ActionInfo, receiver: ContractAddr, owner: ContractAddr): Promise<Call[]> {
+    async withdrawCall(amountInfo: WithdrawActionInfo, receiver: ContractAddr, owner: ContractAddr): Promise<Call[]> {
         throw new Error("Not implemented");
     }
 
@@ -57,7 +115,159 @@ export class BaseStrategy<TVLInfo, ActionInfo> extends CacheClass {
         throw new Error("Not implemented");
     }
 
+    async netAPY(
+        blockIdentifier?: BlockIdentifier,
+        sinceBlocks?: number,
+        timeperiod?: "24h" | "7d" | "30d" | "3m"
+    ): Promise<number | string | NetAPYDetails> {
+        throw new Error("Not implemented");
+    }
+
     async getPendingRewards(): Promise<HarvestInfo[]> {
         return [];
     }
+
+    async getUserRealizedAPY(
+        blockIdentifier?: BlockIdentifier,
+        sinceBlocks?: number
+    ): Promise<number> {
+        throw new Error("Not implemented");
+    }
+
+    async getUserPositionCards(_input: UserPositionCardsInput): Promise<UserPositionCard[]> {
+      throw new Error("Not implemented");
+    }
+
+    protected formatTokenAmountForCard(amount: Web3Number, tokenInfo: TokenInfo): string {
+      const displayDecimals = tokenInfo.displayDecimals ?? 2;
+      const fixed = Number(amount.toFixed(displayDecimals));
+      const normalized = Number.isFinite(fixed) ? fixed : 0;
+      return `${normalized.toLocaleString("en-US", {
+        maximumFractionDigits: displayDecimals,
+        minimumFractionDigits: 0,
+      })} ${tokenInfo.symbol}`;
+    }
+
+    protected formatPercentForCard(value: number): string {
+      if (!Number.isFinite(value)) return "N/A";
+      return `${(value * 100).toFixed(2)}%`;
+    }
+
+    protected resolveApyMethod(input?: UserPositionCardsInput): string | undefined {
+      const fromInput = input?.apyMethod?.trim();
+      if (fromInput) return fromInput;
+      const metadataApyMethod = (this as any)?.metadata?.apyMethodology;
+      if (typeof metadataApyMethod === "string" && metadataApyMethod.trim().length > 0) {
+        return metadataApyMethod;
+      }
+      return undefined;
+    }
+
+    protected normalizeApyDisplayValue(
+      apy: number | string | NetAPYDetails | null | undefined
+    ): string {
+      if (typeof apy === "number") {
+        return this.formatPercentForCard(apy);
+      }
+      if (typeof apy === "string") {
+        return apy.trim().length > 0 ? apy : "N/A";
+      }
+      if (apy && typeof apy === "object" && "net" in apy) {
+        return this.formatPercentForCard(Number(apy.net));
+      }
+      return "N/A";
+    }
+
+    protected async resolveApyValueForCard(input?: UserPositionCardsInput): Promise<string> {
+      if (input && input.apy !== undefined && input.apy !== null) {
+        return this.normalizeApyDisplayValue(input.apy);
+      }
+      try {
+        const netApy = await this.netAPY();
+        return this.normalizeApyDisplayValue(netApy as number | string | NetAPYDetails);
+      } catch {
+        return "N/A";
+      }
+    }
+
+    protected async createApyCard(input?: UserPositionCardsInput): Promise<UserPositionCard> {
+      const apyMethod = this.resolveApyMethod(input);
+      return {
+        title: "APY",
+        value: await this.resolveApyValueForCard(input),
+        tooltip: apyMethod,
+        kind: "apy",
+        apyMethod,
+      };
+    }
+
+    protected formatUSDForCard(value: number): string {
+      if (!Number.isFinite(value)) return "$0.00";
+      return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: "USD",
+        maximumFractionDigits: 2,
+      }).format(value);
+    }
+
+    protected getSubValueColorFromSignedNumber(value: number): UserPositionCardSubValueColor {
+      if (!Number.isFinite(value)) return "default";
+      if (value > 0) return "positive";
+      if (value < 0) return "negative";
+      return "default";
+    }
+
+    /**
+     * Calculate lifetime earnings for a user based on provided data from client
+     * Formula: lifetimeEarnings = currentValue + totalWithdrawals - totalDeposits
+     * 
+     * @param userTVL - The user's current TVL (SingleTokenInfo with amount, usdValue, tokenInfo)
+     * @param investmentFlows - Array of investment flow transactions from client
+     * @returns Object containing lifetime earnings, current value, and total deposits/withdrawals
+     */
+    getLifetimeEarnings(
+        userTVL: SingleTokenInfo,
+        investmentFlows: Array<{ amount: string; type: string; timestamp: number; tx_hash: string }>
+    ): {
+        tokenInfo: SingleTokenInfo;
+        lifetimeEarnings: Web3Number;
+        currentValue: Web3Number;
+        totalDeposits: Web3Number;
+        totalWithdrawals: Web3Number;
+    } {
+        // Get token decimals from userTVL
+        const tokenDecimals = userTVL.tokenInfo.decimals;
+
+        // Initialize totals
+        let totalDeposits = Web3Number.fromWei("0", tokenDecimals);
+        let totalWithdrawals = Web3Number.fromWei("0", tokenDecimals);
+
+        // Process investment flows
+        for (const flow of investmentFlows) {
+            const amount = Web3Number.fromWei(flow.amount, tokenDecimals);
+            
+            if (flow.type === 'deposit') {
+                totalDeposits = totalDeposits.plus(amount);
+            } else if (flow.type === 'withdraw' || flow.type === 'redeem') {
+                totalWithdrawals = totalWithdrawals.plus(amount);
+            }
+        }
+
+        // Calculate lifetime earnings: current value + withdrawals - deposits
+        const lifetimeEarnings = userTVL.amount
+            .plus(totalWithdrawals)
+            .minus(totalDeposits);
+
+        return {
+            tokenInfo: {
+                tokenInfo: userTVL.tokenInfo,
+                amount: lifetimeEarnings,
+                usdValue: 0, // Lifetime earnings are not converted to USD
+            },
+            lifetimeEarnings,
+            currentValue: userTVL.amount,
+            totalDeposits,
+            totalWithdrawals,
+        };
+    }
 }

package/src/strategies/constants.ts

@@ -1,10 +1,10 @@
 import { ContractAddr } from "@/dataTypes";
 
-export const COMMON_CONTRACTS = [{
+export const MY_ACCESS_CONTROL = {
   address: ContractAddr.from("0x0636a3f51cc37f5729e4da4b1de6a8549a28f3c0d5bf3b17f150971e451ff9c2"),
   name: "Access Controller",
   sourceCodeUrl: "https://github.com/strkfarm/strkfarm-contracts/blob/main/src/components/accessControl.cairo",
-}];
+};
 
 export const ENDPOINTS = {
   VESU_BASE: "https://proxy.api.troves.fi/vesu",