@gearbox-protocol/sdk 13.0.0-next.3 → 13.0.0-next.31

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/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 * from "./inner-operations.js";
+export * from "./mapOperations.js";
+export { parseCreditAccountTransaction } from "./parseCreditAccountTransaction.js";
+export * from "./populateContractsRegister.js";
+export * 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 {
+    operation: "IncreaseBorrowedAmount";
+    token: Address;
+    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 {
+    operation: "DecreaseBorrowedAmount";
+    token: Address;
+    amount: bigint;
+}
+/**
+ * Add collateral to credit account.
+ */
+export interface AddCollateralOp {
+    operation: "AddCollateral";
+    token: Address;
+    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 {
+    operation: "WithdrawCollateral";
+    token: Address;
+    amount: bigint;
+    to: Address;
+    phantomToken?: Address;
+}
+/**
+ * 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 {
+    operation: "UpdateQuota";
+    token: Address;
+    change: bigint;
+}
+/**
+ * Union of facade inner-call operation types (non-adapter credit account operations).
+ * Discriminated on the `operation` field.
+ */
+export type InnerFacadeOperation = IncreaseDebtOp | DecreaseDebtOp | AddCollateralOp | WithdrawCollateralOp | UpdateQuotaOp;
+/**
+ * All operations that can happen within a CreditFacade's multicall and that we're interested in.
+ */
+export type InnerOperation = AdapterOperation | InnerFacadeOperation;

package/dist/types/history/internal-types.d.ts

@@ -0,0 +1,47 @@
+import type { Address, Hex } from "viem";
+import type { TokenTransfer } from "../plugins/adapters/index.js";
+import type { ParsedCallV2 } from "../sdk/index.js";
+/**
+ * A single frame from Ethereum's `debug_traceTransaction` callTracer output.
+ * Recursive: each frame may contain nested sub-calls.
+ */
+export interface CallTrace {
+    from: Address;
+    to: Address;
+    input: Hex;
+    output: Hex;
+    value: Hex;
+    /** "CALL", "DELEGATECALL", "STATICCALL", "CREATE", etc. */
+    type: string;
+    /** Present when the call reverted (e.g. "execution reverted"). */
+    error?: string;
+    /** ABI-encoded revert data, if available. */
+    revertReason?: Hex;
+    calls?: CallTrace[];
+}
+/**
+ * The set of credit facade entry-point functions that produce history operations.
+ */
+export type FacadeCallType = "MultiCall" | "BotMulticall" | "OpenCreditAccount" | "CloseCreditAccount" | "LiquidateCreditAccount" | "PartiallyLiquidateCreditAccount";
+/**
+ * A parsed credit facade call extracted from a call trace,
+ * with inner multicall calls already decoded.
+ */
+export interface FacadeParsedCall {
+    operation: FacadeCallType;
+    creditAccount: Address;
+    /** The full ParsedCallV2 from facade calldata parsing. */
+    parsed: ParsedCallV2;
+    /** Inner multicall entries from rawArgs.calls (empty for partiallyLiquidateCreditAccount). */
+    innerCalls: ParsedCallV2[];
+    /** The full call trace node for this facade call (used to extract protocol-level calldata). */
+    trace: CallTrace;
+}
+/**
+ * Data extracted from a single Execute event: the ERC-20 transfers that
+ * occurred between Execute boundaries and the target contract address.
+ */
+export interface ExecuteResult {
+    transfers: TokenTransfer[];
+    targetContract: Address;
+}

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

@@ -0,0 +1,27 @@
+import type { AdapterOperation } from "../plugins/adapters/index.js";
+import type { AddCollateralOp, DecreaseDebtOp, IncreaseDebtOp, UpdateQuotaOp, WithdrawCollateralOp } from "./inner-operations.js";
+import type { CloseCreditAccountOperation, CreditAccountOperation, DirectTokenTransferOperation, FacadeOperationMetadata, LiquidateCreditAccountOperation, MulticallOperation, OpenCreditAccountOperation, PartialLiquidationOperation } from "./types.js";
+/**
+ * Visitor that maps each operation node in a {@link CreditAccountOperation}
+ * tree to a new representation.
+ *
+ */
+export interface OperationVisitor<TInner, TOuter> {
+    Execute(op: AdapterOperation, ctx: FacadeOperationMetadata): TInner;
+    IncreaseBorrowedAmount(op: IncreaseDebtOp, ctx: FacadeOperationMetadata): TInner;
+    DecreaseBorrowedAmount(op: DecreaseDebtOp, ctx: FacadeOperationMetadata): TInner;
+    AddCollateral(op: AddCollateralOp, ctx: FacadeOperationMetadata): TInner;
+    WithdrawCollateral(op: WithdrawCollateralOp, ctx: FacadeOperationMetadata): TInner;
+    UpdateQuota(op: UpdateQuotaOp, ctx: FacadeOperationMetadata): TInner;
+    DirectTokenTransfer(op: DirectTokenTransferOperation): TOuter;
+    MultiCall(op: MulticallOperation, multicall: TInner[]): TOuter;
+    OpenCreditAccount(op: OpenCreditAccountOperation, multicall: TInner[]): TOuter;
+    CloseCreditAccount(op: CloseCreditAccountOperation, multicall: TInner[]): TOuter;
+    LiquidateCreditAccount(op: LiquidateCreditAccountOperation, multicall: TInner[]): TOuter;
+    PartiallyLiquidateCreditAccount(op: PartialLiquidationOperation): TOuter;
+}
+/**
+ * Walks a list of {@link CreditAccountOperation}s, mapping each node via the
+ * given visitor
+ */
+export declare function mapOperations<TInner, TOuter>(ops: CreditAccountOperation[], visitor: OperationVisitor<TInner, TOuter>): TOuter[];

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

@@ -0,0 +1,27 @@
+import type { Address, TransactionReceipt } from "viem";
+import type { ChainContractsRegister } from "../sdk/index.js";
+import type { CreditAccountOperation } from "./types.js";
+export interface ParseTransactionInput {
+    /**
+     * Output of `debug_traceTransaction`
+     */
+    trace: unknown;
+    receipt: Pick<TransactionReceipt<bigint | number>, "logs" | "transactionHash" | "blockNumber" | "blockTimestamp">;
+    pool: Address;
+    /**
+     * Underlying token of the pool.
+     */
+    underlying: Address;
+    creditManager: Address;
+    creditFacade: Address;
+    creditAccount: Address;
+    register: ChainContractsRegister;
+    /**
+     * Whether to throw an error if an unknown adapter/protocol is encountered.
+     */
+    strict?: boolean;
+}
+/**
+ * Parses a single transaction into classified credit account operations.
+ */
+export declare function parseCreditAccountTransaction(input: ParseTransactionInput): CreditAccountOperation[];

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

@@ -0,0 +1,19 @@
+import { type Address, type Chain, type PublicClient, type Transport } from "viem";
+import { ChainContractsRegister, type ILogger, type TokenMetaData, TokensMeta } from "../sdk/index.js";
+export type DeploymentLike = {
+    address: Address;
+    version: number;
+} & ({
+    contractTypePrefix: string;
+    contractTypeSuffix: string;
+} | {
+    contractType: string;
+});
+export interface PopulateContractsRegisterOptions {
+    client: PublicClient<Transport, Chain>;
+    deployments: DeploymentLike[];
+    tokens: TokensMeta | Iterable<TokenMetaData>;
+    logger?: ILogger;
+    strict?: boolean;
+}
+export declare function populateContractsRegister(options: PopulateContractsRegisterOptions): ChainContractsRegister;

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

@@ -0,0 +1,18 @@
+import type { Hex } from "viem";
+import { type OperationVisitor } from "./mapOperations.js";
+import type { CreditAccountOperation } from "./types.js";
+export interface LegacyApiOperation {
+    operation: string;
+    txHash: Hex;
+    blockNum: number;
+    [key: string]: unknown;
+}
+export interface LegacyMulticallOp {
+    operation: string;
+    [key: string]: unknown;
+}
+export interface LegacyVisitorParams {
+    sessionId: string;
+}
+export declare function createLegacyVisitor(params: LegacyVisitorParams): OperationVisitor<LegacyMulticallOp, LegacyApiOperation>;
+export declare function toLegacyOperations(ops: CreditAccountOperation[], params: LegacyVisitorParams): LegacyApiOperation[];

package/dist/types/history/trace-utils.d.ts

@@ -0,0 +1,12 @@
+import { type Address } from "viem";
+import type { CallTrace } from "./internal-types.js";
+/**
+ * Finds the first non-reverted CALL to `target` anywhere in a trace subtree.
+ */
+export declare function findCallTo(node: CallTrace, target: Address): CallTrace | undefined;
+/**
+ * DFS walk of the call trace tree, collecting non-reverted CALL entries
+ * to the given address.
+ * Does not recurse into children of matched nodes
+ */
+export declare function collectTraces(node: CallTrace, target: Address): CallTrace[];

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

@@ -0,0 +1,71 @@
+import type { Address, Hex } from "viem";
+import type { InnerOperation } from "./inner-operations.js";
+/**
+ * An ERC-20 Transfer to the credit account that was not part of any
+ * facade operation (multicall, liquidation, etc.).
+ */
+export interface DirectTransferInfo {
+    token: Address;
+    from: Address;
+    amount: bigint;
+}
+export interface OperationMetadata {
+    txHash: Hex;
+    blockNumber: number;
+    timestamp: number;
+}
+export interface FacadeOperationMetadata extends OperationMetadata {
+    creditManager: Address;
+    creditFacade: Address;
+}
+export interface MulticallOperation extends FacadeOperationMetadata {
+    operation: "MultiCall" | "BotMulticall";
+    creditAccount: Address;
+    multicall: InnerOperation[];
+}
+export interface OpenCreditAccountOperation extends FacadeOperationMetadata {
+    operation: "OpenCreditAccount";
+    creditAccount: Address;
+    onBehalfOf: Address;
+    referralCode: bigint;
+    multicall: InnerOperation[];
+}
+export interface CloseCreditAccountOperation extends FacadeOperationMetadata {
+    operation: "CloseCreditAccount";
+    creditAccount: Address;
+    multicall: InnerOperation[];
+}
+export interface LiquidateCreditAccountOperation extends FacadeOperationMetadata {
+    operation: "LiquidateCreditAccount";
+    creditAccount: Address;
+    to: Address;
+    token: Address;
+    remainingFunds: bigint;
+    multicall: InnerOperation[];
+}
+export interface PartialLiquidationOperation extends FacadeOperationMetadata {
+    operation: "PartiallyLiquidateCreditAccount";
+    creditAccount: Address;
+    token: Address;
+    repaidAmount: bigint;
+    minSeizedAmount: bigint;
+    to: Address;
+}
+export interface DirectTokenTransferOperation extends OperationMetadata {
+    operation: "DirectTokenTransfer";
+    protocol: Address;
+    token: Address;
+    from: Address;
+    creditAccount: Address;
+    amount: bigint;
+}
+/**
+ * Discriminated union of all facade-level operation types.
+ * One per facade entry-point call within a transaction.
+ */
+export type OuterFacadeOperation = MulticallOperation | OpenCreditAccountOperation | CloseCreditAccountOperation | LiquidateCreditAccountOperation | PartialLiquidationOperation;
+/**
+ * Discriminated union of all credit account operation types
+ * (facade operations + direct token transfers).
+ */
+export type CreditAccountOperation = OuterFacadeOperation | DirectTokenTransferOperation;

package/dist/types/plugins/adapters/abi/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./actionAbi.js";
 export * from "./conctructorAbi.js";
+export * from "./targetContractAbi.js";
 export * from "./utils.js";