@augustdigital/sdk 9.2.0 → 9.2.2

package/lib/adapters/solana/getters.js

@@ -48,7 +48,14 @@ const utils_2 = require("../../modules/vaults/utils");
  * @returns Formatted vault object with Solana-specific fields
  */
 const getSolanaVault = async (tokenizedVault, options) => {
-    const solanaRpcUrl = options.rpcUrl;
+    // `options.rpcUrl` is resolved upstream as `providers[vault.chain]`, and that
+    // map is keyed by EVM chain id — Solana's synthetic id is never in it, so the
+    // field arrives undefined for every Solana vault however well the app has
+    // configured its Solana RPC. The connection built from that RPC *is* passed
+    // (`solanaService`), so take the endpoint off it rather than fetching against
+    // `undefined`.
+    const solanaRpcUrl = (options.rpcUrl ??
+        options.solanaService?.connection?.rpcEndpoint);
     const solanaMetadata = tokenizedVault.solana_vault_metadata;
     const programId = utils_1.SolanaUtils.resolveProgramId(tokenizedVault.address, solanaMetadata);
     // Fallback decimals: prefer backend metadata, then the application default

package/lib/adapters/solana/utils.js

@@ -333,6 +333,17 @@ async function getVaultMints({ vaultProgramId, vaultAddress, connection, idl, })
     }
 }
 async function getToken({ mintAddress, endpoint, connection, }) {
+    // `endpoint` is optional on ISolanaConnectionOptions, so a caller with no
+    // Solana RPC configured reaches `fetch(undefined, ...)`, which throws
+    // "Cannot read properties of undefined (reading 'toString')" from inside the
+    // runtime's fetch wrapper — an unactionable error masquerading as a token
+    // failure. Bail before the request instead.
+    if (!endpoint) {
+        core_1.Logger.log.warn('getToken', 'No Solana RPC endpoint configured', {
+            mintAddress: String(mintAddress),
+        });
+        return null;
+    }
     try {
         const cacheKey = `solana_token-${mintAddress}`;
         const cachedData = await (0, core_1.getSafeCache)(cacheKey);
@@ -425,8 +436,11 @@ async function getToken({ mintAddress, endpoint, connection, }) {
         return null;
     }
     catch (error) {
-        core_1.Logger.log.error('getToken', error, {
-            message: 'Error fetching token metadata',
+        // Callers fall back to backend metadata when this returns null, so a failed
+        // lookup is degraded-but-handled — warn, don't raise it as an error.
+        core_1.Logger.log.warn('getToken', 'Error fetching token metadata', {
+            mintAddress: String(mintAddress),
+            error,
         });
         return null;
     }

package/lib/core/analytics/sentry.js

@@ -143,13 +143,34 @@ const ERROR_DEDUPE_MAX_KEYS = 500;
  * true rate. `resetAnalytics()` clears this map for the whole process.
  */
 const errorDedupeState = new Map();
+/**
+ * Strip the per-request variables out of an error message.
+ *
+ * Truncating at 120 characters is not enough on its own: the variable part is
+ * usually a vault or wallet address near the FRONT of the message
+ * (`Request timeout after 90s: /subaccount/0x3F13…/otc_positions`), so one
+ * failure mode still produced a distinct signature — and therefore its own
+ * private rate-limit allowance and its own Sentry issue — per address. That is
+ * how a single backend timeout became 5k events across a dozen issues in a day.
+ *
+ * Placeholders are kept structural (`/subaccount/<addr>/otc_positions`) so
+ * genuinely different endpoints and failure modes stay separate.
+ *
+ * @param message - The raw error message.
+ * @returns The message with addresses, numbers, and query strings masked.
+ */
+function normalizeErrorMessage(message) {
+    return message
+        .replace(/0x[0-9a-fA-F]{6,}/g, '<addr>')
+        .replace(/\?[^\s]*/g, '')
+        .replace(/\b\d{4,}\b/g, '<n>');
+}
 /**
  * Build a low-cardinality signature for an error.
  *
- * Message tails carry the variable parts (addresses, block ranges, response
- * bodies), so only the leading 120 characters participate — enough to separate
- * distinct failure modes without splitting one failure mode into thousands of
- * unique keys.
+ * The message is normalized (see {@link normalizeErrorMessage}) and then capped
+ * at 120 characters — enough to separate distinct failure modes without
+ * splitting one failure mode into thousands of unique keys.
  *
  * @param error - The normalized error being captured.
  * @param origin - The `sdk.origin` call-site tag, when present.
@@ -157,7 +178,8 @@ const errorDedupeState = new Map();
  */
 function errorSignature(error, origin) {
     const tag = typeof origin === 'string' ? origin : '';
-    return `${tag}|${error.name}|${(error.message || '').slice(0, 120)}`;
+    const message = normalizeErrorMessage(error.message || '').slice(0, 120);
+    return `${tag}|${error.name}|${message}`;
 }
 /**
  * Decide whether an error should be sent to Sentry, applying a per-signature
@@ -265,6 +287,17 @@ function createSentrySink() {
                     if (admission.suppressed > 0) {
                         scope.setExtra('sdk.suppressed_since_last', admission.suppressed);
                     }
+                    // Group by the same normalized signature the rate limiter uses.
+                    // Sentry's default grouping keys on the raw message, so one backend
+                    // timeout fans out into an issue per vault/wallet address — the
+                    // per-issue notification volume that flooded the on-call webhook.
+                    // Addresses stay recoverable from the event message and tags.
+                    scope.setFingerprint?.([
+                        'sdk',
+                        typeof context?.tag === 'string' ? context.tag : 'untagged',
+                        normalized.name,
+                        normalizeErrorMessage(normalized.message || '').slice(0, 120),
+                    ]);
                     sdk.captureException(normalized);
                 });
             }

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "9.2.0";
+export declare const SDK_VERSION = "9.2.2";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '9.2.0';
+exports.SDK_VERSION = '9.2.2';
 //# sourceMappingURL=version.js.map

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

@@ -20,8 +20,12 @@ import type { IVaultBaseOptions } from './types';
  * Routes to appropriate chain adapter (EVM v1/v2, Solana, or Stellar) based on vault version.
  * Optionally enriches with loan and allocation data.
  * @param vault - Vault contract address (EVM hex, Stellar C-address, or Solana program ID)
- * @param loans - Include active loan data
- * @param allocations - Include DeFi/CeFi allocation breakdowns
+ * @param loans - Include active loan data. EVM vaults only — there is no
+ *   non-EVM loan book to read, so other families keep the empty default.
+ * @param allocations - Include DeFi/CeFi allocation breakdowns. Resolved for EVM
+ *   vaults (via DeBank) and Stellar vaults (via the Untangled portfolio API).
+ *   Solana and Sui have no vault-level portfolio provider and keep the empty
+ *   default.
  * @param options - RPC and service configuration
  * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
  *   caller already holds the row (e.g. `getVaults` fetched the whole list one

package/lib/modules/vaults/getters.js

@@ -110,8 +110,12 @@ const errors_1 = require("../../core/errors");
  * Routes to appropriate chain adapter (EVM v1/v2, Solana, or Stellar) based on vault version.
  * Optionally enriches with loan and allocation data.
  * @param vault - Vault contract address (EVM hex, Stellar C-address, or Solana program ID)
- * @param loans - Include active loan data
- * @param allocations - Include DeFi/CeFi allocation breakdowns
+ * @param loans - Include active loan data. EVM vaults only — there is no
+ *   non-EVM loan book to read, so other families keep the empty default.
+ * @param allocations - Include DeFi/CeFi allocation breakdowns. Resolved for EVM
+ *   vaults (via DeBank) and Stellar vaults (via the Untangled portfolio API).
+ *   Solana and Sui have no vault-level portfolio provider and keep the empty
+ *   default.
  * @param options - RPC and service configuration
  * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
  *   caller already holds the row (e.g. `getVaults` fetched the whole list one
@@ -153,24 +157,33 @@ async function getVault({ vault, loans = false, allocations = false, options, lo
         core_1.Logger.log.error('getVault', err, { vault });
         throw new Error(`#getVault::${vault}: ${err?.message}`);
     }
-    // Loans/allocations enrichment is only supported for EVM vaults.
-    // Non-EVM vaults already include empty defaults.
+    // Loans enrichment stays EVM-only — there is no non-EVM loan book to read.
+    // Allocations additionally covers Stellar, whose exposure resolves through the
+    // Untangled portfolio API rather than DeBank; gating it on `isEvmVault` left
+    // `getVaultAllocations` unreachable for the one chain family that needed the
+    // new path, so callers got the empty default while the standalone getter
+    // returned real data. Solana and Sui have no vault-level provider, so they
+    // keep the empty defaults.
     const isEvmVault = returnedVault.version !== 'sol-0' &&
         returnedVault.version !== 'stellar-0' &&
         returnedVault.version !== 'sui-0';
-    if (!isEvmVault && (loans || allocations)) {
-        core_1.Logger.log.warn('getVault', 'Loans/allocations enrichment is not supported for non-EVM vaults — skipping', { vault, version: returnedVault.version });
+    const supportsLoans = isEvmVault;
+    const supportsAllocations = isEvmVault || returnedVault.version === 'stellar-0';
+    const readLoans = loans && supportsLoans;
+    const readAllocations = allocations && supportsAllocations;
+    if ((loans && !supportsLoans) || (allocations && !supportsAllocations)) {
+        core_1.Logger.log.warn('getVault', 'Loans/allocations enrichment is not supported for this vault — skipping', { vault, version: returnedVault.version });
     }
-    if (isEvmVault && !(0, core_1.isBadVault)(vault) && (loans || allocations)) {
+    if (!(0, core_1.isBadVault)(vault) && (readLoans || readAllocations)) {
         const [loansResult, allocationsResult] = await Promise.allSettled([
-            loans
+            readLoans
                 ? getVaultLoans(returnedVault, options)
                 : Promise.resolve(undefined),
-            allocations
+            readAllocations
                 ? getVaultAllocations(vault, options)
                 : Promise.resolve(undefined),
         ]);
-        if (loans) {
+        if (readLoans) {
             if (loansResult.status === 'fulfilled') {
                 returnedVault = {
                     ...returnedVault,
@@ -183,7 +196,7 @@ async function getVault({ vault, loans = false, allocations = false, options, lo
                 });
             }
         }
-        if (allocations) {
+        if (readAllocations) {
             if (allocationsResult.status === 'fulfilled') {
                 returnedVault = {
                     ...returnedVault,

package/lib/sdk.d.ts

@@ -19372,8 +19372,12 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                   * Routes to appropriate chain adapter (EVM v1/v2, Solana, or Stellar) based on vault version.
                                   * Optionally enriches with loan and allocation data.
                                   * @param vault - Vault contract address (EVM hex, Stellar C-address, or Solana program ID)
-                                  * @param loans - Include active loan data
-                                  * @param allocations - Include DeFi/CeFi allocation breakdowns
+                                  * @param loans - Include active loan data. EVM vaults only — there is no
+                                  *   non-EVM loan book to read, so other families keep the empty default.
+                                  * @param allocations - Include DeFi/CeFi allocation breakdowns. Resolved for EVM
+                                  *   vaults (via DeBank) and Stellar vaults (via the Untangled portfolio API).
+                                  *   Solana and Sui have no vault-level portfolio provider and keep the empty
+                                  *   default.
                                   * @param options - RPC and service configuration
                                   * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
                                   *   caller already holds the row (e.g. `getVaults` fetched the whole list one

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

@@ -15,8 +15,9 @@
 export interface IUntangledProtocolExposure {
     /**
      * Untangled protocol slug, e.g. `blend`, `templar`, `aquarius`. Two slugs are
-     * not protocols: `stellar-wallet` (custody wallets) and `upshift` (the vault's
-     * own idle buffer).
+     * special: `stellar-wallet` is custody wallet cash, and `upshift` is the
+     * vault's own idle buffer plus any position it holds in another Upshift
+     * vault — only the part beyond the `idle` location is deployed capital.
      */
     protocolId: string;
     /** USD value held in this protocol. */

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

@@ -30,13 +30,20 @@ export declare const UNTANGLED_PROTOCOL_REGISTRY: Record<string, IUntangledProto
  * - Each `byProtocol` entry becomes one position with a single supplying token,
  *   valued in USD (`price: 1`), on the chain from
  *   {@link UNTANGLED_PROTOCOL_REGISTRY}.
- * - `stellar-wallet` and `upshift` are summed into one wallet token, because
- *   both are undeployed capital rather than protocol exposure.
+ * - `stellar-wallet` becomes a wallet token, because custody cash is undeployed
+ *   capital rather than protocol exposure.
+ * - `upshift` is split: the vault's own idle buffer (the `idle` location) joins
+ *   that wallet token, and whatever is left is a real position in another
+ *   Upshift vault, named after its receipt token. Untangled reports one
+ *   `upshift` slice however many vaults that is, so a vault holding receipts in
+ *   two others emits one merged position under the generic name — the value is
+ *   still right, only the label is coarser.
  * - Dust is left in place: `filterOutBySize` in the parser applies the same
  *   threshold Stellar and EVM vaults share.
  *
- * `locations`, `asOf`, `stale` and `tvlUsd` are not consumed — TVL already comes
- * from `getVaultTvl`, and freshness is not yet surfaced on `IVaultAllocations`.
+ * Only the `idle` entries of `locations` are consumed, to size the buffer inside
+ * `upshift`. `asOf`, `stale` and `tvlUsd` are not — TVL already comes from
+ * `getVaultTvl`, and freshness is not yet surfaced on `IVaultAllocations`.
  *
  * @param exposure - A resolved Untangled report, or `null`/`undefined` when the
  *   fetch failed.

package/lib/services/untangled/utils.js

@@ -14,14 +14,87 @@ exports.UNTANGLED_PROTOCOL_REGISTRY = {
     blend: { name: 'Blend', chain: 'stellar' },
     templar: { name: 'Templar (NEAR)', chain: 'near' },
     aquarius: { name: 'Aquarius', chain: 'stellar' },
+    upshift: { name: 'Upshift', chain: 'stellar' },
 };
 /**
- * Slugs that are not protocol positions: `stellar-wallet` is custody wallet
- * cash and `upshift` is the vault's own idle buffer. Both are undeployed
- * capital, which the exposure breakdown renders as wallet holdings — the same
- * treatment EVM vaults get for funds sitting outside a protocol.
+ * Custody wallet cash — undeployed capital, which the exposure breakdown renders
+ * as wallet holdings, the same treatment EVM vaults get for funds sitting
+ * outside a protocol.
  */
-const WALLET_PROTOCOL_IDS = new Set(['stellar-wallet', 'upshift']);
+const CUSTODY_WALLET_PROTOCOL_ID = 'stellar-wallet';
+/**
+ * Capital held inside Upshift itself. This slug is NOT purely idle: it is the
+ * vault's own idle buffer PLUS any receipt tokens the vault holds in another
+ * Upshift vault. Gami earnXLM on 2026-09-11 reported `upshift: $1,371,484` made
+ * up of a `$200,572` idle buffer and `$1,170,913` of earnUSDC shares — counting
+ * all of it as idle hid a third of the vault's deployed capital and overstated
+ * the idle bucket almost sixfold.
+ */
+const UPSHIFT_PROTOCOL_ID = 'upshift';
+/** `locations[].label` for the capital still sitting in the vault contract. */
+const IDLE_LOCATION_LABEL = 'idle';
+/** Tightness of the `byAsset` lookup in {@link matchingAssetSymbol}. */
+const ASSET_MATCH_TOLERANCE = 0.001;
+/**
+ * Smallest `upshift` remainder treated as a real position rather than as float
+ * disagreement between the `idle` location and the `byProtocol` slice. One cent
+ * sits orders of magnitude above double-precision noise on million-dollar
+ * values and orders of magnitude below any holding worth naming.
+ */
+const MIN_POSITION_USD = 0.01;
+/**
+ * USD the vault holds in its own contract, summed from the `idle` locations.
+ *
+ * Returns `null` when no location carries that label, so a caller can tell
+ * "nothing is idle" from "this report does not say".
+ *
+ * The whole sum is charged against the `upshift` slice, which assumes idle
+ * capital never belongs to another protocol. That holds for the shape Untangled
+ * serves — the buffer sitting in the vault contract is exactly what it files
+ * under `upshift` — and the `Math.min` at the call site caps the subtraction, so
+ * a report that broke the assumption would understate the position rather than
+ * invent one.
+ */
+function idleLocationUsd(exposure) {
+    let total = null;
+    (exposure.locations || []).forEach((location) => {
+        if (location?.label?.toLowerCase() !== IDLE_LOCATION_LABEL)
+            return;
+        total = (total ?? 0) + (Number(location.valueUsd) || 0);
+    });
+    return total;
+}
+/**
+ * The `byAsset` symbol whose value matches this position's, within
+ * {@link ASSET_MATCH_TOLERANCE}.
+ *
+ * Untangled splits assets vault-wide, so a position's asset can normally only be
+ * guessed. A vault's holding in another Upshift vault is the exception: the
+ * receipt token is its own `byAsset` entry carrying exactly that position's
+ * value, so it can be named instead of falling back to the vault's dominant
+ * asset.
+ *
+ * This only ever chooses a *label* — the USD value is taken from `byProtocol`
+ * either way — so it is built to abstain rather than guess. Two cases reach it
+ * legitimately and get no answer: a vault holding receipts in two other Upshift
+ * vaults, which Untangled reports as one `upshift` slice whose remainder matches
+ * neither entry on its own, and a remainder small enough that the relative
+ * window closes around rounding noise.
+ *
+ * @param valueUsd - The position's USD value. The caller has already cleared it
+ *   past {@link MIN_POSITION_USD}, so the relative window is never taken around
+ *   zero.
+ * @returns The matching symbol, or `null` when no entry matches or more than one
+ *   does — the caller names the position generically instead.
+ */
+function matchingAssetSymbol(exposure, valueUsd) {
+    const matches = (exposure.byAsset || []).filter((asset) => {
+        const assetUsd = Number(asset?.valueUsd) || 0;
+        return (assetUsd > 0 &&
+            Math.abs(assetUsd - valueUsd) <= valueUsd * ASSET_MATCH_TOLERANCE);
+    });
+    return matches.length === 1 ? matches[0].symbol || null : null;
+}
 const DEFAULT_CHAIN = 'stellar';
 /**
  * Stellar's asset precision, carried only to satisfy the DeBank token shape.
@@ -78,13 +151,20 @@ function dominantAssetSymbol(exposure) {
  * - Each `byProtocol` entry becomes one position with a single supplying token,
  *   valued in USD (`price: 1`), on the chain from
  *   {@link UNTANGLED_PROTOCOL_REGISTRY}.
- * - `stellar-wallet` and `upshift` are summed into one wallet token, because
- *   both are undeployed capital rather than protocol exposure.
+ * - `stellar-wallet` becomes a wallet token, because custody cash is undeployed
+ *   capital rather than protocol exposure.
+ * - `upshift` is split: the vault's own idle buffer (the `idle` location) joins
+ *   that wallet token, and whatever is left is a real position in another
+ *   Upshift vault, named after its receipt token. Untangled reports one
+ *   `upshift` slice however many vaults that is, so a vault holding receipts in
+ *   two others emits one merged position under the generic name — the value is
+ *   still right, only the label is coarser.
  * - Dust is left in place: `filterOutBySize` in the parser applies the same
  *   threshold Stellar and EVM vaults share.
  *
- * `locations`, `asOf`, `stale` and `tvlUsd` are not consumed — TVL already comes
- * from `getVaultTvl`, and freshness is not yet surfaced on `IVaultAllocations`.
+ * Only the `idle` entries of `locations` are consumed, to size the buffer inside
+ * `upshift`. `asOf`, `stale` and `tvlUsd` are not — TVL already comes from
+ * `getVaultTvl`, and freshness is not yet surfaced on `IVaultAllocations`.
  *
  * @param exposure - A resolved Untangled report, or `null`/`undefined` when the
  *   fetch failed.
@@ -106,20 +186,48 @@ function transformUntangledToDebank(exposure) {
     }
     const symbol = dominantAssetSymbol(exposure);
     const vaultChain = exposure.vault?.chain || DEFAULT_CHAIN;
+    const idleUsd = idleLocationUsd(exposure);
     const positions = [];
     let walletValueUsd = 0;
     (exposure.byProtocol || []).forEach((entry) => {
         if (!entry?.protocolId)
             return;
         const valueUsd = Number(entry.valueUsd) || 0;
-        if (WALLET_PROTOCOL_IDS.has(entry.protocolId)) {
+        if (entry.protocolId === CUSTODY_WALLET_PROTOCOL_ID) {
             walletValueUsd += valueUsd;
             return;
         }
+        let positionUsd = valueUsd;
+        let positionSymbol = symbol;
+        let receiptSymbol = null;
+        if (entry.protocolId === UPSHIFT_PROTOCOL_ID) {
+            // A report with no idle location cannot say how much of this is the
+            // buffer, so it claims the whole slice. That leaves a remainder of exactly
+            // zero, which the guard below turns back into the pre-split behaviour —
+            // the two are coupled, so don't change one without the other.
+            const idleShare = idleUsd === null ? valueUsd : Math.min(valueUsd, idleUsd);
+            positionUsd = valueUsd - idleShare;
+            // The buffer reaches us twice, from two different fields, so a vault that
+            // holds nothing in another Upshift vault can still leave a sub-cent
+            // remainder behind. That is disagreement between the fields, not a
+            // position: keep the slice whole in the wallet bucket rather than emit a
+            // phantom the parser's size filter would have to clean up. Genuine dust is
+            // still passed through for that filter to judge.
+            if (positionUsd < MIN_POSITION_USD) {
+                walletValueUsd += valueUsd;
+                return;
+            }
+            walletValueUsd += idleShare;
+            receiptSymbol = matchingAssetSymbol(exposure, positionUsd);
+            positionSymbol = receiptSymbol ?? symbol;
+        }
         const metadata = exports.UNTANGLED_PROTOCOL_REGISTRY[entry.protocolId];
         const chain = metadata?.chain || vaultChain;
-        const name = metadata?.name ||
+        const baseName = metadata?.name ||
             entry.protocolId.charAt(0).toUpperCase() + entry.protocolId.slice(1);
+        // "Upshift" alone reads as the whole product inside Upshift's own UI, so the
+        // slice names the vault it sits in whenever the receipt token identifies it.
+        const name = receiptSymbol ? `${baseName} (${receiptSymbol})` : baseName;
         positions.push({
             id: entry.protocolId,
             chain,
@@ -130,13 +238,13 @@ function transformUntangledToDebank(exposure) {
                 {
                     name,
                     stats: {
-                        asset_usd_value: valueUsd,
+                        asset_usd_value: positionUsd,
                         debt_usd_value: 0,
-                        net_usd_value: valueUsd,
+                        net_usd_value: positionUsd,
                     },
                     detail: {
                         supply_token_list: [
-                            toDebankToken(symbol, chain, valueUsd, 'supply', entry.protocolId),
+                            toDebankToken(positionSymbol, chain, positionUsd, 'supply', entry.protocolId),
                         ],
                         borrow_token_list: [],
                     },

package/package.json

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