@morpho-org/evm-simulation 1.0.0

package/lib/cjs/simulate/pipeline/bundler-retention.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNoBundlerRetention = assertNoBundlerRetention;
+const blue_sdk_1 = require("@morpho-org/blue-sdk");
+const morpho_ts_1 = require("@morpho-org/morpho-ts");
+const viem_1 = require("viem");
+const errors_js_1 = require("../../errors.js");
+/**
+ * Dust tolerance for bundler retention, in raw token units.
+ *
+ * 100 units is negligible for 18-decimal tokens (~1e-16). For low-decimal
+ * tokens (e.g., 2-decimal stablecoins) this represents ~1.00 token — worth
+ * keeping in mind. The threshold is intentionally token-agnostic: its purpose
+ * is to absorb rounding noise from bundler3 routing, not to define an
+ * acceptable retention amount.
+ */
+const DUST_THRESHOLD = 100n;
+function getBundlerAddresses(chainId, logger) {
+    try {
+        const addresses = (0, blue_sdk_1.getChainAddresses)(chainId);
+        if (!addresses.bundler3) {
+            // blue-sdk knows the chain but didn't catalog a bundler3 for it.
+            // Treat the same as UnsupportedChainIdError — retention check skipped.
+            logger?.warn("Chain known to blue-sdk but has no bundler3 config, retention check skipped", {
+                chainId,
+            });
+            return new Set();
+        }
+        return new Set(Object.values(addresses.bundler3)
+            .filter(morpho_ts_1.isDefined)
+            .map((addr) => (0, viem_1.getAddress)(addr)));
+    }
+    catch (error) {
+        if (error instanceof blue_sdk_1.UnsupportedChainIdError) {
+            // Loud warn: this disables a "never bypassable" check for the chain.
+            // Consumers relying on the guarantee must handle this signal.
+            logger?.warn("Chain not supported by blue-sdk, retention check skipped", {
+                chainId,
+            });
+            return new Set();
+        }
+        throw error;
+    }
+}
+/**
+ * Assert that no value is retained by bundler3 contract addresses.
+ *
+ * Uses net flow (inbound minus outbound) per (bundler address, token) pair.
+ * Bundler3 legitimately receives tokens as an intermediary (user → bundler3 →
+ * vault), so gross inbound would fire false positives. We only flag when
+ * `|net| > DUST_THRESHOLD` — catching both **retention** (tokens stuck in
+ * bundler, positive net) and **drain** (bundler sending more than it received
+ * in this bundle, negative net — which implies a pre-existing or state-override
+ * balance is being drawn down, a red flag for pre-broadcast integrity).
+ */
+function assertNoBundlerRetention(params) {
+    const { chainId, transfers, logger } = params;
+    const bundlerAddresses = getBundlerAddresses(chainId, logger);
+    if (bundlerAddresses.size === 0)
+        return;
+    // Map keyed by (bundler, token) → structured entry. Avoids string parse-back.
+    const flow = new Map();
+    const recordFlow = (address, token, delta) => {
+        const key = `${address.toLowerCase()}:${token.toLowerCase()}`;
+        const existing = flow.get(key);
+        if (existing) {
+            existing.netChange += delta;
+        }
+        else {
+            flow.set(key, { address, token, netChange: delta });
+        }
+    };
+    for (const t of transfers) {
+        if (bundlerAddresses.has(t.to))
+            recordFlow(t.to, t.token, t.amount);
+        if (bundlerAddresses.has(t.from))
+            recordFlow(t.from, t.token, -t.amount);
+    }
+    const flagged = [...flow.values()].filter((e) => absBigInt(e.netChange) > DUST_THRESHOLD);
+    if (flagged.length > 0) {
+        throw new errors_js_1.BlacklistViolationError("Simulation detected asset transfers retained or drained by restricted bundler contracts", flagged.map((e) => ({
+            address: e.address,
+            token: e.token,
+            netRetained: e.netChange.toString(),
+        })));
+    }
+}
+function absBigInt(x) {
+    return x < 0n ? -x : x;
+}

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

@@ -0,0 +1,25 @@
+import type { 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 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 declare function executeSimulation(params: {
+    config: SimulationConfig;
+    chainId: number;
+    transactions: SimulationTransaction[];
+    blockNumber?: bigint | BlockTag;
+    shareable: boolean;
+}): Promise<RawSimulationResult>;

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

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeSimulation = executeSimulation;
+const errors_js_1 = require("../../errors.js");
+const index_js_1 = require("../backends/index.js");
+const resolve_chain_js_1 = require("./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).
+ */
+async function executeSimulation(params) {
+    const { config, chainId, transactions, blockNumber, shareable } = params;
+    const chain = (0, resolve_chain_js_1.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 (0, index_js_1.simulateTenderlyRest)({
+                config: config.tenderlyRest,
+                chainId,
+                transactions,
+                blockNumber,
+                shareable,
+                signal: AbortSignal.timeout(tenderlyTimeout),
+                logger: config.logger,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof errors_js_1.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 (0, index_js_1.simulateV1)({
+                rpcUrl: chain.simulateV1Url,
+                chainId,
+                transactions,
+                blockNumber,
+                signal: AbortSignal.timeout(fallbackBudget),
+            });
+        }
+    }
+    if (!chain.simulateV1Url) {
+        throw new errors_js_1.UnsupportedChainError(chainId);
+    }
+    return await (0, index_js_1.simulateV1)({
+        rpcUrl: chain.simulateV1Url,
+        chainId,
+        transactions,
+        blockNumber,
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+}

package/lib/cjs/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/cjs/simulate/pipeline/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateInput = exports.executeSimulation = exports.assertNoBundlerRetention = exports.buildSimulationTxs = void 0;
+var build_simulation_txs_js_1 = require("./build-simulation-txs.js");
+Object.defineProperty(exports, "buildSimulationTxs", { enumerable: true, get: function () { return build_simulation_txs_js_1.buildSimulationTxs; } });
+var bundler_retention_js_1 = require("./bundler-retention.js");
+Object.defineProperty(exports, "assertNoBundlerRetention", { enumerable: true, get: function () { return bundler_retention_js_1.assertNoBundlerRetention; } });
+var execute_simulation_js_1 = require("./execute-simulation.js");
+Object.defineProperty(exports, "executeSimulation", { enumerable: true, get: function () { return execute_simulation_js_1.executeSimulation; } });
+var validate_input_js_1 = require("./validate-input.js");
+Object.defineProperty(exports, "validateInput", { enumerable: true, get: function () { return validate_input_js_1.validateInput; } });

package/lib/cjs/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/cjs/simulate/pipeline/resolve-chain.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveChain = resolveChain;
+const errors_js_1 = require("../../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.
+ */
+function resolveChain(config, chainId) {
+    const tenderlySupported = config.tenderlyRest?.supportedChainIds.has(chainId) ?? false;
+    const simulateV1Url = config.chains.get(chainId)?.simulateV1Url;
+    if (!tenderlySupported && !simulateV1Url) {
+        throw new errors_js_1.UnsupportedChainError(chainId);
+    }
+    return { tenderlySupported, simulateV1Url };
+}

package/lib/cjs/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/cjs/simulate/pipeline/validate-input.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateInput = validateInput;
+const viem_1 = require("viem");
+const errors_js_1 = require("../../errors.js");
+const index_js_1 = require("../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.
+ */
+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 || !(0, viem_1.isAddress)(tx.from) || tx.from === viem_1.zeroAddress) {
+            errors.push(`transactions[${i}].from: must be a valid non-zero address`);
+        }
+        if (!tx.to || !(0, viem_1.isAddress)(tx.to) || tx.to === viem_1.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(...(0, index_js_1.validateAuthorizations)(params.authorizations));
+    }
+    if (errors.length > 0) {
+        throw new errors_js_1.SimulationValidationError("Invalid simulation input", errors);
+    }
+}

package/lib/cjs/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/cjs/simulate/simulate.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulate = simulate;
+const index_js_1 = require("./parsing/index.js");
+const index_js_2 = require("./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.
+ */
+async function simulate(config, params, options = {}) {
+    const { shareable = false } = options;
+    (0, index_js_2.validateInput)(params);
+    const simulationTxs = (0, index_js_2.buildSimulationTxs)(params);
+    const result = await (0, index_js_2.executeSimulation)({
+        config,
+        chainId: params.chainId,
+        transactions: simulationTxs,
+        blockNumber: params.blockNumber,
+        shareable,
+    });
+    const transfers = (0, index_js_1.parseTransfers)(result.logs, config.logger);
+    (0, index_js_2.assertNoBundlerRetention)({
+        chainId: params.chainId,
+        transfers,
+        logger: config.logger,
+    });
+    return {
+        simulationTxs,
+        transfers,
+        tenderlyUrl: result.tenderlyUrl,
+        assetChanges: result.rawAssetChanges,
+    };
+}

package/lib/cjs/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/cjs/types.js

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

package/lib/esm/errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Base error for all simulation package errors.
+ * Transport-agnostic — no HTTP status codes.
+ * Consumers use try/catch + instanceof to handle specific error types.
+ */
+export declare abstract class SimulationPackageError extends Error {
+    abstract readonly code: string;
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Transaction would revert on-chain. Not bypassable. */
+export declare class SimulationRevertedError extends SimulationPackageError {
+    readonly reason: string | undefined;
+    readonly details?: unknown | undefined;
+    readonly code = "SIMULATION_REVERTED";
+    constructor(reason: string | undefined, details?: unknown | undefined);
+}
+interface RetainedAsset {
+    address: string | undefined;
+    token: string | undefined;
+    netRetained: string;
+}
+/** Funds would flow to bundler3 contract addresses. Never bypassable. */
+export declare class BlacklistViolationError extends SimulationPackageError {
+    readonly assetChanges?: RetainedAsset[] | undefined;
+    readonly code = "BLACKLIST_ERROR";
+    constructor(message: string, assetChanges?: RetainedAsset[] | undefined);
+}
+/** Sanctioned or compromised address detected. Never bypassable. */
+export declare class AddressScreeningError extends SimulationPackageError {
+    readonly addresses: string[];
+    readonly code = "SCREENING_ERROR";
+    constructor(message: string, addresses: string[]);
+}
+/** Tenderly or RPC service is down. Bypassable — user can proceed. */
+export declare class ExternalServiceError extends SimulationPackageError {
+    readonly code = "EXTERNAL_SERVICE_ERROR";
+}
+/** Bad input to the simulation functions. Not bypassable. */
+export declare class SimulationValidationError extends SimulationPackageError {
+    readonly fieldErrors?: string[] | undefined;
+    readonly code = "VALIDATION_ERROR";
+    constructor(message: string, fieldErrors?: string[] | undefined);
+}
+/** Chain ID not configured for any simulation method. Not bypassable. */
+export declare class UnsupportedChainError extends SimulationPackageError {
+    readonly chainId: number;
+    readonly code = "UNSUPPORTED_CHAIN";
+    constructor(chainId: number);
+}
+export {};

package/lib/esm/errors.js

@@ -0,0 +1,62 @@
+/**
+ * Base error for all simulation package errors.
+ * Transport-agnostic — no HTTP status codes.
+ * Consumers use try/catch + instanceof to handle specific error types.
+ */
+export class SimulationPackageError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = this.constructor.name;
+    }
+}
+/** Transaction would revert on-chain. Not bypassable. */
+export class SimulationRevertedError extends SimulationPackageError {
+    reason;
+    details;
+    code = "SIMULATION_REVERTED";
+    constructor(reason, details) {
+        super(reason ?? "Transaction simulation reverted");
+        this.reason = reason;
+        this.details = details;
+    }
+}
+/** Funds would flow to bundler3 contract addresses. Never bypassable. */
+export class BlacklistViolationError extends SimulationPackageError {
+    assetChanges;
+    code = "BLACKLIST_ERROR";
+    constructor(message, assetChanges) {
+        super(message);
+        this.assetChanges = assetChanges;
+    }
+}
+/** Sanctioned or compromised address detected. Never bypassable. */
+export class AddressScreeningError extends SimulationPackageError {
+    addresses;
+    code = "SCREENING_ERROR";
+    constructor(message, addresses) {
+        super(message);
+        this.addresses = addresses;
+    }
+}
+/** Tenderly or RPC service is down. Bypassable — user can proceed. */
+export class ExternalServiceError extends SimulationPackageError {
+    code = "EXTERNAL_SERVICE_ERROR";
+}
+/** Bad input to the simulation functions. Not bypassable. */
+export class SimulationValidationError extends SimulationPackageError {
+    fieldErrors;
+    code = "VALIDATION_ERROR";
+    constructor(message, fieldErrors) {
+        super(message);
+        this.fieldErrors = fieldErrors;
+    }
+}
+/** Chain ID not configured for any simulation method. Not bypassable. */
+export class UnsupportedChainError extends SimulationPackageError {
+    chainId;
+    code = "UNSUPPORTED_CHAIN";
+    constructor(chainId) {
+        super(`Chain ${chainId} is not configured for simulation`);
+        this.chainId = chainId;
+    }
+}

package/lib/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { screenAddresses } from "./screen-addresses/index.js";
+export { simulate } from "./simulate/index.js";
+export type { ChainSimulationConfig, SimulateParams, SimulationAuthorization, SimulationConfig, SimulationLogger, SimulationResult, SimulationTransaction, TenderlyRestConfig, Transfer, } from "./types.js";
+export { SimulationPackageError, SimulationRevertedError, BlacklistViolationError, AddressScreeningError, ExternalServiceError, SimulationValidationError, UnsupportedChainError, } from "./errors.js";

package/lib/esm/index.js

@@ -0,0 +1,5 @@
+// Public fns (via feature-folder barrels)
+export { screenAddresses } from "./screen-addresses/index.js";
+export { simulate } from "./simulate/index.js";
+// Errors (for instanceof checks by consumers)
+export { SimulationPackageError, SimulationRevertedError, BlacklistViolationError, AddressScreeningError, ExternalServiceError, SimulationValidationError, UnsupportedChainError, } from "./errors.js";

package/lib/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/esm/screen-addresses/index.d.ts

@@ -0,0 +1 @@
+export { screenAddresses } from "./screen-addresses.js";