@txfence/evm 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @txfence/evm
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public release — policy engine, intent execution, formal verification, adversarial stress testing, cryptographic provenance chains, temporal rules, and MEV protection across EVM, Solana, and Cosmos
+
+### Patch Changes
+
+- Updated dependencies
+  - @txfence/core@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Chauhan
+
+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,106 @@
+# @txfence/evm
+
+EVM chain adapter for [txfence](https://github.com/AdityaChauhanX07/txfence). Simulation (`eth_call` + Tenderly), fork simulation, signing, broadcast, and MEV-protected RPC routing for Ethereum, Arbitrum, Optimism, Base, and any EVM chain supported by viem.
+
+## Installation
+
+```bash
+npm install @txfence/evm @txfence/core viem
+```
+
+## Quick start
+
+```typescript
+import { createAgent, type Policy } from '@txfence/core'
+import { simulateEvmAction, executeEvmAction, privateKeySigner } from '@txfence/evm'
+
+const signer = privateKeySigner(process.env.PRIVATE_KEY as `0x${string}`)
+
+const agent = createAgent(
+  { chains: ['ethereum'], policies: policy, signer },
+  { ethereum: { simulate: simulateEvmAction } },
+  { ethereum: 'https://ethereum.publicnode.com' },
+  (action, chainId, rpcUrl, evaluation, simulation) =>
+    executeEvmAction(action, chainId, rpcUrl, signer, evaluation, simulation),
+)
+```
+
+## Tenderly simulation
+
+Pass a `TenderlyConfig` and `simulateEvmAction` upgrades from `eth_call` to a full Tenderly simulation — state diffs, traces, balance changes:
+
+```typescript
+import { simulateEvmAction } from '@txfence/evm'
+
+const result = await simulateEvmAction(action, 'ethereum', rpcUrl, {
+  tenderly: {
+    accessKey:   process.env.TENDERLY_ACCESS_KEY!,
+    accountSlug: process.env.TENDERLY_ACCOUNT_SLUG!,
+    projectSlug: process.env.TENDERLY_PROJECT_SLUG!,
+  },
+})
+// result.coverageLevel: 'full' when Tenderly returns; 'partial' on eth_call fallback
+```
+
+## Fork simulation
+
+Simulate a multi-step intent against a forked chain state:
+
+```typescript
+import { simulateIntentOnFork } from '@txfence/evm'
+
+const result = await simulateIntentOnFork(
+  rebalanceIntent,
+  {
+    provider: 'tenderly',
+    tenderlyConfig: { accessKey, accountSlug, projectSlug },
+    fromAddress: agentAddress,
+  },
+  'ethereum',
+  rpcUrl,
+)
+// result.wouldAllSucceed, result.finalPosition, result.failingStepId
+// The fork is automatically deleted after simulation.
+```
+
+## MEV protection
+
+Route through Flashbots Protect or MEV Blocker:
+
+```typescript
+const policy: Policy = {
+  // ...
+  mevProtection: 'flashbots',  // 'flashbots' | 'mev-blocker' | 'none'
+}
+```
+
+`getMevProtectedRpcUrl()` and `broadcastWithMevProtection()` are exported for advanced cases.
+
+## Metadata verification
+
+Validate that a contract's on-chain bytecode matches an expected implementation hash:
+
+```typescript
+import { createEvmMetadataVerifier } from '@txfence/evm'
+
+const verifier = createEvmMetadataVerifier(rpcUrl)
+const ok = await verifier.verify('0xCONTRACT', 'ethereum', { implementationHash: '0x...' })
+```
+
+Catches proxy upgrades and unexpected implementations before signing.
+
+## Exports
+
+- `simulateEvmAction`, `simulateWithTenderly` — simulation
+- `executeEvmAction`, `buildEvmTransaction` — execution
+- `createFork`, `simulateOnFork`, `deleteFork`, `simulateIntentOnFork` — fork simulation
+- `privateKeySigner` — viem-backed `Signer`
+- `getMevProtectedRpcUrl`, `broadcastWithMevProtection` — MEV routing
+- `createEvmMetadataVerifier` — on-chain contract verification
+- `getViemChain` — chain id → viem `Chain` helper
+
+Full project README: https://github.com/AdityaChauhanX07/txfence
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { Action, TenderlyForkConfig, ChainId, StateChange, Intent, ForkSimulationConfig, ForkSimulationResult, SimulateOptions, SimulationResult, Signer, PolicyEvaluation, MevProtectionMode, MevProtectionConfig, SuccessReceipt, SerializedTransaction, MetadataVerifier } from '@txfence/core';
+import { Chain } from 'viem';
+
+declare function createFork(config: TenderlyForkConfig, chainId: ChainId, blockNumber?: number): Promise<{
+    forkId: string;
+    forkedAtBlock: number;
+}>;
+declare function simulateOnFork(config: TenderlyForkConfig, forkId: string, transaction: {
+    from: string;
+    to: string;
+    input: string;
+    value: string;
+    gas: number;
+}, chainId: ChainId, blockNumber: number): Promise<{
+    success: boolean;
+    wouldRevert: boolean;
+    revertReason?: string;
+    gasUsed: number;
+    stateChanges: StateChange[];
+    rawTrace: unknown;
+}>;
+declare function deleteFork(config: TenderlyForkConfig, forkId: string): Promise<void>;
+declare function buildForkTransactionParams(action: Action, fromAddress: string): {
+    from: string;
+    to: string;
+    input: string;
+    value: string;
+    gas: number;
+};
+
+declare function simulateIntentOnFork(intent: Intent, config: ForkSimulationConfig, chainId: ChainId, rpcUrl: string): Promise<ForkSimulationResult>;
+
+type TenderlyConfig = {
+    accountSlug: string;
+    projectSlug: string;
+    accessKey: string;
+};
+declare function simulateEvmAction(action: Action, chainId: ChainId, rpcUrl: string, options?: SimulateOptions, tenderlyConfig?: TenderlyConfig): Promise<SimulationResult>;
+
+declare function simulateWithTenderly(action: Action, chainId: ChainId, tenderlyConfig: TenderlyConfig, options?: SimulateOptions): Promise<SimulationResult>;
+
+declare function getViemChain(chainId: ChainId): Chain;
+
+declare function executeEvmAction(action: Action, chainId: ChainId, rpcUrl: string, signer: Signer, evaluation: PolicyEvaluation, simulation: SimulationResult, mevProtection?: MevProtectionMode, mevConfig?: MevProtectionConfig): Promise<SuccessReceipt>;
+
+declare function privateKeySigner(privateKey: `0x${string}`): Signer;
+
+declare function buildEvmTransaction(action: Action, chainId: ChainId, rpcUrl: string, gasEstimate: bigint, gasBufferMultiplier: number, _fromAddress: `0x${string}`): Promise<SerializedTransaction>;
+
+declare function createEvmMetadataVerifier(rpcUrls: Partial<Record<string, string>>): MetadataVerifier;
+
+declare function getMevProtectedRpcUrl(mode: MevProtectionMode | undefined, config?: MevProtectionConfig, fallbackRpcUrl?: string): string;
+declare function broadcastWithMevProtection(signedTxHex: `0x${string}`, mode: MevProtectionMode | undefined, config?: MevProtectionConfig, fallbackRpcUrl?: string): Promise<string>;
+
+export { type TenderlyConfig, broadcastWithMevProtection, buildEvmTransaction, buildForkTransactionParams, createEvmMetadataVerifier, createFork, deleteFork, executeEvmAction, getMevProtectedRpcUrl, getViemChain, privateKeySigner, simulateEvmAction, simulateIntentOnFork, simulateOnFork, simulateWithTenderly };

package/dist/index.js

@@ -0,0 +1,620 @@
+// src/chains.ts
+import { mainnet, arbitrum, optimism, base } from "viem/chains";
+var viemChains = {
+  ethereum: mainnet,
+  arbitrum,
+  optimism,
+  base
+};
+function getViemChain(chainId) {
+  const chain = viemChains[chainId];
+  if (chain === void 0) {
+    throw new Error(`chain not supported by EVM adapter: ${chainId}`);
+  }
+  return chain;
+}
+
+// src/fork-client.ts
+async function createFork(config, chainId, blockNumber) {
+  const viemChain = getViemChain(chainId);
+  const networkId = viemChain.id.toString();
+  const body = {
+    network_id: networkId
+  };
+  if (blockNumber !== void 0) {
+    body.block_number = blockNumber;
+  }
+  const response = await fetch(
+    `https://api.tenderly.co/api/v1/account/${config.accountSlug}/project/${config.projectSlug}/fork`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Access-Key": config.accessKey
+      },
+      body: JSON.stringify(body)
+    }
+  );
+  if (!response.ok) {
+    throw new Error(`Failed to create Tenderly fork: ${response.status} ${await response.text()}`);
+  }
+  const data = await response.json();
+  return {
+    forkId: data.simulation_fork.id,
+    forkedAtBlock: data.simulation_fork.block_number
+  };
+}
+async function simulateOnFork(config, forkId, transaction, chainId, blockNumber) {
+  const response = await fetch(
+    `https://api.tenderly.co/api/v1/account/${config.accountSlug}/project/${config.projectSlug}/fork/${forkId}/simulate`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Access-Key": config.accessKey
+      },
+      body: JSON.stringify({
+        network_id: getViemChain(chainId).id.toString(),
+        from: transaction.from,
+        to: transaction.to,
+        input: transaction.input,
+        value: transaction.value,
+        gas: transaction.gas,
+        save: false,
+        save_if_fails: false,
+        simulation_type: "full"
+      })
+    }
+  );
+  if (!response.ok) {
+    throw new Error(`Fork simulation failed: ${response.status} ${await response.text()}`);
+  }
+  const data = await response.json();
+  const stateChanges = (data.contracts ?? []).filter((c) => c.balanceDiff !== void 0).map((c) => {
+    const before = BigInt(c.balanceDiff.before);
+    const after = BigInt(c.balanceDiff.after);
+    return {
+      address: c.address,
+      balanceBefore: before,
+      balanceAfter: after,
+      delta: after - before
+    };
+  });
+  const revertReason = data.simulation.error_message;
+  return {
+    success: true,
+    wouldRevert: !data.simulation.status,
+    ...revertReason !== null ? { revertReason } : {},
+    gasUsed: data.simulation.gas_used,
+    stateChanges,
+    rawTrace: data.call_trace
+  };
+}
+async function deleteFork(config, forkId) {
+  const response = await fetch(
+    `https://api.tenderly.co/api/v1/account/${config.accountSlug}/project/${config.projectSlug}/fork/${forkId}`,
+    {
+      method: "DELETE",
+      headers: {
+        "X-Access-Key": config.accessKey
+      }
+    }
+  );
+  if (!response.ok && response.status !== 404) {
+    console.error(`[txfence] Failed to delete Tenderly fork ${forkId}: ${response.status}`);
+  }
+}
+function buildForkTransactionParams(action, fromAddress) {
+  switch (action.kind) {
+    case "transfer":
+      return {
+        from: fromAddress,
+        to: action.to,
+        input: "0x",
+        value: "0x" + action.token.amount.toString(16),
+        gas: 21e3
+      };
+    case "swap":
+      return {
+        from: fromAddress,
+        to: action.via,
+        input: action.calldata ?? "0x",
+        value: "0x0",
+        gas: 3e5
+      };
+    case "contract_call":
+      return {
+        from: fromAddress,
+        to: action.contract,
+        input: action.calldata ?? "0x",
+        value: action.value !== void 0 ? "0x" + action.value.amount.toString(16) : "0x0",
+        gas: 3e5
+      };
+  }
+}
+
+// src/fork-simulation.ts
+import { getExecutionPlan, mergePositionChanges } from "@txfence/core";
+async function simulateIntentOnFork(intent, config, chainId, rpcUrl) {
+  if (config.provider !== "tenderly" || config.tenderlyConfig === void 0) {
+    throw new Error(
+      'simulateIntentOnFork requires provider: "tenderly" with tenderlyConfig. Solana fork simulation is planned for v2.'
+    );
+  }
+  const tenderlyConfig = config.tenderlyConfig;
+  const simulatedAt = Date.now();
+  let executionPlan;
+  try {
+    executionPlan = getExecutionPlan(intent);
+  } catch (err) {
+    throw new Error(`Intent graph is invalid: ${err.message}`);
+  }
+  const stepMap = new Map(intent.steps.map((s) => [s.id, s]));
+  let forkId;
+  let forkedAtBlock;
+  try {
+    const fork = await createFork(tenderlyConfig, chainId, config.blockNumber);
+    forkId = fork.forkId;
+    forkedAtBlock = fork.forkedAtBlock;
+  } catch (err) {
+    throw new Error(`Failed to create fork: ${err.message}`);
+  }
+  const stepResults = [];
+  let cumulativePosition = [];
+  let wouldAllSucceed = true;
+  let failingStepId;
+  try {
+    for (const stepId of executionPlan) {
+      const step = stepMap.get(stepId);
+      if (step === void 0) continue;
+      const txParams = buildForkTransactionParams(step.action, config.fromAddress);
+      let simResult;
+      try {
+        simResult = await simulateOnFork(
+          tenderlyConfig,
+          forkId,
+          txParams,
+          chainId,
+          forkedAtBlock
+        );
+      } catch (err) {
+        stepResults.push({
+          stepId,
+          simulation: {
+            success: false,
+            wouldRevert: false,
+            chain: chainId,
+            simulatedAtBlock: forkedAtBlock,
+            gasEstimate: 0n,
+            gasBufferApplied: 1,
+            coverageLevel: "none",
+            caveats: ["state_may_diverge"],
+            provider: "tenderly"
+          },
+          stateChanges: [],
+          cumulativePosition: [...cumulativePosition],
+          wouldRevert: false
+        });
+        if (step.optional !== true) {
+          wouldAllSucceed = false;
+          if (failingStepId === void 0) failingStepId = stepId;
+        }
+        continue;
+      }
+      const stepPositionChanges = simResult.stateChanges.filter((sc) => sc.delta !== 0n).map((sc) => ({
+        token: sc.token ?? "native",
+        amount: sc.delta,
+        chain: chainId
+      }));
+      cumulativePosition = mergePositionChanges(cumulativePosition, stepPositionChanges);
+      const revertReason = simResult.revertReason;
+      const simulation = {
+        success: !simResult.wouldRevert,
+        wouldRevert: simResult.wouldRevert,
+        ...revertReason !== void 0 ? { revertReason } : {},
+        chain: chainId,
+        simulatedAtBlock: forkedAtBlock,
+        gasEstimate: BigInt(simResult.gasUsed),
+        gasBufferApplied: 1,
+        coverageLevel: "deep",
+        caveats: ["state_may_diverge"],
+        provider: "tenderly",
+        trace: {
+          callTrace: simResult.rawTrace,
+          stateDiff: simResult.stateChanges,
+          logs: [],
+          gasUsed: simResult.gasUsed
+        }
+      };
+      stepResults.push({
+        stepId,
+        simulation,
+        stateChanges: simResult.stateChanges,
+        cumulativePosition: [...cumulativePosition],
+        wouldRevert: simResult.wouldRevert,
+        ...revertReason !== void 0 ? { revertReason } : {}
+      });
+      if (simResult.wouldRevert && step.optional !== true) {
+        wouldAllSucceed = false;
+        if (failingStepId === void 0) failingStepId = stepId;
+      }
+    }
+  } finally {
+    await deleteFork(tenderlyConfig, forkId);
+  }
+  return {
+    forkId,
+    chain: chainId,
+    forkedAtBlock,
+    steps: stepResults,
+    finalPosition: cumulativePosition.filter((p) => p.amount !== 0n),
+    wouldAllSucceed,
+    ...failingStepId !== void 0 ? { failingStepId } : {},
+    simulatedAt
+  };
+}
+
+// src/simulate.ts
+import { createPublicClient, http } from "viem";
+
+// src/tenderly.ts
+var TENDERLY_NETWORK_IDS = {
+  ethereum: "1",
+  arbitrum: "42161",
+  optimism: "10",
+  base: "8453"
+};
+var DEFAULT_GAS_BUFFER = 1.2;
+async function simulateWithTenderly(action, chainId, tenderlyConfig, options) {
+  const networkId = TENDERLY_NETWORK_IDS[chainId];
+  if (networkId === void 0) {
+    throw new Error(`Tenderly simulation not supported for chain: ${chainId}`);
+  }
+  let to;
+  let value = "0";
+  let input = "0x";
+  if (action.kind === "swap") {
+    to = action.via;
+  } else if (action.kind === "transfer") {
+    to = action.to;
+    value = action.token.amount.toString();
+  } else {
+    to = action.contract;
+    if (action.value !== void 0) value = action.value.amount.toString();
+    if (action.calldata !== void 0) input = action.calldata;
+  }
+  const stateObjects = {};
+  if (options?.stateOverrides !== void 0) {
+    for (const [addr, override] of Object.entries(options.stateOverrides)) {
+      stateObjects[addr] = {
+        ...override.balance !== void 0 ? { balance: "0x" + override.balance.toString(16) } : {},
+        ...override.nonce !== void 0 ? { nonce: override.nonce } : {}
+      };
+    }
+  }
+  const url = `https://api.tenderly.co/api/v1/account/${tenderlyConfig.accountSlug}/project/${tenderlyConfig.projectSlug}/simulate`;
+  const body = {
+    network_id: networkId,
+    from: "0x0000000000000000000000000000000000000001",
+    to,
+    input,
+    value,
+    save_if_fails: false,
+    simulation_type: "full"
+  };
+  if (Object.keys(stateObjects).length > 0) {
+    body["state_objects"] = stateObjects;
+  }
+  const failResult = (wouldRevert2 = false) => ({
+    success: false,
+    wouldRevert: wouldRevert2,
+    chain: chainId,
+    simulatedAtBlock: 0,
+    gasEstimate: 0n,
+    gasBufferApplied: 0,
+    coverageLevel: "none",
+    caveats: ["state_may_diverge"],
+    provider: "tenderly"
+  });
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Access-Key": tenderlyConfig.accessKey
+      },
+      body: JSON.stringify(body)
+    });
+  } catch {
+    return failResult();
+  }
+  if (!response.ok) {
+    return failResult();
+  }
+  const data = await response.json();
+  const sim = data.simulation;
+  const wouldRevert = !sim.status;
+  const gasEstimate = BigInt(Math.ceil(sim.gas_used * DEFAULT_GAS_BUFFER));
+  return {
+    success: !wouldRevert,
+    wouldRevert,
+    ...wouldRevert && sim.error_message !== void 0 ? { revertReason: sim.error_message } : {},
+    chain: chainId,
+    simulatedAtBlock: sim.block_number,
+    gasEstimate,
+    gasBufferApplied: DEFAULT_GAS_BUFFER,
+    coverageLevel: "deep",
+    caveats: [],
+    provider: "tenderly",
+    trace: {
+      callTrace: data.transaction?.call_trace ?? null,
+      stateDiff: data.transaction?.state_diff ?? null,
+      logs: data.transaction?.logs ?? [],
+      gasUsed: sim.gas_used
+    }
+  };
+}
+
+// src/simulate.ts
+var PLACEHOLDER_FROM = "0x0000000000000000000000000000000000000001";
+var DEFAULT_GAS_BUFFER2 = 1.2;
+async function simulateEvmAction(action, chainId, rpcUrl, options, tenderlyConfig) {
+  if (tenderlyConfig !== void 0) {
+    return simulateWithTenderly(action, chainId, tenderlyConfig, options);
+  }
+  const chain = getViemChain(chainId);
+  const client = createPublicClient({ chain, transport: http(rpcUrl) });
+  try {
+    let gasEstimate;
+    if (action.kind === "swap") {
+      gasEstimate = 200000n;
+    } else if (action.kind === "transfer") {
+      gasEstimate = await client.estimateGas({
+        account: PLACEHOLDER_FROM,
+        to: action.to,
+        value: action.token.amount
+      });
+    } else {
+      gasEstimate = await client.estimateGas({
+        account: PLACEHOLDER_FROM,
+        to: action.contract,
+        value: 0n
+      });
+    }
+    const blockNumber = await client.getBlockNumber();
+    const caveats = ["state_may_diverge"];
+    if (action.kind === "swap") {
+      caveats.push("proxy_implementation_unverified");
+    }
+    return {
+      success: true,
+      wouldRevert: false,
+      chain: chainId,
+      simulatedAtBlock: Number(blockNumber),
+      gasEstimate,
+      gasBufferApplied: DEFAULT_GAS_BUFFER2,
+      coverageLevel: "basic",
+      caveats,
+      provider: "eth_call"
+    };
+  } catch {
+    return {
+      success: false,
+      wouldRevert: false,
+      chain: chainId,
+      simulatedAtBlock: 0,
+      gasEstimate: 0n,
+      gasBufferApplied: 0,
+      coverageLevel: "none",
+      caveats: ["state_may_diverge"],
+      provider: "eth_call"
+    };
+  }
+}
+
+// src/build.ts
+import { getAddress } from "viem";
+async function buildEvmTransaction(action, chainId, rpcUrl, gasEstimate, gasBufferMultiplier, _fromAddress) {
+  const chain = getViemChain(chainId);
+  const gas = BigInt(Math.ceil(Number(gasEstimate) * gasBufferMultiplier));
+  let to;
+  let value;
+  let data;
+  if (action.kind === "swap") {
+    to = getAddress(action.via);
+    value = 0n;
+    data = action.calldata ?? "0x";
+  } else if (action.kind === "transfer") {
+    to = getAddress(action.to);
+    value = action.token.amount;
+    data = "0x";
+  } else {
+    to = getAddress(action.contract);
+    value = action.value?.amount ?? 0n;
+    data = action.calldata ?? "0x";
+  }
+  return { chain: chainId, to, value, data, gas, chainId: chain.id, rpcUrl };
+}
+
+// src/broadcast.ts
+import { createPublicClient as createPublicClient2, http as http2 } from "viem";
+
+// src/mev.ts
+function getMevProtectedRpcUrl(mode, config, fallbackRpcUrl) {
+  switch (mode) {
+    case "flashbots":
+      return config?.flashbots?.rpcUrl ?? "https://rpc.flashbots.net";
+    case "mev-blocker":
+      return config?.mevBlocker?.rpcUrl ?? "https://rpc.mevblocker.io";
+    case "none":
+    case void 0:
+    default:
+      return fallbackRpcUrl ?? "https://ethereum.publicnode.com";
+  }
+}
+function buildFlashbotsAuthHeader(_body, _authSignerKey) {
+  return void 0;
+}
+async function broadcastWithMevProtection(signedTxHex, mode, config, fallbackRpcUrl) {
+  const rpcUrl = getMevProtectedRpcUrl(mode, config, fallbackRpcUrl);
+  const body = JSON.stringify({
+    jsonrpc: "2.0",
+    method: "eth_sendRawTransaction",
+    params: [signedTxHex],
+    id: 1
+  });
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (mode === "flashbots" && config?.flashbots?.authSignerKey !== void 0) {
+    const authHeader = buildFlashbotsAuthHeader(body, config.flashbots.authSignerKey);
+    if (authHeader !== void 0) {
+      headers["X-Flashbots-Signature"] = authHeader;
+    }
+  }
+  const response = await fetch(rpcUrl, {
+    method: "POST",
+    headers,
+    body
+  });
+  if (!response.ok) {
+    throw new Error(
+      `MEV-protected broadcast failed: ${response.status} ${await response.text()}`
+    );
+  }
+  const data = await response.json();
+  if (data.error !== void 0) {
+    throw new Error(`MEV-protected broadcast error: ${data.error.message}`);
+  }
+  if (data.result === void 0) {
+    throw new Error("MEV-protected broadcast: no txHash in response");
+  }
+  return data.result;
+}
+
+// src/broadcast.ts
+async function broadcastAndConfirm(signedTx, action, chainId, rpcUrl, evaluation, simulation, mevProtection, mevConfig) {
+  const chain = getViemChain(chainId);
+  const publicClient = createPublicClient2({ chain, transport: http2(rpcUrl) });
+  let txHash;
+  if (mevProtection !== void 0 && mevProtection !== "none") {
+    const hash = await broadcastWithMevProtection(signedTx, mevProtection, mevConfig, rpcUrl);
+    txHash = hash;
+  } else {
+    txHash = await publicClient.sendRawTransaction({ serializedTransaction: signedTx });
+  }
+  const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
+  return {
+    status: "success",
+    action,
+    policyEvaluation: evaluation,
+    simulation,
+    txHash,
+    confirmedAtBlock: Number(receipt.blockNumber),
+    confirmedAtMs: Date.now(),
+    gasUsed: receipt.gasUsed
+  };
+}
+
+// src/execute.ts
+async function executeEvmAction(action, chainId, rpcUrl, signer, evaluation, simulation, mevProtection, mevConfig) {
+  const serializedTx = await buildEvmTransaction(
+    action,
+    chainId,
+    rpcUrl,
+    simulation.gasEstimate,
+    1.2,
+    signer.address
+  );
+  const signedTx = await signer.sign(serializedTx);
+  return broadcastAndConfirm(
+    signedTx,
+    action,
+    chainId,
+    rpcUrl,
+    evaluation,
+    simulation,
+    mevProtection,
+    mevConfig
+  );
+}
+
+// src/signers.ts
+import { createWalletClient, http as http3 } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+function privateKeySigner(privateKey) {
+  const account = privateKeyToAccount(privateKey);
+  return {
+    address: account.address,
+    sign: async (tx) => {
+      const chain = getViemChain(tx.chain);
+      const client = createWalletClient({
+        account,
+        chain,
+        transport: http3(tx.rpcUrl)
+      });
+      const request = await client.prepareTransactionRequest({
+        to: tx.to,
+        value: tx.value,
+        data: tx.data,
+        gas: tx.gas
+      });
+      const serialized = await client.signTransaction(request);
+      return serialized;
+    }
+  };
+}
+
+// src/verify.ts
+import { createPublicClient as createPublicClient3, http as http4, keccak256 } from "viem";
+function createEvmMetadataVerifier(rpcUrls) {
+  return {
+    async verifyContract(entry) {
+      const rpcUrl = rpcUrls[entry.chain];
+      if (rpcUrl === void 0) throw new Error("no rpcUrl for chain: " + entry.chain);
+      const chain = getViemChain(entry.chain);
+      const client = createPublicClient3({ chain, transport: http4(rpcUrl) });
+      if (entry.bytecodeHash !== void 0) {
+        const bytecode = await client.getBytecode({ address: entry.address });
+        if (bytecode === void 0 || bytecode === "0x") {
+          return { verified: false, reason: "bytecode_hash_mismatch" };
+        }
+        const hash = keccak256(bytecode);
+        if (hash !== entry.bytecodeHash) {
+          return { verified: false, reason: "bytecode_hash_mismatch" };
+        }
+      }
+      if (entry.ownerAddress !== void 0) {
+        try {
+          const result = await client.readContract({
+            address: entry.address,
+            abi: [{ name: "owner", type: "function", inputs: [], outputs: [{ type: "address" }], stateMutability: "view" }],
+            functionName: "owner"
+          });
+          if (result.toLowerCase() !== entry.ownerAddress.toLowerCase()) {
+            return { verified: false, reason: "owner_address_mismatch" };
+          }
+        } catch {
+        }
+      }
+      return { verified: true };
+    }
+  };
+}
+export {
+  broadcastWithMevProtection,
+  buildEvmTransaction,
+  buildForkTransactionParams,
+  createEvmMetadataVerifier,
+  createFork,
+  deleteFork,
+  executeEvmAction,
+  getMevProtectedRpcUrl,
+  getViemChain,
+  privateKeySigner,
+  simulateEvmAction,
+  simulateIntentOnFork,
+  simulateOnFork,
+  simulateWithTenderly
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@txfence/evm",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "viem": "^2.48.8",
+    "@txfence/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}