@upshiftfinance/sdk 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,91 @@
+import type { IDebankTokenExposure } from '../../types';
+import type { IDebankNormalizedResponse } from '../debank/utils';
+import type { IUntangledVaultExposure } from './types';
+/** Display metadata for an Untangled protocol slug. */
+export interface IUntangledProtocolMetadata {
+    /** Name rendered in the exposure breakdown. */
+    name: string;
+    /** Chain the protocol position lives on — not always the vault's own chain. */
+    chain: string;
+}
+/**
+ * Display metadata for the protocol slugs Untangled reports today.
+ *
+ * Untangled does not return protocol names or chains, so they are mapped here.
+ * Unknown slugs fall back to a capitalized slug on the vault's chain rather than
+ * being dropped, so a newly integrated protocol still shows up (unlabelled)
+ * 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.
+ *
+ * This is the Stellar equivalent of `transformOctavfiToDebank`: a foreign
+ * portfolio shape is mapped onto the one normalized structure the vault
+ * allocation parser understands, so Stellar vaults populate the same
+ * `exposurePerCategory` / `protocolExposure` / `tokenExposure` outputs as EVM
+ * vaults with no parser changes.
+ *
+ * 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}. 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.
+ *
+ * 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.
+ * @returns A DeBank-normalized response. Empty positions and tokens when
+ *   `exposure` is absent, so callers can pass a failed fetch straight through.
+ *
+ * @example
+ * ```typescript
+ * const exposure = await fetchUntangledVaultExposure(vault);
+ * const normalized = transformUntangledToDebank(exposure);
+ * parseVaultLevelDebank(
+ *   normalized, protocolExposure, tokenExposure, vault, exposurePerCategory, netValue,
+ * );
+ * ```
+ */
+export declare function transformUntangledToDebank(exposure: IUntangledVaultExposure | null | undefined): IDebankNormalizedResponse;

package/lib/services/untangled/utils.js

@@ -0,0 +1,339 @@
+"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.
+ *
+ * Untangled does not return protocol names or chains, so they are mapped here.
+ * Unknown slugs fall back to a capitalized slug on the vault's chain rather than
+ * being dropped, so a newly integrated protocol still shows up (unlabelled)
+ * instead of silently vanishing from the breakdown.
+ */
+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' },
+};
+/**
+ * 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 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.
+ * The synthesized tokens hold USD values (`price: 1`), so no consumer scales by
+ * this.
+ */
+const SYNTHETIC_TOKEN_DECIMALS = 7;
+/**
+ * Build a DeBank-shaped token carrying a USD value.
+ *
+ * `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 ?? '',
+        chain,
+        name: symbol ?? '',
+        symbol: symbol ?? '',
+        optimized_symbol: symbol ?? '',
+        decimals: SYNTHETIC_TOKEN_DECIMALS,
+        logo_url: '',
+        amount: valueUsd,
+        price: 1,
+        protocol_id: protocolId ?? '',
+        supplying_exposure: exposureType === 'supply' ? 'true' : undefined,
+    };
+}
+/**
+ * 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 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 vaultAssetSymbol(exposure) {
+    const dominant = (exposure.byAsset || []).reduce((best, asset) => !best || Number(asset?.valueUsd || 0) > Number(best.valueUsd || 0)
+        ? asset
+        : best, null);
+    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
+ * that `parseVaultLevelDebank` and `parseLoanLevelDebank` consume.
+ *
+ * This is the Stellar equivalent of `transformOctavfiToDebank`: a foreign
+ * portfolio shape is mapped onto the one normalized structure the vault
+ * allocation parser understands, so Stellar vaults populate the same
+ * `exposurePerCategory` / `protocolExposure` / `tokenExposure` outputs as EVM
+ * vaults with no parser changes.
+ *
+ * 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}. 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.
+ *
+ * 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.
+ * @returns A DeBank-normalized response. Empty positions and tokens when
+ *   `exposure` is absent, so callers can pass a failed fetch straight through.
+ *
+ * @example
+ * ```typescript
+ * const exposure = await fetchUntangledVaultExposure(vault);
+ * const normalized = transformUntangledToDebank(exposure);
+ * parseVaultLevelDebank(
+ *   normalized, protocolExposure, tokenExposure, vault, exposurePerCategory, netValue,
+ * );
+ * ```
+ */
+function transformUntangledToDebank(exposure) {
+    if (!exposure) {
+        return { subaccount: { positions: [], tokens: [] } };
+    }
+    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 (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 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,
+            name,
+            logo_url: '',
+            site_url: '',
+            portfolio_item_list: [
+                {
+                    name,
+                    stats: {
+                        asset_usd_value: positionUsd,
+                        debt_usd_value: 0,
+                        net_usd_value: positionUsd,
+                    },
+                    detail: {
+                        supply_token_list: [
+                            toDebankToken(positionSymbol, chain, positionUsd, 'supply', entry.protocolId),
+                        ],
+                        borrow_token_list: [],
+                    },
+                },
+            ],
+        });
+    });
+    const tokens = [];
+    if (walletValueUsd > 0) {
+        tokens.push({
+            ...toDebankToken(symbol, vaultChain, walletValueUsd, 'wallet'),
+            is_wallet: true,
+            is_core: true,
+        });
+    }
+    return { subaccount: { positions, tokens } };
+}
+//# sourceMappingURL=utils.js.map