@augustdigital/sdk 9.2.1 → 9.3.0

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.1";
+export declare const SDK_VERSION = "9.3.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 = '9.2.1';
+exports.SDK_VERSION = '9.3.0';
 //# sourceMappingURL=version.js.map

package/lib/modules/vaults/getters.js

@@ -480,6 +480,16 @@ async function getVaultAllocations(vault, options) {
     const netValue = { value: 0 };
     let debankErr = false;
     let unfilteredTokens = [];
+    // Untangled publishes the vault's asset composition as its own decomposition of
+    // tvlUsd, with no join to `byProtocol`. It therefore cannot be accumulated into
+    // `tokenExposure` alongside the synthesized position tokens without
+    // double-counting, so it replaces those rows below for Stellar vaults.
+    let untangledAssets = null;
+    // How much of `tokenExposure` the Untangled parse produced. Only that prefix is
+    // replaced: the accumulator is shared with the per-borrower loop that runs
+    // afterwards, and a borrower on a chain with portfolio coverage would otherwise
+    // have its rows silently dropped rather than double-counted.
+    let untangledTokenCount = 0;
     const borrowerPortfolioFetchers = {
         solana: async (borrower) => {
             const portfolios = await (0, octavfi_1.fetchOctavfiPortfolios)([borrower]);
@@ -567,6 +577,8 @@ async function getVaultAllocations(vault, options) {
                 const untangledRes = (0, untangled_1.transformUntangledToDebank)(untangledExposure);
                 (0, debank_1.parseVaultLevelDebank)(untangledRes, protocolExposure, tokenExposure, vault, exposurePerCategory, netValue);
                 unfilteredTokens = untangledRes.subaccount.tokens;
+                untangledAssets = (0, untangled_1.untangledAssetExposure)(untangledExposure);
+                untangledTokenCount = tokenExposure.length;
                 defiPerBorrower[vault] = (0, debank_1.parseLoanLevelDebank)(untangledRes);
             }
         }
@@ -658,7 +670,9 @@ async function getVaultAllocations(vault, options) {
         defi: protocolExposure,
         cefi: cefiExposure,
         otc: otcPositions,
-        tokens: tokenExposure,
+        tokens: untangledAssets?.length
+            ? [...untangledAssets, ...tokenExposure.slice(untangledTokenCount)]
+            : tokenExposure,
         defiPerBorrower,
         exposurePerCategory,
         netValue: netValue.value,

package/lib/sdk.d.ts

@@ -23170,6 +23170,16 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                   */
                                  export declare interface IVaultAllocations {
                                      defi: IDebankProtocolExposure[];
+                                     /**
+                                      * The vault's asset composition, in USD (`amount` is a dollar value).
+                                      *
+                                      * On Stellar this is Untangled's `byAsset` breakdown, which decomposes the
+                                      * same `tvlUsd` that `defi` does along a different axis — assets rather than
+                                      * venues. The two do not join: which venue holds which asset is not published,
+                                      * so this is the only place a Stellar vault's assets are stated, and reading a
+                                      * per-venue asset split out of `exposurePerCategory` is not supported for
+                                      * multi-asset Stellar vaults.
+                                      */
                                      tokens: IDebankTokenExposure[];
                                      cefi: IWSSubaccountCefi[];
                                      unfilteredTokens: IDebankTokenExposure[];

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

@@ -1,3 +1,4 @@
+import type { IDebankTokenExposure } from '../../types';
 import type { IDebankNormalizedResponse } from '../debank/utils';
 import type { IUntangledVaultExposure } from './types';
 /** Display metadata for an Untangled protocol slug. */
@@ -16,6 +17,31 @@ export interface IUntangledProtocolMetadata {
  * instead of silently vanishing from the breakdown.
  */
 export declare const UNTANGLED_PROTOCOL_REGISTRY: Record<string, IUntangledProtocolMetadata>;
+/**
+ * The vault's asset composition, as vault-level token exposure.
+ *
+ * This is the one asset breakdown Untangled actually publishes, and it is
+ * authoritative: `byAsset` decomposes the same `tvlUsd` that `byProtocol` does.
+ * It is returned separately from {@link transformUntangledToDebank} because it
+ * cannot be folded into that structure — attributing an asset to a position
+ * would require a join the API does not provide, and adding these on top of the
+ * synthesized position tokens would double-count the vault.
+ *
+ * Negative rows are kept. A vault that has moved capital into another Upshift
+ * vault is reported holding the receipt token and owing the asset it spent —
+ * earnXLM carries `earnUSDC +$1,170,913` against `USDC -$1,170,271` — and those
+ * only sum back to `tvlUsd` together. Dropping the liability would overstate the
+ * vault's assets by the full size of the position.
+ *
+ * @param exposure - A resolved Untangled report, or `null`/`undefined` when the
+ *   fetch failed.
+ * @returns One row per asset clearing `filterOutBySize` in absolute terms,
+ *   largest first, with `amount` denominated in USD. Empty when `exposure` is
+ *   absent. `id` carries the asset symbol rather than an address — Untangled
+ *   reports assets by ticker and publishes no contract address for them — so it
+ *   is safe as a display key and must not be read as an on-chain address.
+ */
+export declare function untangledAssetExposure(exposure: IUntangledVaultExposure | null | undefined): IDebankTokenExposure[];
 /**
  * Transform an Untangled vault exposure report into the DeBank-normalized shape
  * that `parseVaultLevelDebank` and `parseLoanLevelDebank` consume.
@@ -29,14 +55,24 @@ export declare const UNTANGLED_PROTOCOL_REGISTRY: Record<string, IUntangledProto
  * Mapping:
  * - 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.
+ *   {@link UNTANGLED_PROTOCOL_REGISTRY}. The token is labelled with the vault's
+ *   asset only when one asset covers essentially all of it (see
+ *   {@link vaultAssetSymbol}); otherwise it carries the value with no symbol,
+ *   and {@link untangledAssetExposure} supplies the composition separately.
+ * - `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

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UNTANGLED_PROTOCOL_REGISTRY = void 0;
+exports.untangledAssetExposure = untangledAssetExposure;
 exports.transformUntangledToDebank = transformUntangledToDebank;
+const core_1 = require("../../core/helpers/core");
 /**
  * Display metadata for the protocol slugs Untangled reports today.
  *
@@ -14,14 +16,98 @@ 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;
+/**
+ * Share of `tvlUsd` the largest `byAsset` entry must cover before a synthesized
+ * position may be labelled with it.
+ *
+ * `byProtocol` and `byAsset` are two orthogonal decompositions of the same TVL,
+ * and Untangled publishes no join between them, so which venue holds which asset
+ * is genuinely unknown. Tagging every position with the largest asset is only
+ * honest when there is effectively nothing else in the vault; below that, the
+ * label would assert a holding the report does not support.
+ */
+const SINGLE_ASSET_SHARE = 0.99;
+/**
+ * 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.
@@ -34,14 +120,19 @@ const SYNTHETIC_TOKEN_DECIMALS = 7;
  *
  * `parseVaultLevelDebank` computes USD as `price * amount`, so a value already
  * denominated in dollars is expressed as `price: 1, amount: <usd>`.
+ *
+ * @param symbol - The asset this slice holds, or `null` when the report cannot
+ *   say. A null symbol still produces a token — the value has to reach
+ *   `netValue` and the protocol totals either way — but carries no asset label,
+ *   so consumers render the slice's value without naming an asset.
  */
 function toDebankToken(symbol, chain, valueUsd, exposureType, protocolId) {
     return {
-        id: symbol,
+        id: symbol ?? '',
         chain,
-        name: symbol,
-        symbol,
-        optimized_symbol: symbol,
+        name: symbol ?? '',
+        symbol: symbol ?? '',
+        optimized_symbol: symbol ?? '',
         decimals: SYNTHETIC_TOKEN_DECIMALS,
         logo_url: '',
         amount: valueUsd,
@@ -51,18 +142,71 @@ function toDebankToken(symbol, chain, valueUsd, exposureType, protocolId) {
     };
 }
 /**
- * The asset holding most of the vault's value.
+ * The symbol every synthesized position may be tagged with, or `null` when the
+ * report cannot support tagging them at all.
  *
- * Untangled splits assets vault-wide rather than per protocol, so every
- * synthesized position is tagged with this one symbol. For the Gami vaults it is
- * an exact description (earnUSDC is ~100% USDC); an exact per-protocol split
- * needs `byProtocol[].assets[]` from Untangled.
+ * Untangled splits assets vault-wide rather than per protocol, so the only
+ * defensible label is the dominant asset, and only while it covers essentially
+ * the whole vault ({@link SINGLE_ASSET_SHARE}). Gami earnXLM qualifies (99.98%
+ * XLM); earnUSDC does not (84.18% USDC, 15.82% deJTRSY), and labelling its
+ * positions USDC claimed the whole $25.3M was USDC while $4.0M of deJTRSY went
+ * unmentioned. Callers that get `null` emit no asset label and let
+ * {@link untangledAssetExposure} carry the composition instead.
+ *
+ * An exact per-protocol split needs `byProtocol[].assets[]` from Untangled.
  */
-function dominantAssetSymbol(exposure) {
+function vaultAssetSymbol(exposure) {
     const dominant = (exposure.byAsset || []).reduce((best, asset) => !best || Number(asset?.valueUsd || 0) > Number(best.valueUsd || 0)
         ? asset
         : best, null);
-    return dominant?.symbol || 'UNKNOWN';
+    if (!dominant?.symbol)
+        return null;
+    const tvlUsd = Number(exposure.tvlUsd) || 0;
+    if (tvlUsd <= 0)
+        return null;
+    const share = (Number(dominant.valueUsd) || 0) / tvlUsd;
+    return share >= SINGLE_ASSET_SHARE ? dominant.symbol : null;
+}
+/**
+ * The vault's asset composition, as vault-level token exposure.
+ *
+ * This is the one asset breakdown Untangled actually publishes, and it is
+ * authoritative: `byAsset` decomposes the same `tvlUsd` that `byProtocol` does.
+ * It is returned separately from {@link transformUntangledToDebank} because it
+ * cannot be folded into that structure — attributing an asset to a position
+ * would require a join the API does not provide, and adding these on top of the
+ * synthesized position tokens would double-count the vault.
+ *
+ * Negative rows are kept. A vault that has moved capital into another Upshift
+ * vault is reported holding the receipt token and owing the asset it spent —
+ * earnXLM carries `earnUSDC +$1,170,913` against `USDC -$1,170,271` — and those
+ * only sum back to `tvlUsd` together. Dropping the liability would overstate the
+ * vault's assets by the full size of the position.
+ *
+ * @param exposure - A resolved Untangled report, or `null`/`undefined` when the
+ *   fetch failed.
+ * @returns One row per asset clearing `filterOutBySize` in absolute terms,
+ *   largest first, with `amount` denominated in USD. Empty when `exposure` is
+ *   absent. `id` carries the asset symbol rather than an address — Untangled
+ *   reports assets by ticker and publishes no contract address for them — so it
+ *   is safe as a display key and must not be read as an on-chain address.
+ */
+function untangledAssetExposure(exposure) {
+    if (!exposure)
+        return [];
+    const chain = exposure.vault?.chain || DEFAULT_CHAIN;
+    return (exposure.byAsset || [])
+        .filter((asset) => asset?.symbol && (0, core_1.filterOutBySize)(Math.abs(Number(asset.valueUsd) || 0)))
+        .map((asset) => ({
+        amount: Number(asset.valueUsd) || 0,
+        chain,
+        decimals: SYNTHETIC_TOKEN_DECIMALS,
+        id: asset.symbol,
+        logoUrl: '',
+        name: asset.symbol,
+        symbol: asset.symbol,
+    }))
+        .sort((a, b) => b.amount - a.amount);
 }
 /**
  * Transform an Untangled vault exposure report into the DeBank-normalized shape
@@ -77,14 +221,24 @@ function dominantAssetSymbol(exposure) {
  * Mapping:
  * - 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.
+ *   {@link UNTANGLED_PROTOCOL_REGISTRY}. The token is labelled with the vault's
+ *   asset only when one asset covers essentially all of it (see
+ *   {@link vaultAssetSymbol}); otherwise it carries the value with no symbol,
+ *   and {@link untangledAssetExposure} supplies the composition separately.
+ * - `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.
@@ -104,22 +258,50 @@ function transformUntangledToDebank(exposure) {
     if (!exposure) {
         return { subaccount: { positions: [], tokens: [] } };
     }
-    const symbol = dominantAssetSymbol(exposure);
+    const symbol = vaultAssetSymbol(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 +312,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/lib/types/vaults.d.ts

@@ -143,6 +143,16 @@ export type IExposurePerCategory = {
  */
 export interface IVaultAllocations {
     defi: IDebankProtocolExposure[];
+    /**
+     * The vault's asset composition, in USD (`amount` is a dollar value).
+     *
+     * On Stellar this is Untangled's `byAsset` breakdown, which decomposes the
+     * same `tvlUsd` that `defi` does along a different axis — assets rather than
+     * venues. The two do not join: which venue holds which asset is not published,
+     * so this is the only place a Stellar vault's assets are stated, and reading a
+     * per-venue asset split out of `exposurePerCategory` is not supported for
+     * multi-asset Stellar vaults.
+     */
     tokens: IDebankTokenExposure[];
     cefi: IWSSubaccountCefi[];
     unfilteredTokens: IDebankTokenExposure[];

package/package.json

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