@morpho-org/evm-simulation 4.2.0 → 5.0.0

package/lib/esm/simulate/backends/tenderly-rpc.d.ts

@@ -1,23 +0,0 @@
-import { type BlockTag } from "viem";
-import type { RawSimulationResult, SimulationTransaction, TenderlyRpcConfig } from "../../types.js";
-/**
- * Simulate one or more transactions via Tenderly's Node Web3 Gateway.
- * Dispatches to `tenderly_simulateTransaction` for a single call and
- * `tenderly_simulateBundle` for a multi-call bundle.
- *
- * @param params.config - Tenderly RPC config (URL with access key embedded).
- * @param params.transactions - Bundle to simulate, in execution order.
- * @param params.blockNumber - Optional pinned block number or `BlockTag`. Defaults to `latest`.
- * @param params.signal - Optional `AbortSignal` for cancellation / timeout.
- * @returns A {@link RawSimulationResult} with one `RawCall` per input transaction.
- * @throws {SimulationValidationError} when `transactions` is empty.
- * @throws {SimulationRevertedError} when any simulated tx reports `status: false`.
- * @throws {ExternalServiceError} on non-2xx response, JSON-RPC envelope error,
- *   schema-validation failure, or fetch-layer failure.
- */
-export declare function simulateTenderlyRpc(params: {
-    config: TenderlyRpcConfig;
-    transactions: SimulationTransaction[];
-    blockNumber?: bigint | BlockTag;
-    signal?: AbortSignal;
-}): Promise<RawSimulationResult>;

package/lib/esm/simulate/backends/tenderly-rpc.js

@@ -1,231 +0,0 @@
-import { ethAddress, isAddress, isHex, maxUint256, numberToHex, } from "viem";
-import { z } from "zod";
-import { ExternalServiceError, SimulationRevertedError, SimulationValidationError, } from "../../errors.js";
-import { groupAssetChanges, normalizeAssetToken, } from "../asset-changes.js";
-const addressSchema = z.custom((val) => typeof val === "string" && isAddress(val));
-const hexSchema = z.custom((val) => typeof val === "string" && isHex(val));
-const traceFrameSchema = z
-    .object({
-    output: hexSchema.optional(),
-    error: z.string().optional(),
-    errorReason: z.string().optional(),
-})
-    .passthrough();
-const logSchema = z
-    .object({
-    raw: z
-        .object({
-        address: addressSchema,
-        topics: z.array(hexSchema).optional(),
-        data: hexSchema.optional(),
-    })
-        .passthrough()
-        .optional(),
-})
-    .passthrough();
-const assetChangeSchema = z
-    .object({
-    assetInfo: z
-        .object({
-        contractAddress: addressSchema.optional(),
-        symbol: z.string().optional(),
-        decimals: z.number().optional(),
-    })
-        .passthrough(),
-    from: addressSchema.optional(),
-    to: addressSchema.optional(),
-    rawAmount: hexSchema,
-})
-    .passthrough();
-const simResultSchema = z
-    .object({
-    status: z.boolean(),
-    gasUsed: hexSchema,
-    logs: z.array(logSchema).optional(),
-    trace: z.array(traceFrameSchema).optional(),
-    assetChanges: z.array(assetChangeSchema).optional(),
-    error: z.string().optional(),
-    errorMessage: z.string().optional(),
-})
-    .passthrough();
-const rpcErrorSchema = z
-    .object({
-    code: z.number().optional(),
-    message: z.string(),
-    data: z.unknown().optional(),
-})
-    .passthrough();
-function rpcEnvelope(result) {
-    return z
-        .object({ result: result.optional(), error: rpcErrorSchema.optional() })
-        .passthrough();
-}
-const singleEnvelope = rpcEnvelope(simResultSchema);
-const bundleEnvelope = rpcEnvelope(z.array(simResultSchema).min(1));
-/**
- * Simulate one or more transactions via Tenderly's Node Web3 Gateway.
- * Dispatches to `tenderly_simulateTransaction` for a single call and
- * `tenderly_simulateBundle` for a multi-call bundle.
- *
- * @param params.config - Tenderly RPC config (URL with access key embedded).
- * @param params.transactions - Bundle to simulate, in execution order.
- * @param params.blockNumber - Optional pinned block number or `BlockTag`. Defaults to `latest`.
- * @param params.signal - Optional `AbortSignal` for cancellation / timeout.
- * @returns A {@link RawSimulationResult} with one `RawCall` per input transaction.
- * @throws {SimulationValidationError} when `transactions` is empty.
- * @throws {SimulationRevertedError} when any simulated tx reports `status: false`.
- * @throws {ExternalServiceError} on non-2xx response, JSON-RPC envelope error,
- *   schema-validation failure, or fetch-layer failure.
- */
-export async function simulateTenderlyRpc(params) {
-    const { config, transactions, blockNumber, signal } = params;
-    const firstTx = transactions[0];
-    if (!firstTx) {
-        throw new SimulationValidationError("At least one transaction is required", []);
-    }
-    const block = encodeBlock(blockNumber);
-    // Inflate sender ETH balance to avoid false "insufficient funds for gas"
-    // reverts on wallets low on native gas token — mirrors simulateV1.
-    const stateOverrides = buildStateOverrides(firstTx.from);
-    try {
-        if (transactions.length === 1) {
-            const json = await rpcRequest({
-                rpcUrl: config.rpcUrl,
-                method: "tenderly_simulateTransaction",
-                params: [buildCall(firstTx), block, stateOverrides],
-                signal,
-            });
-            const result = unwrapResult(singleEnvelope.parse(json));
-            return {
-                calls: [toRawCall(result)],
-                assetChanges: toAssetChanges([result]),
-            };
-        }
-        const json = await rpcRequest({
-            rpcUrl: config.rpcUrl,
-            method: "tenderly_simulateBundle",
-            params: [transactions.map(buildCall), block, stateOverrides],
-            signal,
-        });
-        const results = unwrapResult(bundleEnvelope.parse(json));
-        return {
-            calls: results.map(toRawCall),
-            assetChanges: toAssetChanges(results),
-        };
-    }
-    catch (error) {
-        if (error instanceof SimulationRevertedError)
-            throw error;
-        if (error instanceof ExternalServiceError)
-            throw error;
-        throw new ExternalServiceError(`Tenderly RPC error: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-    }
-}
-async function rpcRequest(params) {
-    const { rpcUrl, method, params: rpcParams, signal } = params;
-    const response = await fetch(rpcUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params: rpcParams }),
-        signal,
-    });
-    if (!response.ok) {
-        throw new ExternalServiceError(`Tenderly RPC returned ${response.status}: ${response.statusText}`);
-    }
-    return await response.json();
-}
-function unwrapResult(envelope) {
-    if (envelope.error) {
-        throw new ExternalServiceError(`Tenderly RPC error: ${envelope.error.message}`);
-    }
-    if (envelope.result === undefined) {
-        throw new ExternalServiceError("Tenderly RPC returned no result");
-    }
-    return envelope.result;
-}
-function buildCall(tx) {
-    return {
-        from: tx.from,
-        to: tx.to,
-        input: tx.data,
-        data: tx.data,
-        value: numberToHex(tx.value ?? 0n),
-    };
-}
-function buildStateOverrides(sender) {
-    // Half of uint256 (not the ceiling) so the override leaves headroom for
-    // inbound native ETH — a WETH.withdraw refund or swap payout would overflow
-    // the recipient balance and revert the value transfer if the sender were
-    // pinned at maxUint256.
-    return { [sender]: { balance: numberToHex(maxUint256 / 2n) } };
-}
-function encodeBlock(blockNumber) {
-    if (blockNumber === undefined)
-        return "latest";
-    return typeof blockNumber === "bigint"
-        ? numberToHex(blockNumber)
-        : blockNumber;
-}
-function toRawCall(data) {
-    if (data.status !== true) {
-        // Tenderly RPC surfaces the revert reason on the trace frame; the
-        // top-level fields are checked as a defensive fallback.
-        const traceError = data.trace?.find((f) => f.errorReason || f.error);
-        const message = traceError?.errorReason ||
-            traceError?.error ||
-            data.errorMessage ||
-            data.error ||
-            "Transaction simulation reverted";
-        throw new SimulationRevertedError(message, data);
-    }
-    const logs = [];
-    for (const log of data.logs ?? []) {
-        if (log.raw) {
-            logs.push({
-                address: log.raw.address,
-                topics: log.raw.topics ?? [],
-                data: log.raw.data ?? "0x",
-            });
-        }
-    }
-    return {
-        logs,
-        status: true,
-        returnData: data.trace?.[0]?.output ?? "0x",
-        gasUsed: BigInt(data.gasUsed),
-    };
-}
-/**
- * Reduce Tenderly's per-transfer asset changes to net per-token balance changes
- * grouped by account. Both endpoints of each transfer are accounted (sender,
- * counterparties, and the zero address for mints/burns).
- */
-function toAssetChanges(results) {
-    const entries = [];
-    for (const result of results) {
-        for (const change of result.assetChanges ?? []) {
-            const amount = BigInt(change.rawAmount);
-            const token = change.assetInfo.contractAddress
-                ? normalizeAssetToken(change.assetInfo.contractAddress)
-                : ethAddress;
-            const { symbol, decimals } = change.assetInfo;
-            if (change.to)
-                entries.push({
-                    account: change.to,
-                    token,
-                    diff: amount,
-                    symbol,
-                    decimals,
-                });
-            if (change.from)
-                entries.push({
-                    account: change.from,
-                    token,
-                    diff: -amount,
-                    symbol,
-                    decimals,
-                });
-        }
-    }
-    return groupAssetChanges(entries);
-}

package/lib/esm/simulate/pipeline/build-simulation-txs.d.ts

@@ -1,17 +0,0 @@
-import type { SimulateParams, SimulationTransaction } from "../../types.js";
-/**
- * Stage 3 of the simulate() pipeline.
- *
- * Prepends any resolved authorizations (e.g. ERC20 `approve` calls generated from
- * `{ type: 'signature' }` entries) to the user's transactions. If no authorizations
- * were supplied, returns the user's transactions unchanged.
- *
- * Defense-in-depth: after prepending, verifies EVERY resolved tx shares the user
- * sender. This catches an `{ type: 'approval', transaction }` auth where the
- * caller-provided `transaction.from` does not match the bundle sender — the
- * `approval` variant otherwise passes through without validation. Rejecting here
- * keeps the "all simulationTxs share one `from`" invariant the downstream
- * backends (eth_simulateV1) assume, and prevents a malicious or buggy caller
- * from prepending a tx on behalf of an unexpected address.
- */
-export declare function buildSimulationTxs(params: SimulateParams): SimulationTransaction[];

package/lib/esm/simulate/pipeline/build-simulation-txs.js

@@ -1,47 +0,0 @@
-import { getAddress } from "viem";
-import { SimulationValidationError } from "../../errors.js";
-import { resolveAuthorizations } from "../authorizations/index.js";
-/**
- * Stage 3 of the simulate() pipeline.
- *
- * Prepends any resolved authorizations (e.g. ERC20 `approve` calls generated from
- * `{ type: 'signature' }` entries) to the user's transactions. If no authorizations
- * were supplied, returns the user's transactions unchanged.
- *
- * Defense-in-depth: after prepending, verifies EVERY resolved tx shares the user
- * sender. This catches an `{ type: 'approval', transaction }` auth where the
- * caller-provided `transaction.from` does not match the bundle sender — the
- * `approval` variant otherwise passes through without validation. Rejecting here
- * keeps the "all simulationTxs share one `from`" invariant the downstream
- * backends (eth_simulateV1) assume, and prevents a malicious or buggy caller
- * from prepending a tx on behalf of an unexpected address.
- */
-export function buildSimulationTxs(params) {
-    const { transactions, authorizations } = params;
-    if (!authorizations || authorizations.length === 0) {
-        return transactions;
-    }
-    const sender = transactions[0].from;
-    const resolved = resolveAuthorizations(authorizations, sender);
-    const simulationTxs = [...resolved, ...transactions];
-    const senderChecksum = getAddress(sender);
-    const mismatches = [];
-    for (let i = 0; i < simulationTxs.length; i++) {
-        const tx = simulationTxs[i];
-        let txFromChecksum;
-        try {
-            txFromChecksum = getAddress(tx.from);
-        }
-        catch {
-            mismatches.push(`simulationTxs[${i}].from: not a valid address (${tx.from})`);
-            continue;
-        }
-        if (txFromChecksum !== senderChecksum) {
-            mismatches.push(`simulationTxs[${i}].from: expected ${senderChecksum}, got ${txFromChecksum}`);
-        }
-    }
-    if (mismatches.length > 0) {
-        throw new SimulationValidationError("Authorization transaction(s) must share the user sender", mismatches);
-    }
-    return simulationTxs;
-}

package/lib/esm/simulate/pipeline/execute-simulation.d.ts

@@ -1,22 +0,0 @@
-import type { Address, BlockTag } from "viem";
-import type { RawSimulationResult, SimulationConfig, SimulationTransaction } from "../../types.js";
-/**
- * Stage 4 of the simulate() pipeline.
- *
- * Dispatches the transaction bundle to the available backend with a shared timeout
- * budget:
- * - If a Tenderly RPC URL is configured for the chain, it gets
- *   `TENDERLY_BUDGET_RATIO` (60%) of the timeout. On `ExternalServiceError`,
- *   falls back to `eth_simulateV1` with `max(remaining, FALLBACK_MIN_BUDGET_MS)`
- *   so the fallback still has a viable window when Tenderly eats its full slice.
- *   `SimulationRevertedError` (contract revert) propagates immediately without
- *   retry — a revert is a property of the bundle, not the backend.
- * - If only `eth_simulateV1` is configured, it gets the full timeout.
- */
-export declare function executeSimulation(params: {
-    config: SimulationConfig;
-    chainId: number;
-    transactions: SimulationTransaction[];
-    blockNumber?: bigint | BlockTag;
-    wNative?: Address | null;
-}): Promise<RawSimulationResult>;

package/lib/esm/simulate/pipeline/execute-simulation.js

@@ -1,79 +0,0 @@
-import { ExternalServiceError, UnsupportedChainError } from "../../errors.js";
-import { simulateTenderlyRpc, simulateV1 } from "../backends/index.js";
-import { resolveChain } from "./resolve-chain.js";
-/** Total budget for a single `simulate()` call across both backends. */
-const DEFAULT_TIMEOUT_MS = 5000;
-/** Fraction of `timeoutMs` given to Tenderly before falling back to `eth_simulateV1`. */
-const TENDERLY_BUDGET_RATIO = 0.6;
-/**
- * Minimum budget (ms) handed to the `eth_simulateV1` fallback when Tenderly fails.
- *
- * Without a floor, if Tenderly exhausts its slice and dies at the deadline, the
- * fallback would get ~0 ms and abort immediately — turning a degraded-Tenderly
- * scenario into a total outage even when the fallback backend is healthy. A
- * modest floor keeps the fallback viable at the cost of the overall
- * `timeoutMs` being treated as a soft ceiling.
- */
-const FALLBACK_MIN_BUDGET_MS = 1500;
-/**
- * Stage 4 of the simulate() pipeline.
- *
- * Dispatches the transaction bundle to the available backend with a shared timeout
- * budget:
- * - If a Tenderly RPC URL is configured for the chain, it gets
- *   `TENDERLY_BUDGET_RATIO` (60%) of the timeout. On `ExternalServiceError`,
- *   falls back to `eth_simulateV1` with `max(remaining, FALLBACK_MIN_BUDGET_MS)`
- *   so the fallback still has a viable window when Tenderly eats its full slice.
- *   `SimulationRevertedError` (contract revert) propagates immediately without
- *   retry — a revert is a property of the bundle, not the backend.
- * - If only `eth_simulateV1` is configured, it gets the full timeout.
- */
-export async function executeSimulation(params) {
-    const { config, chainId, transactions, blockNumber, wNative } = params;
-    const chain = resolveChain(config, chainId);
-    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const deadline = Date.now() + timeoutMs;
-    if (chain.tenderlyRpc) {
-        const tenderlyTimeout = Math.floor(timeoutMs * TENDERLY_BUDGET_RATIO);
-        try {
-            return await simulateTenderlyRpc({
-                config: chain.tenderlyRpc,
-                transactions,
-                blockNumber,
-                signal: AbortSignal.timeout(tenderlyTimeout),
-            });
-        }
-        catch (error) {
-            if (!(error instanceof ExternalServiceError))
-                throw error;
-            config.logger?.warn("Tenderly simulation failed, attempting fallback", {
-                chainId,
-                error: error.message,
-                cause: error.cause,
-            });
-            if (!chain.simulateV1Url)
-                throw error;
-            const fallbackBudget = Math.max(deadline - Date.now(), FALLBACK_MIN_BUDGET_MS);
-            return await simulateV1({
-                rpcUrl: chain.simulateV1Url,
-                chainId,
-                transactions,
-                blockNumber,
-                wNative,
-                signal: AbortSignal.timeout(fallbackBudget),
-            });
-        }
-    }
-    /* v8 ignore next: resolveChain rejects this state before executeSimulation reaches the fallback path. */
-    if (!chain.simulateV1Url) {
-        throw new UnsupportedChainError(chainId);
-    }
-    return await simulateV1({
-        rpcUrl: chain.simulateV1Url,
-        chainId,
-        transactions,
-        blockNumber,
-        wNative,
-        signal: AbortSignal.timeout(timeoutMs),
-    });
-}

package/lib/esm/simulate/pipeline/index.d.ts

@@ -1,4 +0,0 @@
-export { buildSimulationTxs } from "./build-simulation-txs.js";
-export { assertNoBundlesRetention } from "./bundles-retention.js";
-export { executeSimulation } from "./execute-simulation.js";
-export { validateInput } from "./validate-input.js";

package/lib/esm/simulate/pipeline/index.js

@@ -1,4 +0,0 @@
-export { buildSimulationTxs } from "./build-simulation-txs.js";
-export { assertNoBundlesRetention } from "./bundles-retention.js";
-export { executeSimulation } from "./execute-simulation.js";
-export { validateInput } from "./validate-input.js";

package/lib/esm/simulate/pipeline/validate-input.d.ts

@@ -1,10 +0,0 @@
-import type { SimulateParams } from "../../types.js";
-/**
- * Stage 1 of the simulate() pipeline.
- *
- * Throws `SimulationValidationError` with a `fieldErrors[]` list on any invalid input:
- * empty transactions, malformed / zero-addr fields, missing `data`, negative `value`,
- * bad `chainId`, or mixed senders (all txs in a bundle must share the same `from`).
- * Also runs `validateAuthorizations` on the optional authorizations array.
- */
-export declare function validateInput(params: SimulateParams): void;

package/lib/esm/simulate/pipeline/validate-input.js

@@ -1,52 +0,0 @@
-import { isAddress, zeroAddress } from "viem";
-import { SimulationValidationError } from "../../errors.js";
-import { validateAuthorizations } from "../authorizations/index.js";
-/**
- * Stage 1 of the simulate() pipeline.
- *
- * Throws `SimulationValidationError` with a `fieldErrors[]` list on any invalid input:
- * empty transactions, malformed / zero-addr fields, missing `data`, negative `value`,
- * bad `chainId`, or mixed senders (all txs in a bundle must share the same `from`).
- * Also runs `validateAuthorizations` on the optional authorizations array.
- */
-export function validateInput(params) {
-    const errors = [];
-    if (!Number.isInteger(params.chainId) || params.chainId <= 0) {
-        errors.push(`chainId: must be a positive integer (got ${params.chainId})`);
-    }
-    const transactions = params.transactions ?? [];
-    if (transactions.length === 0) {
-        errors.push("transactions: must contain at least 1 transaction");
-    }
-    for (let i = 0; i < transactions.length; i++) {
-        const tx = transactions[i];
-        if (!tx.from || !isAddress(tx.from) || tx.from === zeroAddress) {
-            errors.push(`transactions[${i}].from: must be a valid non-zero address`);
-        }
-        if (!tx.to || !isAddress(tx.to) || tx.to === zeroAddress) {
-            errors.push(`transactions[${i}].to: must be a valid non-zero address`);
-        }
-        if (!tx.data) {
-            errors.push(`transactions[${i}].data: must be provided`);
-        }
-        if (tx.value !== undefined && tx.value < 0n) {
-            errors.push(`transactions[${i}].value: must be non-negative`);
-        }
-    }
-    // Same-sender check uses RAW `.from` strings (lowercased) so the invariant
-    // fires even when some tx `from`s are malformed — individual txs already
-    // flagged above, but we still want one loud signal that the bundle's
-    // senders don't match.
-    if (transactions.length > 1) {
-        const distinct = new Set(transactions.map((tx) => (tx.from ?? "").toLowerCase()));
-        if (distinct.size > 1) {
-            errors.push("transactions: all transactions must share the same from address");
-        }
-    }
-    if (params.authorizations) {
-        errors.push(...validateAuthorizations(params.authorizations));
-    }
-    if (errors.length > 0) {
-        throw new SimulationValidationError("Invalid simulation input", errors);
-    }
-}