@morpho-org/evm-simulation 1.0.0

package/lib/esm/screen-addresses/index.js

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

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

@@ -0,0 +1,11 @@
+/**
+ * Static list of sanctioned/compromised addresses.
+ * Ported from offchain-services-server/src/functions/screen/blacklist.ts.
+ * These addresses are checked before calling the Chainalysis API (fast, no network).
+ *
+ * **Invariant** (enforced at module load, see below): every entry is a
+ * well-formed lowercased EVM address. `screenAddresses` does
+ * `sanctionedAddresses.has(addr.toLowerCase())` — a mixed-case entry would
+ * never match and would silently bypass the sanctioned check.
+ */
+export declare const sanctionedAddresses: Set<string>;

package/lib/esm/screen-addresses/sanctioned-addresses.js

@@ -0,0 +1,74 @@
+/**
+ * Static list of sanctioned/compromised addresses.
+ * Ported from offchain-services-server/src/functions/screen/blacklist.ts.
+ * These addresses are checked before calling the Chainalysis API (fast, no network).
+ *
+ * **Invariant** (enforced at module load, see below): every entry is a
+ * well-formed lowercased EVM address. `screenAddresses` does
+ * `sanctionedAddresses.has(addr.toLowerCase())` — a mixed-case entry would
+ * never match and would silently bypass the sanctioned check.
+ */
+export const sanctionedAddresses = new Set([
+    // Bybit hack addresses
+    "0x47666Fab8bd0Ac7003bce3f5C3585383F09486E2",
+    "0xA4B2Fd68593B6F34E51cB9eDB66E71c1B4Ab449e",
+    "0x36ed3C0213565530C35115d93A80F9c04d94E4Cb",
+    "0x1542368a03ad1f03d96D51B414f4738961Cf4443",
+    "0xdD90071D52F20e85c89802e5Dc1eC0A7B6475f92",
+    "0x40e98FeEEbaD7Ddb0F0534Ccaa617427eA10187e",
+    "0x30a822CDD2782D2B2A12a08526452e885978FA1D",
+    "0x6d46bd3AfF100f23C194e5312f93507978a6DC91",
+    "0x660BfcEa3A5FAF823e8f8bF57dd558db034dea1d",
+    "0x140c9Ab92347734641b1A7c124ffDeE58c20C3E3",
+    "0x8c7235e1A6EeF91b980D0FcA083347FBb7EE1806",
+    "0xb172F7e99452446f18FF49A71bfEeCf0873003b4",
+    "0xCd7eC020121Ead6f99855cbB972dF502dB5bC63a",
+    "0x0e8C1E2881F35Ef20343264862A242FB749d6b35",
+    "0x2290937A4498C96eFfb87b8371a33D108F8D433f",
+    "0x1bb0970508316DC735329752a4581E0a4bAbc6B4",
+    "0xf0a16603289eAF35F64077Ba3681af41194a1c09",
+    "0x5Af75eAB6BEC227657fA3E749a8BFd55f02e4b1D",
+    "0xB4a862A81aBB2f952FcA4C6f5510962e18c7f1A2",
+    "0x959c4CA19c4532C97A657D82d97acCBAb70e6fb4",
+    "0xB72334cB9D0b614D30C4c60e2bd12fF5Ed03c305",
+    "0xFc926659Dd8808f6e3e0a8d61B20B871F3Fa6465",
+    "0xfa3FcCCB897079fD83bfBA690E7D47Eb402d6c49",
+    "0x51E9d833Ecae4E8D9D8Be17300AEE6D3398C135D",
+    "0x1eB27f136BFe7947f80d6ceE3Cf0bfDf92b45e57",
+    "0x83Ef5E80faD88288F770152875Ab0bb16641a09E",
+    "0x52207Ec7B1b43AA5DB116931a904371ae2C1619e",
+    "0x23Db729908137cb60852f2936D2b5c6De0e1c887",
+    "0xAF620E6d32B1c67f3396EF5d2F7d7642Dc2e6CE9",
+    "0xCd1a4A457cA8b0931c3BF81Df3CFa227ADBdb6E9",
+    "0x96244D83DC15d36847C35209bBDc5bdDE9bEc3D8",
+    "0x09278b36863bE4cCd3d0c22d643E8062D7a11377",
+    "0x3A21F4E6Bbe527D347ca7c157F4233c935779847",
+    "0xBC3e5e8C10897a81b63933348f53f2e052F89a7E",
+    "0x9271EDdda0F0f2bB7b1A0c712bdF8dbD0A38d1Ab",
+    "0x4C198B3B5F3a4b1Aa706daC73D826c2B795ccd67",
+    "0x684d4b58Dc32af786BF6D572A792fF7A883428B9",
+    "0xD3C611AeD139107DEC2294032da3913BC26507fb",
+    "0x9eF42873Ae015AA3da0c4354AeF94a18D2B3407b",
+    "0xbdE2Cc5375fa9E0383309A2cA31213f2D6cabcbd",
+    "0xe69753Ddfbedbd249E703EB374452E78dae1ae49",
+    "0xE9bc552fdFa54b30296d95F147e3e0280FF7f7e6",
+    "0xBCA02B395747D62626a65016F2e64A20bd254A39",
+    "0xF302572594a68aA8F951faE64ED3aE7DA41c72Be",
+    "0x21032176B43d9f7E9410fB37290a78f4fEd6044C",
+    "0xD5b58Cf7813c1eDC412367b97876bD400ea5c489",
+    "0xA5A023E052243b7cce34Cbd4ba20180e8Dea6Ad6",
+    "0x723a7084028421994d4a7829108D63aB44658315",
+    "0x1512fcb09463A61862B73ec09B9b354aF1790268",
+    "0xEB0bAA3A556586192590CAD296b1e48dF62a8549",
+    "0xf03AfB1c6A11A7E370920ad42e6eE735dBedF0b1",
+    "0x55CCa2f5eB07907696afe4b9Db5102bcE5feB734",
+].map((a) => a.toLowerCase()));
+// Runtime invariant check at module load. Catches a future edit that adds an
+// entry via `sanctionedAddresses.add(...)` bypassing the `.map(toLowerCase)` or
+// inserts a malformed string. Throwing at load is the loudest signal — the
+// package won't import if the dataset is invalid.
+for (const entry of sanctionedAddresses) {
+    if (!/^0x[0-9a-f]{40}$/.test(entry)) {
+        throw new Error(`sanctioned-addresses.ts: entry "${entry}" is not a well-formed lowercased EVM address. Every entry must match /^0x[0-9a-f]{40}$/ so lowercase lookup matches.`);
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { SimulationLogger, SimulationTransaction, Transfer } from "../types.js";
+/**
+ * Screen all relevant addresses from a simulation for sanctioned/compromised addresses.
+ *
+ * Screening targets (deduped, lowercased, zero-addr removed):
+ * - Transfer senders and recipients from simulation result
+ * - `from` and `to` of every tx in `simulationTxs` (catches native-value flows)
+ *
+ * Checks run in order:
+ * 1. Static {@link sanctionedAddresses} set (fast, no network, always on).
+ * 2. Chainalysis Entity API — one lookup per address, lookups across addresses
+ *    run in parallel. Only fires if `chainalysisApiKey` is provided.
+ *    **Fail-open on transport errors before registration** (network / timeout /
+ *    non-ok POST): the address is treated as clean, a warn is logged, and the
+ *    simulation proceeds. This is the documented posture — a Chainalysis
+ *    outage must not block all simulations.
+ *    **Fail-closed on partial registration**: if the registration POST succeeded
+ *    but the subsequent lookup GET fails, the address is treated as Severe.
+ *    The data already persisted server-side, so failing open at this point
+ *    would let a pass slip through based on a half-completed check.
+ *    **Fail-closed on schema drift**: if Chainalysis returns an unknown risk
+ *    tier or a body that doesn't parse, the address is treated as Severe so a
+ *    future stricter tier isn't silently downgraded.
+ *
+ * Throws `AddressScreeningError` on any Severe hit. Intended to be called after
+ * `simulate`, passing the returned `simulationTxs` and `transfers`.
+ */
+export declare function screenAddresses(params: {
+    simulationTxs: SimulationTransaction[];
+    transfers: Transfer[];
+    chainalysisApiKey?: string;
+    signal?: AbortSignal;
+    logger?: SimulationLogger;
+}): Promise<void>;

package/lib/esm/screen-addresses/screen-addresses.js

@@ -0,0 +1,149 @@
+import { getAddress, zeroAddress } from "viem";
+import { z } from "zod";
+import { AddressScreeningError } from "../errors.js";
+import { sanctionedAddresses } from "./sanctioned-addresses.js";
+const CHAINALYSIS_API_URL = "https://api.chainalysis.com/api/risk/v2/entities";
+const CHAINALYSIS_TIMEOUT_MS = 5_000;
+/**
+ * Known tiers whose presence means NOT severe. Any other value (unknown future
+ * tier, malformed field) is treated as Severe so a stricter tier Chainalysis
+ * might introduce later isn't silently downgraded to clean.
+ */
+const NON_SEVERE_TIERS = new Set(["High", "Medium", "Low"]);
+const chainalysisEntitySchema = z
+    .object({
+    risk: z.string().nullable(),
+})
+    .passthrough();
+/**
+ * Screen all relevant addresses from a simulation for sanctioned/compromised addresses.
+ *
+ * Screening targets (deduped, lowercased, zero-addr removed):
+ * - Transfer senders and recipients from simulation result
+ * - `from` and `to` of every tx in `simulationTxs` (catches native-value flows)
+ *
+ * Checks run in order:
+ * 1. Static {@link sanctionedAddresses} set (fast, no network, always on).
+ * 2. Chainalysis Entity API — one lookup per address, lookups across addresses
+ *    run in parallel. Only fires if `chainalysisApiKey` is provided.
+ *    **Fail-open on transport errors before registration** (network / timeout /
+ *    non-ok POST): the address is treated as clean, a warn is logged, and the
+ *    simulation proceeds. This is the documented posture — a Chainalysis
+ *    outage must not block all simulations.
+ *    **Fail-closed on partial registration**: if the registration POST succeeded
+ *    but the subsequent lookup GET fails, the address is treated as Severe.
+ *    The data already persisted server-side, so failing open at this point
+ *    would let a pass slip through based on a half-completed check.
+ *    **Fail-closed on schema drift**: if Chainalysis returns an unknown risk
+ *    tier or a body that doesn't parse, the address is treated as Severe so a
+ *    future stricter tier isn't silently downgraded.
+ *
+ * Throws `AddressScreeningError` on any Severe hit. Intended to be called after
+ * `simulate`, passing the returned `simulationTxs` and `transfers`.
+ */
+export async function screenAddresses(params) {
+    const { simulationTxs, transfers, chainalysisApiKey, signal, logger } = params;
+    const addressesToScreen = new Set();
+    for (const transfer of transfers) {
+        addressesToScreen.add(transfer.from.toLowerCase());
+        addressesToScreen.add(transfer.to.toLowerCase());
+    }
+    for (const tx of simulationTxs) {
+        addressesToScreen.add(tx.from.toLowerCase());
+        addressesToScreen.add(tx.to.toLowerCase());
+    }
+    addressesToScreen.delete(zeroAddress);
+    // 1. Static sanctioned list — always on, no network.
+    const sanctioned = [];
+    for (const addr of addressesToScreen) {
+        if (sanctionedAddresses.has(addr))
+            sanctioned.push(getAddress(addr));
+    }
+    if (sanctioned.length > 0) {
+        throw new AddressScreeningError("Transaction involves sanctioned addresses", sanctioned);
+    }
+    // 2. Chainalysis (optional).
+    if (!chainalysisApiKey) {
+        logger?.warn("Chainalysis screening skipped: no API key configured");
+        return;
+    }
+    const results = await Promise.allSettled([...addressesToScreen].map(async (addr) => {
+        const verdict = await screenWithChainalysis(addr, chainalysisApiKey, signal);
+        return { addr, verdict };
+    }));
+    const flagged = [];
+    for (const r of results) {
+        if (r.status === "fulfilled") {
+            if (r.value.verdict === "severe")
+                flagged.push(getAddress(r.value.addr));
+        }
+        else {
+            // Transport fail-open: registration POST couldn't even complete, so the
+            // address was never registered with Chainalysis and the package's
+            // fail-open posture applies.
+            logger?.warn("Chainalysis screening failed (fail-open)", {
+                error: r.reason instanceof Error ? r.reason.message : String(r.reason),
+            });
+        }
+    }
+    if (flagged.length > 0) {
+        throw new AddressScreeningError("Transaction involves addresses flagged as Severe risk", flagged);
+    }
+}
+/**
+ * Run the Chainalysis Entity flow for one address.
+ *
+ * Returns `'severe'` or `'clean'`. Throws only if the initial registration POST
+ * fails before any server-side side effect — then the outer handler treats the
+ * rejection as fail-open. After registration succeeds, every error path returns
+ * `'severe'` so the check fails closed.
+ *
+ * A SINGLE deadline covers both the POST and the GET, keeping the per-address
+ * wall-time budget at `CHAINALYSIS_TIMEOUT_MS` (5 s) rather than doubling it.
+ */
+async function screenWithChainalysis(address, apiKey, parentSignal) {
+    const headers = {
+        "Content-Type": "application/json",
+        token: apiKey,
+    };
+    const deadline = AbortSignal.timeout(CHAINALYSIS_TIMEOUT_MS);
+    const signal = parentSignal
+        ? AbortSignal.any([parentSignal, deadline])
+        : deadline;
+    // POST to register. Pre-registration failure → fail-open via thrown Error.
+    const registration = await fetch(CHAINALYSIS_API_URL, {
+        headers,
+        method: "POST",
+        body: JSON.stringify({ address }),
+        signal,
+    });
+    if (!registration.ok) {
+        throw new Error(`Chainalysis registration failed: ${registration.status} ${registration.statusText}`);
+    }
+    // From here on we've already told Chainalysis about the address — fail closed.
+    let response;
+    try {
+        response = await fetch(`${CHAINALYSIS_API_URL}/${encodeURIComponent(address)}`, {
+            method: "GET",
+            headers,
+            signal,
+        });
+    }
+    catch {
+        return "severe";
+    }
+    if (!response.ok)
+        return "severe";
+    let parsed;
+    try {
+        parsed = chainalysisEntitySchema.parse(await response.json());
+    }
+    catch {
+        return "severe";
+    }
+    if (parsed.risk === null)
+        return "clean";
+    if (NON_SEVERE_TIERS.has(parsed.risk))
+        return "clean";
+    return "severe";
+}

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

@@ -0,0 +1,2 @@
+export { resolveAuthorizations } from "./resolve.js";
+export { validateAuthorizations } from "./validate.js";

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

@@ -0,0 +1,2 @@
+export { resolveAuthorizations } from "./resolve.js";
+export { validateAuthorizations } from "./validate.js";

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

@@ -0,0 +1,9 @@
+import { type Address } from "viem";
+import type { SimulationAuthorization, SimulationTransaction } from "../../types.js";
+/**
+ * Resolve SimulationAuthorization[] into SimulationTransaction[].
+ *
+ * - "approval" → use authorization.transaction as-is
+ * - "signature" → encode approve(spender, amount) on the token contract
+ */
+export declare function resolveAuthorizations(authorizations: SimulationAuthorization[], sender: Address): SimulationTransaction[];

package/lib/esm/simulate/authorizations/resolve.js

@@ -0,0 +1,26 @@
+import { encodeFunctionData, erc20Abi, maxUint256 } from "viem";
+/**
+ * Resolve SimulationAuthorization[] into SimulationTransaction[].
+ *
+ * - "approval" → use authorization.transaction as-is
+ * - "signature" → encode approve(spender, amount) on the token contract
+ */
+export function resolveAuthorizations(authorizations, sender) {
+    return authorizations.map((auth) => {
+        if (auth.type === "approval") {
+            return auth.transaction;
+        }
+        const amount = auth.amount ?? maxUint256;
+        const data = encodeFunctionData({
+            abi: erc20Abi,
+            functionName: "approve",
+            args: [auth.spender, amount],
+        });
+        return {
+            from: sender,
+            to: auth.token,
+            data,
+            value: 0n,
+        };
+    });
+}

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

@@ -0,0 +1,6 @@
+import type { SimulationAuthorization } from "../../types.js";
+/**
+ * Validate all signature authorizations have non-zero token and spender.
+ * Returns an array of error strings (empty if valid).
+ */
+export declare function validateAuthorizations(authorizations: SimulationAuthorization[]): string[];

package/lib/esm/simulate/authorizations/validate.js

@@ -0,0 +1,20 @@
+import { zeroAddress } from "viem";
+/**
+ * Validate all signature authorizations have non-zero token and spender.
+ * Returns an array of error strings (empty if valid).
+ */
+export function validateAuthorizations(authorizations) {
+    const errors = [];
+    for (let i = 0; i < authorizations.length; i++) {
+        const auth = authorizations[i];
+        if (auth.type === "signature") {
+            if (!auth.token || auth.token === zeroAddress) {
+                errors.push(`authorizations[${i}]: signature authorization has zero-address token`);
+            }
+            if (!auth.spender || auth.spender === zeroAddress) {
+                errors.push(`authorizations[${i}]: signature authorization has zero-address spender`);
+            }
+        }
+    }
+    return errors;
+}

package/lib/esm/simulate/backends/eth-simulate-v1.d.ts

@@ -0,0 +1,15 @@
+import { type BlockTag } from "viem";
+import type { RawSimulationResult, SimulationTransaction } from "../../types.js";
+/**
+ * Simulate transactions using eth_simulateV1 (viem simulateCalls).
+ *
+ * Uses stateOverride to set the user's ETH balance high enough to avoid
+ * false "insufficient balance for gas" reverts.
+ */
+export declare function simulateV1(params: {
+    rpcUrl: string;
+    chainId: number;
+    transactions: SimulationTransaction[];
+    blockNumber?: bigint | BlockTag;
+    signal?: AbortSignal;
+}): Promise<RawSimulationResult>;

package/lib/esm/simulate/backends/eth-simulate-v1.js

@@ -0,0 +1,73 @@
+import { http, createPublicClient, getAddress, maxUint256, } from "viem";
+import { ExternalServiceError, SimulationRevertedError, SimulationValidationError, } from "../../errors.js";
+/**
+ * Simulate transactions using eth_simulateV1 (viem simulateCalls).
+ *
+ * Uses stateOverride to set the user's ETH balance high enough to avoid
+ * false "insufficient balance for gas" reverts.
+ */
+export async function simulateV1(params) {
+    const { rpcUrl, transactions, blockNumber, signal } = params;
+    const client = createPublicClient({
+        transport: http(rpcUrl, {
+            fetchOptions: signal ? { signal } : undefined,
+        }),
+    });
+    const firstTx = transactions[0];
+    if (!firstTx) {
+        throw new SimulationValidationError("At least one transaction is required", []);
+    }
+    const sender = getAddress(firstTx.from);
+    // eth_simulateV1 executes all calls as the same account. Reject mixed senders
+    // to avoid silently simulating under the wrong address.
+    const mixedSender = transactions.find((tx) => getAddress(tx.from) !== sender);
+    if (mixedSender) {
+        throw new SimulationValidationError("All transactions must have the same from address for eth_simulateV1", [`expected ${sender}, got ${mixedSender.from}`]);
+    }
+    const calls = transactions.map((tx) => ({
+        to: tx.to,
+        data: tx.data,
+        value: tx.value,
+    }));
+    const blockParam = typeof blockNumber === "bigint"
+        ? { blockNumber }
+        : blockNumber !== undefined
+            ? { blockTag: blockNumber }
+            : {};
+    try {
+        const simulationResult = await client.simulateCalls({
+            account: sender,
+            calls,
+            ...blockParam,
+            // Inflate sender ETH balance to prevent false "insufficient gas" reverts.
+            // Without this, valid ERC20 flows fail when the sender has low ETH.
+            stateOverrides: [{ address: sender, balance: maxUint256 }],
+        });
+        const results = simulationResult.results;
+        if (!Array.isArray(results)) {
+            throw new ExternalServiceError("eth_simulateV1 returned unexpected response format");
+        }
+        const failedResult = results.find((r) => r.status !== "success");
+        if (failedResult) {
+            throw new SimulationRevertedError(failedResult.error?.message ?? "Simulation failed", results);
+        }
+        const rawLogs = [];
+        for (const r of results) {
+            for (const log of r.logs ?? []) {
+                rawLogs.push({
+                    address: log.address,
+                    topics: [...log.topics],
+                    data: log.data ?? "0x",
+                });
+            }
+        }
+        return { logs: rawLogs };
+    }
+    catch (error) {
+        if (error instanceof SimulationRevertedError)
+            throw error;
+        if (error instanceof ExternalServiceError)
+            throw error;
+        throw new ExternalServiceError(`eth_simulateV1 error: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}

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

@@ -0,0 +1,2 @@
+export { simulateV1 } from "./eth-simulate-v1.js";
+export { simulateTenderlyRest } from "./tenderly-rest.js";

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

@@ -0,0 +1,2 @@
+export { simulateV1 } from "./eth-simulate-v1.js";
+export { simulateTenderlyRest } from "./tenderly-rest.js";

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

@@ -0,0 +1,20 @@
+import { type BlockTag } from "viem";
+import type { RawSimulationResult, SimulationLogger, SimulationTransaction, TenderlyRestConfig } from "../../types.js";
+/**
+ * Simulate transactions using Tenderly REST API.
+ *
+ * @param shareable - true persists the simulation in Tenderly and returns a shareable URL;
+ *   false runs ephemerally with no URL. Translates to Tenderly's `save` wire field
+ *   (`save_if_fails` is also set to `shareable` — so failed preview simulations are
+ *   ALSO persisted and shareable. Callers that preview sensitive calldata should be
+ *   aware this persists in Tenderly's dashboard regardless of success/failure).
+ */
+export declare function simulateTenderlyRest(params: {
+    config: TenderlyRestConfig;
+    chainId: number;
+    transactions: SimulationTransaction[];
+    blockNumber?: bigint | BlockTag;
+    shareable: boolean;
+    signal?: AbortSignal;
+    logger?: SimulationLogger;
+}): Promise<RawSimulationResult>;