@morpho-org/evm-simulation 1.0.0

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

@@ -0,0 +1,84 @@
+import { ExternalServiceError, UnsupportedChainError } from "../../errors.js";
+import { simulateTenderlyRest, 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 Tenderly 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.
+ *
+ * `shareable` is Tenderly-only: when true, the backend persists the simulation and
+ * returns a shareable URL. `eth_simulateV1` ignores it (no persistence concept).
+ */
+export async function executeSimulation(params) {
+    const { config, chainId, transactions, blockNumber, shareable } = params;
+    const chain = resolveChain(config, chainId);
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    if (chain.tenderlySupported && config.tenderlyRest) {
+        const tenderlyTimeout = Math.floor(timeoutMs * TENDERLY_BUDGET_RATIO);
+        try {
+            return await simulateTenderlyRest({
+                config: config.tenderlyRest,
+                chainId,
+                transactions,
+                blockNumber,
+                shareable,
+                signal: AbortSignal.timeout(tenderlyTimeout),
+                logger: config.logger,
+            });
+        }
+        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;
+            // Give the fallback a reasonable minimum even if Tenderly consumed the
+            // whole budget — otherwise slow-Tenderly == total outage.
+            const fallbackBudget = Math.max(deadline - Date.now(), FALLBACK_MIN_BUDGET_MS);
+            return await simulateV1({
+                rpcUrl: chain.simulateV1Url,
+                chainId,
+                transactions,
+                blockNumber,
+                signal: AbortSignal.timeout(fallbackBudget),
+            });
+        }
+    }
+    if (!chain.simulateV1Url) {
+        throw new UnsupportedChainError(chainId);
+    }
+    return await simulateV1({
+        rpcUrl: chain.simulateV1Url,
+        chainId,
+        transactions,
+        blockNumber,
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+}

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

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

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

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

package/lib/esm/simulate/pipeline/resolve-chain.d.ts

@@ -0,0 +1,14 @@
+import type { SimulationConfig } from "../../types.js";
+interface ChainCapability {
+    tenderlySupported: boolean;
+    simulateV1Url?: string;
+}
+/**
+ * Stage 2 of the simulate() pipeline.
+ *
+ * Determines which backend(s) are available for a chainId. Throws
+ * `UnsupportedChainError` when neither Tenderly nor `eth_simulateV1` is reachable
+ * for the requested chain.
+ */
+export declare function resolveChain(config: SimulationConfig, chainId: number): ChainCapability;
+export {};

package/lib/esm/simulate/pipeline/resolve-chain.js

@@ -0,0 +1,16 @@
+import { UnsupportedChainError } from "../../errors.js";
+/**
+ * Stage 2 of the simulate() pipeline.
+ *
+ * Determines which backend(s) are available for a chainId. Throws
+ * `UnsupportedChainError` when neither Tenderly nor `eth_simulateV1` is reachable
+ * for the requested chain.
+ */
+export function resolveChain(config, chainId) {
+    const tenderlySupported = config.tenderlyRest?.supportedChainIds.has(chainId) ?? false;
+    const simulateV1Url = config.chains.get(chainId)?.simulateV1Url;
+    if (!tenderlySupported && !simulateV1Url) {
+        throw new UnsupportedChainError(chainId);
+    }
+    return { tenderlySupported, simulateV1Url };
+}

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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,52 @@
+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);
+    }
+}

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

@@ -0,0 +1,26 @@
+import type { SimulateParams, SimulationConfig, SimulationResult } from "../types.js";
+/**
+ * Simulate a bundle of EVM transactions.
+ *
+ * Validates input → resolves authorizations into prepended approve txs → runs the bundle
+ * through Tenderly REST (primary) or `eth_simulateV1` (fallback) with a shared timeout
+ * budget → parses ERC20/WETH transfers from logs → asserts no funds are retained by
+ * `bundler3` → returns the full result set. The caller reads whichever fields they need:
+ *
+ * - `transfers` + `tenderlyUrl` → user-facing preview.
+ * - `simulationTxs` + `transfers` → server-side verification before broadcast, then pass
+ *   both to `screenAddresses` for compliance.
+ *
+ * Throws `SimulationValidationError` for bad input, `UnsupportedChainError` when the chain
+ * is not configured, `SimulationRevertedError` if the bundle reverts,
+ * `BlacklistViolationError` if bundler retention is detected, or `ExternalServiceError` if
+ * both backends are unavailable within the timeout budget.
+ */
+export declare function simulate(config: SimulationConfig, params: SimulateParams, options?: {
+    /**
+     * When true, persist the simulation in Tenderly and return a shareable
+     * `tenderlyUrl` in the result. Only honored when the Tenderly backend runs
+     * (not the `eth_simulateV1` fallback). Defaults to `false`.
+     */
+    shareable?: boolean;
+}): Promise<SimulationResult>;

package/lib/esm/simulate/simulate.js

@@ -0,0 +1,43 @@
+import { parseTransfers } from "./parsing/index.js";
+import { assertNoBundlerRetention, buildSimulationTxs, executeSimulation, validateInput, } from "./pipeline/index.js";
+/**
+ * Simulate a bundle of EVM transactions.
+ *
+ * Validates input → resolves authorizations into prepended approve txs → runs the bundle
+ * through Tenderly REST (primary) or `eth_simulateV1` (fallback) with a shared timeout
+ * budget → parses ERC20/WETH transfers from logs → asserts no funds are retained by
+ * `bundler3` → returns the full result set. The caller reads whichever fields they need:
+ *
+ * - `transfers` + `tenderlyUrl` → user-facing preview.
+ * - `simulationTxs` + `transfers` → server-side verification before broadcast, then pass
+ *   both to `screenAddresses` for compliance.
+ *
+ * Throws `SimulationValidationError` for bad input, `UnsupportedChainError` when the chain
+ * is not configured, `SimulationRevertedError` if the bundle reverts,
+ * `BlacklistViolationError` if bundler retention is detected, or `ExternalServiceError` if
+ * both backends are unavailable within the timeout budget.
+ */
+export async function simulate(config, params, options = {}) {
+    const { shareable = false } = options;
+    validateInput(params);
+    const simulationTxs = buildSimulationTxs(params);
+    const result = await executeSimulation({
+        config,
+        chainId: params.chainId,
+        transactions: simulationTxs,
+        blockNumber: params.blockNumber,
+        shareable,
+    });
+    const transfers = parseTransfers(result.logs, config.logger);
+    assertNoBundlerRetention({
+        chainId: params.chainId,
+        transfers,
+        logger: config.logger,
+    });
+    return {
+        simulationTxs,
+        transfers,
+        tenderlyUrl: result.tenderlyUrl,
+        assetChanges: result.rawAssetChanges,
+    };
+}

package/lib/esm/types.d.ts

@@ -0,0 +1,131 @@
+import type { Address, BlockTag, Hex } from "viem";
+/**
+ * Credentials and routing for the Tenderly REST simulation backend.
+ * Omit from `SimulationConfig.tenderlyRest` to disable the Tenderly path entirely.
+ */
+export interface TenderlyRestConfig {
+    /** e.g. "https://api.tenderly.co" */
+    apiBaseUrl: string;
+    accessToken: string;
+    accountSlug: string;
+    projectSlug: string;
+    /** Chain IDs that Tenderly supports for simulation */
+    supportedChainIds: Set<number>;
+}
+/**
+ * Per-chain capabilities. Stored as a `Map` value in
+ * `SimulationConfig.chains`, keyed by chain ID.
+ */
+export interface ChainSimulationConfig {
+    /** JSON-RPC URL supporting `eth_simulateV1`. undefined = not available for this chain. */
+    simulateV1Url?: string;
+}
+/**
+ * Top-level configuration for `simulate`.
+ *
+ * At least one backend must be reachable for a given chainId — either Tenderly
+ * (via `tenderlyRest` with that chainId in `TenderlyRestConfig.supportedChainIds`)
+ * or `ChainSimulationConfig.simulateV1Url` in the `chains` map. Otherwise the
+ * orchestrator throws `UnsupportedChainError`.
+ */
+export interface SimulationConfig {
+    /** Tenderly REST API config. undefined = Tenderly not available. */
+    tenderlyRest?: TenderlyRestConfig;
+    /** Per-chain simulation capabilities. */
+    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).
+     */
+    timeoutMs?: number;
+}
+/**
+ * A single EVM call to simulate. `from` must be identical across all transactions
+ * in a bundle — the orchestrator rejects mixed senders with `SimulationValidationError`.
+ */
+export interface SimulationTransaction {
+    from: Address;
+    to: Address;
+    data: Hex;
+    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;
+};
+/**
+ * A parsed ERC20 / WETH9 transfer extracted from simulation logs. Returned in
+ * `SimulationResult.transfers`.
+ */
+export interface Transfer {
+    token: Address;
+    from: Address;
+    to: Address;
+    amount: bigint;
+}
+/**
+ * Happy-path return of `simulate`. All failures throw typed errors. The same shape is
+ * returned regardless of `options.shareable` — fields unused by your use case can be
+ * ignored:
+ *
+ * - Preview (`shareable: true`): read `transfers` + `tenderlyUrl`.
+ * - Verify (`shareable: false`, default): read `simulationTxs` + `transfers`, pass both
+ *   to `screenAddresses`.
+ *
+ * `tenderlyUrl` is set only when `shareable: true` AND the Tenderly backend ran
+ * successfully (not the `eth_simulateV1` fallback). `assetChanges` is Tenderly-only
+ * raw data.
+ */
+export interface SimulationResult {
+    /** The full resolved transaction list (including prepended authorization txs). */
+    simulationTxs: SimulationTransaction[];
+    /** Parsed ERC-20 / WETH9 transfers from the simulation. */
+    transfers: Transfer[];
+    /** Shareable Tenderly URL. Present only when `shareable: true` and Tenderly ran (not fallback). */
+    tenderlyUrl?: string;
+    /** Raw Tenderly `asset_changes` payload. Opaque `unknown` — do not destructure without validation. */
+    assetChanges?: unknown;
+}
+/** Minimal structured logger the package calls for warnings and info. */
+export interface SimulationLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    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.
+ * Both Tenderly and simulateV1 produce this.
+ */
+export interface RawSimulationResult {
+    logs: RawLog[];
+    tenderlyUrl?: string;
+    rawAssetChanges?: unknown;
+}
+export interface RawLog {
+    address: Address;
+    topics: Hex[];
+    data: Hex;
+}

package/lib/esm/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@morpho-org/evm-simulation",
+  "description": "EVM simulation engine for Morpho transactions.",
+  "version": "1.0.0",
+  "author": "Morpho Association <contact@morpho.org>",
+  "contributors": [
+    "Rubilmax <rmilon@gmail.com>"
+  ],
+  "repository": "github:morpho-org/sdks",
+  "homepage": "https://github.com/morpho-org/sdks",
+  "bugs": {
+    "url": "https://github.com/morpho-org/sdks/issues",
+    "email": "contact@morpho.org"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "src/index.ts",
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "zod": "^4.1.12",
+    "@morpho-org/blue-sdk": "^5.23.1",
+    "@morpho-org/morpho-ts": "^2.5.1"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "viem": "^2.41.2",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "prepublish": "$npm_execpath build",
+    "build": "tsc --noEmit && $npm_execpath build:cjs && $npm_execpath build:esm",
+    "build:cjs": "tsc --build tsconfig.build.cjs.json && echo '{\"type\":\"commonjs\"}' > lib/cjs/package.json",
+    "build:esm": "tsc --build tsconfig.build.esm.json && echo '{\"type\":\"module\"}' > lib/esm/package.json",
+    "test": "vitest --root ../.. --project evm-simulation"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/esm/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Public fns (via feature-folder barrels)
+export { screenAddresses } from "./screen-addresses/index.js";
+export { simulate } from "./simulate/index.js";
+
+// Types
+export type {
+  ChainSimulationConfig,
+  SimulateParams,
+  SimulationAuthorization,
+  SimulationConfig,
+  SimulationLogger,
+  SimulationResult,
+  SimulationTransaction,
+  TenderlyRestConfig,
+  Transfer,
+} from "./types.js";
+
+// Errors (for instanceof checks by consumers)
+export {
+  SimulationPackageError,
+  SimulationRevertedError,
+  BlacklistViolationError,
+  AddressScreeningError,
+  ExternalServiceError,
+  SimulationValidationError,
+  UnsupportedChainError,
+} from "./errors.js";