@augustdigital/sdk 8.3.2 → 8.6.0

package/lib/modules/vaults/utils.js

@@ -17,6 +17,10 @@ const abis_1 = require("../../abis");
 const core_1 = require("../../core");
 const vaults_1 = require("../../core/helpers/vaults");
 const ethers_1 = require("ethers");
+/**
+ * @param walletClient a wagmi-derived client (from useWalletClient)
+ * @returns An ethers JsonRpcSigner object used in sdk.evm.setSigner
+ */
 async function walletClientToSigner(walletClient) {
     const { account, chain, transport } = walletClient;
     const network = {
@@ -24,14 +28,23 @@ async function walletClientToSigner(walletClient) {
         name: chain.name,
         ensAddress: chain.contracts?.ensRegistry?.address,
     };
+    //@ts-expect-error
     const provider = new ethers_1.BrowserProvider(transport, network);
     const signer = await provider.getSigner(account.address);
     return signer;
 }
+/**
+ * Calculates the reward multiplier based on the vault and optional timestamp.
+ * Returns the applicable multiplier for a given vault at a specific timestamp,
+ * or the latest multiplier if no timestamp is provided.
+ * @param foundPool The vault to get the multiplier for
+ * @param timestamp Optional timestamp to get historical multiplier
+ * @returns The reward multiplier value
+ */
 const getRewardMultiplierByTimestamp = (foundPool, timestamp) => {
     const multipliers = foundPool.rewards?.multipliers;
     if (!multipliers?.length) {
-        return 1;
+        return 1; // default multiplier if multipliers are not found
     }
     const multipliersByTimestamp = multipliers.reduce((acc, curr) => {
         return {
@@ -40,8 +53,9 @@ const getRewardMultiplierByTimestamp = (foundPool, timestamp) => {
         };
     }, {});
     if (!multipliersByTimestamp) {
-        return 1;
+        return 1; // default multiplier if pool is not found
     }
+    // return the latest if timestamp not provided
     if (!timestamp) {
         const latest = Object.keys(multipliersByTimestamp)
             .map(Number)
@@ -50,13 +64,43 @@ const getRewardMultiplierByTimestamp = (foundPool, timestamp) => {
     }
     const applicableTimestamp = Object.keys(multipliersByTimestamp)
         .map(Number)
-        .filter((ts) => ts <= timestamp)
-        .sort((a, b) => b - a)[0];
+        .filter((ts) => ts <= timestamp) // filter only timestamps before or equal to the given timestamp
+        .sort((a, b) => b - a)[0]; // get the latest applicable timestamp
     return applicableTimestamp !== undefined
         ? (multipliersByTimestamp[applicableTimestamp] ?? 1)
         : 1;
 };
 exports.getRewardMultiplierByTimestamp = getRewardMultiplierByTimestamp;
+/**
+ * Build the human-readable display label for a single reward.
+ *
+ * The format is `"{multiplier}x {text}"`, with the multiplier prefix omitted
+ * when it equals 1 (e.g. `"2x Cores"`, `" Cores"` when multiplier is 1 — the
+ * leading space is preserved to keep `additionalPoints` and the
+ * `additionalPointsDetailed` label in lockstep). This is a display string only;
+ * consumers that need a stable key should join on the reward's `id`
+ * (see {@link IVaultRewardDetail}), not on this label.
+ *
+ * @param reward - The raw tokenized-vault reward.
+ * @returns The display label string.
+ */
+function getRewardLabel(reward) {
+    return `${reward.multiplier !== 1 ? `${reward.multiplier}x` : ''} ${reward.text}`;
+}
+/**
+ * Get the rewards for the vault.
+ *
+ * Builds the display-facing rewards summary from the raw tokenized-vault
+ * rewards array. In addition to the legacy `additionalPoints` string list, it
+ * emits `additionalPointsDetailed`, which pairs each label with its
+ * backend-provided `img_url`. Consumers (e.g. the Upshift app) resolve a
+ * reward's logo from this `imgUrl` first, falling back to a bundled asset only
+ * when it is absent — so a newly-added reward with a backend logo (e.g.
+ * "Cores") renders its icon without any client-side keyword mapping.
+ *
+ * @param tokenizedVault - The tokenized vault.
+ * @returns The rewards summary, including `additionalPointsDetailed`.
+ */
 function getVaultRewards(tokenizedVault) {
     const upshiftPointRewards = tokenizedVault.rewards?.filter((r) => r.text === 'Upshift Points');
     const sortedPointsMultipliers = upshiftPointRewards?.sort((a, b) => new Date(b.start_datetime).getTime() -
@@ -72,16 +116,31 @@ function getVaultRewards(tokenizedVault) {
             : '',
         multiplier: latestUpshiftPointMultiplier,
         multipliers: upshiftPointsMultipliers,
-        additionalPoints: tokenizedVault.rewards.map((r) => `${r.multiplier !== 1 ? `${r.multiplier}x` : ''} ${r.text}`),
+        additionalPoints: tokenizedVault.rewards.map(getRewardLabel),
+        additionalPointsDetailed: tokenizedVault.rewards.map((r) => ({
+            id: r.id,
+            label: getRewardLabel(r),
+            text: r.text,
+            imgUrl: r.img_url || null,
+            multiplier: r.multiplier,
+        })),
     };
     return rewards;
 }
+/**
+ * Get the idle assets for the vault
+ * @param provider - The provider
+ * @param vaultAddress - The vault address
+ * @param totalAssets - The total assets of the vault
+ * @returns The idle assets
+ */
 async function getIdleAssets(provider, vaultAddress, underlying, totalAssets) {
     const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vaultAddress))?.[0];
     const version = (0, vaults_1.getVaultVersionV2)(tokenizedVault);
     let idleAssets;
     switch (version) {
         case 'evm-0': {
+            // old lending pool
             const globalLoansAmount = await (0, core_1.createContract)({
                 provider,
                 address: vaultAddress,
@@ -105,6 +164,7 @@ async function getIdleAssets(provider, vaultAddress, underlying, totalAssets) {
             break;
         }
         default: {
+            // tokenized vault
             idleAssets = await (0, core_1.createContract)({
                 provider,
                 address: underlying,
@@ -146,6 +206,7 @@ async function getYieldLastRealizedOn(provider, vaultAddress) {
             return 0;
         }
         default: {
+            // Default to V3 ABI which has assetsUpdatedOn
             const contract = (0, core_1.createContract)({
                 provider,
                 address: vaultAddress,
@@ -157,6 +218,10 @@ async function getYieldLastRealizedOn(provider, vaultAddress) {
     }
     return Number(assetsUpdatedOn);
 }
+/**
+ * Format APY data from backend tokenized vault into the unified IVaultApy shape.
+ * Shared across all chain adapters (EVM, Solana, Stellar).
+ */
 function formatVaultApy(tokenizedVault) {
     const { reported_apy, campaign_apy } = tokenizedVault;
     return {
@@ -170,6 +235,10 @@ function formatVaultApy(tokenizedVault) {
         underlyingApy: (reported_apy?.underlying_apy ?? 0) * 100,
     };
 }
+/**
+ * Map strategists from backend subaccounts or hardcoded list.
+ * Shared across all chain adapters.
+ */
 function mapStrategists(tokenizedVault) {
     const hasValidStrategists = tokenizedVault.subaccounts?.length > 0 &&
         tokenizedVault.subaccounts.some((s) => s.strategist !== null);
@@ -191,6 +260,10 @@ function mapStrategists(tokenizedVault) {
             website_url: s.website_url ?? null,
         }));
 }
+/**
+ * Map composability integrations from backend format to vault format.
+ * Shared across all chain adapters.
+ */
 function mapComposabilityIntegrations(tokenizedVault) {
     return (tokenizedVault.composability_integrations?.map((integration) => ({
         name: integration.name,
@@ -202,6 +275,11 @@ function mapComposabilityIntegrations(tokenizedVault) {
         id: integration.id,
     })) || []);
 }
+/**
+ * Convert a backend-reported TVL (whole token units) to a NormalizedBn.
+ * Handles null, undefined, and non-finite values (NaN, Infinity) safely, defaulting to 0.
+ * Shared between non-EVM adapters (Solana, Stellar) and the module-level getVaultTvl handler.
+ */
 function backendTvlToNormalizedBn(tvl, decimals) {
     if (tvl == null) {
         core_1.Logger.log.warn('backendTvlToNormalizedBn', 'TVL is null/undefined, defaulting to 0 — check backend data pipeline', { decimals });
@@ -217,6 +295,10 @@ function backendTvlToNormalizedBn(tvl, decimals) {
     const tvlWhole = BigInt(Math.round(tvl));
     return (0, core_1.toNormalizedBn)(tvlWhole * scaleFactor, decimals);
 }
+/**
+ * Map daily PnL per share from backend Record format to array format.
+ * Shared across non-EVM adapters.
+ */
 function mapDailyPnlPerShare(dailyPnl) {
     if (!dailyPnl)
         return [];
@@ -225,6 +307,11 @@ function mapDailyPnlPerShare(dailyPnl) {
         value,
     }));
 }
+/**
+ * Build a base IVault from backend data, shared across non-EVM adapters (Solana, Stellar).
+ * Chain-specific fields (chainId, version, name, totalAssets, totalSupply, depositAssets, receipt)
+ * must be provided via the overrides parameter.
+ */
 function buildBackendVault(tokenizedVault, overrides) {
     const apy = formatVaultApy(tokenizedVault);
     const rewards = tokenizedVault.rewards?.length
@@ -234,6 +321,7 @@ function buildBackendVault(tokenizedVault, overrides) {
             multiplier: 0,
             multipliers: [],
             additionalPoints: [],
+            additionalPointsDetailed: [],
         };
     return {
         operator: '0x',
@@ -256,8 +344,9 @@ function buildBackendVault(tokenizedVault, overrides) {
         isVisible: tokenizedVault.is_visible || false,
         reserveTarget: tokenizedVault.reserve_target || 0,
         reserveTolerance: tokenizedVault.reserve_tolerance || 0,
+        // Vault decimals are derived from the receipt token decimals for non-EVM vaults
         decimals: overrides.receipt.decimals,
-        maxSupply: (0, core_1.toNormalizedBn)(1000000000),
+        maxSupply: (0, core_1.toNormalizedBn)(1_000_000_000),
         depositCap: null,
         apy,
         rewards,
@@ -331,13 +420,22 @@ function buildBackendVault(tokenizedVault, overrides) {
             : {}),
         showCapFilled: tokenizedVault?.show_cap_filled ?? null,
         apyOverride: tokenizedVault.apy_override ?? null,
+        // Spread chain-specific overrides last so they take precedence
         ...overrides,
     };
 }
+/**
+ * Build the formatted vault
+ * @param provider - The provider
+ * @param tokenizedVault - The tokenized vault
+ * @param contractCalls - The contract calls
+ * @returns The formatted vault
+ */
 async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
     const strategists = mapStrategists(tokenizedVault);
     const operators = tokenizedVault?.operators || [];
     const eoa_operators = tokenizedVault?.eoa_operators || [];
+    // Load offchain props
     const baseProps = {
         chainId: tokenizedVault.chain,
         maxDailyDrawdown: tokenizedVault.max_daily_drawdown || 0,
@@ -392,6 +490,7 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
         isWithdrawalPaused: contractCalls.withdrawalsPaused,
         idleAssets: (0, core_1.toNormalizedBn)(await getIdleAssets(provider, tokenizedVault.address, contractCalls.asset, contractCalls.totalAssets), Number(contractCalls.decimals)),
     };
+    // Version specific logic
     const version = (0, vaults_1.getVaultVersionV2)(tokenizedVault);
     let operator = '0x';
     let depositAssets = [];
@@ -407,6 +506,7 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
     };
     switch (version) {
         case 'sol-0': {
+            // @todo
             break;
         }
         case 'evm-2': {
@@ -431,15 +531,18 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
             depositAssets = [...depositAssets, ...extraAssets];
             totalSupply = contractCalls.totalSupply;
             (maxSupply =
-                (0, core_1.toNormalizedBn)(1000000000000)),
+                (0, core_1.toNormalizedBn)(1_000_000_000_000)), // @hardcoded: no maxSupply on here
                 (receipt = {
                     symbol: tokenizedVault.receipt_token_symbol,
                     address: contractCalls.lpTokenAddress,
                     decimals: contractCalls.decimals,
                 });
+            // @todo: get operator
+            // operator = contractCalls.loansOperator as IAddress;
             break;
         }
         default: {
+            // get idle assets
             depositAssets = [
                 {
                     address: contractCalls.asset,
@@ -462,10 +565,13 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
             break;
         }
     }
+    // Check for adapter configuration and add adapter deposit tokens
     const adapterConfig = (0, core_1.getVaultAdapterConfig)(tokenizedVault.address);
     if (adapterConfig) {
         const allDepositTokens = (0, core_1.getVaultDepositTokens)(tokenizedVault.address, contractCalls.asset);
+        // Build deposit assets array including adapter tokens
         const depositAssetsWithAdapters = await Promise.all(allDepositTokens.map(async (tokenAddress) => {
+            // Skip if already in depositAssets
             if (depositAssets.find((a) => a.address.toLowerCase() === tokenAddress.toLowerCase())) {
                 return null;
             }
@@ -477,6 +583,7 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
                 decimals,
             };
         }));
+        // Add adapter tokens to depositAssets
         depositAssets = [
             ...depositAssets,
             ...depositAssetsWithAdapters.filter((a) => a !== null),
@@ -527,6 +634,17 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
     return result;
 }
 exports.ERC_20_PERMIT_HASH = '0x6e71edae12b1b97f4d1f60370fef10105fa2faae0126114a169c64845d6126c9';
+/**
+ * Generate an ERC2612 permit signature
+ * @param token - The ERC20 token contract address
+ * @param owner - The token owner's address (signer)
+ * @param spender - The address that will be approved to spend (your pool contract)
+ * @param value - The amount to approve
+ * @param deadline - Unix timestamp for when the permit expires
+ * @param signer - The ethers.js Signer (wallet)
+ * @param provider - The ethers.js Provider
+ * @returns The signature components (v, r, s) and deadline
+ */
 async function generatePermitSignature(token, owner, spender, value, deadline, signer, chainId) {
     const tokenContract = (0, core_1.createContract)({
         address: token,
@@ -564,10 +682,14 @@ async function generatePermitSignature(token, owner, spender, value, deadline, s
     }
     if (!matchingDomain) {
         const name = (await tokenContract.name());
+        // Try different domain configurations to find which matches
         const domainConfigs = [
+            // Standard EIP-2612
             { name, version: '1', chainId, verifyingContract: token },
             { name, version: '2', chainId, verifyingContract: token },
+            // Without version
             { name, chainId, verifyingContract: token },
+            // With different salt values (some contracts use this)
             {
                 name,
                 version: '1',
@@ -584,6 +706,8 @@ async function generatePermitSignature(token, owner, spender, value, deadline, s
             }
         }
         if (!matchingDomain) {
+            // If no match, try to get the version from the contract
+            // Some token contracts have a version() method for EIP-2612 domain
             try {
                 const version = await tokenContract.version();
                 matchingDomain = { name, version, chainId, verifyingContract: token };
@@ -600,6 +724,7 @@ async function generatePermitSignature(token, owner, spender, value, deadline, s
             ttl: 60 * 60 * 1000,
         });
     }
+    // EIP-2612 Permit type
     const types = {
         Permit: [
             { name: 'owner', type: 'address' },
@@ -616,7 +741,9 @@ async function generatePermitSignature(token, owner, spender, value, deadline, s
         nonce: Number(nonce),
         deadline: deadline,
     };
+    // Sign the typed data
     const signature = await signer.signTypedData(matchingDomain, types, message);
+    // Split signature into r, s, v
     const sig = ethers_1.ethers.Signature.from(signature);
     return {
         r: sig.r,
@@ -625,6 +752,11 @@ async function generatePermitSignature(token, owner, spender, value, deadline, s
         deadline: deadline,
     };
 }
+/**
+ * Helper to create a deadline (current time + offset in seconds)
+ * @param offsetSeconds - Number of seconds from now (default: 20 minutes)
+ * @returns Unix timestamp
+ */
 function createDeadline(offsetSeconds = 1200) {
     return Math.floor(Date.now() / 1000) + offsetSeconds;
 }