@augustdigital/sdk 8.14.0 → 8.15.0

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.14.0";
+export declare const SDK_VERSION = "8.15.0";

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.14.0';
+exports.SDK_VERSION = '8.15.0';
 //# sourceMappingURL=version.js.map

package/lib/core/errors/index.d.ts

@@ -15,7 +15,7 @@
  * ```
  */
 /** Stable error codes attached to SDK errors. */
-export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'UNKNOWN';
+export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'HISTORY_UNAVAILABLE' | 'UNKNOWN';
 /** Options accepted by every SDK error constructor. */
 export interface AugustErrorOptions {
     /** Original error preserved for stack-trace chaining. */
@@ -72,5 +72,43 @@ export declare class AugustServerError extends AugustSDKError {
     constructor(status: number, message: string, options?: AugustErrorOptions);
     toJSON(): Record<string, unknown>;
 }
+/**
+ * Transaction/position history required to compute a value could not be
+ * retrieved or was empty, so the computed result would be wrong rather than
+ * merely missing.
+ *
+ * Motivation — the 2026-07-09 lifetime-PnL over-inflation incident. Lifetime
+ * PnL is `currentPosition + totalWithdrawn - totalDeposited`. Every
+ * history-fetch failure (deleted subgraph, subgraph deployed against the wrong
+ * ABI, missing archive backfill, deposits indexed on a different
+ * chain/contract) collapses the deposit/withdrawal history to empty. With
+ * `deposited = 0` and `withdrawn = 0` but a live on-chain `position > 0`, the
+ * formula degenerates to reporting the entire position as profit. Throwing this
+ * typed error makes that unrecoverable state fail loudly instead of returning
+ * an inflated number that looks plausible.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.vaults.getVaultUserLifetimePnl({ vault, wallet, options });
+ * } catch (err) {
+ *   if (err instanceof AugustHistoryUnavailableError) {
+ *     // History backfill is broken — surface "temporarily unavailable",
+ *     // never a fabricated PnL number.
+ *     showUnavailable(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+export declare class AugustHistoryUnavailableError extends AugustSDKError {
+    /**
+     * @param message - Human-readable description of the missing history. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   `{ vault, wallet }` (or equivalent) identifiers that scope the failure.
+     */
+    constructor(message: string, options?: AugustErrorOptions);
+}
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 export declare function isAugustSDKError(err: unknown): err is AugustSDKError;

package/lib/core/errors/index.js

@@ -16,7 +16,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
+exports.AugustHistoryUnavailableError = exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
 exports.isAugustSDKError = isAugustSDKError;
 /** Base class for all SDK errors. */
 class AugustSDKError extends Error {
@@ -131,6 +131,48 @@ class AugustServerError extends AugustSDKError {
     }
 }
 exports.AugustServerError = AugustServerError;
+/**
+ * Transaction/position history required to compute a value could not be
+ * retrieved or was empty, so the computed result would be wrong rather than
+ * merely missing.
+ *
+ * Motivation — the 2026-07-09 lifetime-PnL over-inflation incident. Lifetime
+ * PnL is `currentPosition + totalWithdrawn - totalDeposited`. Every
+ * history-fetch failure (deleted subgraph, subgraph deployed against the wrong
+ * ABI, missing archive backfill, deposits indexed on a different
+ * chain/contract) collapses the deposit/withdrawal history to empty. With
+ * `deposited = 0` and `withdrawn = 0` but a live on-chain `position > 0`, the
+ * formula degenerates to reporting the entire position as profit. Throwing this
+ * typed error makes that unrecoverable state fail loudly instead of returning
+ * an inflated number that looks plausible.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.vaults.getVaultUserLifetimePnl({ vault, wallet, options });
+ * } catch (err) {
+ *   if (err instanceof AugustHistoryUnavailableError) {
+ *     // History backfill is broken — surface "temporarily unavailable",
+ *     // never a fabricated PnL number.
+ *     showUnavailable(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+class AugustHistoryUnavailableError extends AugustSDKError {
+    /**
+     * @param message - Human-readable description of the missing history. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   `{ vault, wallet }` (or equivalent) identifiers that scope the failure.
+     */
+    constructor(message, options) {
+        super('HISTORY_UNAVAILABLE', message, options);
+        this.name = 'AugustHistoryUnavailableError';
+    }
+}
+exports.AugustHistoryUnavailableError = AugustHistoryUnavailableError;
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 function isAugustSDKError(err) {
     return (err instanceof AugustSDKError ||

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

@@ -273,6 +273,72 @@ export declare function getYieldLastRealizedOn({ vault, options, }: {
     vault: IAddress;
     options: IVaultBaseOptions;
 }): Promise<number>;
+/** Inputs the lifetime-PnL history guard inspects. */
+export interface PnlHistoryConsistencyParams {
+    /** Vault contract address, used for the error message and context. */
+    vault: IAddress;
+    /** User wallet address, used for the error message and context. */
+    wallet: IAddress;
+    /**
+     * Whether the resolved deposit history contains at least one deposit record
+     * (subgraph deposits or LayerZero cross-chain deposits).
+     */
+    hasDeposits: boolean;
+    /** Total withdrawn, in raw base units (asset decimals). */
+    totalWithdrawnRaw: bigint;
+    /** Current on-chain position value, in raw base units (asset decimals). */
+    currentPositionRaw: bigint;
+}
+/**
+ * Guard against the 2026-07-09 lifetime-PnL over-inflation failure mode.
+ *
+ * Lifetime PnL is `currentPosition + totalWithdrawn - totalDeposited`. When the
+ * deposit/withdrawal history fails to load it collapses to empty, so both
+ * `totalDeposited` and `totalWithdrawn` read as zero. If the wallet still holds
+ * a live on-chain position, the formula degenerates to reporting the entire
+ * position as pure profit — a plausible-looking but wrong number.
+ *
+ * This guard rejects exactly that state: a non-zero position with no recorded
+ * deposits *and* no recorded withdrawals. Any of the following is treated as
+ * consistent and passes:
+ * - deposits are present (the normal, computable case);
+ * - withdrawals are present (a fully-exited-then-re-entered position is still
+ *   computable — the withdrawal records prove history loaded);
+ * - the current position is zero (the wallet never interacted or fully exited,
+ *   so a zero PnL is correct, not inflated).
+ *
+ * Pure and synchronous — no RPC, no I/O — so it is safe to call inside the hot
+ * path with no added latency.
+ *
+ * Known imprecision — vault shares are transferable ERC-20 receipt tokens, so a
+ * wallet that *received* shares via a direct token transfer (never deposited,
+ * never withdrew) legitimately has `position > 0` with no history records and
+ * will throw `HISTORY_UNAVAILABLE` even though its history loaded fine. This is
+ * not a regression — the pre-guard formula reported that same position as 100%
+ * profit, which was also wrong — but the error message is misleading for that
+ * (rare) path. If receipt-token transfer becomes a real user flow, distinguish
+ * it here (e.g. by checking for a share-transfer event) rather than widening
+ * the guard.
+ *
+ * @param params - See {@link PnlHistoryConsistencyParams}.
+ * @returns `void` when the history is consistent.
+ * @throws {@link AugustHistoryUnavailableError} with code `HISTORY_UNAVAILABLE`
+ *   and `context: { vault, wallet }` when a non-zero position has neither
+ *   deposits nor withdrawals recorded. The message carries the
+ *   `#getVaultUserLifetimePnl::<vault>::<wallet>` prefix so it groups with the
+ *   other errors leaving the getter.
+ * @example
+ * ```ts
+ * assertPnlHistoryConsistent({
+ *   vault,
+ *   wallet,
+ *   hasDeposits: depositsByAsset.size > 0,
+ *   totalWithdrawnRaw,
+ *   currentPositionRaw: currentPositionValue.raw,
+ * });
+ * ```
+ */
+export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawnRaw, currentPositionRaw, }: PnlHistoryConsistencyParams): void;
 /**
  * Calculate lifetime PnL for a user in a specific vault.
  *

package/lib/modules/vaults/getters.js

@@ -53,6 +53,7 @@ exports.getUserPoints = getUserPoints;
 exports.registerUserForPoints = registerUserForPoints;
 exports.fetchPointsLeaderboard = fetchPointsLeaderboard;
 exports.getYieldLastRealizedOn = getYieldLastRealizedOn;
+exports.assertPnlHistoryConsistent = assertPnlHistoryConsistent;
 exports.getVaultUserLifetimePnl = getVaultUserLifetimePnl;
 exports.getVaultPnl = getVaultPnl;
 exports.getVaultHistoricalTimeseries = getVaultHistoricalTimeseries;
@@ -85,6 +86,7 @@ const date_utils_1 = require("./utils/date-utils");
 const call_data_decoder_1 = require("./utils/call-data-decoder");
 const deposits_1 = require("../../services/layerzero/deposits");
 const redeems_1 = require("../../services/layerzero/redeems");
+const errors_1 = require("../../core/errors");
 /**
  * Vault Data Getters
  *
@@ -1840,6 +1842,62 @@ async function getYieldLastRealizedOn({ vault, options, }) {
         throw new Error(`#getYieldLastRealizedOn::${vault}:${errorMessage}`);
     }
 }
+/**
+ * Guard against the 2026-07-09 lifetime-PnL over-inflation failure mode.
+ *
+ * Lifetime PnL is `currentPosition + totalWithdrawn - totalDeposited`. When the
+ * deposit/withdrawal history fails to load it collapses to empty, so both
+ * `totalDeposited` and `totalWithdrawn` read as zero. If the wallet still holds
+ * a live on-chain position, the formula degenerates to reporting the entire
+ * position as pure profit — a plausible-looking but wrong number.
+ *
+ * This guard rejects exactly that state: a non-zero position with no recorded
+ * deposits *and* no recorded withdrawals. Any of the following is treated as
+ * consistent and passes:
+ * - deposits are present (the normal, computable case);
+ * - withdrawals are present (a fully-exited-then-re-entered position is still
+ *   computable — the withdrawal records prove history loaded);
+ * - the current position is zero (the wallet never interacted or fully exited,
+ *   so a zero PnL is correct, not inflated).
+ *
+ * Pure and synchronous — no RPC, no I/O — so it is safe to call inside the hot
+ * path with no added latency.
+ *
+ * Known imprecision — vault shares are transferable ERC-20 receipt tokens, so a
+ * wallet that *received* shares via a direct token transfer (never deposited,
+ * never withdrew) legitimately has `position > 0` with no history records and
+ * will throw `HISTORY_UNAVAILABLE` even though its history loaded fine. This is
+ * not a regression — the pre-guard formula reported that same position as 100%
+ * profit, which was also wrong — but the error message is misleading for that
+ * (rare) path. If receipt-token transfer becomes a real user flow, distinguish
+ * it here (e.g. by checking for a share-transfer event) rather than widening
+ * the guard.
+ *
+ * @param params - See {@link PnlHistoryConsistencyParams}.
+ * @returns `void` when the history is consistent.
+ * @throws {@link AugustHistoryUnavailableError} with code `HISTORY_UNAVAILABLE`
+ *   and `context: { vault, wallet }` when a non-zero position has neither
+ *   deposits nor withdrawals recorded. The message carries the
+ *   `#getVaultUserLifetimePnl::<vault>::<wallet>` prefix so it groups with the
+ *   other errors leaving the getter.
+ * @example
+ * ```ts
+ * assertPnlHistoryConsistent({
+ *   vault,
+ *   wallet,
+ *   hasDeposits: depositsByAsset.size > 0,
+ *   totalWithdrawnRaw,
+ *   currentPositionRaw: currentPositionValue.raw,
+ * });
+ * ```
+ */
+function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawnRaw, currentPositionRaw, }) {
+    const positionExists = currentPositionRaw > BigInt(0);
+    const noHistory = !hasDeposits && totalWithdrawnRaw === BigInt(0);
+    if (positionExists && noHistory) {
+        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 } });
+    }
+}
 /**
  * Calculate lifetime PnL for a user in a specific vault.
  *
@@ -2171,6 +2229,17 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             totalWithdrawnRaw += totalWithdrawalsInShares;
         }
         const totalWithdrawn = (0, core_1.toNormalizedBn)(totalWithdrawnRaw, decimals);
+        // Guard the 2026-07-09 over-inflation incident: a live position with no
+        // deposits *and* no withdrawals means the history failed to load, and the
+        // PnL formula would report the whole position as profit. Fail loudly with a
+        // typed error instead of returning a fabricated number.
+        assertPnlHistoryConsistent({
+            vault,
+            wallet,
+            hasDeposits: depositsByAsset.size > 0,
+            totalWithdrawnRaw,
+            currentPositionRaw: BigInt(currentPositionValue.raw),
+        });
         const tokenPriceUsd = await pricePromise;
         // Validate token price and log warning if invalid
         const effectiveTokenPrice = tokenPriceUsd > 0 ? tokenPriceUsd : 1;
@@ -2223,6 +2292,11 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
     }
     catch (e) {
         core_1.Logger.log.error('getVaultUserLifetimePnl', e, { vault, wallet });
+        // Preserve the typed history guard so callers can distinguish an
+        // unavailable-history failure from a generic getter error. Its message
+        // already carries the `#getVaultUserLifetimePnl::vault::wallet` prefix.
+        if (e instanceof errors_1.AugustHistoryUnavailableError)
+            throw e;
         const errorMessage = e instanceof Error ? e.message : String(e);
         throw new Error(`#getVaultUserLifetimePnl::${vault}::${wallet}:${errorMessage}`);
     }

package/lib/modules/vaults/utils.js

@@ -330,6 +330,7 @@ function buildBackendVault(tokenizedVault, overrides) {
         historical_snapshots: tokenizedVault.historical_snapshots || [],
         address: tokenizedVault.address,
         historical_apy: tokenizedVault.historical_apy,
+        historical_compound_apy: tokenizedVault.historical_compound_apy,
         max_drawdown: tokenizedVault.max_drawdown,
         logoUrl: tokenizedVault.vault_logo_url || '/img/strategist/august.svg',
         description: tokenizedVault.description || '',
@@ -600,6 +601,7 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
         maxDepositAmount: maxDepositAmount,
         receipt: receipt,
         historical_apy: tokenizedVault?.historical_apy,
+        historical_compound_apy: tokenizedVault?.historical_compound_apy,
         historical_snapshots: tokenizedVault?.historical_snapshots || [],
         max_drawdown: tokenizedVault?.max_drawdown,
         composabilityIntegrations: mapComposabilityIntegrations(tokenizedVault),