@augustdigital/sdk 8.14.0 → 8.16.0

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.14.0";
+export declare const SDK_VERSION = "8.16.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.16.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.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.
@@ -330,6 +358,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 || '',
@@ -397,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,
@@ -600,6 +630,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),
@@ -613,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,
     };