@morpho-org/evm-simulation 4.2.0 → 5.0.0

package/lib/cjs/simulate/slippage.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSlippage = checkSlippage;
+const morpho_ts_1 = require("@morpho-org/morpho-ts");
+const errors_js_1 = require("../errors.js");
+/**
+ * Compare observed amounts against the caller's quote and percentage tolerance.
+ * Minimum outputs round up and maximum inputs round down, so rounding never
+ * permits a deviation greater than the requested percentage.
+ * @param params - Parsed quote/tolerance, matching observations, and error context.
+ * @returns The checked quote and tolerance, deep-frozen.
+ * @throws {ConsumerLimitViolationError} When adverse slippage exceeds tolerance.
+ * @throws {MissingVerificationEvidenceError} When a quoted amount has no observation.
+ * @internal
+ */
+function checkSlippage(params) {
+    const { limits, observed, context, debtShares = false } = params;
+    const quote = {};
+    for (const [field, output] of [
+        ["assetsReceived", true],
+        ["sharesMinted", !debtShares],
+        ["assetsPaid", false],
+        ["sharesBurned", debtShares],
+    ]) {
+        const expected = limits.quote[field];
+        if (expected === undefined)
+            continue;
+        const amount = observed[field];
+        if (amount === undefined) {
+            throw new errors_js_1.MissingVerificationEvidenceError(`Missing observation for "${field}". Supply the matching asset or position.`, { context: { ...context, field } });
+        }
+        const bound = output
+            ? morpho_ts_1.MathLib.wMulUp(expected, morpho_ts_1.MathLib.WAD - limits.slippageTolerance)
+            : morpho_ts_1.MathLib.wMulDown(expected, morpho_ts_1.MathLib.WAD + limits.slippageTolerance);
+        if (output ? amount < bound : amount > bound) {
+            throw new errors_js_1.ConsumerLimitViolationError(`Slippage for "${field}" exceeds tolerance "${limits.slippageTolerance}" against quote "${expected}"; allowed bound "${bound}", got "${amount}". Adjust the transaction or tolerance.`, { context: { ...context, field, expected: bound, observed: amount } });
+        }
+        quote[field] = expected;
+    }
+    return (0, morpho_ts_1.deepFreeze)({ quote, slippageTolerance: limits.slippageTolerance });
+}

package/lib/cjs/simulate/state/contract.d.ts

@@ -0,0 +1,19 @@
+import type { MarketId } from "@morpho-org/blue-sdk";
+import type { Address, Hex } from "viem";
+/** Minimal view call replayed before and after the user bundle. @internal */
+export type StateRead = {
+    readonly id: string;
+    readonly to: Address;
+    readonly data: Hex;
+} & ({
+    readonly kind: "erc20.balance";
+    readonly token: Address;
+    readonly account: Address;
+} | {
+    readonly kind: "morpho.position";
+    readonly morpho: Address;
+    readonly marketId: MarketId;
+    readonly owner: Address;
+});
+/** Phase at which a slippage observation is read. @internal */
+export type ReadPhase = "before" | "after";

package/lib/cjs/simulate/state/contract.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/simulate/state/read-state.d.ts

@@ -0,0 +1,60 @@
+import { type Address, type Hex } from "viem";
+import type { OperationLimit, SlippageQuote } from "../../limits.js";
+import type { SimulationMode } from "../../params.js";
+import type { ResolvedSlippageOperation } from "../backends/resolve-assets.js";
+import type { StateRead } from "./contract.js";
+/** One quoted amount's observation source. @internal */
+type SlippageMeasurement = {
+    readonly field: keyof SlippageQuote;
+} & ({
+    readonly type: "native";
+    readonly account: Address;
+} | {
+    readonly type: "balance";
+    readonly readId: string;
+} | {
+    readonly type: "position";
+    readonly readId: string;
+    readonly shares: "supplyShares" | "borrowShares";
+});
+/** Caller quote paired with exactly the observations it needs. @internal */
+export interface SlippageOperationReads {
+    readonly limit: OperationLimit;
+    readonly measurements: readonly SlippageMeasurement[];
+}
+/** Scalar balance or the two share counts returned by Morpho.position. @internal */
+export type StateValue = bigint | {
+    readonly supplyShares: bigint;
+    readonly borrowShares: bigint;
+};
+/**
+ * Plan only quoted balance and position reads, deduplicating contract calls.
+ * Native deltas use the execution's transfer traces and require no view call.
+ * @param params - Resolved caller operations and the transaction sender/Morpho address.
+ * @returns Read calls and their mapping to each quoted amount; empty without limits.
+ * @internal
+ */
+export declare function planStateReads(params: {
+    readonly operations: readonly ResolvedSlippageOperation[];
+    readonly owner: Address;
+    readonly morpho: Address;
+}): {
+    readonly reads: readonly StateRead[];
+    readonly operations: readonly SlippageOperationReads[];
+};
+/**
+ * Decode one requested balance or position without reconstructing protocol entities.
+ * @param read - Planned view call.
+ * @param data - Return data from its simulated execution.
+ * @param context - Request chain, mode and pinned block, attached to thrown errors.
+ * @returns Raw balance or supply/borrow share counts.
+ * @throws {MissingVerificationEvidenceError} When the selected subject returned no data.
+ * @throws {InvalidSimulationResponseError} When non-empty return data cannot be decoded.
+ * @internal
+ */
+export declare function decodeStateRead(read: StateRead, data: Hex, context: {
+    readonly chainId: number;
+    readonly mode: SimulationMode;
+    readonly blockNumber: bigint;
+}): StateValue;
+export {};

package/lib/cjs/simulate/state/read-state.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planStateReads = planStateReads;
+exports.decodeStateRead = decodeStateRead;
+const abis_1 = require("@morpho-org/morpho-sdk/abis");
+const viem_1 = require("viem");
+const errors_js_1 = require("../../errors.js");
+const measurement_plan_js_1 = require("../measurement-plan.js");
+function planBalanceRead(params) {
+    const { reads, token, account } = params;
+    const id = `balance:${token}:${account}`.toLowerCase();
+    reads.set(id, {
+        kind: "erc20.balance",
+        id,
+        to: token,
+        token,
+        account,
+        data: (0, viem_1.encodeFunctionData)({
+            abi: viem_1.erc20Abi,
+            functionName: "balanceOf",
+            args: [account],
+        }),
+    });
+    return id;
+}
+function planPositionRead(params) {
+    const { reads, morpho, marketId, account } = params;
+    const id = `position:${marketId}:${account}`.toLowerCase();
+    reads.set(id, {
+        kind: "morpho.position",
+        id,
+        to: morpho,
+        morpho,
+        marketId,
+        owner: account,
+        data: (0, viem_1.encodeFunctionData)({
+            abi: abis_1.blueAbi,
+            functionName: "position",
+            args: [marketId, account],
+        }),
+    });
+    return id;
+}
+/**
+ * Plan only quoted balance and position reads, deduplicating contract calls.
+ * Native deltas use the execution's transfer traces and require no view call.
+ * @param params - Resolved caller operations and the transaction sender/Morpho address.
+ * @returns Read calls and their mapping to each quoted amount; empty without limits.
+ * @internal
+ */
+function planStateReads(params) {
+    const reads = new Map();
+    const operations = params.operations.map(({ limit, assetsPaid, assetsReceived }) => {
+        const measurements = [];
+        const account = limit.account ?? params.owner;
+        const plan = (0, measurement_plan_js_1.operationMeasurementPlan)(limit);
+        for (const field of [
+            "assetsReceived",
+            "assetsPaid",
+            "sharesMinted",
+            "sharesBurned",
+        ]) {
+            if (limit.quote[field] === undefined)
+                continue;
+            const assetField = field === "assetsReceived" || field === "assetsPaid";
+            if (!assetField) {
+                const source = field === "sharesMinted" ? plan.sharesMinted : plan.sharesBurned;
+                if (source === undefined)
+                    continue;
+                if (source.type === "position") {
+                    measurements.push({
+                        field,
+                        type: "position",
+                        readId: planPositionRead({
+                            reads,
+                            morpho: params.morpho,
+                            marketId: source.marketId,
+                            account,
+                        }),
+                        shares: source.shares,
+                    });
+                    continue;
+                }
+                measurements.push({
+                    field,
+                    type: "balance",
+                    readId: planBalanceRead({
+                        reads,
+                        token: source.token,
+                        account,
+                    }),
+                });
+                continue;
+            }
+            const token = field === "assetsReceived" ? assetsReceived : assetsPaid;
+            const holder = field === "assetsReceived"
+                ? (limit.receiver ?? params.owner)
+                : params.owner;
+            if (token === undefined) {
+                continue;
+            }
+            if ((0, viem_1.isAddressEqual)(token, viem_1.ethAddress)) {
+                measurements.push({ field, type: "native", account: holder });
+                continue;
+            }
+            measurements.push({
+                field,
+                type: "balance",
+                readId: planBalanceRead({ reads, token, account: holder }),
+            });
+        }
+        return { limit, measurements };
+    });
+    return { reads: [...reads.values()], operations };
+}
+/**
+ * Decode one requested balance or position without reconstructing protocol entities.
+ * @param read - Planned view call.
+ * @param data - Return data from its simulated execution.
+ * @param context - Request chain, mode and pinned block, attached to thrown errors.
+ * @returns Raw balance or supply/borrow share counts.
+ * @throws {MissingVerificationEvidenceError} When the selected subject returned no data.
+ * @throws {InvalidSimulationResponseError} When non-empty return data cannot be decoded.
+ * @internal
+ */
+// biome-ignore lint/complexity/useMaxParams: the call mirrors the failure context it attaches
+function decodeStateRead(read, data, context) {
+    if (data === "0x") {
+        throw new errors_js_1.MissingVerificationEvidenceError(`Cannot observe slippage read "${read.id}": the selected subject returned no data (likely not a contract).`, { context: { stage: "verification", ...context, field: read.id } });
+    }
+    try {
+        if (read.kind === "erc20.balance")
+            return (0, viem_1.decodeFunctionResult)({
+                abi: viem_1.erc20Abi,
+                functionName: "balanceOf",
+                data,
+            });
+        const [supplyShares, borrowShares] = (0, viem_1.decodeFunctionResult)({
+            abi: abis_1.blueAbi,
+            functionName: "position",
+            data,
+        });
+        return { supplyShares, borrowShares };
+    }
+    catch (cause) {
+        throw new errors_js_1.InvalidSimulationResponseError(`Cannot decode slippage observation "${read.id}". Check the selected contract and RPC response.`, { cause });
+    }
+}

package/lib/cjs/simulate/verify-slippage.d.ts

@@ -0,0 +1,24 @@
+import { type Address } from "viem";
+import type { SimulatedOperation } from "../result.js";
+import type { Transfer } from "../types.js";
+import type { CheckContext } from "./context.js";
+import type { SlippageOperationReads, StateValue } from "./state/read-state.js";
+/**
+ * Measure only caller-quoted amounts and compare their percentage slippage.
+ * @param params - Planned observations, decoded before/after values, and user transfer traces.
+ * @returns Each caller subject and its checked quote/tolerance.
+ * @throws {ConsumerLimitViolationError} When adverse slippage exceeds tolerance.
+ * @throws {MissingVerificationEvidenceError} When a requested observation is absent.
+ * @internal
+ */
+export declare function verifySlippage(params: {
+    readonly ctx: CheckContext;
+    readonly operations: readonly SlippageOperationReads[];
+    readonly before: ReadonlyMap<string, StateValue>;
+    readonly after: ReadonlyMap<string, StateValue>;
+    readonly transfers: readonly Transfer[];
+    readonly requestTransactions: readonly {
+        readonly from: Address;
+        readonly value?: bigint;
+    }[];
+}): readonly SimulatedOperation[];

package/lib/cjs/simulate/verify-slippage.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifySlippage = verifySlippage;
+const blue_sdk_1 = require("@morpho-org/blue-sdk");
+const viem_1 = require("viem");
+const errors_js_1 = require("../errors.js");
+const measurement_plan_js_1 = require("./measurement-plan.js");
+const slippage_js_1 = require("./slippage.js");
+/**
+ * Measure only caller-quoted amounts and compare their percentage slippage.
+ * @param params - Planned observations, decoded before/after values, and user transfer traces.
+ * @returns Each caller subject and its checked quote/tolerance.
+ * @throws {ConsumerLimitViolationError} When adverse slippage exceeds tolerance.
+ * @throws {MissingVerificationEvidenceError} When a requested observation is absent.
+ * @internal
+ */
+function verifySlippage(params) {
+    const { ctx, before, after, transfers, requestTransactions } = params;
+    return params.operations.map(({ limit, measurements }) => {
+        const subject = (0, measurement_plan_js_1.operationMeasurementPlan)(limit).subject;
+        const context = {
+            stage: "verification",
+            chainId: ctx.chainId,
+            mode: ctx.mode,
+            blockNumber: ctx.block.stateBlockNumber,
+            ...subject,
+        };
+        const observed = {};
+        for (const measurement of measurements) {
+            let delta;
+            if (measurement.type === "native") {
+                const tracedOutgoing = transfers.reduce((total, transfer) => (0, viem_1.isAddressEqual)(transfer.token, viem_1.ethAddress) &&
+                    (0, viem_1.isAddressEqual)(transfer.from, measurement.account)
+                    ? total + transfer.amount
+                    : total, 0n);
+                const sentValue = requestTransactions.reduce((total, transaction) => (0, viem_1.isAddressEqual)(transaction.from, measurement.account)
+                    ? total + (transaction.value ?? 0n)
+                    : total, 0n);
+                if (tracedOutgoing < sentValue) {
+                    throw new errors_js_1.MissingVerificationEvidenceError(`Missing native transfer evidence for "${measurement.field}" from a transaction with value.`, { context: { ...context, field: measurement.field } });
+                }
+                delta = 0n;
+                for (const transfer of transfers) {
+                    if (!(0, viem_1.isAddressEqual)(transfer.token, viem_1.ethAddress))
+                        continue;
+                    if ((0, viem_1.isAddressEqual)(transfer.to, measurement.account))
+                        delta += transfer.amount;
+                    if ((0, viem_1.isAddressEqual)(transfer.from, measurement.account))
+                        delta -= transfer.amount;
+                }
+            }
+            else {
+                const b = before.get(measurement.readId);
+                const a = after.get(measurement.readId);
+                if (measurement.type === "balance" &&
+                    typeof b === "bigint" &&
+                    typeof a === "bigint")
+                    delta = a - b;
+                else if (measurement.type === "position" &&
+                    typeof b === "object" &&
+                    typeof a === "object")
+                    delta = a[measurement.shares] - b[measurement.shares];
+                else
+                    throw new errors_js_1.MissingVerificationEvidenceError(`Missing observation for "${measurement.field}". Check the selected subject.`, { context: { ...context, field: measurement.field } });
+            }
+            observed[measurement.field] =
+                measurement.field === "assetsPaid" ||
+                    measurement.field === "sharesBurned"
+                    ? blue_sdk_1.MathLib.max(0n, -delta)
+                    : delta;
+        }
+        return {
+            ...subject,
+            account: limit.account ?? ctx.owner,
+            receiver: limit.receiver ?? ctx.owner,
+            checkedLimits: (0, slippage_js_1.checkSlippage)({
+                limits: limit,
+                observed,
+                context,
+                debtShares: measurements.some((measurement) => measurement.type === "position" &&
+                    measurement.shares === "borrowShares"),
+            }),
+        };
+    });
+}

package/lib/cjs/types.d.ts

@@ -1,41 +1,21 @@
-import type { Address, BlockTag, Hex } from "viem";
-/**
- * Credentials for the Tenderly Node Web3 Gateway. The `rpcUrl` is the
- * chain-specific gateway URL with the access key embedded in the path,
- * e.g. `https://mainnet.gateway.tenderly.co/{ACCESS_KEY}`.
- */
-export interface TenderlyRpcConfig {
-    rpcUrl: string;
+import type { Address, Hex } from "viem";
+/** Per-chain endpoint for the sole supported simulation method, `eth_simulateV1`. */
+export interface ChainSimulationConfig {
+    /** JSON-RPC URL supporting `eth_simulateV1`. Required for every configured chain. */
+    readonly simulateV1Url: string;
 }
-/**
- * Per-chain backend capabilities. Exactly one configuration shape per chain;
- * the discriminated union enforces that **at least one** of `tenderlyRpc`
- * (primary) or `simulateV1Url` (fallback) is supplied.
- */
-export type ChainSimulationConfig = {
-    /** Tenderly RPC config — `tenderly_simulateTransaction` / `tenderly_simulateBundle`. */
-    tenderlyRpc: TenderlyRpcConfig;
-    /** JSON-RPC URL supporting `eth_simulateV1`. Optional when Tenderly is set. */
-    simulateV1Url?: string;
-} | {
-    tenderlyRpc?: TenderlyRpcConfig;
-    simulateV1Url: string;
-};
 /**
  * Top-level configuration for `simulate`.
  *
- * Every chain entry must declare at least one backend (Tenderly RPC primary,
- * `eth_simulateV1` fallback, or both). Calling `simulate` for a `chainId`
- * missing from `chains` throws `UnsupportedChainError`.
+ * Every chain entry must supply an `eth_simulateV1` endpoint. An absent chain
+ * or missing endpoint throws `UnsupportedChainError`; execution never selects
+ * another provider after a failure.
  */
 export interface SimulationConfig {
-    /** Per-chain simulation capabilities. */
+    /** Per-chain simulation endpoints. */
     chains: Map<number, ChainSimulationConfig>;
     logger?: SimulationLogger;
-    /**
-     * Overall timeout budget in ms (default 5000). Tenderly gets ~60% of budget.
-     * On timeout/failure, fallback gets remaining time (deadline - now).
-     */
+    /** Overall execution timeout budget in ms (default 5000). */
     timeoutMs?: number;
 }
 /**
@@ -43,31 +23,15 @@ export interface SimulationConfig {
  * in a bundle — the orchestrator rejects mixed senders with `SimulationValidationError`.
  */
 export interface SimulationTransaction {
-    from: Address;
-    to: Address;
-    data: Hex;
-    value?: bigint;
+    readonly from: Address;
+    readonly to: Address;
+    readonly data: Hex;
+    readonly value?: bigint;
 }
-/**
- * How the caller expresses a token authorization that must be in place before the
- * main transactions run. The package decides HOW to simulate each one:
- * - "approval" → prepend tx as-is
- * - "signature" → today: encode approve(spender, amount); future: ecrecover override?
- */
-export type SimulationAuthorization = {
-    type: "approval";
-    transaction: SimulationTransaction;
-} | {
-    type: "signature";
-    token: Address;
-    spender: Address;
-    /** Defaults to maxUint256. Caller can set explicit amount for tokens that don't support max approval. */
-    amount?: bigint;
-};
 /**
  * Net balance change for a single asset (one token) within an account's entry.
  * Native ETH uses viem's `ethAddress` sentinel as `token`. `symbol`/`decimals`
- * are best-effort and may be absent, notably on the `eth_simulateV1` fallback.
+ * are optional metadata; the log-derived `eth_simulateV1` output omits them.
  */
 export interface AssetChange {
     readonly token: Address;
@@ -80,12 +44,11 @@ export interface AssetChange {
  * Net per-token balance changes for one account over the whole bundle. Returned
  * for every account that nets a non-zero change, the sender and counterparties
  * alike (the zero address is kept for mints/burns). Accounts and their `changes`
- * are sorted by address for deterministic, cross-backend output.
+ * are sorted by address for deterministic output.
  *
- * Both backends report the full net native-ETH delta, including ETH moved via
- * internal calls (e.g. a `WETH.withdraw` refund): Tenderly derives it from its
- * trace, and the `eth_simulateV1` fallback runs with `traceTransfers` so the
- * node synthesizes native moves as transfer logs under viem's `ethAddress`.
+ * The backend reports the full net native-ETH delta, including ETH moved via
+ * internal calls (e.g. a `WETH.withdraw` refund). `traceTransfers` makes the
+ * node synthesize native moves as transfer logs under viem's `ethAddress`.
  */
 export interface AccountAssetChanges {
     readonly account: Address;
@@ -101,29 +64,27 @@ export interface Transfer {
     readonly to: Address;
     readonly amount: bigint;
     /**
-     * Index into `SimulationResult.simulationTxs` of the transaction that
-     * emitted the underlying log. For bundles with prepended authorization
-     * approvals, indices `[0, simulationTxs.length - params.transactions.length)`
-     * are authorization txs; the remainder are caller-supplied.
+     * Index into `SimulationResult.simulationTxs` of the user transaction that
+     * emitted the underlying log. `txIdx` only ever indexes caller-supplied
+     * transactions.
      */
     readonly txIdx: number;
 }
 /**
  * Happy-path return of `simulate`. All failures throw typed errors.
  *
- * - `simulationTxs` is the full resolved transaction list (including
- *   prepended authorization txs).
+ * - `simulationTxs` are exactly the caller's ordered transactions, normalized
+ *   (checksummed `from`/`to`, `value` defaulted to `0n`).
  * - `calls[i]` corresponds 1:1 with `simulationTxs[i]` — read raw logs,
  *   status, returnData/gasUsed.
  * - `assetChanges` is the net per-asset balance change over the whole bundle,
- *   grouped by account (sender and counterparties), normalized to the same
- *   shape across backends — see `AccountAssetChanges`.
+ *   grouped by account (sender and counterparties) — see `AccountAssetChanges`.
  * - `transfers[k].txIdx` indexes into `simulationTxs` to attribute each
- *   transfer to its emitting transaction.
+ *   transfer to its emitting user transaction.
  */
 export interface SimulationResult {
-    /** The full resolved transaction list (including prepended authorization txs). */
-    readonly simulationTxs: readonly SimulationTransaction[];
+    /** Exactly the caller's ordered transactions, normalized. */
+    readonly simulationTxs: readonly Readonly<SimulationTransaction>[];
     /**
      * Per-transaction normalized output. `calls[i]` corresponds 1:1 with
      * `simulationTxs[i]`. Use this to read raw logs, status, return data, gas used.
@@ -140,29 +101,9 @@ export interface SimulationLogger {
     warn(message: string, data?: Record<string, unknown>): void;
     error(message: string, data?: Record<string, unknown>): void;
 }
-/**
- * Input to `simulate`. Pin a `blockNumber` for deterministic / historical
- * simulation; omit to simulate against `latest`.
- */
-export interface SimulateParams {
-    chainId: number;
-    transactions: SimulationTransaction[];
-    authorizations?: SimulationAuthorization[];
-    blockNumber?: bigint | BlockTag;
-}
-/**
- * Internal raw result from a simulation adapter before normalization.
- * `calls[i]` corresponds 1:1 with the i-th transaction passed to the
- * backend; `assetChanges` is the bundle-level aggregate grouped by account.
- */
-export interface RawSimulationResult {
-    calls: RawCall[];
-    assetChanges: AccountAssetChanges[];
-}
 /**
  * Normalized EVM log emitted by a single simulated call. The shape is the
- * common subset both backends (`eth_simulateV1` via viem and Tenderly RPC)
- * produce after schema validation. Returned indirectly via
+ * log shape produced by `eth_simulateV1` via viem. Returned indirectly via
  * `SimulationCall.logs` and consumed by the SDK's transfer parser.
  */
 export interface RawLog {
@@ -171,16 +112,15 @@ export interface RawLog {
     readonly data: Hex;
 }
 /**
- * Internal mirror of `SimulationCall`, mutable during construction by the
- * simulation backends.
+ * Input-side mirror of `SimulationCall` accepted by the transfer parser.
  *
  * @internal
  */
 export interface RawCall {
-    logs: RawLog[];
-    status: boolean;
-    returnData: Hex;
-    gasUsed: bigint;
+    readonly logs: readonly RawLog[];
+    readonly status: boolean;
+    readonly returnData: Hex;
+    readonly gasUsed: bigint;
 }
 /**
  * Per-transaction normalized output from the simulation backend.
@@ -196,7 +136,7 @@ export interface SimulationCall {
      * True iff the call succeeded. The bundle as a whole reverts via
      * `SimulationRevertedError` before the result is returned, so on a
      * successful `simulate()` every entry is `true` today. Field kept for
-     * forward-compatibility with backends that may surface per-call status.
+     * per-call inspection alongside logs and return data.
      */
     readonly status: boolean;
     /** Return data from the top-level call. */