@gearbox-protocol/sdk 14.10.6 → 14.11.0-next.1

package/dist/types/preview/prerequisites/types.d.ts

@@ -0,0 +1,78 @@
+import type { Address } from "viem";
+import type { OnchainSDK } from "../../sdk/index.js";
+/**
+ * Extension point that ties each prerequisite kind to its detail payload.
+ *
+ * Adding a new prerequisite kind only requires a new entry here: the generic
+ * machinery below and the UI renderer registry both key off this map, so TS
+ * forces every consumer to handle the new kind.
+ *
+ * IMPORTANT: only add prerequisites that are *actionable by the transaction
+ * sender* (the LP provider or borrower). A valid prerequisite is one the user
+ * can resolve themselves before retrying, e.g. approve a token (`allowance`)
+ * or acquire/free up funds (`balance`). Do NOT add protocol- or admin-level
+ * state the user cannot change, such as pool pause status or available pool
+ * liquidity; those are not actionable and must not be listed as prerequisites.
+ */
+export interface PrerequisiteDetailMap {
+    /** ERC-20 allowance from `owner` to `spender` must cover `required`. */
+    allowance: {
+        token: Address;
+        owner: Address;
+        spender: Address;
+        required: bigint;
+        /** On-chain allowance read; only present when the read succeeded. */
+        actual?: bigint;
+    };
+    /** ERC-20 balance of `owner` must cover `required`. */
+    balance: {
+        token: Address;
+        owner: Address;
+        required: bigint;
+        /** On-chain balance read; only present when the read succeeded. */
+        actual?: bigint;
+    };
+}
+export type PrerequisiteKind = keyof PrerequisiteDetailMap;
+export type PrerequisiteDetail<K extends PrerequisiteKind = PrerequisiteKind> = PrerequisiteDetailMap[K];
+/** Failure of the underlying on-chain read (revert, decode error, RPC error). */
+export interface PrerequisiteError {
+    /** Decoded revert reason / error name, human-readable. */
+    reason: string;
+    /** Original error, kept for debugging. */
+    cause?: unknown;
+}
+export interface PrerequisiteBase<K extends PrerequisiteKind> {
+    id: string;
+    kind: K;
+    title: string;
+    detail: PrerequisiteDetail<K>;
+}
+/**
+ * Outcome of verifying a single prerequisite: either the read succeeded (a
+ * `satisfied` boolean) or it reverted/failed (an `error` with the revert
+ * reason). The two variants are mutually exclusive.
+ */
+export type PrerequisiteResult<K extends PrerequisiteKind = PrerequisiteKind> = PrerequisiteBase<K> & ({
+    satisfied: boolean;
+    error?: undefined;
+} | {
+    satisfied?: undefined;
+    error: PrerequisiteError;
+});
+/**
+ * Discriminated union over every prerequisite kind. Switching on `kind`
+ * narrows `detail` to the matching payload, so React components can render
+ * kind-specific details with full type safety.
+ */
+export type AnyPrerequisiteResult = {
+    [K in PrerequisiteKind]: PrerequisiteResult<K>;
+}[PrerequisiteKind];
+/** Shared inputs for building and verifying prerequisites. */
+export interface PrerequisiteContext {
+    sdk: OnchainSDK;
+    /** Address whose balances/allowances are checked (the tx sender). */
+    wallet: Address;
+    /** Block to read at; defaults to latest. Only set for testnet forks. */
+    blockNumber?: bigint;
+}

package/dist/types/preview/simulate/decodeSimulationError.d.ts

@@ -0,0 +1,18 @@
+import { type Hex } from "viem";
+import type { SimulationError } from "./types.js";
+/** Per-call slice of a `simulateCalls` failure we need to decode. */
+export interface SimulationRevert {
+    error?: Error;
+    /** Raw revert return data, when present. */
+    data?: Hex;
+}
+/**
+ * Decodes a simulated transaction revert into a {@link SimulationError}.
+ *
+ * The simulated call is raw calldata (no ABI), so viem cannot decode the revert
+ * itself. We first try to decode the raw return bytes against the SDK's
+ * {@link errorAbis} (Gearbox protocol exceptions plus standard ERC-20 custom
+ * errors); failing that, we walk viem's error chain for a
+ * {@link ContractFunctionRevertedError} (covers `Error(string)` / `Panic`).
+ */
+export declare function decodeSimulationError(revert: SimulationRevert): SimulationError;

package/dist/types/preview/simulate/extractERC20Transfers.d.ts

@@ -0,0 +1,11 @@
+import { type Address, type Log } from "viem";
+import type { TokenTransfer } from "../../plugins/adapters/index.js";
+/**
+ * Parses ERC-20 `Transfer` logs and keeps only those involving one of the
+ * watched addresses (as sender or receiver). A log that touches several watched
+ * addresses is still emitted once.
+ *
+ * @param logs - raw logs from the simulated call
+ * @param watch - addresses whose transfers we care about (e.g. wallet + recipient)
+ */
+export declare function extractERC20Transfers(logs: Log[], watch: Address[]): TokenTransfer[];

package/dist/types/preview/simulate/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./decodeSimulationError.js";
+export * from "./extractERC20Transfers.js";
+export * from "./simulatePoolOperation.js";
+export * from "./types.js";

package/dist/types/preview/simulate/simulatePoolOperation.d.ts

@@ -0,0 +1,30 @@
+import { type Address, type Hex } from "viem";
+import type { OnchainSDK } from "../../sdk/index.js";
+import type { PoolOperation } from "../parse/index.js";
+import type { PoolSimulationResult } from "./types.js";
+export interface SimulatePoolOperationInput {
+    /** Only `client` is used, so any OnchainSDK works. */
+    sdk: OnchainSDK;
+    /** Parsed operation, used to resolve the underlying and pool tokens. */
+    operation: PoolOperation;
+    /** Target contract the calldata is sent to (the pool). */
+    to: Address;
+    /** Raw deposit/redeem calldata to simulate. */
+    calldata: Hex;
+    /** Wallet whose balance changes and transfers we track. */
+    wallet: Address;
+    /** Block to simulate at; defaults to latest. Only set for testnet forks. */
+    blockNumber?: bigint;
+}
+/**
+ * Simulates a pool deposit/redeem by sandwiching the raw calldata between
+ * `balanceOf(wallet)` reads of the underlying and pool (share) tokens.
+ *
+ * On success, returns the ERC-20 transfers emitted by the call that involve the
+ * wallet or the operation recipient (for merging into the parsed operation) and
+ * the balance changes grouped by watched address (wallet, plus the recipient
+ * when distinct); on revert, returns the decoded reason. Simulation runs against
+ * real chain state (no overrides), so an unmet prerequisite surfaces here as a
+ * failure.
+ */
+export declare function simulatePoolOperation(input: SimulatePoolOperationInput): Promise<PoolSimulationResult>;

package/dist/types/preview/simulate/types.d.ts

@@ -0,0 +1,43 @@
+import type { Address } from "viem";
+import type { TokenTransfer } from "../../plugins/adapters/index.js";
+/**
+ * Change in an address's balance of a single token over the simulated call.
+ * `delta` is `after - before` (negative when the address spent the token).
+ */
+export interface TokenBalanceChange {
+    token: Address;
+    before: bigint;
+    after: bigint;
+    delta: bigint;
+}
+/**
+ * Balance changes for a single watched address (e.g. the wallet or the
+ * operation recipient). Keyed purely by address; UI labeling is resolved
+ * separately by the presentation layer.
+ */
+export interface AddressBalanceChanges {
+    address: Address;
+    changes: TokenBalanceChange[];
+}
+/** Decoded revert of the simulated transaction. */
+export interface SimulationError {
+    /** Human-readable revert reason / error name. */
+    reason: string;
+    /** Original error, kept for debugging. */
+    cause?: unknown;
+}
+/**
+ * Outcome of simulating a pool operation. On success it carries the
+ * wallet-filtered ERC-20 transfers (to merge into the parsed operation) and the
+ * balance changes grouped by watched address; on failure it carries the decoded
+ * revert reason.
+ */
+export type PoolSimulationResult = {
+    status: "success";
+    transfers: TokenTransfer[];
+    balanceChanges: AddressBalanceChanges[];
+    gasUsed: bigint;
+} | {
+    status: "failure";
+    error: SimulationError;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "14.10.6",
+  "version": "14.11.0-next.1",
   "description": "Gearbox SDK",
   "license": "MIT",
   "repository": {
@@ -44,6 +44,11 @@
       "import": "./dist/esm/permissionless/index.js",
       "default": "./dist/cjs/permissionless/index.js"
     },
+    "./preview": {
+      "types": "./dist/types/preview/index.d.ts",
+      "import": "./dist/esm/preview/index.js",
+      "default": "./dist/cjs/preview/index.js"
+    },
     "./common-utils": {
       "types": "./dist/types/common-utils/index.d.ts",
       "import": "./dist/esm/common-utils/index.js",