@morpho-org/evm-simulation 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Morpho Association
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @morpho-org/evm-simulation
+
+EVM transaction simulation engine for Morpho — bundle execution preview,
+transfer parsing, and compliance screening.
+
+## Install
+
+Add to the consuming app's `package.json`:
+
+```jsonc
+{
+  "dependencies": {
+    "@morpho-org/evm-simulation": "workspace:*"
+  }
+}
+```
+
+## Quick start
+
+```ts
+import {
+  simulate,
+  screenAddresses,
+  type SimulationConfig,
+  SimulationRevertedError
+} from "@morpho-org/evm-simulation";
+
+const config: SimulationConfig = {
+  tenderlyRest: {
+    apiBaseUrl: "https://api.tenderly.co",
+    accessToken: process.env.TENDERLY_ACCESS_TOKEN!,
+    accountSlug: "my-account",
+    projectSlug: "my-project",
+    supportedChainIds: new Set([1]),
+  },
+  chains: new Map([[1, { simulateV1Url: process.env.MAINNET_RPC_URL }]]),
+  timeoutMs: 5000,
+};
+
+try {
+  // Pass { shareable: true } when you want a shareable Tenderly URL (user-facing preview).
+  // Omit it for server-side verification — the same function, same return shape.
+  const { transfers, simulationTxs, tenderlyUrl } = await simulate(
+    config,
+    {
+      chainId: 1,
+      transactions: [{ from: user, to: vault, data: encodedDeposit }],
+      authorizations: [{ type: "signature", token: usdc, spender: vault }],
+    },
+    { shareable: true }
+  );
+
+  // For server-side flows, pipe into screenAddresses:
+  await screenAddresses({ simulationTxs, transfers });
+} catch (err) {
+  if (err instanceof SimulationRevertedError) {
+    // show err.reason to the user
+  }
+  throw err;
+}
+```
+
+## API surface
+
+All symbols below are re-exported from the package root.
+
+- `simulate(config, params, options?)` — run a bundle through the simulation pipeline. Pass `{ shareable: true }` for a shareable Tenderly URL; omit for server-side verification.
+- `screenAddresses({ simulationTxs, transfers, chainalysisApiKey? })` — static sanctioned-set + optional Chainalysis screening.
+- Config types: `SimulationConfig`, `TenderlyRestConfig`, `ChainSimulationConfig`, `SimulationLogger`.
+- Data types: `SimulationTransaction`, `SimulationAuthorization`, `Transfer`, `SimulateParams`, `SimulationResult`.
+- Errors: `SimulationPackageError` (abstract base — `instanceof` it to catch any package error), `SimulationRevertedError`, `BlacklistViolationError`, `AddressScreeningError`, `ExternalServiceError`, `SimulationValidationError`, `UnsupportedChainError`.
+
+## Deeper docs
+
+See [`CLAUDE.md`](./CLAUDE.md) in this directory for the execution flow diagram,
+backend tradeoffs, authorizations model, screening design, error-handling table,
+and recipes for adding a chain or a new backend.

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

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

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsupportedChainError = exports.SimulationValidationError = exports.ExternalServiceError = exports.AddressScreeningError = exports.BlacklistViolationError = exports.SimulationRevertedError = exports.SimulationPackageError = exports.simulate = exports.screenAddresses = void 0;
+// Public fns (via feature-folder barrels)
+var index_js_1 = require("./screen-addresses/index.js");
+Object.defineProperty(exports, "screenAddresses", { enumerable: true, get: function () { return index_js_1.screenAddresses; } });
+var index_js_2 = require("./simulate/index.js");
+Object.defineProperty(exports, "simulate", { enumerable: true, get: function () { return index_js_2.simulate; } });
+// Errors (for instanceof checks by consumers)
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "SimulationPackageError", { enumerable: true, get: function () { return errors_js_1.SimulationPackageError; } });
+Object.defineProperty(exports, "SimulationRevertedError", { enumerable: true, get: function () { return errors_js_1.SimulationRevertedError; } });
+Object.defineProperty(exports, "BlacklistViolationError", { enumerable: true, get: function () { return errors_js_1.BlacklistViolationError; } });
+Object.defineProperty(exports, "AddressScreeningError", { enumerable: true, get: function () { return errors_js_1.AddressScreeningError; } });
+Object.defineProperty(exports, "ExternalServiceError", { enumerable: true, get: function () { return errors_js_1.ExternalServiceError; } });
+Object.defineProperty(exports, "SimulationValidationError", { enumerable: true, get: function () { return errors_js_1.SimulationValidationError; } });
+Object.defineProperty(exports, "UnsupportedChainError", { enumerable: true, get: function () { return errors_js_1.UnsupportedChainError; } });

package/lib/cjs/package.json

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

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

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

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

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenAddresses = void 0;
+var screen_addresses_js_1 = require("./screen-addresses.js");
+Object.defineProperty(exports, "screenAddresses", { enumerable: true, get: function () { return screen_addresses_js_1.screenAddresses; } });

package/lib/cjs/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/cjs/screen-addresses/sanctioned-addresses.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanctionedAddresses = void 0;
+/**
+ * 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.
+ */
+exports.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 exports.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/cjs/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/cjs/screen-addresses/screen-addresses.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenAddresses = screenAddresses;
+const viem_1 = require("viem");
+const zod_1 = require("zod");
+const errors_js_1 = require("../errors.js");
+const sanctioned_addresses_js_1 = require("./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 = zod_1.z
+    .object({
+    risk: zod_1.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`.
+ */
+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(viem_1.zeroAddress);
+    // 1. Static sanctioned list — always on, no network.
+    const sanctioned = [];
+    for (const addr of addressesToScreen) {
+        if (sanctioned_addresses_js_1.sanctionedAddresses.has(addr))
+            sanctioned.push((0, viem_1.getAddress)(addr));
+    }
+    if (sanctioned.length > 0) {
+        throw new errors_js_1.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((0, viem_1.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 errors_js_1.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/cjs/simulate/authorizations/index.d.ts

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

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

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAuthorizations = exports.resolveAuthorizations = void 0;
+var resolve_js_1 = require("./resolve.js");
+Object.defineProperty(exports, "resolveAuthorizations", { enumerable: true, get: function () { return resolve_js_1.resolveAuthorizations; } });
+var validate_js_1 = require("./validate.js");
+Object.defineProperty(exports, "validateAuthorizations", { enumerable: true, get: function () { return validate_js_1.validateAuthorizations; } });

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

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

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

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAuthorizations = validateAuthorizations;
+const viem_1 = require("viem");
+/**
+ * Validate all signature authorizations have non-zero token and spender.
+ * Returns an array of error strings (empty if valid).
+ */
+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 === viem_1.zeroAddress) {
+                errors.push(`authorizations[${i}]: signature authorization has zero-address token`);
+            }
+            if (!auth.spender || auth.spender === viem_1.zeroAddress) {
+                errors.push(`authorizations[${i}]: signature authorization has zero-address spender`);
+            }
+        }
+    }
+    return errors;
+}

package/lib/cjs/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>;