@augustdigital/sdk 9.2.2 → 9.4.0

package/lib/services/subgraph/schema.d.ts

@@ -28,7 +28,7 @@ export declare function isSubgraphSchemaFieldError(errors: {
  * `august-citrea-earn-ctusd`). A wrong guess made every subgraph read query
  * non-existent field names, so the subgraph returned GraphQL errors with no
  * `data` and the SDK silently returned empty sets — emptying the Pending
- * Withdrawals and History tabs for that vault (AUGUST-6568).
+ * Withdrawals and History tabs for that vault.
  *
  * Because the schema is immutable for a fixed subgraph deployment, the result is
  * cached per URL ({@link SCHEMA_TTL_MS}); across a page's positions/history/

package/lib/services/subgraph/schema.js

@@ -28,7 +28,7 @@ function isSubgraphSchemaFieldError(errors) {
  * `august-citrea-earn-ctusd`). A wrong guess made every subgraph read query
  * non-existent field names, so the subgraph returned GraphQL errors with no
  * `data` and the SDK silently returned empty sets — emptying the Pending
- * Withdrawals and History tabs for that vault (AUGUST-6568).
+ * Withdrawals and History tabs for that vault.
  *
  * Because the schema is immutable for a fixed subgraph deployment, the result is
  * cached per URL ({@link SCHEMA_TTL_MS}); across a page's positions/history/

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/pools.d.ts

@@ -111,7 +111,7 @@ export type IPoolWithPositions = IPoolWithUnderlying & {
     redeemable: INormalizedNumber;
     walletBalance: string;
 };
-export type IPoolFunctions = 'decimals' | 'symbol' | 'name' | 'asset' | 'totalSupply' | 'maxSupply' | 'totalAssets' | 'globalLoansAmount' | 'loansOperator' | 'getTotalLoansDeployed' | 'withdrawalFee' | 'lagDuration' | 'withdrawalsPaused' | 'assetsWhitelistAddress' | 'getWhitelistedAssets' | 'maxDepositAmount' | 'getTotalAssets' | 'lpTokenAddress' | 'depositCap';
+export type IPoolFunctions = 'decimals' | 'symbol' | 'name' | 'asset' | 'totalSupply' | 'maxSupply' | 'totalAssets' | 'globalLoansAmount' | 'loansOperator' | 'getTotalLoansDeployed' | 'withdrawalFee' | 'lagDuration' | 'withdrawalsPaused' | 'depositsPaused' | 'assetsWhitelistAddress' | 'getWhitelistedAssets' | 'maxDepositAmount' | 'getTotalAssets' | 'lpTokenAddress' | 'depositCap';
 export type IPoolAction = 'deposit' | 'withdraw' | 'claim' | 'stake' | 'getReward' | 'unstake';
 export type IPoolModal = {
     isOpen: boolean;

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[];
@@ -166,7 +176,7 @@ export interface IVaultAllocations {
  *
  * This is stated explicitly because the convention going undocumented let a
  * consumer scale a subset of these fields twice, making them contribute 1/100th of
- * their value to a displayed total (AUGUST-6967). The unit is uniform here by
+ * their value to a displayed total. The unit is uniform here by
  * design; treating some of these fields as decimals and others as percentages is
  * always a bug on the consumer side.
  */
@@ -457,16 +467,16 @@ export interface IVaultPnl {
  * Supported Vaults: cUSDO, tETH, wstETH, rsETH
  *
  * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` fields are deprecated.
- * These fields will be removed on 2026-01-01.
+ * These fields will be removed in the next major release.
  * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
  */
 export interface IVaultAnnualizedApy {
     vaultAddress: IAddress;
     liquidityApy: number;
     annualizedApy: number;
-    /** @deprecated Use `liquidAPY7Day` instead. Will be removed on 2026-01-01. */
+    /** @deprecated Use `liquidAPY7Day` instead. Will be removed in the next major release. */
     hgETH7dLiquidAPY?: number;
-    /** @deprecated Use `liquidAPY30Day` instead. Will be removed on 2026-01-01. */
+    /** @deprecated Use `liquidAPY30Day` instead. Will be removed in the next major release. */
     hgETH30dLiquidAPY?: number;
     liquidAPY7Day?: number;
     liquidAPY30Day?: number;

package/package.json

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