@augustdigital/sdk 9.12.0 → 9.13.1

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 = "9.12.0";
+export declare const SDK_VERSION = "9.13.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 = '9.12.0';
+exports.SDK_VERSION = '9.13.1';
 //# sourceMappingURL=version.js.map

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

@@ -860,9 +860,21 @@ export declare function getVaultUserLifetimePnl({ vault, wallet, options, }: {
  * Calculate PnL for a vault (vault-level, not user-specific).
  * Returns the vault's overall profit and loss across all users.
  *
+ * Sums, over the vault's whole history, each day's change in assets per share
+ * times that day's total shares, then prices the result at the receipt
+ * token's current USD price. The daily history comes from
+ * `GET /tokenized_vault/{vault}/historical-timeseries`, the replacement for the
+ * deprecated `load_snapshots` flag on the vault read.
+ *
+ * Network: one backend vault read, one timeseries read and one price read.
+ *
  * @param vault - Vault contract address
  * @param options - RPC configuration and service options
- * @returns Vault PnL in USD and notional value
+ * @returns Vault PnL in the deposit asset (`totalPnl`) and in USD (`pnlUsd`).
+ *   Both are zero for a vault with no recorded history. `pnlUsd` is also zero
+ *   when the receipt token price cannot be fetched.
+ * @throws Error when `vault` is missing, is a Stellar vault, is not an
+ *   address, or the vault or its history cannot be read.
  */
 export declare function getVaultPnl({ vault, options, }: {
     vault: IAddress;

package/lib/modules/vaults/getters.js

@@ -3445,9 +3445,21 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
  * Calculate PnL for a vault (vault-level, not user-specific).
  * Returns the vault's overall profit and loss across all users.
  *
+ * Sums, over the vault's whole history, each day's change in assets per share
+ * times that day's total shares, then prices the result at the receipt
+ * token's current USD price. The daily history comes from
+ * `GET /tokenized_vault/{vault}/historical-timeseries`, the replacement for the
+ * deprecated `load_snapshots` flag on the vault read.
+ *
+ * Network: one backend vault read, one timeseries read and one price read.
+ *
  * @param vault - Vault contract address
  * @param options - RPC configuration and service options
- * @returns Vault PnL in USD and notional value
+ * @returns Vault PnL in the deposit asset (`totalPnl`) and in USD (`pnlUsd`).
+ *   Both are zero for a vault with no recorded history. `pnlUsd` is also zero
+ *   when the receipt token price cannot be fetched.
+ * @throws Error when `vault` is missing, is a Stellar vault, is not an
+ *   address, or the vault or its history cannot be read.
  */
 async function getVaultPnl({ vault, options, }) {
     try {
@@ -3456,60 +3468,33 @@ async function getVaultPnl({ vault, options, }) {
         (0, utils_3.assertNotStellar)(vault, 'Vault PnL');
         if (!(0, ethers_1.isAddress)(vault))
             throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
-        // Get vault data
-        const vaultData = await getVault({
-            vault,
-            loans: false,
-            allocations: false,
-            options,
-        });
+        // The vault row only supplies decimals, chain and receipt token, so skip
+        // its subaccounts and snapshots. 3650 days reads the full history, as
+        // `fetchShareRatios` does.
+        const [vaultData, { data: history }] = await Promise.all([
+            getVault({
+                vault,
+                loans: false,
+                allocations: false,
+                options,
+                loadSubaccounts: false,
+                loadSnapshots: false,
+            }),
+            (0, core_1.fetchVaultHistoricalTimeseries)(vault, 3650, options?.headers),
+        ]);
         if (!vaultData) {
             throw new Error(`Vault ${vault} not found`);
         }
-        // Check if vault has daily_pnl_per_share and historical_snapshots
-        if (!vaultData.dailyPnlPerShare ||
-            !Array.isArray(vaultData.dailyPnlPerShare) ||
-            vaultData.dailyPnlPerShare.length === 0) {
-            return {
-                totalPnl: (0, core_1.toNormalizedBn)(0, vaultData.decimals),
-                pnlUsd: 0,
-            };
-        }
-        if (!vaultData.historical_snapshots ||
-            !Array.isArray(vaultData.historical_snapshots) ||
-            vaultData.historical_snapshots.length === 0) {
-            return {
-                totalPnl: (0, core_1.toNormalizedBn)(0, vaultData.decimals),
-                pnlUsd: 0,
-            };
-        }
         const decimals = vaultData.decimals;
-        // Filter out dates with zero PnL
-        const validDailyPnl = vaultData.dailyPnlPerShare.filter((dayData) => dayData.value && dayData.value !== 0);
-        // Create a map of historical_snapshots by date (YYYY-MM-DD) for quick lookup
-        const snapshotsByDate = new Map();
-        vaultData.historical_snapshots.forEach((snapshot) => {
-            const snapshotDate = new Date(snapshot.snapshot_datetime);
-            const dateKey = snapshotDate.toISOString().split('T')[0]; // YYYY-MM-DD
-            snapshotsByDate.set(dateKey, snapshot);
-        });
-        // Calculate PnL for each day using historical_snapshots
+        // `daily_pnl` is the day's change in assets per share. It is zero on the
+        // first day and on forward-filled (`missing`) days, so those add nothing.
         let totalPnlRaw = BigInt(0);
-        validDailyPnl.forEach((dayData) => {
-            const dayTimestamp = dayData.timestamp;
-            const dailyPnlPerShare = dayData.value;
-            // Get date key (YYYY-MM-DD) from timestamp
-            const dayDate = new Date(dayTimestamp);
-            const dateKey = dayDate.toISOString().split('T')[0];
-            // Find matching snapshot for this date
-            const snapshot = snapshotsByDate.get(dateKey);
-            if (!snapshot?.total_shares) {
-                core_1.Logger.log.warn('getVaultPnl:snapshotNotFound', `No snapshot found for date ${dateKey}`);
+        Object.values(history ?? {}).forEach((day) => {
+            if (!day.daily_pnl || !day.total_shares)
                 return;
-            }
             // Convert normalized numbers to BigInt using toNormalizedBn's normalized string
-            const dailyPnlNorm = (0, core_1.toNormalizedBn)(dailyPnlPerShare, decimals);
-            const totalSharesNorm = (0, core_1.toNormalizedBn)(snapshot.total_shares, decimals);
+            const dailyPnlNorm = (0, core_1.toNormalizedBn)(day.daily_pnl, decimals);
+            const totalSharesNorm = (0, core_1.toNormalizedBn)(day.total_shares, decimals);
             // Convert normalized strings to BigInt (split, pad fraction, combine) - all inline
             const [dailyWhole = '0', dailyFrac = ''] = dailyPnlNorm.normalized.split('.');
             const dailyPnlPerShareScaled = BigInt(dailyWhole + (dailyFrac || '').padEnd(decimals, '0').slice(0, decimals));
@@ -3520,6 +3505,10 @@ async function getVaultPnl({ vault, options, }) {
             const dayPnlRaw = (dailyPnlPerShareScaled * totalSharesScaled) / BigInt(10 ** decimals);
             totalPnlRaw += dayPnlRaw;
         });
+        // No history (or no PnL in it) prices to zero, so skip the price read.
+        if (totalPnlRaw === BigInt(0)) {
+            return { totalPnl: (0, core_1.toNormalizedBn)(0, decimals), pnlUsd: 0 };
+        }
         // Convert totalPnlRaw (BigInt) to normalized number using toNormalizedBn
         const totalPnl = (0, core_1.toNormalizedBn)(totalPnlRaw, decimals);
         const totalPnlNormalized = Number(totalPnl.normalized);

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

@@ -82,6 +82,14 @@ export declare function formatVaultApy(tokenizedVault: ITokenizedVault): IVault[
  *   the trailing `Z` is preserved.
  */
 export declare function mapVaultFreshness(tokenizedVault: ITokenizedVault | undefined | null): IVaultFreshness | null;
+/**
+ * Map a wrapper vault's link to the vault it wraps.
+ *
+ * @param tokenizedVault - Backend tokenized-vault payload.
+ * @returns The underlying vault address (casing preserved) and chain id, both
+ *   null for a non-wrapper vault. A chain id without an address is dropped.
+ */
+export declare function mapUnderlyingVault(tokenizedVault: ITokenizedVault | undefined | null): Pick<IVault, 'underlyingVaultAddress' | 'underlyingChainId'>;
 /**
  * Map strategists from backend subaccounts or hardcoded list.
  * Shared across all chain adapters.

package/lib/modules/vaults/utils.js

@@ -7,6 +7,7 @@ exports.getIdleAssets = getIdleAssets;
 exports.getYieldLastRealizedOn = getYieldLastRealizedOn;
 exports.formatVaultApy = formatVaultApy;
 exports.mapVaultFreshness = mapVaultFreshness;
+exports.mapUnderlyingVault = mapUnderlyingVault;
 exports.mapStrategists = mapStrategists;
 exports.mapComposabilityIntegrations = mapComposabilityIntegrations;
 exports.backendTvlToNormalizedBn = backendTvlToNormalizedBn;
@@ -268,6 +269,22 @@ function mapVaultFreshness(tokenizedVault) {
         cachedAt: freshness.cached_at ?? null,
     };
 }
+/**
+ * Map a wrapper vault's link to the vault it wraps.
+ *
+ * @param tokenizedVault - Backend tokenized-vault payload.
+ * @returns The underlying vault address (casing preserved) and chain id, both
+ *   null for a non-wrapper vault. A chain id without an address is dropped.
+ */
+function mapUnderlyingVault(tokenizedVault) {
+    const address = tokenizedVault?.underlying_vault_address;
+    if (!address)
+        return { underlyingVaultAddress: null, underlyingChainId: null };
+    return {
+        underlyingVaultAddress: address,
+        underlyingChainId: tokenizedVault?.underlying_chain ?? null,
+    };
+}
 /**
  * Map strategists from backend subaccounts or hardcoded list.
  * Shared across all chain adapters.
@@ -437,6 +454,7 @@ function buildBackendVault(tokenizedVault, overrides) {
         dailyPnlPerShare: mapDailyPnlPerShare(tokenizedVault.daily_pnl_per_share),
         enabled_historical_price_horizons: tokenizedVault.enabled_historical_price_horizons || [],
         latest_reported_tvl: tokenizedVault.latest_reported_tvl,
+        ...mapUnderlyingVault(tokenizedVault),
         defaultApyHorizon: tokenizedVault.default_apy_horizon,
         ...(tokenizedVault.instant_redeem_config
             ? {
@@ -659,6 +677,7 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
         enabled_historical_price_horizons: tokenizedVault?.enabled_historical_price_horizons,
         defaultApyHorizon: tokenizedVault?.default_apy_horizon ?? null,
         latest_reported_tvl: tokenizedVault?.latest_reported_tvl,
+        ...mapUnderlyingVault(tokenizedVault),
         cachedAt: tokenizedVault?.cached_at ?? null,
         freshness: mapVaultFreshness(tokenizedVault),
         showCapFilled: tokenizedVault?.show_cap_filled ?? null,

package/lib/sdk.d.ts

@@ -20178,9 +20178,21 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                                                      * Calculate PnL for a vault (vault-level, not user-specific).
                                                                      * Returns the vault's overall profit and loss across all users.
                                                                      *
+                                                                     * Sums, over the vault's whole history, each day's change in assets per share
+                                                                     * times that day's total shares, then prices the result at the receipt
+                                                                     * token's current USD price. The daily history comes from
+                                                                     * `GET /tokenized_vault/{vault}/historical-timeseries`, the replacement for the
+                                                                     * deprecated `load_snapshots` flag on the vault read.
+                                                                     *
+                                                                     * Network: one backend vault read, one timeseries read and one price read.
+                                                                     *
                                                                      * @param vault - Vault contract address
                                                                      * @param options - RPC configuration and service options
-                                                                     * @returns Vault PnL in USD and notional value
+                                                                     * @returns Vault PnL in the deposit asset (`totalPnl`) and in USD (`pnlUsd`).
+                                                                     *   Both are zero for a vault with no recorded history. `pnlUsd` is also zero
+                                                                     *   when the receipt token price cannot be fetched.
+                                                                     * @throws Error when `vault` is missing, is a Stellar vault, is not an
+                                                                     *   address, or the vault or its history cannot be read.
                                                                      */
                                                                     export declare function getVaultPnl({ vault, options, }: {
                                                                         vault: IAddress;
@@ -24276,6 +24288,14 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                                                              enabled_historical_price_horizons?: number[];
                                                                              defaultApyHorizon?: 7 | 30 | null;
                                                                              latest_reported_tvl?: number | null;
+                                                                             /**
+                                                                              * Wrapper vaults only: the vault this one wraps, which holds the assets. A
+                                                                              * wrapper's own on-chain `totalAssets` reads 0, so its TVL is the underlying
+                                                                              * vault's. Null on a non-wrapper vault. Address casing is preserved verbatim.
+                                                                              */
+                                                                             underlyingVaultAddress?: VaultAddress | null;
+                                                                             /** Chain id of {@link IVault.underlyingVaultAddress}; null on a non-wrapper vault. */
+                                                                             underlyingChainId?: number | null;
                                                                              cachedAt?: string | null;
                                                                              /**
                                                                               * Provenance timestamps for the vault's server-side data — when its APY was last
@@ -25621,6 +25641,15 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                                                              website_url: string;
                                                                          }[];
 
+                                                                         /**
+                                                                          * Map a wrapper vault's link to the vault it wraps.
+                                                                          *
+                                                                          * @param tokenizedVault - Backend tokenized-vault payload.
+                                                                          * @returns The underlying vault address (casing preserved) and chain id, both
+                                                                          *   null for a non-wrapper vault. A chain id without an address is dropped.
+                                                                          */
+                                                                         export declare function mapUnderlyingVault(tokenizedVault: ITokenizedVault | undefined | null): Pick<IVault, 'underlyingVaultAddress' | 'underlyingChainId'>;
+
                                                                          /**
                                                                           * Map the backend `freshness` object onto the camelCased {@link IVaultFreshness}
                                                                           * shape carried on `IVault`. Shared across all chain adapters (EVM, Solana,

package/lib/types/vaults.d.ts

@@ -383,6 +383,14 @@ export interface IVault {
     enabled_historical_price_horizons?: number[];
     defaultApyHorizon?: 7 | 30 | null;
     latest_reported_tvl?: number | null;
+    /**
+     * Wrapper vaults only: the vault this one wraps, which holds the assets. A
+     * wrapper's own on-chain `totalAssets` reads 0, so its TVL is the underlying
+     * vault's. Null on a non-wrapper vault. Address casing is preserved verbatim.
+     */
+    underlyingVaultAddress?: VaultAddress | null;
+    /** Chain id of {@link IVault.underlyingVaultAddress}; null on a non-wrapper vault. */
+    underlyingChainId?: number | null;
     cachedAt?: string | null;
     /**
      * Provenance timestamps for the vault's server-side data — when its APY was last

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augustdigital/sdk",
-  "version": "9.12.0",
+  "version": "9.13.1",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [