@strkfarm/sdk 2.0.0-dev.26 → 2.0.0-dev.28

package/src/utils/starknet-call-parser.ts

@@ -0,0 +1,1036 @@
+import { hash, uint256 } from "starknet";
+import type { Call } from "starknet";
+import { ContractAddr, Web3Number } from "@/dataTypes";
+import type { TokenInfo } from "@/interfaces";
+import type { ManageCall } from "@/strategies/universal-adapters/baseAdapter";
+import { logger } from "./logger";
+
+type DecoderEntry = {
+  label: string;
+  decode: (
+    calldata: string[],
+    options: StarknetCallParserOptions,
+  ) => unknown;
+};
+
+export type ParsedStarknetCall = {
+  target: string;
+  method: string;
+  selector?: string;
+  sanitizer?: string;
+  decodedArgs: unknown;
+  rawCalldata: string[];
+  parserUsed: string;
+  parseError?: string;
+};
+
+export type StarknetCallParserOptions = {
+  tokenSymbols?: Record<string, string>;
+  tokenDecimals?: Record<string, number>;
+  poolNames?: Record<string, string>;
+};
+
+/**
+ * Integration guide for new methods/protocols:
+ * 1) Add method name to METHOD_BY_SELECTOR if it comes from ManageCall selector.
+ * 2) Add a decoder in METHOD_DECODERS with a focused decode* method.
+ * 3) Keep decoder output concise and operator-friendly.
+ * 4) Prefer existing primitives (ContractAddr, uint256, Web3Number where needed).
+ * 5) Add/extend tests in test/starknet-call-parser.test.ts for parse + log behavior.
+ */
+export class StarknetCallParser {
+  private static readonly METHOD_DECODERS: Record<string, DecoderEntry[]> = {
+    modify_lever: [
+      {
+        label: "vesu-multiple",
+        decode: (calldata, options) =>
+          StarknetCallParser.decodeModifyLever(calldata, options),
+      },
+    ],
+    modify_delegation: [
+      {
+        label: "vesu-pool-v2",
+        decode: (calldata) =>
+          StarknetCallParser.decodeModifyDelegation(calldata, true),
+      },
+      {
+        label: "vesu-singleton",
+        decode: (calldata) =>
+          StarknetCallParser.decodeModifyDelegation(calldata, false),
+      },
+    ],
+    modify_position: [
+      {
+        label: "vesu-modify-position",
+        decode: (calldata, options) =>
+          StarknetCallParser.decodeModifyPosition(calldata, options),
+      },
+    ],
+    approve: [
+      {
+        label: "erc20",
+        decode: (calldata) => StarknetCallParser.decodeApprove(calldata),
+      },
+    ],
+    flash_loan: [
+      {
+        label: "vault-manager",
+        decode: (calldata) => StarknetCallParser.decodeFlashLoan(calldata),
+      },
+    ],
+    bring_liquidity: [
+      {
+        label: "universal-vault",
+        decode: (calldata) => StarknetCallParser.decodeBringLiquidity(calldata),
+      },
+    ],
+    manage_vault_with_merkle_verification: [
+      {
+        label: "vault-manager",
+        decode: (calldata, options) =>
+          StarknetCallParser.decodeManageVaultWithMerkleVerification(
+            calldata,
+            options,
+          ),
+      },
+    ],
+    multi_route_swap: [
+      {
+        label: "avnu",
+        decode: (calldata, options) =>
+          StarknetCallParser.decodeMultiRouteSwap(calldata, options),
+      },
+    ],
+  };
+
+  private static readonly METHOD_BY_SELECTOR: Map<string, string> = new Map(
+    [
+      "modify_lever",
+      "modify_delegation",
+      "modify_position",
+      "approve",
+      "flash_loan",
+      "bring_liquidity",
+      "manage_vault_with_merkle_verification",
+      "multi_route_swap",
+    ].map((method) => [
+      StarknetCallParser.normalizeHex(hash.getSelectorFromName(method)),
+      method,
+    ]),
+  );
+
+  static parseManageCall(
+    manageCall: ManageCall,
+    options: StarknetCallParserOptions = {},
+  ): ParsedStarknetCall {
+    const selector = StarknetCallParser.normalizeHex(manageCall.call.selector);
+    const method =
+      StarknetCallParser.METHOD_BY_SELECTOR.get(selector) ??
+      `unknown_selector_${selector}`;
+    const target = StarknetCallParser.addressToString(
+      manageCall.call.contractAddress,
+    );
+    const sanitizer = StarknetCallParser.addressToString(manageCall.sanitizer);
+
+    return StarknetCallParser.parseRaw({
+      method,
+      target,
+      selector,
+      sanitizer,
+      calldata: manageCall.call.calldata,
+      options,
+    });
+  }
+
+  static parseManageCalls(
+    manageCalls: ManageCall[],
+    options: StarknetCallParserOptions = {},
+  ): ParsedStarknetCall[] {
+    return manageCalls.map((call) =>
+      StarknetCallParser.parseManageCall(call, options),
+    );
+  }
+
+  static parseCall(
+    call: Call,
+    options: StarknetCallParserOptions = {},
+  ): ParsedStarknetCall {
+    return StarknetCallParser.parseRaw({
+      method: call.entrypoint,
+      target: StarknetCallParser.addressToString(call.contractAddress),
+      calldata: call.calldata,
+      options,
+    });
+  }
+
+  static parseCalls(
+    calls: Call[],
+    options: StarknetCallParserOptions = {},
+  ): ParsedStarknetCall[] {
+    return calls.map((call) => StarknetCallParser.parseCall(call, options));
+  }
+
+  static logManageCalls(
+    context: string,
+    manageCalls: ManageCall[],
+    options: StarknetCallParserOptions = {},
+  ): void {
+    logger.debug(
+      StarknetCallParser.formatManageCallsSummary(context, manageCalls, options),
+    );
+  }
+
+  static logCalls(
+    context: string,
+    calls: Call[],
+    options: StarknetCallParserOptions = {},
+  ): void {
+    logger.debug(StarknetCallParser.formatCallsSummary(context, calls, options));
+  }
+
+  static logCallsSummary(
+    context: string,
+    calls: Call[],
+    options: StarknetCallParserOptions = {},
+    sink: (message: string) => void = logger.debug,
+  ): void {
+    sink(StarknetCallParser.formatCallsSummary(context, calls, options));
+  }
+
+  static logManageCallsSummary(
+    context: string,
+    manageCalls: ManageCall[],
+    options: StarknetCallParserOptions = {},
+    sink: (message: string) => void = logger.debug,
+  ): void {
+    sink(
+      StarknetCallParser.formatManageCallsSummary(context, manageCalls, options),
+    );
+  }
+
+  static formatCallsSummary(
+    context: string,
+    calls: Call[],
+    options: StarknetCallParserOptions = {},
+  ): string {
+    const parsed = StarknetCallParser.parseCalls(calls, options);
+    const summaries = parsed.map((call, index) =>
+      StarknetCallParser.toCallSummary(call, index),
+    );
+    return `${context}: ${summaries.join(" | ")}`;
+  }
+
+  static formatManageCallsSummary(
+    context: string,
+    manageCalls: ManageCall[],
+    options: StarknetCallParserOptions = {},
+  ): string {
+    const parsed = StarknetCallParser.parseManageCalls(manageCalls, options);
+    const summaries = parsed.map((call, index) =>
+      StarknetCallParser.toCallSummary(call, index),
+    );
+    return `${context}: ${summaries.join(" | ")}`;
+  }
+
+  static buildTokenSymbolLookup(tokens: TokenInfo[]): Record<string, string> {
+    return tokens.reduce<Record<string, string>>((acc, token) => {
+      const addr = StarknetCallParser.toAddressHex(token.address.address);
+      acc[addr] = token.symbol;
+      return acc;
+    }, {});
+  }
+
+  static buildPoolNameLookup(
+    pools: { poolId: string | bigint; name: string }[],
+  ): Record<string, string> {
+    return pools.reduce<Record<string, string>>((acc, pool) => {
+      acc[StarknetCallParser.toPoolIdKey(pool.poolId)] = pool.name;
+      return acc;
+    }, {});
+  }
+
+  static buildTokenDecimalsLookup(tokens: TokenInfo[]): Record<string, number> {
+    return tokens.reduce<Record<string, number>>((acc, token) => {
+      const addr = StarknetCallParser.toAddressHex(token.address.address);
+      acc[addr] = token.decimals;
+      return acc;
+    }, {});
+  }
+
+  private static parseRaw(params: {
+    method: string;
+    target: string;
+    calldata: unknown;
+    selector?: string;
+    sanitizer?: string;
+    options: StarknetCallParserOptions;
+  }): ParsedStarknetCall {
+    const rawCalldata = StarknetCallParser.toStringCalldata(params.calldata);
+    const decoders = StarknetCallParser.METHOD_DECODERS[params.method] ?? [];
+
+    if (decoders.length === 0) {
+      return {
+        target: params.target,
+        method: params.method,
+        selector: params.selector,
+        sanitizer: params.sanitizer,
+        decodedArgs: {},
+        rawCalldata,
+        parserUsed: "none",
+      };
+    }
+
+    let parseError: string | undefined;
+    for (const decoder of decoders) {
+      try {
+        const decodedArgs = StarknetCallParser.enrichDecodedArgs(
+          decoder.decode(rawCalldata, params.options),
+          params.options,
+        );
+        return {
+          target: params.target,
+          method: params.method,
+          selector: params.selector,
+          sanitizer: params.sanitizer,
+          decodedArgs,
+          rawCalldata,
+          parserUsed: `abi:${decoder.label}`,
+        };
+      } catch (err) {
+        parseError = err instanceof Error ? err.message : String(err);
+      }
+    }
+
+    return {
+      target: params.target,
+      method: params.method,
+      selector: params.selector,
+      sanitizer: params.sanitizer,
+      decodedArgs: {},
+      rawCalldata,
+      parserUsed: "abi-fallback",
+      parseError,
+    };
+  }
+
+  private static enrichDecodedArgs(
+    decodedArgs: unknown,
+    options: StarknetCallParserOptions,
+  ): unknown {
+    if (!decodedArgs || typeof decodedArgs !== "object") return decodedArgs;
+    const args = decodedArgs as Record<string, unknown>;
+    const poolId = args.poolId;
+    if (poolId === undefined) return decodedArgs;
+    const key = StarknetCallParser.toPoolIdKey(poolId as string | bigint);
+    const poolName = options.poolNames?.[key];
+    if (!poolName) return decodedArgs;
+    return { ...args, poolName };
+  }
+
+  private static toStringCalldata(
+    calldata: unknown,
+  ): string[] {
+    if (!calldata) return [];
+    if (!Array.isArray(calldata)) {
+      return [String(calldata)];
+    }
+    return Array.from(calldata).map((value) =>
+      typeof value === "bigint" ? value.toString() : String(value),
+    );
+  }
+
+  private static toBigInt(value: unknown): bigint | null {
+    try {
+      if (typeof value === "bigint") return value;
+      if (typeof value === "number") return BigInt(value.toString());
+      if (typeof value === "string") return BigInt(value);
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  private static decodeApprove(calldata: string[]) {
+    if (calldata.length < 3) {
+      throw new Error(`approve calldata too short: ${calldata.length}`);
+    }
+    return {
+      spender: StarknetCallParser.toAddressHex(calldata[0]),
+      amount: StarknetCallParser.u256FromParts(calldata[1], calldata[2]),
+    };
+  }
+
+  private static decodeBringLiquidity(calldata: string[]) {
+    if (calldata.length < 2) {
+      throw new Error(`bring_liquidity calldata too short: ${calldata.length}`);
+    }
+    return {
+      amount: StarknetCallParser.u256FromParts(calldata[0], calldata[1]),
+    };
+  }
+
+  private static decodeFlashLoan(calldata: string[]) {
+    if (calldata.length < 6) {
+      throw new Error(`flash_loan calldata too short: ${calldata.length}`);
+    }
+    const dataLen = Number(StarknetCallParser.toBigInt(calldata[5]) ?? 0n);
+    return {
+      receiver: StarknetCallParser.toAddressHex(calldata[0]),
+      asset: StarknetCallParser.toAddressHex(calldata[1]),
+      amount: StarknetCallParser.u256FromParts(calldata[2], calldata[3]),
+      isLegacy: calldata[4] === "1",
+      dataLen,
+      data: calldata.slice(6, 6 + dataLen),
+    };
+  }
+
+  private static decodeModifyDelegation(calldata: string[], isV2: boolean) {
+    if (isV2) {
+      if (calldata.length !== 2) {
+        throw new Error(`modify_delegation v2 calldata length mismatch: ${calldata.length}`);
+      }
+      return {
+        version: "v2",
+        delegatee: StarknetCallParser.toAddressHex(calldata[0]),
+        delegation: calldata[1] === "1",
+      };
+    }
+
+    if (calldata.length !== 3) {
+      throw new Error(`modify_delegation v1 calldata length mismatch: ${calldata.length}`);
+    }
+    return {
+      version: "v1",
+      poolId: StarknetCallParser.toPoolIdKey(calldata[0]),
+      delegatee: StarknetCallParser.toAddressHex(calldata[1]),
+      delegation: calldata[2] === "1",
+    };
+  }
+
+  private static parseVesuAmount(
+    calldata: string[],
+    cursor: { value: number },
+    tokenAddress: string,
+    options: StarknetCallParserOptions,
+  ) {
+    const amountTypeTag = calldata[cursor.value++] ?? "0";
+    const denominationTag = calldata[cursor.value++] ?? "0";
+    const abs = StarknetCallParser.u256FromParts(
+      calldata[cursor.value++] ?? "0",
+      calldata[cursor.value++] ?? "0",
+    );
+    const isNegative = calldata[cursor.value++] === "1";
+    const absHuman = StarknetCallParser.toHumanAmount(abs, tokenAddress, options);
+    const signedAmount = isNegative ? `-${abs}` : abs;
+    const signedAmountHuman = isNegative ? `-${absHuman}` : absHuman;
+    return {
+      amountTypeTag,
+      denominationTag,
+      abs,
+      absHuman,
+      isNegative,
+      signedAmount,
+      signedAmountHuman,
+    };
+  }
+
+  private static decodeModifyPosition(
+    calldata: string[],
+    options: StarknetCallParserOptions,
+  ) {
+    const tryParseV1 = () => {
+      if (calldata.length < 15) {
+        throw new Error(`modify_position v1 calldata too short: ${calldata.length}`);
+      }
+      const cursor = { value: 0 };
+      const poolId = StarknetCallParser.toPoolIdKey(calldata[cursor.value++]);
+      const collateralAssetAddress = StarknetCallParser.toAddressHex(calldata[cursor.value++]);
+      const debtAssetAddress = StarknetCallParser.toAddressHex(calldata[cursor.value++]);
+      const user = StarknetCallParser.toAddressHex(calldata[cursor.value++]);
+      const collateral = StarknetCallParser.parseVesuAmount(
+        calldata,
+        cursor,
+        collateralAssetAddress,
+        options,
+      );
+      const debt = StarknetCallParser.parseVesuAmount(
+        calldata,
+        cursor,
+        debtAssetAddress,
+        options,
+      );
+      const dataLen = Number(StarknetCallParser.toBigInt(calldata[cursor.value++]) ?? 0n);
+      const data = calldata.slice(cursor.value, cursor.value + dataLen);
+      if (data.length !== dataLen) {
+        throw new Error(`modify_position v1 data length mismatch: expected ${dataLen}, got ${data.length}`);
+      }
+      const collateralAsset = StarknetCallParser.toAssetLabel(collateralAssetAddress, options);
+      const debtAsset = StarknetCallParser.toAssetLabel(debtAssetAddress, options);
+      return {
+        version: "v1",
+        poolId,
+        collateralAsset,
+        collateralAssetAddress,
+        debtAsset,
+        debtAssetAddress,
+        user,
+        collateral,
+        debt,
+        dataLen,
+        data,
+        summary: `Modify position v1: collateral ${collateral.signedAmountHuman} ${collateralAsset}, debt ${debt.signedAmountHuman} ${debtAsset}`,
+      };
+    };
+
+    const tryParseV2 = () => {
+      if (calldata.length < 13) {
+        throw new Error(`modify_position v2 calldata too short: ${calldata.length}`);
+      }
+      const cursor = { value: 0 };
+      const collateralAssetAddress = StarknetCallParser.toAddressHex(calldata[cursor.value++]);
+      const debtAssetAddress = StarknetCallParser.toAddressHex(calldata[cursor.value++]);
+      const user = StarknetCallParser.toAddressHex(calldata[cursor.value++]);
+      const collateral = StarknetCallParser.parseVesuAmount(
+        calldata,
+        cursor,
+        collateralAssetAddress,
+        options,
+      );
+      const debt = StarknetCallParser.parseVesuAmount(
+        calldata,
+        cursor,
+        debtAssetAddress,
+        options,
+      );
+      const collateralAsset = StarknetCallParser.toAssetLabel(collateralAssetAddress, options);
+      const debtAsset = StarknetCallParser.toAssetLabel(debtAssetAddress, options);
+      return {
+        version: "v2",
+        collateralAsset,
+        collateralAssetAddress,
+        debtAsset,
+        debtAssetAddress,
+        user,
+        collateral,
+        debt,
+        summary: `Modify position v2: collateral ${collateral.signedAmountHuman} ${collateralAsset}, debt ${debt.signedAmountHuman} ${debtAsset}`,
+      };
+    };
+
+    try {
+      return tryParseV1();
+    } catch {
+      return tryParseV2();
+    }
+  }
+
+  private static decodeModifyLever(
+    calldata: string[],
+    options: StarknetCallParserOptions,
+  ) {
+    if (calldata.length < 6) {
+      throw new Error(`modify_lever calldata too short: ${calldata.length}`);
+    }
+    const actionTag = calldata[0] ?? "0";
+    const action = actionTag === "0" ? "IncreaseLever" : "DecreaseLever";
+    const cursor = { value: 1 };
+
+    const poolId = StarknetCallParser.toPoolIdKey(calldata[cursor.value++]);
+    const collateralAssetAddress = StarknetCallParser.toAddressHex(
+      calldata[cursor.value++],
+    );
+    const debtAssetAddress = StarknetCallParser.toAddressHex(calldata[cursor.value++]);
+    const collateralAsset = StarknetCallParser.toAssetLabel(
+      collateralAssetAddress,
+      options,
+    );
+    const debtAsset = StarknetCallParser.toAssetLabel(debtAssetAddress, options);
+    const user = StarknetCallParser.toAddressHex(calldata[cursor.value++]);
+
+    if (calldata.length <= 6) {
+      const amountOrSubMargin = calldata[5] ?? "0";
+      return {
+        action,
+        poolId,
+        collateralAsset,
+        collateralAssetAddress,
+        debtAsset,
+        debtAssetAddress,
+        user,
+        amountOrSubMargin,
+        summary:
+          action === "IncreaseLever"
+            ? `Modify lever increase: margin ${StarknetCallParser.toHumanAmount(amountOrSubMargin, collateralAssetAddress, options)} ${collateralAsset}`
+            : `Modify lever decrease: sub margin ${StarknetCallParser.toHumanAmount(amountOrSubMargin, collateralAssetAddress, options)} ${collateralAsset}`,
+        calldataLen: calldata.length,
+      };
+    }
+
+    if (action === "IncreaseLever") {
+      const addMargin = calldata[cursor.value++];
+      const marginSwap = StarknetCallParser.parseSwapArray(calldata, cursor);
+      const marginSwapLimitAmount = calldata[cursor.value++] ?? "0";
+      const leverSwap = StarknetCallParser.parseSwapArray(calldata, cursor);
+      const leverSwapLimitAmount = calldata[cursor.value++] ?? "0";
+      const marginSwapInputAmount = marginSwap.swapTokenAmountAbs;
+      const inferredDebtAmount = leverSwap.swapTokenAmountAbs;
+      const marginInputAssetAddress = marginSwap.firstTokenAddress ?? "";
+      const marginInputAsset = marginInputAssetAddress
+        ? StarknetCallParser.toAssetLabel(marginInputAssetAddress, options)
+        : "margin_token";
+      const marginSwapInputAmountHuman = StarknetCallParser.toHumanAmount(
+        marginSwapInputAmount,
+        marginInputAssetAddress || collateralAssetAddress,
+        options,
+      );
+      const inferredDebtAmountHuman = StarknetCallParser.toHumanAmount(
+        inferredDebtAmount,
+        debtAssetAddress,
+        options,
+      );
+      const addMarginHuman = StarknetCallParser.toHumanAmount(
+        addMargin,
+        collateralAssetAddress,
+        options,
+      );
+      const marginSwapLimitAmountHuman = StarknetCallParser.toHumanAmount(
+        marginSwapLimitAmount,
+        marginInputAssetAddress || collateralAssetAddress,
+        options,
+      );
+      const leverSwapLimitAmountHuman = StarknetCallParser.toHumanAmount(
+        leverSwapLimitAmount,
+        collateralAssetAddress,
+        options,
+      );
+      const marginMode =
+        marginSwap.count > 0 || addMargin === "0" ? "margin_swap" : "direct_margin";
+
+      return {
+        action,
+        poolId,
+        collateralAsset,
+        collateralAssetAddress,
+        debtAsset,
+        debtAssetAddress,
+        user,
+        addMargin,
+        marginMode,
+        marginSwapCount: marginSwap.count,
+        marginSwapLimitAmount,
+        marginSwapLimitAmountHuman,
+        marginSwapInputAmount,
+        marginSwapInputAmountHuman,
+        leverSwapCount: leverSwap.count,
+        inferredDebtAmount,
+        inferredDebtAmountHuman,
+        leverSwapLimitAmount,
+        leverSwapLimitAmountHuman,
+        summary:
+          marginMode === "margin_swap"
+            ? `Modify lever increase: margin swap exact-output to collateral (first swap input ${marginSwapInputAmountHuman} ${marginInputAsset}, max input ${marginSwapLimitAmountHuman} ${marginInputAsset}); lever swap exact-input debt->collateral, debt ${inferredDebtAmountHuman} ${debtAsset} -> at least ${leverSwapLimitAmountHuman} ${collateralAsset}`
+            : `Modify lever increase: direct margin ${addMarginHuman} ${collateralAsset}; lever swap exact-input debt->collateral, debt ${inferredDebtAmountHuman} ${debtAsset} -> at least ${leverSwapLimitAmountHuman} ${collateralAsset}`,
+        calldataLen: calldata.length,
+      };
+    }
+
+    const subMargin = calldata[cursor.value++];
+    const recipient = StarknetCallParser.toAddressHex(calldata[cursor.value++]);
+    const leverSwap = StarknetCallParser.parseSwapArray(calldata, cursor);
+    const leverSwapLimitAmount = calldata[cursor.value++] ?? "0";
+    const leverSwapInputAmount = leverSwap.swapTokenAmountAbs;
+
+    const leverSwapWeightsLen = Number(
+      StarknetCallParser.toBigInt(calldata[cursor.value++]) ?? 0n,
+    );
+    cursor.value += leverSwapWeightsLen;
+
+    const withdrawSwap = StarknetCallParser.parseSwapArray(calldata, cursor);
+    const withdrawSwapLimitAmount = calldata[cursor.value++] ?? "0";
+    const withdrawSwapInputAmount = withdrawSwap.swapTokenAmountAbs;
+
+    const withdrawSwapWeightsLen = Number(
+      StarknetCallParser.toBigInt(calldata[cursor.value++]) ?? 0n,
+    );
+    cursor.value += withdrawSwapWeightsLen;
+
+    const closePosition = calldata[cursor.value] === "1";
+    const subMarginHuman = StarknetCallParser.toHumanAmount(
+      subMargin,
+      collateralAssetAddress,
+      options,
+    );
+    const leverLimitTokenAddress = closePosition
+      ? collateralAssetAddress
+      : debtAssetAddress;
+    const leverSwapLimitAmountHuman = StarknetCallParser.toHumanAmount(
+      leverSwapLimitAmount,
+      leverLimitTokenAddress,
+      options,
+    );
+    const leverSwapInputAmountHuman = StarknetCallParser.toHumanAmount(
+      leverSwapInputAmount,
+      collateralAssetAddress,
+      options,
+    );
+    const withdrawTokenAddress = withdrawSwap.inferredOutputTokenAddress ?? "";
+    const withdrawTokenLabel = withdrawTokenAddress
+      ? StarknetCallParser.toAssetLabel(withdrawTokenAddress, options)
+      : "withdrawToken";
+
+    const withdrawSwapLimitAmountHuman = StarknetCallParser.toHumanAmount(
+      withdrawSwapLimitAmount,
+      withdrawTokenAddress,
+      options,
+    );
+    const withdrawSwapInputAmountHuman = StarknetCallParser.toHumanAmount(
+      withdrawSwapInputAmount,
+      collateralAssetAddress,
+      options,
+    );
+    return {
+      action,
+      poolId,
+        collateralAsset,
+        collateralAssetAddress,
+        debtAsset,
+        debtAssetAddress,
+      user,
+      subMargin,
+      recipient,
+      leverSwapCount: leverSwap.count,
+      leverSwapInputAmount,
+      leverSwapInputAmountHuman,
+      leverSwapLimitAmount,
+      leverSwapLimitAmountHuman,
+      withdrawSwapCount: withdrawSwap.count,
+      withdrawSwapInputAmount,
+      withdrawSwapInputAmountHuman,
+      withdrawSwapLimitAmount,
+      withdrawSwapLimitAmountHuman,
+      closePosition,
+      summary: closePosition
+        ? `Modify lever decrease: close position, repay all outstanding ${debtAsset} debt using max ${leverSwapLimitAmountHuman} ${collateralAsset} (first swap input ${leverSwapInputAmountHuman} ${collateralAsset}), remaining collateral is freed${withdrawSwap.count > 0 ? ` (withdraw swap active: input ${withdrawSwapInputAmountHuman} ${collateralAsset}, min ${withdrawSwapLimitAmountHuman} ${withdrawTokenLabel})` : ""}`
+        : `Modify lever decrease: repay at least ${leverSwapLimitAmountHuman} ${debtAsset} debt via collateral swap (first swap input ${leverSwapInputAmountHuman} ${collateralAsset}), free ${subMarginHuman} ${collateralAsset} collateral${withdrawSwap.count > 0 ? ` (withdraw swap active: input ${withdrawSwapInputAmountHuman} ${collateralAsset}, min ${withdrawSwapLimitAmountHuman} ${withdrawTokenLabel})` : ""}`,
+      calldataLen: calldata.length,
+    };
+  }
+
+  private static decodeMultiRouteSwap(
+    calldata: string[],
+    options: StarknetCallParserOptions,
+  ) {
+    if (calldata.length < 8) {
+      throw new Error(`multi_route_swap calldata too short: ${calldata.length}`);
+    }
+    const fromAddress = StarknetCallParser.toAddressHex(calldata[0]);
+    const toAddress = StarknetCallParser.toAddressHex(calldata[3]);
+    const fromAmount = StarknetCallParser.u256FromParts(calldata[1], calldata[2]);
+    const minTokenOutput = StarknetCallParser.u256FromParts(
+      calldata[6],
+      calldata[7],
+    );
+    const fromAmountHuman = StarknetCallParser.toHumanAmountIfDecimals(
+      fromAmount,
+      fromAddress,
+      options,
+    );
+    const minTokenOutputHuman = StarknetCallParser.toHumanAmountIfDecimals(
+      minTokenOutput,
+      toAddress,
+      options,
+    );
+
+    return {
+      fromTokenSymbol: options.tokenSymbols?.[fromAddress] ?? fromAddress,
+      toTokenSymbol: options.tokenSymbols?.[toAddress] ?? toAddress,
+      fromAmount,
+      ...(fromAmountHuman !== undefined ? { fromAmountHuman } : {}),
+      minTokenOutput,
+      ...(minTokenOutputHuman !== undefined ? { minTokenOutputHuman } : {}),
+    };
+  }
+
+  private static decodeManageVaultWithMerkleVerification(
+    calldata: string[],
+    options: StarknetCallParserOptions,
+  ) {
+    let cursor = 0;
+
+    const readLen = (): number => {
+      const length = Number(StarknetCallParser.toBigInt(calldata[cursor]) ?? 0n);
+      cursor += 1;
+      return length;
+    };
+
+    const readFlatSpan = (): string[] => {
+      const length = readLen();
+      const values = calldata.slice(cursor, cursor + length);
+      cursor += length;
+      return values;
+    };
+
+    const readNestedSpan = (): string[][] => {
+      const outerLen = readLen();
+      const nested: string[][] = [];
+      for (let i = 0; i < outerLen; i += 1) {
+        nested.push(readFlatSpan());
+      }
+      return nested;
+    };
+
+    const proofs = readNestedSpan();
+    const decoderAndSanitizers = readFlatSpan();
+    const targets = readFlatSpan();
+    const selectors = readFlatSpan();
+    const calldatas = readNestedSpan();
+
+    const internalCalls = selectors.map((selector, index) => {
+      const selectorHex = StarknetCallParser.toSelectorHex(selector);
+      const method =
+        StarknetCallParser.METHOD_BY_SELECTOR.get(selectorHex) ??
+        `unknown_selector_${selectorHex}`;
+
+      const decoded = StarknetCallParser.parseRaw({
+        method,
+        target: StarknetCallParser.toAddressHex(targets[index] ?? "0x0"),
+        selector: selectorHex,
+        sanitizer: StarknetCallParser.toAddressHex(
+          decoderAndSanitizers[index] ?? "0x0",
+        ),
+        calldata: calldatas[index] ?? [],
+        options,
+      });
+
+      return {
+        index,
+        ...decoded,
+      };
+    });
+
+    return {
+      proofsCount: proofs.length,
+      internalCallsCount: internalCalls.length,
+      internalCalls,
+    };
+  }
+
+  private static toCallSummary(
+    parsed: ParsedStarknetCall,
+    index: number,
+  ): string {
+    const prefix = `#${index} ${parsed.method}@${parsed.target}`;
+    const args = parsed.decodedArgs as any;
+
+    if (parsed.method === "manage_vault_with_merkle_verification") {
+      const internalCalls = Array.isArray(args?.internalCalls)
+        ? args.internalCalls
+        : [];
+      const internalSummary = internalCalls
+        .map(
+          (call: any, i: number) =>
+            `${i}:${call.method}(${StarknetCallParser.pickKeyFields(call.decodedArgs)})`,
+        )
+        .join(", ");
+      return `${prefix} internalCalls=${args?.internalCallsCount ?? 0} [${internalSummary}]`;
+    }
+
+    return `${prefix} ${StarknetCallParser.pickKeyFields(args)}`;
+  }
+
+  private static pickKeyFields(decodedArgs: any): string {
+    if (!decodedArgs || typeof decodedArgs !== "object") return "";
+    if (typeof decodedArgs.summary === "string" && decodedArgs.summary.length > 0) {
+      return decodedArgs.summary;
+    }
+    const keys = [
+      "fromTokenSymbol",
+      "toTokenSymbol",
+      "fromAmount",
+      "fromAmountHuman",
+      "minTokenOutput",
+      "minTokenOutputHuman",
+      "spender",
+      "amount",
+      "inferredDebtAmountHuman",
+      "leverSwapLimitAmountHuman",
+      "withdrawSwapLimitAmountHuman",
+      "version",
+      "delegatee",
+      "delegation",
+      "action",
+      "poolId",
+      "calldataLen",
+    ];
+
+    const parts: string[] = [];
+    if (decodedArgs.poolId !== undefined) {
+      const poolName = decodedArgs.poolName ?? decodedArgs.poolLabel;
+      parts.push(
+        poolName ? `poolId=${decodedArgs.poolId}(${poolName})` : `poolId=${decodedArgs.poolId}`,
+      );
+    }
+    for (const key of keys) {
+      if (key === "poolId") continue;
+      if (decodedArgs[key] !== undefined) {
+        parts.push(`${key}=${decodedArgs[key]}`);
+      }
+    }
+    if (parts.length === 0) {
+      return `fields=${Object.keys(decodedArgs).length}`;
+    }
+    return parts.join(", ");
+  }
+
+  private static u256FromParts(low: string, high: string): string {
+    try {
+      return uint256
+        .uint256ToBN({ low, high } as unknown as { low: string; high: string })
+        .toString();
+    } catch {
+      return "0";
+    }
+  }
+
+  private static toSelectorHex(selector: string): string {
+    try {
+      if (selector.startsWith("0x") || selector.startsWith("0X")) {
+        return selector.toLowerCase();
+      }
+      return `0x${BigInt(selector).toString(16)}`.toLowerCase();
+    } catch {
+      return selector.toLowerCase();
+    }
+  }
+
+  private static parseSwapArray(
+    calldata: string[],
+    cursor: { value: number },
+  ): {
+    count: number;
+    swapTokenAmountAbs: string;
+    firstTokenAddress?: string;
+    inferredOutputTokenAddress?: string;
+  } {
+    const count = Number(
+      StarknetCallParser.toBigInt(calldata[cursor.value++]) ?? 0n,
+    );
+    let swapTokenAmountAbs = "0";
+    let firstTokenAddress: string | undefined;
+    let inferredOutputTokenAddress: string | undefined;
+
+    for (let i = 0; i < count; i += 1) {
+      const routeLen = Number(
+        StarknetCallParser.toBigInt(calldata[cursor.value++]) ?? 0n,
+      );
+      const routePairs: Array<{ token0: string; token1: string }> = [];
+      // route node = pool_key(5) + sqrt_ratio_limit(u256=2) + skip_ahead(1)
+      for (let j = 0; j < routeLen; j++) {
+        const token0 = StarknetCallParser.toAddressHex(
+          calldata[cursor.value++] ?? "0x0",
+        );
+        const token1 = StarknetCallParser.toAddressHex(
+          calldata[cursor.value++] ?? "0x0",
+        );
+        cursor.value += 6;
+        routePairs.push({ token0, token1 });
+      }
+
+      // token_amount: token + i129(mag + sign)
+      const tokenAddress = StarknetCallParser.toAddressHex(
+        calldata[cursor.value++] ?? "0x0",
+      );
+      let currentTokenForRoute: string | undefined = tokenAddress;
+      for (const pair of routePairs) {
+        if (currentTokenForRoute === pair.token0) {
+          currentTokenForRoute = pair.token1;
+        } else if (currentTokenForRoute === pair.token1) {
+          currentTokenForRoute = pair.token0;
+        }
+      }
+      const mag = StarknetCallParser.toBigInt(calldata[cursor.value++]) ?? 0n;
+      const sign = calldata[cursor.value++] === "1" ? -1n : 1n;
+      if (i === 0) {
+        firstTokenAddress = tokenAddress;
+        inferredOutputTokenAddress = currentTokenForRoute;
+        swapTokenAmountAbs = (mag * sign < 0n ? -mag * sign : mag * sign).toString();
+      }
+    }
+
+    return {
+      count,
+      swapTokenAmountAbs,
+      firstTokenAddress,
+      inferredOutputTokenAddress,
+    };
+  }
+
+  private static toPoolIdKey(poolId: string | bigint): string {
+    try {
+      const asBigInt = typeof poolId === "bigint" ? poolId : BigInt(poolId);
+      return `0x${asBigInt.toString(16)}`.toLowerCase();
+    } catch {
+      return String(poolId).toLowerCase();
+    }
+  }
+
+  private static toAssetLabel(
+    address: string,
+    options: StarknetCallParserOptions,
+  ): string {
+    return options.tokenSymbols?.[address] ?? address;
+  }
+
+  private static toHumanAmount(
+    rawWei: string,
+    tokenAddress: string,
+    options: StarknetCallParserOptions,
+  ): string {
+    const decimals = options.tokenDecimals?.[tokenAddress];
+    if (decimals === undefined) return rawWei;
+    try {
+      return Web3Number.fromWei(rawWei, decimals).toNumber().toString();
+    } catch {
+      return rawWei;
+    }
+  }
+
+  private static toHumanAmountIfDecimals(
+    rawWei: string,
+    tokenAddress: string,
+    options: StarknetCallParserOptions,
+  ): string | undefined {
+    const decimals = options.tokenDecimals?.[tokenAddress];
+    if (decimals === undefined) return undefined;
+    try {
+      return Web3Number.fromWei(rawWei, decimals).toNumber().toString();
+    } catch {
+      return undefined;
+    }
+  }
+
+  private static normalizeHex(value: string): string {
+    return value.toLowerCase();
+  }
+
+  private static toAddressHex(value: string | bigint): string {
+    try {
+      const input = typeof value === "bigint" ? `0x${value.toString(16)}` : value;
+      return `0x${ContractAddr.from(input).toBigInt().toString(16)}`.toLowerCase();
+    } catch {
+      if (typeof value === "bigint") {
+        return `0x${value.toString(16)}`.toLowerCase();
+      }
+      return String(value).toLowerCase();
+    }
+  }
+
+  private static addressToString(value: unknown): string {
+    if (typeof value === "string") return value;
+    if (typeof value === "bigint") return `0x${value.toString(16)}`;
+    if (value && typeof value === "object" && "address" in (value as any)) {
+      return String((value as any).address);
+    }
+    return String(value ?? "");
+  }
+}