@augustdigital/sdk 9.2.2 → 9.3.0

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.2";
+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.2';
+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/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,7 +55,10 @@ 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}.
+ *   {@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

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.
  *
@@ -42,6 +44,17 @@ const ASSET_MATCH_TOLERANCE = 0.001;
  * 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.
  *
@@ -107,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,
@@ -124,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
@@ -150,7 +221,10 @@ 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}.
+ *   {@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
@@ -184,7 +258,7 @@ 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 = [];

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.2",
+  "version": "9.3.0",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [