@augustdigital/sdk 9.9.0 → 9.10.1

package/lib/core/helpers/concurrency.d.ts

@@ -35,3 +35,17 @@
  * @internal
  */
 export declare function mapWithConcurrency<TIn, TOut>(items: readonly TIn[], limit: number, task: (item: TIn, index: number) => Promise<TOut>): Promise<TOut[]>;
+/**
+ * Race a promise against a timeout so a hung call can't block indefinitely. The
+ * timer is always cleared, so a fast-resolving promise leaves nothing pending.
+ *
+ * @param promise - The call to bound. It keeps running after a timeout; only
+ *   the wait is abandoned.
+ * @param ms - Timeout in milliseconds. Values below 0 are treated as 0.
+ * @param label - Names the call in the rejection message.
+ * @returns What `promise` resolves to.
+ * @throws `Error("<label> timed out after <ms>ms")` on timeout, or whatever
+ *   `promise` rejects with.
+ * @internal
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;

package/lib/core/helpers/concurrency.js

@@ -10,6 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapWithConcurrency = mapWithConcurrency;
+exports.withTimeout = withTimeout;
 /**
  * Map over `items` running at most `limit` tasks at a time.
  *
@@ -55,4 +56,24 @@ async function mapWithConcurrency(items, limit, task) {
     await Promise.all(Array.from({ length: width }, worker));
     return results;
 }
+/**
+ * Race a promise against a timeout so a hung call can't block indefinitely. The
+ * timer is always cleared, so a fast-resolving promise leaves nothing pending.
+ *
+ * @param promise - The call to bound. It keeps running after a timeout; only
+ *   the wait is abandoned.
+ * @param ms - Timeout in milliseconds. Values below 0 are treated as 0.
+ * @param label - Names the call in the rejection message.
+ * @returns What `promise` resolves to.
+ * @throws `Error("<label> timed out after <ms>ms")` on timeout, or whatever
+ *   `promise` rejects with.
+ * @internal
+ */
+function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), Math.max(0, ms));
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
 //# sourceMappingURL=concurrency.js.map

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

@@ -311,6 +311,16 @@ export interface PnlHistoryConsistencyParams {
      * (subgraph deposits or LayerZero cross-chain deposits).
      */
     hasDeposits: boolean;
+    /**
+     * Whether the indexed deposits explain every share mint to the wallet (see
+     * {@link historyCoversMints}). Defaults to `true`.
+     */
+    mintsMatchHistory?: boolean;
+    /**
+     * Shares received by peer transfer, priced in raw base units (asset
+     * decimals) by {@link transferCostBasis}. Defaults to zero.
+     */
+    receivedByTransferRaw?: bigint;
     /** Total withdrawn, in raw base units (asset decimals). */
     totalWithdrawnRaw: bigint;
     /** Current on-chain position value, in raw base units (asset decimals). */
@@ -326,9 +336,14 @@ export interface PnlHistoryConsistencyParams {
  * 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, no shares received by transfer *and* no recorded withdrawals. It
+ * also rejects a non-zero position with no recorded deposits when a share mint
+ * to the wallet has no matching deposit (`mintsMatchHistory: false`): the mint
+ * proves a deposit the history failed to return, so neither a peer transfer
+ * nor a withdrawal makes the cost basis complete. Otherwise, any of the
+ * following is treated as consistent and passes:
  * - deposits are present (the normal, computable case);
+ * - shares were received by transfer and priced (see {@link transferCostBasis});
  * - 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,
@@ -338,15 +353,17 @@ export interface PnlHistoryConsistencyParams {
  * path with no added latency.
  *
  * Shares received by a direct token transfer (never deposited, never withdrew)
- * reach this guard as deposits: {@link getVaultUserLifetimePnl} prices them
- * with {@link transferCostBasis} first. The guard still throws for such a
- * wallet when its transfers cannot be read or priced.
+ * reach this guard as `receivedByTransferRaw`: {@link getVaultUserLifetimePnl}
+ * prices them with {@link transferCostBasis} first. The guard still throws for
+ * such a wallet when its transfers cannot be read or priced, or when a share
+ * mint to it has no indexed deposit.
  *
  * @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
+ *   and `context: { vault, wallet }` when a non-zero position has no deposits
+ *   recorded and either a share mint without a matching deposit or neither
+ *   received shares nor withdrawals. The message carries the
  *   `#getVaultUserLifetimePnl::<vault>::<wallet>` prefix so it groups with the
  *   other errors leaving the getter.
  * @example
@@ -355,12 +372,14 @@ export interface PnlHistoryConsistencyParams {
  *   vault,
  *   wallet,
  *   hasDeposits: depositsByAsset.size > 0,
+ *   mintsMatchHistory,
+ *   receivedByTransferRaw: costBasis.receivedByTransferRaw,
  *   totalWithdrawnRaw,
  *   currentPositionRaw: currentPositionValue.raw,
  * });
  * ```
  */
-export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawnRaw, currentPositionRaw, }: PnlHistoryConsistencyParams): void;
+export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, mintsMatchHistory, receivedByTransferRaw, totalWithdrawnRaw, currentPositionRaw, }: PnlHistoryConsistencyParams): void;
 /** Inputs the lifetime-PnL price guard inspects. */
 export interface PnlTokenPriceParams {
     /** Vault contract address, used for the error message and context. */
@@ -728,7 +747,9 @@ export interface PnlCostBasis {
  *
  * A depositor whose history misses a mint ({@link historyCoversMints}) is the
  * exception: its transfers do not count, so the result matches what the getter
- * returned before transfers counted for depositors. On a LayerZero OVault the
+ * returned before transfers counted for depositors. A wallet with no deposit
+ * still gets a basis here when its history misses a mint, but
+ * {@link assertPnlHistoryConsistent} rejects it. On a LayerZero OVault the
  * caller leaves the hub composer and share OFT out of the transfers (see
  * {@link selectPeerTransfers}): the composer's deliveries are already counted
  * as LayerZero deposits, and shares bridged to a spoke chain still count in the
@@ -789,16 +810,18 @@ export declare function pnlCostBasis({ depositedRaw, withdrawnAssetsRaw, hasDepo
  * shares add to `totalDeposited` (and are reported again as
  * `receivedByTransfer`), sent shares add to `totalWithdrawn`. This holds
  * alongside indexed deposits, so a wallet that received shares and also
- * deposited is not credited with the received shares as profit. LayerZero
- * OVaults count transfers only when history holds no deposit, because their
- * composer delivers cross-chain deposits by transfer.
+ * deposited is not credited with the received shares as profit. On LayerZero
+ * OVaults, transfers from or to the hub composer and share OFT do not count,
+ * because the composer delivers cross-chain deposits by transfer and those
+ * are already counted as LayerZero deposits.
  *
  * Gaps in the indexed history: a share mint with no `Deposit` event counts as
  * a deposit of the assets in its `ReserveDeposit` event
  * ({@link selectReserveDeposits}; High Growth ETH emits it for Kelp gain-adapter
  * deposits), and a withdrawal request the vault logged twice counts once
  * ({@link countWithdrawalRequestsOnce}). Transfers fold in for a depositor only
- * once every mint is explained.
+ * once every mint is explained. A wallet with no indexed deposit and a mint
+ * that no deposit explains throws `HISTORY_UNAVAILABLE`.
  *
  * Tokenized Vault V2 redemptions carry only shares, so a settled one counts at
  * the assets the vault paid, or at the share ratio on its claim date when the
@@ -813,9 +836,8 @@ export declare function pnlCostBasis({ depositedRaw, withdrawnAssetsRaw, hasDepo
  * for a Tokenized Vault V2 wallet with redemption requests, a `lagDuration()`
  * read plus one backend timeseries request. A timeseries window with no usable
  * ratio (a closed vault whose history stopped earlier) is read again in full,
- * so the latest earlier day still prices it. For
- * non-LayerZero vaults the transfer query runs in parallel with the history
- * read; for LayerZero vaults it runs only when history holds no deposit.
+ * so the latest earlier day still prices it. The transfer query runs for
+ * every vault, in parallel with the history read.
  *
  * @param vault - Vault contract address
  * @param wallet - User wallet address
@@ -823,7 +845,8 @@ export declare function pnlCostBasis({ depositedRaw, withdrawnAssetsRaw, hasDepo
  * @returns Lifetime PnL data in both native token and USD
  * @throws {@link AugustHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a
  *   live position has no indexed deposits, withdrawals or priceable share
- *   transfers.
+ *   transfers, or has no indexed deposit while a share mint to the wallet has
+ *   no matching deposit.
  * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
  *   underlying asset has no USD price, or `asset()` cannot be read.
  */

package/lib/modules/vaults/getters.js

@@ -641,11 +641,14 @@ async function getVaultAllocations(vault, options, tokenizedVault) {
     // afterwards, and a borrower on a chain with portfolio coverage would otherwise
     // have its rows silently dropped rather than double-counted.
     let untangledTokenCount = 0;
+    let vaultOctav;
     const borrowerPortfolioFetchers = {
         solana: async (borrower) => {
-            const portfolios = await (0, octavfi_1.fetchOctavfiPortfolios)([borrower]);
-            return portfolios.length > 0
-                ? (0, octavfi_1.transformOctavfiToDebank)(portfolios[0])
+            vaultOctav ??= (0, octavfi_1.fetchVaultOctavResponse)(vault, options?.headers);
+            const response = await vaultOctav;
+            const portfolio = response ? response[borrower] : undefined;
+            return portfolio && !('error' in portfolio)
+                ? (0, octavfi_1.transformOctavfiToDebank)(portfolio)
                 : null;
         },
     };
@@ -2270,9 +2273,14 @@ async function getYieldLastRealizedOn({ vault, options, }) {
  * 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, no shares received by transfer *and* no recorded withdrawals. It
+ * also rejects a non-zero position with no recorded deposits when a share mint
+ * to the wallet has no matching deposit (`mintsMatchHistory: false`): the mint
+ * proves a deposit the history failed to return, so neither a peer transfer
+ * nor a withdrawal makes the cost basis complete. Otherwise, any of the
+ * following is treated as consistent and passes:
  * - deposits are present (the normal, computable case);
+ * - shares were received by transfer and priced (see {@link transferCostBasis});
  * - 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,
@@ -2282,15 +2290,17 @@ async function getYieldLastRealizedOn({ vault, options, }) {
  * path with no added latency.
  *
  * Shares received by a direct token transfer (never deposited, never withdrew)
- * reach this guard as deposits: {@link getVaultUserLifetimePnl} prices them
- * with {@link transferCostBasis} first. The guard still throws for such a
- * wallet when its transfers cannot be read or priced.
+ * reach this guard as `receivedByTransferRaw`: {@link getVaultUserLifetimePnl}
+ * prices them with {@link transferCostBasis} first. The guard still throws for
+ * such a wallet when its transfers cannot be read or priced, or when a share
+ * mint to it has no indexed deposit.
  *
  * @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
+ *   and `context: { vault, wallet }` when a non-zero position has no deposits
+ *   recorded and either a share mint without a matching deposit or neither
+ *   received shares nor withdrawals. The message carries the
  *   `#getVaultUserLifetimePnl::<vault>::<wallet>` prefix so it groups with the
  *   other errors leaving the getter.
  * @example
@@ -2299,16 +2309,23 @@ async function getYieldLastRealizedOn({ vault, options, }) {
  *   vault,
  *   wallet,
  *   hasDeposits: depositsByAsset.size > 0,
+ *   mintsMatchHistory,
+ *   receivedByTransferRaw: costBasis.receivedByTransferRaw,
  *   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 } });
+function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, mintsMatchHistory = true, receivedByTransferRaw = BigInt(0), totalWithdrawnRaw, currentPositionRaw, }) {
+    if (currentPositionRaw <= BigInt(0) || hasDeposits)
+        return;
+    const missingDeposit = !mintsMatchHistory;
+    const noHistory = receivedByTransferRaw === BigInt(0) && totalWithdrawnRaw === BigInt(0);
+    if (missingDeposit || noHistory) {
+        const reason = missingDeposit
+            ? 'a share mint has no indexed deposit'
+            : 'no deposits or withdrawals were indexed';
+        throw new errors_1.AugustHistoryUnavailableError(`#getVaultUserLifetimePnl::${vault}::${wallet}:transaction history unavailable — a live position exists but ${reason}, so lifetime PnL cannot be computed without over-reporting the entire position as profit`, { context: { vault, wallet } });
     }
 }
 /**
@@ -2710,7 +2727,9 @@ function settleV2Redemptions({ history, lagDuration, ratios, now, }) {
  *
  * A depositor whose history misses a mint ({@link historyCoversMints}) is the
  * exception: its transfers do not count, so the result matches what the getter
- * returned before transfers counted for depositors. On a LayerZero OVault the
+ * returned before transfers counted for depositors. A wallet with no deposit
+ * still gets a basis here when its history misses a mint, but
+ * {@link assertPnlHistoryConsistent} rejects it. On a LayerZero OVault the
  * caller leaves the hub composer and share OFT out of the transfers (see
  * {@link selectPeerTransfers}): the composer's deliveries are already counted
  * as LayerZero deposits, and shares bridged to a spoke chain still count in the
@@ -2852,16 +2871,18 @@ async function readV2Redemptions(provider, vault, history, headers) {
  * shares add to `totalDeposited` (and are reported again as
  * `receivedByTransfer`), sent shares add to `totalWithdrawn`. This holds
  * alongside indexed deposits, so a wallet that received shares and also
- * deposited is not credited with the received shares as profit. LayerZero
- * OVaults count transfers only when history holds no deposit, because their
- * composer delivers cross-chain deposits by transfer.
+ * deposited is not credited with the received shares as profit. On LayerZero
+ * OVaults, transfers from or to the hub composer and share OFT do not count,
+ * because the composer delivers cross-chain deposits by transfer and those
+ * are already counted as LayerZero deposits.
  *
  * Gaps in the indexed history: a share mint with no `Deposit` event counts as
  * a deposit of the assets in its `ReserveDeposit` event
  * ({@link selectReserveDeposits}; High Growth ETH emits it for Kelp gain-adapter
  * deposits), and a withdrawal request the vault logged twice counts once
  * ({@link countWithdrawalRequestsOnce}). Transfers fold in for a depositor only
- * once every mint is explained.
+ * once every mint is explained. A wallet with no indexed deposit and a mint
+ * that no deposit explains throws `HISTORY_UNAVAILABLE`.
  *
  * Tokenized Vault V2 redemptions carry only shares, so a settled one counts at
  * the assets the vault paid, or at the share ratio on its claim date when the
@@ -2876,9 +2897,8 @@ async function readV2Redemptions(provider, vault, history, headers) {
  * for a Tokenized Vault V2 wallet with redemption requests, a `lagDuration()`
  * read plus one backend timeseries request. A timeseries window with no usable
  * ratio (a closed vault whose history stopped earlier) is read again in full,
- * so the latest earlier day still prices it. For
- * non-LayerZero vaults the transfer query runs in parallel with the history
- * read; for LayerZero vaults it runs only when history holds no deposit.
+ * so the latest earlier day still prices it. The transfer query runs for
+ * every vault, in parallel with the history read.
  *
  * @param vault - Vault contract address
  * @param wallet - User wallet address
@@ -2886,7 +2906,8 @@ async function readV2Redemptions(provider, vault, history, headers) {
  * @returns Lifetime PnL data in both native token and USD
  * @throws {@link AugustHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a
  *   live position has no indexed deposits, withdrawals or priceable share
- *   transfers.
+ *   transfers, or has no indexed deposit while a share mint to the wallet has
+ *   no matching deposit.
  * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
  *   underlying asset has no USD price, or `asset()` cannot be read.
  */
@@ -3256,7 +3277,9 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         assertPnlHistoryConsistent({
             vault,
             wallet,
-            hasDeposits: hasDeposits || costBasis.receivedByTransferRaw > BigInt(0),
+            hasDeposits,
+            mintsMatchHistory,
+            receivedByTransferRaw: costBasis.receivedByTransferRaw,
             totalWithdrawnRaw: costBasis.withdrawnAssetsRaw,
             currentPositionRaw: BigInt(currentPositionValue.raw),
         });