@gearbox-protocol/sdk 12.8.1 → 12.9.0-txparser.2

package/dist/esm/sdk/base/BaseContract.js

@@ -11,6 +11,8 @@ import {
   bytes32ToString,
   createRawTx,
   functionArgsToMap,
+  functionArgsToRecord,
+  getFunctionSignature,
   json_stringify
 } from "../utils/index.js";
 import { Construct } from "./Construct.js";
@@ -195,6 +197,57 @@ class BaseContract extends Construct {
       args
     };
   }
+  /**
+   * Parses calldata into structured result with preserved original types.
+   * When strict is true, throws {@link ContractParseError} on unknown selectors;
+   * otherwise returns a fallback with the raw calldata.
+   */
+  parseFunctionDataV2(calldata, strict) {
+    try {
+      const decoded = decodeFunctionData({
+        abi: this.abi,
+        data: calldata
+      });
+      const functionName = getFunctionSignature(this.abi, calldata);
+      return this.wrapParseCallV2(
+        functionName,
+        this.parseFunctionParamsV2(decoded, strict)
+      );
+    } catch (e) {
+      if (strict) {
+        throw new ContractParseError(e, {
+          address: this.address,
+          callData: calldata,
+          contractName: this.name
+        });
+      }
+      this.logger?.warn(e);
+      const selector = calldata.slice(0, 10);
+      const data = `0x${calldata.slice(10)}`;
+      return this.wrapParseCallV2(`unknown function ${selector}`, {
+        _data: data
+      });
+    }
+  }
+  /**
+   * Converts viem-decoded function arguments to a record preserving original types.
+   * Override in subclasses to handle nesting (e.g., multicall inner calls).
+   * @param strict - propagated from parseFunctionDataV2 for recursive parsing
+   */
+  parseFunctionParamsV2(params, _strict) {
+    return functionArgsToRecord(this.abi, params.functionName, params.args);
+  }
+  wrapParseCallV2(functionName, rawArgs) {
+    return {
+      chainId: this.chainId,
+      target: this.address,
+      contractType: this.contractType,
+      label: this.register.labelAddress(this.address, true),
+      version: this.version,
+      functionName,
+      rawArgs
+    };
+  }
   /**
    * Creates a raw transaction for a function in this contract
    * @param parameters

package/dist/esm/sdk/base/ChainContractsRegister.js

@@ -113,6 +113,39 @@ class ChainContractsRegister {
       (call) => this.parseFunctionData(call.target, call.callData)
     );
   }
+  /**
+   * Parses calldata for a contract at the given address, preserving original types.
+   * When strict is true, throws on unknown address or selector; otherwise returns a fallback.
+   */
+  parseFunctionDataV2(address, calldata, strict) {
+    const contract = this.contracts.get(address);
+    if (contract) {
+      return contract.parseFunctionDataV2(calldata, strict);
+    }
+    if (strict) {
+      throw new Error(`contract ${address} not found on chain ${this.chainId}`);
+    }
+    const selector = calldata.slice(0, 10);
+    const data = `0x${calldata.slice(10)}`;
+    return {
+      chainId: this.chainId,
+      target: address,
+      contractType: "",
+      label: this.labelAddress(address, true),
+      version: 0,
+      functionName: `unknown function ${selector}`,
+      rawArgs: { _data: data }
+    };
+  }
+  /**
+   * Parses multicalls preserving original types.
+   * When strict is true, throws on unknown targets or selectors.
+   */
+  parseMultiCallV2(calls, strict) {
+    return calls.map(
+      (call) => this.parseFunctionDataV2(call.target, call.callData, strict)
+    );
+  }
 }
 export {
   ChainContractsRegister

package/dist/esm/sdk/base/PlaceholderContract.js

@@ -1,8 +1,8 @@
 import { BaseContract } from "./BaseContract.js";
 const abi = [];
 class PlaceholderContract extends BaseContract {
-  constructor(sdk, args) {
-    super(sdk, { ...args, abi });
+  constructor(options, args) {
+    super(options, { ...args, abi });
   }
 }
 export {

package/dist/esm/sdk/base/TokensMeta.js

@@ -1,6 +1,10 @@
 import { iVersionAbi } from "../../abi/iVersion.js";
-import { bytes32ToString } from "../index.js";
-import { AddressMap, AddressSet, formatBN } from "../utils/index.js";
+import {
+  AddressMap,
+  AddressSet,
+  bytes32ToString,
+  formatBN
+} from "../utils/index.js";
 class TokensMeta extends AddressMap {
   #client;
   #phantomTokensLoaded;

package/dist/esm/sdk/base/errors.js

@@ -0,0 +1,11 @@
+class MissingSerializedParamsError extends Error {
+  constructor(propertyName) {
+    super(
+      `Cannot access '${propertyName}': serializedParams were not provided`
+    );
+    this.name = "MissingSerializedParamsError";
+  }
+}
+export {
+  MissingSerializedParamsError
+};

package/dist/esm/sdk/base/index.js

@@ -1,6 +1,7 @@
 export * from "./BaseContract.js";
 export * from "./ChainContractsRegister.js";
 export * from "./Construct.js";
+export * from "./errors.js";
 export * from "./PlaceholderContract.js";
 export * from "./SDKConstruct.js";
 export * from "./TokensMeta.js";

package/dist/esm/sdk/market/adapters/PlaceholderAdapterContracts.js

@@ -1,9 +1,18 @@
-import { PlaceholderContract } from "../../base/index.js";
+import {
+  MissingSerializedParamsError,
+  PlaceholderContract
+} from "../../base/index.js";
 class PlaceholderAdapterContract extends PlaceholderContract {
-  targetContract;
-  constructor(sdk, args) {
-    super(sdk, args.baseParams);
-    this.targetContract = args.targetContract;
+  #targetContract;
+  constructor(options, args) {
+    super(options, args.baseParams);
+    this.#targetContract = args.targetContract;
+  }
+  get targetContract() {
+    if (!this.#targetContract) {
+      throw new MissingSerializedParamsError("targetContract");
+    }
+    return this.#targetContract;
   }
 }
 export {

package/dist/esm/sdk/market/adapters/index.js

@@ -1,3 +1,3 @@
-export * from "./factory.js";
+export * from "./createAdapter.js";
 export * from "./PlaceholderAdapterContracts.js";
 export * from "./types.js";

package/dist/esm/sdk/market/credit/CreditFacadeV310BaseContract.js

@@ -0,0 +1,86 @@
+import {
+  iCreditFacadeMulticallV310Abi,
+  iCreditFacadeV310Abi
+} from "../../../abi/310/generated.js";
+import { iPausableAbi } from "../../../abi/iPausable.js";
+import { BaseContract } from "../../base/index.js";
+const abi = [
+  ...iCreditFacadeV310Abi,
+  ...iCreditFacadeMulticallV310Abi,
+  ...iPausableAbi
+];
+class CreditFacadeV310BaseContract extends BaseContract {
+  constructor(options, args) {
+    super(options, { ...args, abi });
+  }
+  parseFunctionParamsV2(params, strict) {
+    switch (params.functionName) {
+      case "openCreditAccount": {
+        const [onBehalfOf, calls, referralCode] = params.args;
+        return {
+          onBehalfOf,
+          calls: this.register.parseMultiCallV2([...calls], strict),
+          referralCode
+        };
+      }
+      case "closeCreditAccount": {
+        const [creditAccount, calls] = params.args;
+        return {
+          creditAccount,
+          calls: this.register.parseMultiCallV2([...calls], strict)
+        };
+      }
+      case "botMulticall":
+      case "multicall": {
+        const [creditAccount, calls] = params.args;
+        return {
+          creditAccount,
+          calls: this.register.parseMultiCallV2([...calls], strict)
+        };
+      }
+      case "liquidateCreditAccount": {
+        const [creditAccount, to, calls] = params.args;
+        return {
+          creditAccount,
+          to,
+          calls: this.register.parseMultiCallV2([...calls], strict)
+        };
+      }
+      default:
+        return super.parseFunctionParamsV2(params, strict);
+    }
+  }
+  stringifyFunctionParams(params) {
+    switch (params.functionName) {
+      case "openCreditAccount": {
+        const [onBehalfOf, calls, referralCode] = params.args;
+        return [
+          this.labelAddress(onBehalfOf),
+          this.register.parseMultiCall([...calls]).join(","),
+          `${referralCode}`
+        ];
+      }
+      case "closeCreditAccount": {
+        const [creditAccount, calls] = params.args;
+        return [
+          this.labelAddress(creditAccount),
+          this.register.parseMultiCall([...calls]).join(",")
+        ];
+      }
+      case "liquidateCreditAccount": {
+        const [creditAccount, to, calls] = params.args;
+        return [
+          this.labelAddress(creditAccount),
+          this.labelAddress(to),
+          this.register.parseMultiCall([...calls]).join(",")
+        ];
+      }
+      default:
+        return super.stringifyFunctionParams(params);
+    }
+  }
+}
+export {
+  CreditFacadeV310BaseContract,
+  abi as creditFacadeV310Abi
+};

package/dist/esm/sdk/market/credit/CreditFacadeV310Contract.js

@@ -1,28 +1,17 @@
-import {
-  iCreditFacadeMulticallV310Abi,
-  iCreditFacadeV310Abi
-} from "../../../abi/310/generated.js";
-import { iPausableAbi } from "../../../abi/iPausable.js";
-import { BaseContract } from "../../base/index.js";
 import { ADDRESS_0X0 } from "../../constants/index.js";
 import {
   fmtBinaryMask,
   formatBNvalue,
   formatTimestamp
 } from "../../utils/index.js";
-const abi = [
-  ...iCreditFacadeV310Abi,
-  ...iCreditFacadeMulticallV310Abi,
-  ...iPausableAbi
-];
-class CreditFacadeV310Contract extends BaseContract {
+import { CreditFacadeV310BaseContract } from "./CreditFacadeV310BaseContract.js";
+class CreditFacadeV310Contract extends CreditFacadeV310BaseContract {
   underlying;
   constructor(options, { creditFacade, creditManager }) {
     const { baseParams, ...rest } = creditFacade;
     super(options, {
       ...baseParams,
-      name: `CreditFacadeV310(${creditManager.name})`,
-      abi
+      name: `CreditFacadeV310(${creditManager.name})`
     });
     Object.assign(this, rest);
     this.underlying = creditManager.underlying;
@@ -89,35 +78,6 @@ class CreditFacadeV310Contract extends BaseContract {
       args: [to, calls, referralCode]
     });
   }
-  stringifyFunctionParams(params) {
-    switch (params.functionName) {
-      case "openCreditAccount": {
-        const [onBehalfOf, calls, referralCode] = params.args;
-        return [
-          this.labelAddress(onBehalfOf),
-          this.register.parseMultiCall([...calls]).join(","),
-          `${referralCode}`
-        ];
-      }
-      case "closeCreditAccount": {
-        const [creditAccount, calls] = params.args;
-        return [
-          this.labelAddress(creditAccount),
-          this.register.parseMultiCall([...calls]).join(",")
-        ];
-      }
-      case "liquidateCreditAccount": {
-        const [creditAccount, to, calls] = params.args;
-        return [
-          this.labelAddress(creditAccount),
-          this.labelAddress(to),
-          this.register.parseMultiCall([...calls]).join(",")
-        ];
-      }
-      default:
-        return super.stringifyFunctionParams(params);
-    }
-  }
 }
 export {
   CreditFacadeV310Contract

package/dist/esm/sdk/market/credit/index.js

@@ -1,6 +1,7 @@
 export * from "./CreditConfiguratorV300Contract.js";
 export * from "./CreditConfiguratorV310Contract.js";
 export * from "./CreditFacadeV300Contract.js";
+export * from "./CreditFacadeV310BaseContract.js";
 export * from "./CreditFacadeV310Contract.js";
 export * from "./CreditManagerV300Contract.js";
 export * from "./CreditManagerV310Contract.js";

package/dist/esm/sdk/utils/abi-decode.js

@@ -1,8 +1,19 @@
 import {
   AbiFunctionNotFoundError,
-  getAbiItem
+  getAbiItem,
+  toFunctionSelector,
+  toFunctionSignature
 } from "viem";
 import { json_stringify } from "../../sdk/utils/index.js";
+function getFunctionSignature(abi, calldataOrSelector) {
+  const selector = calldataOrSelector.slice(0, 10);
+  for (const item of abi) {
+    if (item.type === "function" && toFunctionSelector(item) === selector) {
+      return toFunctionSignature(item);
+    }
+  }
+  throw new Error(`Function with selector ${selector} not found in ABI`);
+}
 function functionArgsToMap(abi, functionName, args) {
   const abiItem = getAbiItem({
     abi,
@@ -32,6 +43,36 @@ function functionArgsToMap(abi, functionName, args) {
   }
   return namedArgs;
 }
+function functionArgsToRecord(abi, functionName, args) {
+  const abiItem = getAbiItem({
+    abi,
+    name: functionName,
+    args
+  });
+  if (!abiItem || abiItem.type !== "function") {
+    throw new AbiFunctionNotFoundError(functionName);
+  }
+  const namedArgs = {};
+  if (Array.isArray(args)) {
+    args.forEach((value, i) => {
+      const input = abiItem.inputs?.[i];
+      const key = input?.name || `${i}`;
+      namedArgs[key] = value;
+    });
+  } else {
+    Object.entries(args || {}).forEach(([key, value]) => {
+      const index = parseInt(key, 10);
+      if (!Number.isNaN(index) && abiItem.inputs?.[index]?.name) {
+        namedArgs[abiItem.inputs[index].name] = value;
+      } else {
+        namedArgs[key] = value;
+      }
+    });
+  }
+  return namedArgs;
+}
 export {
-  functionArgsToMap
+  functionArgsToMap,
+  functionArgsToRecord,
+  getFunctionSignature
 };

package/dist/types/dev/providers.d.ts

@@ -8,11 +8,11 @@ export declare const rpcProvidersSchema: z.ZodEnum<{
     ankr: "ankr";
 }>;
 export type RpcProvider = z.infer<typeof rpcProvidersSchema>;
-export declare function getRpcProviderUrl(provider: RpcProvider, network: NetworkType, apiKey?: string, protocol?: "http" | "ws"): string | undefined;
-export declare function getAlchemyUrl(network: NetworkType, apiKey?: string, protocol?: "http" | "ws"): string | undefined;
-export declare function getDrpcUrl(network: NetworkType, apiKey?: string, protocol?: "http" | "ws"): string | undefined;
-export declare function getAnkrUrl(network: NetworkType, apiKey?: string, protocol?: "http" | "ws"): string | undefined;
-export declare function getThirdWebUrl(network: NetworkType, apiKey?: string, protocol?: "http" | "ws"): string | undefined;
+export declare function getRpcProviderUrl(provider: RpcProvider, network: NetworkType, apiKey: string, protocol?: "http" | "ws"): string | undefined;
+export declare function getAlchemyUrl(network: NetworkType, apiKey: string, protocol?: "http" | "ws"): string | undefined;
+export declare function getDrpcUrl(network: NetworkType, apiKey: string, protocol?: "http" | "ws"): string | undefined;
+export declare function getAnkrUrl(network: NetworkType, apiKey: string, protocol?: "http" | "ws"): string | undefined;
+export declare function getThirdWebUrl(network: NetworkType, apiKey: string, protocol?: "http" | "ws"): string | undefined;
 export declare function getErpcKey(network: NetworkType, projectId?: string, urlBase?: string): string | undefined;
 /**
  Non-existent event:

package/dist/types/history/assembleOperations.d.ts

@@ -0,0 +1,24 @@
+import type { Address, Hex } from "viem";
+import type { AddressMap, ChainContractsRegister } from "../sdk/index.js";
+import type { ExecuteResult, FacadeParsedCall } from "./internal-types.js";
+import type { OuterFacadeOperation } from "./types.js";
+export interface AssembleOperationsInput {
+    facadeCalls: FacadeParsedCall[];
+    executeResults: ExecuteResult[];
+    register: ChainContractsRegister;
+    underlying: Address;
+    txHash: Hex;
+    blockNumber: number;
+    liquidationRemainingFunds?: bigint;
+    phantomTokens?: AddressMap<Address>;
+    strict?: boolean;
+}
+/**
+ * Combines parsed facade calls with per-Execute transfer data into
+ * fully classified {@link OuterFacadeOperation} entries.
+ *
+ * The flat `executeResults` array (one entry per Execute event across
+ * the entire transaction) is sliced per facade call based on how many
+ * adapter/unknown inner calls each one contains.
+ */
+export declare function assembleOperations(input: AssembleOperationsInput): OuterFacadeOperation[];

package/dist/types/history/classifyMulticallOperations.d.ts

@@ -0,0 +1,35 @@
+import { type Address, type Hex } from "viem";
+import type { AddressMap, ChainContractsRegister, ParsedCallV2 } from "../sdk/index.js";
+import type { InnerOperation } from "./inner-operations.js";
+import type { ExecuteResult } from "./internal-types.js";
+export interface ClassifyMulticallOperationsInput {
+    innerCalls: ParsedCallV2[];
+    executeResults: ExecuteResult[];
+    protocolCalldatas: Hex[];
+    register: ChainContractsRegister;
+    creditAccount: Address;
+    underlying: Address;
+    strict?: boolean;
+    phantomTokens?: AddressMap<Address>;
+}
+/**
+ * Classifies each multicall inner call into a {@link InnerOperation}:
+ *
+ * - **Adapter calls** (target registered as an adapter): delegates to
+ *   `adapter.parseAdapterOperation()` and consumes the next entry from
+ *   `executeTransfers` (one Execute event per adapter call).
+ *
+ * - **Facade self-calls** (`increaseDebt`, `updateQuota`, etc.): mapped
+ *   directly from `functionName` / `rawArgs`. No transfer consumed.
+ *
+ * - **Unknown contracts** (address not in register): treated as adapter
+ *   calls with a fallback to generic `Swap` from transfers.
+ *
+ * Skips facade calls we're not interested in (`onDemandPriceUpdates`, `disableToken`, etc.).
+ *
+ * @throws {TransferAlignmentError} if the number of adapter calls does not
+ *   match the number of Execute transfers.
+ * @throws {UnknownAdapterError} if strict is true and an inner call target
+ *   is not in the register.
+ */
+export declare function classifyMulticallOperations(input: ClassifyMulticallOperationsInput): InnerOperation[];

package/dist/types/history/enrichTokens.d.ts

@@ -0,0 +1,5 @@
+import type { Address } from "viem";
+import type { TokenInfo } from "../plugins/adapters/types.js";
+import type { CreditAccountOperation } from "./types.js";
+export type TokenResolver = (addr: Address) => TokenInfo;
+export declare function enrichOperations(ops: CreditAccountOperation[], resolve: TokenResolver): CreditAccountOperation<TokenInfo>[];

package/dist/types/history/errors.d.ts

@@ -0,0 +1,30 @@
+import type { Address, Hex } from "viem";
+export declare class UnknownAdapterError extends Error {
+    readonly address: Address;
+    constructor(address: Address);
+}
+export declare class TransferAlignmentError extends Error {
+    constructor(expected: number, actual: number);
+}
+export declare class ProtocolCallNotFoundError extends Error {
+    readonly targetContract: Address;
+    readonly executeIndex: number;
+    constructor(targetContract: Address, executeIndex: number);
+}
+export declare class AdapterTraceAlignmentError extends Error {
+    readonly expected: number;
+    readonly actual: number;
+    constructor(expected: number, actual: number);
+}
+export declare class UnexpectedFacadeEventOrderError extends Error {
+    constructor(e: {
+        eventName: string;
+        logIndex: number;
+        transactionHash: Hex;
+    });
+}
+export declare class UnknownFacadeCallError extends Error {
+    readonly address: Address;
+    readonly functionName: string;
+    constructor(address: Address, functionName: string);
+}

package/dist/types/history/extractProtocolCalls.d.ts

@@ -0,0 +1,8 @@
+import type { Hex } from "viem";
+import type { CallTrace, ExecuteResult } from "./internal-types.js";
+/**
+ * Extracts calldata sent to target contract for each Execute event.
+ *
+ * @returns
+ */
+export declare function extractProtocolCalls(facadeTrace: CallTrace, executeResults: ExecuteResult[]): Hex[];

package/dist/types/history/extractTransfers.d.ts

@@ -0,0 +1,22 @@
+import { type Address, type Log } from "viem";
+import { AddressMap } from "../sdk/index.js";
+import type { ExecuteResult } from "./internal-types.js";
+import type { DirectTransferInfo } from "./types.js";
+type RawLog = Log<bigint | number, number, false>;
+/**
+ * Extracts per-adapter-call token balance changes and detects direct
+ * incoming transfers to the credit account.
+ *
+ * @param logs - raw viem Log[] from transaction receipt, sorted by logIndex
+ * @param facadeAddress - the credit facade address (sole boundary event source)
+ * @param creditAccount - the credit account address to track
+ */
+export interface ExtractTransfersResult {
+    executeResults: ExecuteResult[];
+    directTransfers: DirectTransferInfo[];
+    liquidationRemainingFunds?: bigint;
+    /** Maps phantom token address to its deposited (underlying) token address. */
+    phantomTokens: AddressMap<Address>;
+}
+export declare function extractTransfers(logs: RawLog[], creditAccount: Address, pool: Address, creditFacade: Address): ExtractTransfersResult;
+export {};

package/dist/types/history/findFacadeCalls.d.ts

@@ -0,0 +1,9 @@
+import { type Address } from "viem";
+import type { ChainContractsRegister } from "../sdk/index.js";
+import type { CallTrace, FacadeParsedCall } from "./internal-types.js";
+/**
+ * Walks a `debug_traceTransaction` callTracer tree, finds all non-reverted
+ * calls to the credit facade, parses them via the register, and returns
+ * structured {@link FacadeParsedCall} entries for the given credit account.
+ */
+export declare function findFacadeCalls(trace: CallTrace, creditFacade: Address, creditAccount: Address, register: ChainContractsRegister, strict?: boolean): FacadeParsedCall[];

package/dist/types/history/index.d.ts

@@ -0,0 +1,6 @@
+export type { TokenInfo } from "../plugins/adapters/types.js";
+export * from "./inner-operations.js";
+export { parseCreditAccountTransaction } from "./parseCreditAccountTransaction.js";
+export * from "./populateContractsRegister.js";
+export { toLegacyOperations } from "./toLegacyOperation.js";
+export * from "./types.js";

package/dist/types/history/inner-operations.d.ts

@@ -0,0 +1,57 @@
+import type { Address } from "viem";
+import type { AdapterOperation } from "../plugins/adapters/index.js";
+/**
+ * Increase debt (borrow more).
+ * @see https://github.com/Gearbox-protocol/charts_server/blob/master/core/operation_type_v3.go#L149-L154
+ */
+export interface IncreaseDebtOp<TToken = Address> {
+    operation: "IncreaseBorrowedAmount";
+    token: TToken;
+    amount: bigint;
+}
+/**
+ * Decrease debt (repay).
+ * @see https://github.com/Gearbox-protocol/charts_server/blob/master/core/operation_type_v3.go#L155-L161
+ */
+export interface DecreaseDebtOp<TToken = Address> {
+    operation: "DecreaseBorrowedAmount";
+    token: TToken;
+    amount: bigint;
+}
+/**
+ * Add collateral to credit account.
+ */
+export interface AddCollateralOp<TToken = Address> {
+    operation: "AddCollateral";
+    token: TToken;
+    amount: bigint;
+}
+/**
+ * Withdraw collateral from credit account.
+ * @see https://github.com/Gearbox-protocol/charts_server/blob/master/core/operation_type_v3.go#L162-L171
+ */
+export interface WithdrawCollateralOp<TToken = Address> {
+    operation: "WithdrawCollateral";
+    token: TToken;
+    amount: bigint;
+    to: Address;
+    phantomToken?: TToken;
+}
+/**
+ * Update token quota on credit account.
+ * @see https://github.com/Gearbox-protocol/charts_server/blob/master/core/operation_type_v3.go#L172-L178
+ */
+export interface UpdateQuotaOp<TToken = Address> {
+    operation: "UpdateQuota";
+    token: TToken;
+    change: bigint;
+}
+/**
+ * Union of facade inner-call operation types (non-adapter credit account operations).
+ * Discriminated on the `operation` field.
+ */
+export type InnerFacadeOperation<TToken = Address> = IncreaseDebtOp<TToken> | DecreaseDebtOp<TToken> | AddCollateralOp<TToken> | WithdrawCollateralOp<TToken> | UpdateQuotaOp<TToken>;
+/**
+ * All operations that can happen within a CreditFacade's multicall and that we're interested in.
+ */
+export type InnerOperation<TToken = Address> = AdapterOperation<TToken> | InnerFacadeOperation<TToken>;