@augustdigital/sdk 8.15.0 → 8.16.1

package/lib/adapters/solana/index.d.ts

@@ -19,7 +19,7 @@ export declare const Solana: {
         isSolanaAddress: typeof import("./utils").isSolanaAddress;
         isSolana: (signature: string) => boolean;
         getProgram: ({ provider, idl, programId, network, }: {
-            idl: any;
+            idl?: any;
             programId?: string;
         } & import("./types").ISolanaConnectionOptions) => import("@coral-xyz/anchor").Program<any>;
         getProvider: ({ connection, publicKey, signTransaction, }: {
@@ -83,9 +83,6 @@ export declare const Solana: {
             "mainnet-beta": {
                 vault: string;
             };
-            testnet: {
-                vault: string;
-            };
             localnet: {
                 vault: string;
             };
@@ -128,7 +125,36 @@ declare class SolanaAdapter {
     get connection(): web3.Connection;
     get provider(): AnchorProvider;
     setWalletProvider(_publicKey: PublicKey | string, signTransaction: (<T extends Transaction | web3.VersionedTransaction>(transaction: T) => Promise<T>) | undefined): void;
-    getProgram(programIdl: any): import("@coral-xyz/anchor").Program<any>;
+    /**
+     * Build an Anchor `Program` bound to this adapter's provider and network.
+     *
+     * The program id is resolved as: explicit `programId` → the `address` carried
+     * by a custom `programIdl` → the canonical deployment for this adapter's
+     * network. A copy of the SDK's bundled `vaultIdl` defers to the network
+     * default (its embedded `address` is a build stamp, not network-aware), so
+     * forwarding it on devnet never silently targets the mainnet program.
+     *
+     * @param programIdl - Anchor IDL to bind. Defaults to the SDK's bundled
+     *   `august_vault` IDL. A custom IDL's `address` is honoured when it differs
+     *   from the bundled build stamp.
+     * @param programId - Base58 program id that overrides both the IDL's address
+     *   and the network default. Use this to target a non-canonical deployment.
+     * @returns An Anchor `Program` for the resolved program id. No RPC is made —
+     *   construction is offline.
+     * @throws {@link AugustValidationError} if no program id can be resolved
+     *   because this adapter's network has no canonical deployment (e.g.
+     *   `testnet`) and neither `programId` nor a custom IDL address was supplied.
+     *
+     * @example
+     * ```ts
+     * // canonical program on the adapter's network
+     * const program = sdk.solana.getProgram();
+     *
+     * // a different deployment, same interface
+     * const legacy = sdk.solana.getProgram(vaultIdl, '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq');
+     * ```
+     */
+    getProgram(programIdl?: any, programId?: string): import("@coral-xyz/anchor").Program<any>;
     getVaultState(vaultProgramId: PublicKey | string, idl: any, vaultAddress?: PublicKey | string): Promise<{
         vaultState: unknown | null;
         depositMintDecimals: number | null;
@@ -193,6 +219,15 @@ declare class SolanaAdapter {
      * @param redeemShares  `bigint` (raw share units) or `number` (UI amount).
      */
     vaultRedeem(vaultProgramId: PublicKey | string, idl: any, publicKey: PublicKey | string, redeemShares: number | bigint, sendTransaction: (transaction: Transaction | web3.VersionedTransaction, connection: Connection, options?: SendTransactionOptions) => Promise<web3.TransactionSignature>, vaultAddress?: PublicKey | string): Promise<any>;
+    /**
+     * Canonical program id for a program type on this adapter's network.
+     *
+     * @param type - Program to look up. Only `'vault'` (august_vault) exists today.
+     * @returns The base58 program id.
+     * @throws {@link AugustValidationError} if the canonical program is not
+     *   deployed on this adapter's network (e.g. `testnet`). Previously an
+     *   unmapped network threw a bare `TypeError`.
+     */
     getProgramId(type: 'vault'): string;
 }
 export default SolanaAdapter;

package/lib/adapters/solana/index.js

@@ -46,6 +46,7 @@ const web3_js_1 = require("@solana/web3.js");
 const utils_1 = require("./utils");
 const vault_actions_1 = require("./vault.actions");
 const constants_1 = require("./constants");
+const core_1 = require("../../core");
 exports.Solana = {
     utils: utils_1.SolanaUtils,
     constants: SolanaConstants,
@@ -108,11 +109,41 @@ class SolanaAdapter {
             });
         }
     }
-    getProgram(programIdl) {
+    /**
+     * Build an Anchor `Program` bound to this adapter's provider and network.
+     *
+     * The program id is resolved as: explicit `programId` → the `address` carried
+     * by a custom `programIdl` → the canonical deployment for this adapter's
+     * network. A copy of the SDK's bundled `vaultIdl` defers to the network
+     * default (its embedded `address` is a build stamp, not network-aware), so
+     * forwarding it on devnet never silently targets the mainnet program.
+     *
+     * @param programIdl - Anchor IDL to bind. Defaults to the SDK's bundled
+     *   `august_vault` IDL. A custom IDL's `address` is honoured when it differs
+     *   from the bundled build stamp.
+     * @param programId - Base58 program id that overrides both the IDL's address
+     *   and the network default. Use this to target a non-canonical deployment.
+     * @returns An Anchor `Program` for the resolved program id. No RPC is made —
+     *   construction is offline.
+     * @throws {@link AugustValidationError} if no program id can be resolved
+     *   because this adapter's network has no canonical deployment (e.g.
+     *   `testnet`) and neither `programId` nor a custom IDL address was supplied.
+     *
+     * @example
+     * ```ts
+     * // canonical program on the adapter's network
+     * const program = sdk.solana.getProgram();
+     *
+     * // a different deployment, same interface
+     * const legacy = sdk.solana.getProgram(vaultIdl, '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq');
+     * ```
+     */
+    getProgram(programIdl, programId) {
         return utils_1.SolanaUtils.getProgram({
             network: this._network,
             provider: this._provider,
             idl: programIdl,
+            programId,
         });
     }
     async getVaultState(vaultProgramId, idl, vaultAddress) {
@@ -238,9 +269,22 @@ class SolanaAdapter {
             sendTransaction,
         });
     }
+    /**
+     * Canonical program id for a program type on this adapter's network.
+     *
+     * @param type - Program to look up. Only `'vault'` (august_vault) exists today.
+     * @returns The base58 program id.
+     * @throws {@link AugustValidationError} if the canonical program is not
+     *   deployed on this adapter's network (e.g. `testnet`). Previously an
+     *   unmapped network threw a bare `TypeError`.
+     */
     getProgramId(type) {
-        const network = this._network;
-        return constants_1.programIds[network][type];
+        const deployment = (0, constants_1.getDeployedProgramIds)(this._network);
+        if (!deployment) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `No canonical august_vault deployment for Solana network '${this._network}'. ` +
+                `Deployed networks: ${Object.keys(constants_1.programIds).join(', ')}.`);
+        }
+        return deployment[type];
     }
 }
 exports.default = SolanaAdapter;

package/lib/adapters/solana/utils.d.ts

@@ -9,7 +9,7 @@ import { isSolanaAddress } from '../../core/helpers/chain-address';
 export { isSolanaAddress };
 declare function isSolana(signature: string): boolean;
 declare function getProgram({ provider, idl, programId, network, }: {
-    idl: any;
+    idl?: any;
     programId?: string;
 } & ISolanaConnectionOptions): Program<any>;
 declare function getBestRpcEndpoint({ endpoint, network, connection, }: ISolanaConnectionOptions): Promise<"http://127.0.0.1:8899" | `https://${string}`>;
@@ -132,9 +132,6 @@ export declare const SolanaUtils: {
         "mainnet-beta": {
             vault: string;
         };
-        testnet: {
-            vault: string;
-        };
         localnet: {
             vault: string;
         };

package/lib/adapters/solana/utils.js

@@ -39,18 +39,32 @@ function isSolana(signature) {
     return (signature.length >= 80 && signature.length <= 100);
 }
 function getProgram({ provider, idl, programId, network, }) {
-    if (!idl) {
-        return new anchor_1.Program(constants_1.vaultIdl, provider);
+    const baseIdl = idl ?? constants_1.vaultIdl;
+    // Precedence: explicit `programId` → a custom IDL's `address` → the network
+    // default → the bundled IDL's embedded `address`.
+    //
+    // The custom-address check compares by VALUE, not reference. Keying off
+    // `idl === vaultIdl` broke for a structurally-identical-but-not-reference-equal
+    // copy (second bundle instance, or JSON round-tripped), silently retargeting
+    // devnet callers at mainnet. Every copy carries the same build stamp, so it
+    // still defers to the network default — but a genuinely custom IDL is honoured.
+    const suppliedAddress = typeof baseIdl?.address === 'string' && baseIdl.address !== constants_1.vaultIdl.address
+        ? baseIdl.address
+        : undefined;
+    const explicitId = programId ?? suppliedAddress;
+    if (explicitId) {
+        return new anchor_1.Program({ ...baseIdl, address: explicitId }, provider);
     }
-    // If programId is provided, create a modified IDL with the correct address
-    if (programId) {
-        const modifiedIdl = {
-            ...idl,
-            address: programId,
-        };
-        return new anchor_1.Program(modifiedIdl, provider);
+    if (network) {
+        const networkDefault = (0, constants_1.getDeployedProgramIds)(network)?.vault;
+        if (!networkDefault) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `No canonical august_vault deployment for Solana network '${network}'. ` +
+                `Deployed networks: ${Object.keys(constants_1.programIds).join(', ')}. ` +
+                `Pass an explicit \`programId\` (or an IDL carrying the target \`address\`) to target a program on this network.`);
+        }
+        return new anchor_1.Program({ ...baseIdl, address: networkDefault }, provider);
     }
-    return new anchor_1.Program(idl, provider);
+    return new anchor_1.Program(baseIdl, provider);
 }
 // ============================================================================
 // SOLANA PROVIDERS

package/lib/core/analytics/method-taxonomy.js

@@ -77,6 +77,10 @@ exports.METHOD_CATEGORIES = {
     fetchUserTokenBalance: 'read.solana',
     fetchUserShareBalance: 'read.solana',
     fetchUserShareBalanceRaw: 'read.solana',
+    // Both are offline resolvers (no RPC) — classified so the partner dashboard
+    // sees program-targeting calls instead of dropping them into 'unknown'.
+    getProgram: 'read.solana',
+    getProgramId: 'read.solana',
     // submitTransaction broadcasts a signed Soroban tx — it mutates on-chain
     // state and belongs in the write bucket even though Stellar adapter call
     // shape mirrors the read helpers (returns a hash, takes signed XDR).

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "8.15.0";
+export declare const SDK_VERSION = "8.16.1";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '8.15.0';
+exports.SDK_VERSION = '8.16.1';
 //# sourceMappingURL=version.js.map

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

@@ -339,6 +339,31 @@ export interface PnlHistoryConsistencyParams {
  * ```
  */
 export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawnRaw, currentPositionRaw, }: PnlHistoryConsistencyParams): void;
+/**
+ * Sum a wallet's per-asset deposits into the vault's own decimals, at face
+ * value — 1 unit of any deposited asset is treated as 1 unit of the vault's
+ * reporting currency, with no live price conversion.
+ *
+ * Used by {@link getVaultUserLifetimePnl} for `totalDeposited`. Pre-deposit
+ * multi-asset vaults only accept dollar-pegged stablecoins (USDC, USDT, DAI,
+ * USDS, RLUSD, etc.) into a dollar-denominated vault, so face value is a
+ * reasonable stand-in for USD value. This intentionally does NOT re-quote
+ * through a live price oracle: doing so priced a historical deposit at
+ * today's market rate, so `totalDeposited` (and lifetimePnl) drifted between
+ * calls purely from stablecoin peg noise, and approximately re-inflated
+ * deposits back toward face value — which silently excluded the vault's
+ * entry fee from PnL. The fee is money the user actually paid, so PnL must
+ * be computed net of it.
+ *
+ * @param depositsByAsset - Raw deposited amount per asset, keyed by
+ *   lowercased asset address (or `'default'` / `'lz-default'` for
+ *   single-asset / cross-chain rows).
+ * @param assetDecimals - Decimals for each key in `depositsByAsset`.
+ * @param vaultDecimals - The vault's own decimals — the target scale every
+ *   asset is rescaled to.
+ * @returns Total deposited, in raw base units at `vaultDecimals`.
+ */
+export declare function sumDepositsAtFaceValue(depositsByAsset: Map<string, bigint>, assetDecimals: Map<string, number>, vaultDecimals: number): bigint;
 /**
  * Calculate lifetime PnL for a user in a specific vault.
  *
@@ -347,6 +372,15 @@ export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits,
  * 2. Fetch user's current assets (balanceOf * sharePrice via convertToAssets)
  * 3. Calculate PnL = assets withdrawn + current assets - assets deposited
  *
+ * `totalDeposited` is the face value of what the user actually paid in
+ * (each deposited asset's raw amount, rescaled to the vault's decimals — no
+ * live price conversion), so any entry/exit fee the vault charges is
+ * automatically counted as a cost against PnL rather than excluded from it.
+ * Pre-deposit multi-asset vaults are assumed to only accept dollar-pegged
+ * stablecoins into a dollar-denominated vault; a vault accepting a
+ * non-pegged deposit asset would need deposit-time price conversion, which
+ * this function does not perform.
+ *
  * @param vault - Vault contract address
  * @param wallet - User wallet address
  * @param options - RPC configuration and service options

package/lib/modules/vaults/getters.js

@@ -54,6 +54,7 @@ exports.registerUserForPoints = registerUserForPoints;
 exports.fetchPointsLeaderboard = fetchPointsLeaderboard;
 exports.getYieldLastRealizedOn = getYieldLastRealizedOn;
 exports.assertPnlHistoryConsistent = assertPnlHistoryConsistent;
+exports.sumDepositsAtFaceValue = sumDepositsAtFaceValue;
 exports.getVaultUserLifetimePnl = getVaultUserLifetimePnl;
 exports.getVaultPnl = getVaultPnl;
 exports.getVaultHistoricalTimeseries = getVaultHistoricalTimeseries;
@@ -1898,6 +1899,46 @@ function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawn
         throw new errors_1.AugustHistoryUnavailableError(`#getVaultUserLifetimePnl::${vault}::${wallet}:transaction history unavailable — a live position exists but no deposits or withdrawals were indexed, so lifetime PnL cannot be computed without over-reporting the entire position as profit`, { context: { vault, wallet } });
     }
 }
+/**
+ * Sum a wallet's per-asset deposits into the vault's own decimals, at face
+ * value — 1 unit of any deposited asset is treated as 1 unit of the vault's
+ * reporting currency, with no live price conversion.
+ *
+ * Used by {@link getVaultUserLifetimePnl} for `totalDeposited`. Pre-deposit
+ * multi-asset vaults only accept dollar-pegged stablecoins (USDC, USDT, DAI,
+ * USDS, RLUSD, etc.) into a dollar-denominated vault, so face value is a
+ * reasonable stand-in for USD value. This intentionally does NOT re-quote
+ * through a live price oracle: doing so priced a historical deposit at
+ * today's market rate, so `totalDeposited` (and lifetimePnl) drifted between
+ * calls purely from stablecoin peg noise, and approximately re-inflated
+ * deposits back toward face value — which silently excluded the vault's
+ * entry fee from PnL. The fee is money the user actually paid, so PnL must
+ * be computed net of it.
+ *
+ * @param depositsByAsset - Raw deposited amount per asset, keyed by
+ *   lowercased asset address (or `'default'` / `'lz-default'` for
+ *   single-asset / cross-chain rows).
+ * @param assetDecimals - Decimals for each key in `depositsByAsset`.
+ * @param vaultDecimals - The vault's own decimals — the target scale every
+ *   asset is rescaled to.
+ * @returns Total deposited, in raw base units at `vaultDecimals`.
+ */
+function sumDepositsAtFaceValue(depositsByAsset, assetDecimals, vaultDecimals) {
+    let total = BigInt(0);
+    for (const [assetAddress, rawAmount] of depositsByAsset) {
+        const assetDec = assetDecimals.get(assetAddress) ?? vaultDecimals;
+        if (assetDec === vaultDecimals) {
+            total += rawAmount;
+        }
+        else if (assetDec > vaultDecimals) {
+            total += rawAmount / BigInt(10 ** (assetDec - vaultDecimals));
+        }
+        else {
+            total += rawAmount * BigInt(10 ** (vaultDecimals - assetDec));
+        }
+    }
+    return total;
+}
 /**
  * Calculate lifetime PnL for a user in a specific vault.
  *
@@ -1906,6 +1947,15 @@ function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawn
  * 2. Fetch user's current assets (balanceOf * sharePrice via convertToAssets)
  * 3. Calculate PnL = assets withdrawn + current assets - assets deposited
  *
+ * `totalDeposited` is the face value of what the user actually paid in
+ * (each deposited asset's raw amount, rescaled to the vault's decimals — no
+ * live price conversion), so any entry/exit fee the vault charges is
+ * automatically counted as a cost against PnL rather than excluded from it.
+ * Pre-deposit multi-asset vaults are assumed to only accept dollar-pegged
+ * stablecoins into a dollar-denominated vault; a vault accepting a
+ * non-pegged deposit asset would need deposit-time price conversion, which
+ * this function does not perform.
+ *
  * @param vault - Vault contract address
  * @param wallet - User wallet address
  * @param options - RPC configuration and service options
@@ -2069,32 +2119,7 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                 assetDecimals.set(assetAddress, dec);
             }
         }));
-        // Store deposits as a map: assetAddress -> INormalizedNumber (with correct decimals)
-        const totalDepositedRaw = new Map();
-        for (const [assetAddress, rawAmount] of depositsByAsset) {
-            const assetDec = assetDecimals.get(assetAddress) ?? decimals;
-            totalDepositedRaw.set(assetAddress, (0, core_1.toNormalizedBn)(rawAmount, assetDec));
-        }
-        // Fetch USD prices for each unique deposit asset in parallel
-        const assetPrices = new Map();
-        if (tokenizedVault.chain) {
-            await Promise.all(Array.from(depositsByAsset.keys()).map(async (assetAddress) => {
-                if (assetAddress === 'default' || assetAddress === 'lz-default') {
-                    // Will use underlying asset price later
-                    assetPrices.set(assetAddress, 0);
-                }
-                else {
-                    try {
-                        const price = await (0, core_1.fetchTokenPriceByAddress)(assetAddress, tokenizedVault.chain, options?.headers);
-                        assetPrices.set(assetAddress, price);
-                    }
-                    catch (error) {
-                        core_1.Logger.log.warn('getVaultUserLifetimePnl:fetchAssetPrice', `Failed to fetch price for ${assetAddress}: ${error}`);
-                        assetPrices.set(assetAddress, 0);
-                    }
-                }
-            }));
-        }
+        const totalDepositedNativeRaw = sumDepositsAtFaceValue(depositsByAsset, assetDecimals, decimals);
         const { underlyingTokenSymbol, underlyingAssetAddress } = await underlyingSymbolPromise;
         // Calculate current position value and fetch price in parallel
         let currentPositionValue = (0, core_1.toNormalizedBn)(0, decimals);
@@ -2246,15 +2271,12 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         if (tokenPriceUsd <= 0) {
             core_1.Logger.log.warn('getVaultUserLifetimePnl:tokenPrice', `Invalid underlying token price: ${tokenPriceUsd}, using fallback of 1`);
         }
-        // Sum all deposited amounts in USD using each asset's own price
-        let totalDepositedUsd = 0;
-        for (const [assetAddress, normalizedAmount] of totalDepositedRaw) {
-            // Use the asset-specific price, or underlying price for 'default'
-            const assetPrice = assetAddress === 'default' || assetAddress === 'lz-default'
-                ? effectiveTokenPrice
-                : assetPrices.get(assetAddress) || effectiveTokenPrice;
-            totalDepositedUsd += Number(normalizedAmount.normalized) * assetPrice;
-        }
+        // totalDeposited is already in the vault's own decimals (face value,
+        // computed above) — convert to USD with the same underlying price used
+        // for the other two legs below, so all three legs share one conversion
+        // factor instead of drifting independently against each other.
+        const totalDeposited = (0, core_1.toNormalizedBn)(totalDepositedNativeRaw, decimals);
+        const totalDepositedUsd = Number(totalDeposited.normalized) * effectiveTokenPrice;
         const totalWithdrawnUsd = Number(totalWithdrawn.normalized) * effectiveTokenPrice;
         const currentPositionValueUsd = Number(currentPositionValue.normalized) * effectiveTokenPrice;
         // Calculate lifetimePnl in USD first (since deposits may be in different tokens with different prices)
@@ -2262,12 +2284,6 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         // Use BigInt-scaled arithmetic to minimize precision loss when converting USD to native
         const scaleFactor = BigInt(10 ** 18); // High precision scale
         const tokenPriceScaled = BigInt(Math.round(effectiveTokenPrice * Number(scaleFactor)));
-        // Convert totalDepositedUsd to native units for backwards compatibility
-        const totalDepositedUsdScaled = BigInt(Math.round(totalDepositedUsd * Number(scaleFactor)));
-        const totalDepositedNativeRaw = tokenPriceScaled > BigInt(0)
-            ? (totalDepositedUsdScaled * BigInt(10 ** decimals)) / tokenPriceScaled
-            : BigInt(0);
-        const totalDeposited = (0, core_1.toNormalizedBn)(totalDepositedNativeRaw, decimals);
         // Convert lifetimePnlUsd to native units
         const lifetimePnlUsdScaled = BigInt(Math.round(lifetimePnlUsd * Number(scaleFactor)));
         const lifetimePnlRaw = tokenPriceScaled > BigInt(0)

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

@@ -1,4 +1,4 @@
-import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault } from '../../types';
+import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault, IVaultFreshness } from '../../types';
 import { ethers } from 'ethers';
 import type { WalletClient } from 'viem';
 /**
@@ -59,6 +59,24 @@ export declare function getYieldLastRealizedOn(provider: IContractRunner, vaultA
  * Shared across all chain adapters (EVM, Solana, Stellar).
  */
 export declare function formatVaultApy(tokenizedVault: ITokenizedVault): IVault['apy'];
+/**
+ * Map the backend `freshness` object onto the camelCased {@link IVaultFreshness}
+ * shape carried on `IVault`. Shared across all chain adapters (EVM, Solana,
+ * Stellar) so every surface reports provenance identically.
+ *
+ * Each of the three stamps is passed through independently: a missing member
+ * becomes `null` and is never defaulted from one of the others. That is the point
+ * of the object — `apy_computed_at` and `share_ratio_snapshot_at` describe two
+ * different pipelines, and collapsing them would erase the very staleness signal
+ * (snapshot newer than APY) the field exists to expose.
+ *
+ * @param tokenizedVault - Backend tokenized-vault payload. `freshness` is absent on
+ *   responses predating the backend change, and may be explicitly null.
+ * @returns The mapped freshness object, or `null` when the backend reported none.
+ *   Values are the backend's RFC 3339 UTC strings verbatim — no reformatting, so
+ *   the trailing `Z` is preserved.
+ */
+export declare function mapVaultFreshness(tokenizedVault: ITokenizedVault | undefined | null): IVaultFreshness | null;
 /**
  * Map strategists from backend subaccounts or hardcoded list.
  * Shared across all chain adapters.

package/lib/modules/vaults/utils.js

@@ -6,6 +6,7 @@ exports.getVaultRewards = getVaultRewards;
 exports.getIdleAssets = getIdleAssets;
 exports.getYieldLastRealizedOn = getYieldLastRealizedOn;
 exports.formatVaultApy = formatVaultApy;
+exports.mapVaultFreshness = mapVaultFreshness;
 exports.mapStrategists = mapStrategists;
 exports.mapComposabilityIntegrations = mapComposabilityIntegrations;
 exports.backendTvlToNormalizedBn = backendTvlToNormalizedBn;
@@ -235,6 +236,33 @@ function formatVaultApy(tokenizedVault) {
         underlyingApy: (reported_apy?.underlying_apy ?? 0) * 100,
     };
 }
+/**
+ * Map the backend `freshness` object onto the camelCased {@link IVaultFreshness}
+ * shape carried on `IVault`. Shared across all chain adapters (EVM, Solana,
+ * Stellar) so every surface reports provenance identically.
+ *
+ * Each of the three stamps is passed through independently: a missing member
+ * becomes `null` and is never defaulted from one of the others. That is the point
+ * of the object — `apy_computed_at` and `share_ratio_snapshot_at` describe two
+ * different pipelines, and collapsing them would erase the very staleness signal
+ * (snapshot newer than APY) the field exists to expose.
+ *
+ * @param tokenizedVault - Backend tokenized-vault payload. `freshness` is absent on
+ *   responses predating the backend change, and may be explicitly null.
+ * @returns The mapped freshness object, or `null` when the backend reported none.
+ *   Values are the backend's RFC 3339 UTC strings verbatim — no reformatting, so
+ *   the trailing `Z` is preserved.
+ */
+function mapVaultFreshness(tokenizedVault) {
+    const freshness = tokenizedVault?.freshness;
+    if (!freshness)
+        return null;
+    return {
+        apyComputedAt: freshness.apy_computed_at ?? null,
+        shareRatioSnapshotAt: freshness.share_ratio_snapshot_at ?? null,
+        cachedAt: freshness.cached_at ?? null,
+    };
+}
 /**
  * Map strategists from backend subaccounts or hardcoded list.
  * Shared across all chain adapters.
@@ -398,6 +426,7 @@ function buildBackendVault(tokenizedVault, overrides) {
         composabilityIntegrations: mapComposabilityIntegrations(tokenizedVault),
         strategists: mapStrategists(tokenizedVault),
         cachedAt: tokenizedVault.cached_at ?? null,
+        freshness: mapVaultFreshness(tokenizedVault),
         dailyPnlPerShare: mapDailyPnlPerShare(tokenizedVault.daily_pnl_per_share),
         enabled_historical_price_horizons: tokenizedVault.enabled_historical_price_horizons || [],
         latest_reported_tvl: tokenizedVault.latest_reported_tvl,
@@ -615,6 +644,7 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
         defaultApyHorizon: tokenizedVault?.default_apy_horizon ?? null,
         latest_reported_tvl: tokenizedVault?.latest_reported_tvl,
         cachedAt: tokenizedVault?.cached_at ?? null,
+        freshness: mapVaultFreshness(tokenizedVault),
         showCapFilled: tokenizedVault?.show_cap_filled ?? null,
         apyOverride: tokenizedVault?.apy_override ?? null,
     };