@augustdigital/sdk 8.5.0 → 8.6.1

package/lib/services/coingecko/fetcher.d.ts

@@ -2,13 +2,14 @@
  * Fetch the latest USD price for a token symbol from CoinGecko's
  * `/market_chart/range` endpoint, mapped through `COINGECKO_COIN_ID_MAP`.
  *
- * @param symbol Token symbol (case-insensitive). Must be present in
- *   `COINGECKO_COIN_ID_MAP`; unmapped symbols still hit the network and
- *   404 today (see todo/32-coingecko-fetcher-defects.md).
- * @param coinGeckoKey CoinGecko Pro API key passed as `x-cg-pro-api-key`.
- * @returns The latest price in USD on success; `null` on any failure
- *   (non-2xx response, network error, JSON parse error, or missing
- *   `prices` array). The `musd` short-circuit returns a tuple literal
- *   for back-compat — see todo/32 for the cleanup.
+ * @param symbol - Token symbol (case-insensitive). Must be present in
+ *   `COINGECKO_COIN_ID_MAP`.
+ * @param coinGeckoKey - CoinGecko Pro API key passed as `x-cg-pro-api-key`.
+ * @returns The latest price in USD (a number) on success; `null` when the
+ *   response contains an empty or missing `prices` array. `musd` (mezo-usd)
+ *   is a USD-pegged stablecoin and short-circuits to a price of `1`.
+ * @throws {@link AugustValidationError} When `symbol` is not in `COINGECKO_COIN_ID_MAP`.
+ * @throws {@link AugustRateLimitError} On a 429 response from CoinGecko.
+ * @throws {@link AugustServerError} On any other non-2xx response.
  */
-export declare function fetchTokenPricesFromCoinGecko(symbol: string, coinGeckoKey: string): Promise<any>;
+export declare function fetchTokenPricesFromCoinGecko(symbol: string, coinGeckoKey: string): Promise<number>;

package/lib/services/coingecko/fetcher.js

@@ -2,26 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchTokenPricesFromCoinGecko = fetchTokenPricesFromCoinGecko;
 const logger_1 = require("../../core/logger");
+const errors_1 = require("../../core/errors");
 const utils_1 = require("./utils");
 /**
  * Fetch the latest USD price for a token symbol from CoinGecko's
  * `/market_chart/range` endpoint, mapped through `COINGECKO_COIN_ID_MAP`.
  *
- * @param symbol Token symbol (case-insensitive). Must be present in
- *   `COINGECKO_COIN_ID_MAP`; unmapped symbols still hit the network and
- *   404 today (see todo/32-coingecko-fetcher-defects.md).
- * @param coinGeckoKey CoinGecko Pro API key passed as `x-cg-pro-api-key`.
- * @returns The latest price in USD on success; `null` on any failure
- *   (non-2xx response, network error, JSON parse error, or missing
- *   `prices` array). The `musd` short-circuit returns a tuple literal
- *   for back-compat — see todo/32 for the cleanup.
+ * @param symbol - Token symbol (case-insensitive). Must be present in
+ *   `COINGECKO_COIN_ID_MAP`.
+ * @param coinGeckoKey - CoinGecko Pro API key passed as `x-cg-pro-api-key`.
+ * @returns The latest price in USD (a number) on success; `null` when the
+ *   response contains an empty or missing `prices` array. `musd` (mezo-usd)
+ *   is a USD-pegged stablecoin and short-circuits to a price of `1`.
+ * @throws {@link AugustValidationError} When `symbol` is not in `COINGECKO_COIN_ID_MAP`.
+ * @throws {@link AugustRateLimitError} On a 429 response from CoinGecko.
+ * @throws {@link AugustServerError} On any other non-2xx response.
  */
 async function fetchTokenPricesFromCoinGecko(symbol, coinGeckoKey) {
     const coinId = utils_1.COINGECKO_COIN_ID_MAP[symbol.toLowerCase()];
     if (coinId === 'mezo-usd') {
-        return [['175394880000', 1]];
+        return 1;
+    }
+    if (!coinId) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `fetchTokenPricesFromCoinGecko: symbol "${symbol}" is not in COINGECKO_COIN_ID_MAP`, { context: { symbol } });
     }
-    // this is what we do in FE - not sure if we really need 7d worth of data since we just want something but it'll do for now
     const sevendDaysInS = 7 * 24 * 60 * 60;
     const from = Date.now() / 1000 - sevendDaysInS;
     const url = `https://pro-api.coingecko.com/api/v3/coins/${coinId}/market_chart/range?vs_currency=usd&from=${from}&to=${Math.floor(Date.now() / 1000)}&interval=daily`;
@@ -34,14 +38,10 @@ async function fetchTokenPricesFromCoinGecko(symbol, coinGeckoKey) {
             },
         });
         if (!response.ok) {
-            const err = new Error(`CoinGecko API error: ${response.status} ${response.statusText}`);
-            logger_1.Logger.log.error('fetchTokenPricesFromCoinGecko', err, {
-                status: response.status,
-                statusText: response.statusText,
-                coinId,
-                symbol,
-            });
-            throw err;
+            if (response.status === 429) {
+                throw new errors_1.AugustRateLimitError(`CoinGecko rate-limited (429): symbol "${symbol}"`, { context: { symbol, coinId, status: response.status } });
+            }
+            throw new errors_1.AugustServerError(response.status, `CoinGecko API error ${response.status} ${response.statusText}: symbol "${symbol}"`, { context: { symbol, coinId } });
         }
         const data = (await response.json());
         // `/market_chart/range` returns `{ prices, market_caps, total_volumes }` —
@@ -57,6 +57,10 @@ async function fetchTokenPricesFromCoinGecko(symbol, coinGeckoKey) {
             coinId,
             symbol,
         });
+        // Re-throw typed SDK errors (AugustRateLimitError, AugustServerError, etc.)
+        // so callers can distinguish rate-limits and server errors from "no data".
+        if (error instanceof errors_1.AugustSDKError)
+            throw error;
         return null;
     }
 }

package/lib/services/debank/fetcher.d.ts

@@ -1,4 +1,4 @@
-import { IAddress, IWSMonitorHeaders } from '../../types';
+import type { IAddress, IWSMonitorHeaders } from '../../types';
 export interface IDebankStatsObject {
     asset_usd_value: number;
     debt_usd_value: number;

package/lib/services/debank/utils.d.ts

@@ -1,4 +1,4 @@
-import { IAddress, IDebankProtocolExposure, IDebankTokenExposure } from '../../types';
+import type { IAddress, IDebankProtocolExposure, IDebankTokenExposure } from '../../types';
 export interface IDebankNormalizedResponse {
     subaccount: {
         positions: any[];

package/lib/services/debank/utils.js

@@ -263,7 +263,7 @@ function parseLoanLevelDebank(debankRes) {
         if (protocolExposures.length === 0) {
             if (debankRes?.subaccount?.tokens) {
                 debankRes.subaccount.tokens.forEach((t) => {
-                    if (t?.amount && t?.price && t.amount * t.price >= 10000) {
+                    if (t?.amount && t?.price && t.amount * t.price >= 10_000) {
                         exposure.push({
                             value: t?.id,
                             label: t?.symbol,

package/lib/services/layerzero/deposits.d.ts

@@ -2,7 +2,7 @@
  * LayerZero Deposits Service
  * Handles querying LayerZero USDC deposits from subgraphs
  */
-import { IAddress } from '../../types';
+import type { IAddress } from '../../types';
 export declare const LAYERZERO_VAULTS: {
     coreUSDC: {
         address: IAddress;

package/lib/services/layerzero/redeems.d.ts

@@ -2,7 +2,7 @@
  * LayerZero Redeems Service
  * Handles querying LayerZero earnAUSD redeems from subgraphs
  */
-import { IAddress } from '../../types';
+import type { IAddress } from '../../types';
 export interface ILayerZeroRedeem {
     id: string;
     recipient: string;

package/lib/services/octavfi/fetcher.d.ts

@@ -1,4 +1,4 @@
-import { IOctavfiPortfolio } from './types';
+import type { IOctavfiPortfolio } from './types';
 /**
  * Fetches portfolio data from Octavfi API.
  * Note: The API currently doesn't support multiple addresses in a single request,

package/lib/services/octavfi/types.d.ts

@@ -1,4 +1,4 @@
-import { IAddress } from '../../types';
+import type { IAddress } from '../../types';
 export type IOctavfiEndpoint = 'portfolio';
 export interface IOctavfiAsset {
     balance: string;

package/lib/services/octavfi/utils.d.ts

@@ -1,5 +1,5 @@
-import { IOctavfiPortfolio } from './types';
-import { IDebankNormalizedResponse } from '../debank/utils';
+import type { IOctavfiPortfolio } from './types';
+import type { IDebankNormalizedResponse } from '../debank/utils';
 /**
  * Transforms Octavfi portfolio response to DeBank-compatible format.
  * This allows Solana addresses to use Octavfi data while maintaining

package/lib/services/subgraph/fetcher.js

@@ -47,7 +47,7 @@ async function fetchSubgraphWithRetry(graphUrl, query, apiKey, maxRetries = 3, b
                     error.name === 'AbortError' ||
                     error.message.includes('ETIMEDOUT') ||
                     error.message.includes('timeout'))) {
-                const delay = baseDelay * Math.pow(2, attempt); // Exponential backoff
+                const delay = baseDelay * 2 ** attempt; // Exponential backoff
                 core_1.Logger.log.warn(`fetchSubgraph`, `${graphUrl?.includes('/subgraphs') ? graphUrl?.split('/subgraphs/')?.[1]?.split('/')?.[0] : graphUrl}: Attempt ${attempt + 1} failed, retrying in ${delay}ms`);
                 await new Promise((resolve) => setTimeout(resolve, delay));
                 continue;

package/lib/services/subgraph/vaults.js

@@ -183,12 +183,19 @@ const NEW_DEPOSIT_QUERY_PROPS = `
     senderAddr
     receiverAddr
   `;
+// The `block_number: blockNumber` alias on these new-schema withdrawal prop
+// sets is required, not cosmetic: getWithdrawalRequestsWithStatus prunes by
+// `Number(req.block_number) >= blockCutoff` (per the ISubgraphBase contract).
+// New-schema subgraphs expose the field as `blockNumber`, so without the alias
+// it reads undefined → Number(undefined) is NaN → every request is pruned
+// (AUGUST-6514). Only the REQUESTED set is read today; the processed/withdrawals
+// aliases below are kept for the same type contract so the NaN prune can't recur.
 const NEW_WITHDRAWALS_REQUESTED_QUERY_PROPS = `
     id
     shares
     receiverAddr
     holderAddr
-    blockNumber
+    block_number: blockNumber
     transactionHash_: transactionHash
     timestamp_: blockTimestamp
 `;
@@ -196,7 +203,7 @@ const NEW_WITHDRAWALS_PROCESSED_QUERY_PROPS = `
     id
     receiverAddr
     assetsAmount
-    blockNumber
+    block_number: blockNumber
     transactionHash_: transactionHash
     timestamp_: blockTimestamp
 `;
@@ -204,7 +211,7 @@ const NEW_WITHDRAWALS_QUERY_PROPS = `
     id
     transactionHash_: transactionHash
     timestamp_: blockTimestamp
-    blockNumber
+    block_number: blockNumber
     assets
     receiver
     sender
@@ -463,8 +470,84 @@ async function getSubgraphAllWithdrawals(pool, provider, slackWebookUrl = slack_
         };
     }
 }
+/**
+ * Fetch a user's deposit/withdraw history for an archived vault from the backend
+ * Mongo snapshot (`/upshift/vault_history`) instead of its retired subgraph.
+ *
+ * Returns the same {@link ISubgraphUserHistoryItem} shape as the subgraph path,
+ * so the caller's downstream transform/normalization is unchanged. `amount` is
+ * the raw deposited-asset amount (base units); `decimals` is attached so the
+ * caller can normalize, mirroring the subgraph path.
+ *
+ * Pre-deposit vaults accept multiple deposit assets with differing decimals
+ * (e.g. USDS at 18, USDC at 6). When the backend supplies `asset_address` per
+ * row, it is propagated as {@link ISubgraphUserHistoryItem.assetIn} (and, when
+ * present, `asset_decimals` is used for that row's `decimals`) so lifetime PnL
+ * resolves each deposit against its own token rather than the vault decimals —
+ * without it, an 18-decimal deposit normalized at the vault's 6 decimals
+ * inflates the cost basis by ~1e12. This mirrors the subgraph path, whose
+ * deposit rows already carry `assetIn`.
+ *
+ * Side effects: one RPC read (`getDecimals`) and one HTTP GET to the public API.
+ *
+ * @param user - The wallet whose history to fetch.
+ * @param provider - Contract runner, used to read the vault's decimals.
+ * @param pool - The (archived) vault contract address.
+ * @returns The user's deposits and settled withdrawals. Empty on a non-200
+ *   response.
+ */
+async function getArchivedVaultUserHistory(user, provider, pool) {
+    const decimals = await (0, core_1.getDecimals)(provider, pool);
+    const response = await (0, core_1.fetchAugustPublic)(core_1.WEBSERVER_ENDPOINTS.public.tokenizedVault.userHistory(pool, user));
+    if (response.status !== 200) {
+        core_1.Logger.log.error('getArchivedVaultUserHistory', `non-200 from vault_history for ${pool}: ${response.status}`);
+        return [];
+    }
+    const rows = (await response.json());
+    // The backend already stores final ISubgraphUserHistoryItem.type values, so
+    // no translation is needed. Two row-level guards before mapping, since both
+    // bad shapes propagate destructively downstream:
+    //   - amount_raw must be a non-negative integer: the caller does
+    //     BigInt(amount) outside a try/catch, and one bad row would throw and
+    //     wipe the user's entire (all-vault) history.
+    //   - timestamp must parse to a real time: a malformed value makes getTime()
+    //     return NaN, which stringifies to "NaN" and then sorts/normalizes
+    //     incorrectly downstream. Drop the row rather than emit a "NaN" stamp.
+    return (rows
+        .filter((row) => /^\d+$/.test(row.amount_raw) &&
+        !Number.isNaN(new Date(row.timestamp).getTime()))
+        .map((row) => ({
+        id: row.transaction_hash,
+        contractId_: pool,
+        timestamp_: String(Math.floor(new Date(row.timestamp).getTime() / 1000)),
+        transactionHash_: row.transaction_hash,
+        block_number: row.block_number != null ? String(row.block_number) : '0',
+        address: row.wallet,
+        amount: row.amount_raw,
+        type: row.type,
+        // Per-asset decimals when known, else the vault's. PnL re-resolves
+        // decimals from `assetIn` anyway; this keeps display/normalization
+        // correct for any consumer that reads the row's `decimals` directly.
+        decimals: row.asset_decimals ?? decimals,
+        // Carry the deposit asset through so mixed-decimal deposits normalize
+        // against their own token, not the vault's. Omitted when unknown.
+        ...(row.asset_address ? { assetIn: row.asset_address } : {}),
+    }))
+        // Match the subgraph path's ordering contract: sortUserHistory sorts
+        // ascending by unix timestamp_, and downstream consumers rely on that
+        // chronology. The backend returns rows in arbitrary order, so re-sort here.
+        .sort((a, b) => Number(a.timestamp_) - Number(b.timestamp_)));
+}
 async function getSubgraphUserHistory(user, provider, pool, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
     try {
+        // Archived vaults: serve history from the backend Mongo snapshot instead of
+        // the (retired) subgraph. The archived set is fetched from the backend (the
+        // routing source of truth) so a vault is only rerouted once its history is
+        // backfilled. Same return shape keeps downstream unchanged.
+        const archivedVaults = await (0, fetcher_2.fetchArchivedVaults)();
+        if (archivedVaults.has(pool.toLowerCase())) {
+            return await getArchivedVaultUserHistory(user, provider, pool);
+        }
         // setup
         const chainId = await (0, core_1.getChainId)(provider);
         const requests = [];

package/lib/services/swap-quotes/index.d.ts

@@ -29,6 +29,15 @@ export interface ISwapQuoteRequest {
      * in `[0, 10_000)` — 10_000 disables protection entirely and is rejected.
      */
     slippageBps?: number;
+    /**
+     * Optional aggregator contract-method filter. When set, the aggregator is
+     * constrained to this single method (ParaSwap's `/prices`
+     * `includeContractMethods`), so the returned calldata's leading 4-byte
+     * selector is deterministic — required when the on-chain SwapRouter only
+     * authorizes one selector per router. When omitted, the aggregator picks the
+     * optimal method freely and the selector may vary between quotes.
+     */
+    contractMethod?: string;
     /** Aggregator partner key. Defaults to `'august'`. */
     partner?: string;
     /** Aggregator partner-fee receiver. Defaults to the August partner address. */

package/lib/services/swap-quotes/index.js

@@ -45,6 +45,7 @@ async function fetchSwapQuote(request) {
         slippageBps,
         partner: request.partner ?? paraswap_1.PARASWAP_DEFAULTS.partner,
         partnerAddress: request.partnerAddress ?? paraswap_1.PARASWAP_DEFAULTS.partnerAddress,
+        contractMethod: request.contractMethod,
         fetchImpl,
         signal: request.signal,
     });
@@ -60,7 +61,7 @@ async function fetchSwapQuote(request) {
 }
 function validateRequest(req) {
     if (req.slippageBps !== undefined &&
-        (req.slippageBps < 0 || req.slippageBps >= 10000)) {
+        (req.slippageBps < 0 || req.slippageBps >= 10_000)) {
         throw new errors_1.AugustValidationError('INVALID_INPUT', `fetchSwapQuote: slippageBps must be in [0, 10000), got ${req.slippageBps}. 10000 bps = 100% slippage and disables protection entirely; use a tighter bound.`);
     }
     if (req.amount === 0n) {

package/lib/services/swap-quotes/paraswap.d.ts

@@ -17,6 +17,14 @@ export interface IParaswapQuoteInput {
     slippageBps: number;
     partner: string;
     partnerAddress: IAddress;
+    /**
+     * Optional `includeContractMethods` value passed to Paraswap's `/prices`. When
+     * set, Paraswap is restricted to this single contract method so the resulting
+     * calldata's leading selector is deterministic and matches the one the
+     * SwapRouter authorizes for this router. When omitted, Paraswap is free to
+     * pick whichever method is optimal for the route.
+     */
+    contractMethod?: string;
     fetchImpl: typeof fetch;
     signal?: AbortSignal;
 }

package/lib/services/swap-quotes/paraswap.js

@@ -42,6 +42,14 @@ async function getPriceRoute(input) {
         partnerAddress: input.partnerAddress,
         version: PARASWAP_VERSION,
     });
+    // Restrict the route to a single contract method when the caller pins one,
+    // so the calldata's selector is deterministic and matches the SwapRouter's
+    // per-router authorized selector. Without this the aggregator may return a
+    // route-optimized method (e.g. swapExactAmountInOnUniswapV3) whose selector
+    // the SwapRouter has not whitelisted, reverting with InvalidNotWhitelisted().
+    if (input.contractMethod) {
+        params.append('includeContractMethods', input.contractMethod);
+    }
     const url = `${PARASWAP_PRICES_URL}?${params.toString()}`;
     let response;
     try {

package/lib/types/pools.d.ts

@@ -1,8 +1,8 @@
 /**
  * @deprecated
  */
-import { IAddress, INormalizedNumber } from './web3';
-import { IDebankProtocolExposure, IDebankTokenExposure, ITokenizedVaultStrategist, IWSSubaccountCefi } from './webserver';
+import type { IAddress, INormalizedNumber } from './web3';
+import type { IDebankProtocolExposure, IDebankTokenExposure, ITokenizedVaultStrategist, IWSSubaccountCefi } from './webserver';
 type ILabelValue = {
     label: string;
     value: string;

package/lib/types/staking.d.ts

@@ -1,4 +1,4 @@
-import { IAddress, INormalizedNumber } from './web3';
+import type { IAddress, INormalizedNumber } from './web3';
 export type IActiveStakingPosition = {
     stakingToken: {
         decimals: number;

package/lib/types/sub-accounts.d.ts

@@ -1,4 +1,4 @@
-import { IAddress } from './web3';
+import type { IAddress } from './web3';
 export interface IWSSubAccountHealthFactor {
     id: IAddress;
     datetime: string;

package/lib/types/subgraph.d.ts

@@ -1,4 +1,4 @@
-import { IAddress } from './web3';
+import type { IAddress } from './web3';
 export interface ISubgraphBase {
     id: string;
     contractId_: IAddress;
@@ -12,6 +12,15 @@ export interface ISubgraphUserHistoryItem extends ISubgraphBase {
     type: 'withdraw-request' | 'deposit' | 'withdraw-processed';
     decimals?: number;
     isInstant?: boolean;
+    /**
+     * Deposit asset token address, when known. Pre-deposit vaults accept
+     * multiple deposit assets with differing decimals (e.g. USDS at 18,
+     * USDC at 6), so `amount` cannot be normalized with the vault's own
+     * decimals alone — consumers (notably lifetime PnL) key off this address
+     * to resolve the correct per-asset decimals and USD price. Absent for
+     * single-asset vaults, where the vault `decimals` is correct.
+     */
+    assetIn?: IAddress;
 }
 export interface ISubgraphWithdrawProccessed extends ISubgraphBase {
     processedOn: string;

package/lib/types/vaults.d.ts

@@ -49,6 +49,26 @@ export type IVaultUserHistoryItem = {
     type: 'withdraw-request' | 'deposit' | 'withdraw-processed' | 'redeem';
     transactionHash: IAddress;
 };
+/**
+ * A single reward paired with its backend-provided logo.
+ *
+ * `id` is the reward's stable backend identifier ({@link ITokenizedVaultReward.id})
+ * and is the key consumers should join on — it is unique even when two rewards
+ * share a multiplier and text. `label` is display-only: it mirrors the
+ * corresponding {@link IVaultRewards.additionalPoints} string (and so carries a
+ * leading space when `multiplier === 1`, e.g. `" Cores"`), so it is fine to
+ * print but must not be treated as a unique key.
+ *
+ * `imgUrl` is `null` when the backend has no logo for the reward, in which
+ * case consumers fall back to a bundled asset.
+ */
+export type IVaultRewardDetail = {
+    id: string;
+    label: string;
+    text: string;
+    imgUrl: string | null;
+    multiplier: number;
+};
 export type IVaultRewards = {
     points: string;
     multiplier: number;
@@ -57,6 +77,12 @@ export type IVaultRewards = {
         timestamp: number;
     }[];
     additionalPoints: string[];
+    /**
+     * Optional so this addition is non-breaking for external code that
+     * constructs an {@link IVaultRewards}. `getVaultRewards` always populates it;
+     * readers should treat an absent value as an empty list.
+     */
+    additionalPointsDetailed?: IVaultRewardDetail[];
 };
 export type IVaultExposureItem = {
     amount: number;

package/lib/types/web3.d.ts

@@ -1,4 +1,4 @@
-import { Signer, Provider } from 'ethers';
+import type { Signer, Provider } from 'ethers';
 export type IAddress = `0x${string}`;
 /**
  * Address type for vault contracts across all supported chains.

package/lib/types/webserver.d.ts

@@ -1,5 +1,5 @@
-import { IUserRoles } from './user';
-import { IAddress, type ChainType, type IStellarNetwork } from './web3';
+import type { IUserRoles } from './user';
+import type { IAddress, ChainType, IStellarNetwork } from './web3';
 /**
  * Table of Contents
  * 1) Subaccounts

package/package.json

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