Ethereum transaction simulator leveraging Foundry's codebase

Overview

Enso Transaction ๐Ÿง Simulator ๐Ÿง

A simple API which simulates a given transaction request.

test

cover

๐Ÿ“ซ API ๐Ÿ“ซ

POST /api/v1/simulate

Simulates a single transaction against a local EVM.

See the full request and response types below.

Example body:

{
  "chainId": 1,
  "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "to": "0x66fc62c1748e45435b06cf8dd105b73e9855f93e",
  "data": "0xffa2ca3b44eea7c8e659973cbdf476546e9e6adfd1c580700537e52ba7124933a97904ea000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000001d0e30db00300ffffffffffffc02aaa39b223fe8d0a0e5c4f27ead9083c756cc200000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000186a0",
  "gasLimit": 500000,
  "value": "100000",
  "blockNumber": 16784600
}

Example response:

{
  "gasUsed": 214622,
  "blockNumber": 16784600,
  "success": true,
  "trace": { ... },
  "logs": [ ... ],
  "exitReason": "Return"
}

Notes:

  • blockNumber can be omitted and the latest block will be used, however providing a blockNumber is recommended where possible to use the cache.

POST /api/v1/simulate-bundle

Simulates a bundle of transactions in order against the same EVM.

See the full request and response types below.

Example body:

[
  {
    "chainId": 1,
    "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "to": "0x66fc62c1748e45435b06cf8dd105b73e9855f93e",
    "data": "0xffa2ca3b44eea7c8e659973cbdf476546e9e6adfd1c580700537e52ba7124933a97904ea000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000001d0e30db00300ffffffffffffc02aaa39b223fe8d0a0e5c4f27ead9083c756cc200000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000186a0",
    "gasLimit": 500000,
    "value": "100000",
    "blockNumber": 16784600
  }
]

Example response:

[{
  "gasUsed": 214622,
  "blockNumber": 16784600,
  "success": true,
  "trace": { ... },
  "logs": [ ... ],
  "exitReason": "Return"
}]

Notes:

  • chainId must be the same in all transactions.
  • blockNumber can be included and incremented when a multi-block simulation is required, or omitted in all transactions to use latest.

Authentication

If you set an API_KEY environment variable then all calls to the API must be accompanied by a X-API-KEY header which contains this API Key.

๐Ÿƒโ€โ™‚๏ธ Running ๐Ÿƒโ€โ™‚๏ธ

Locally

Copy .env.example to .env, fill out required values and run:

$ cargo run

If you want the server to restart on any code changes run:

$ cargo watch -x run

๐Ÿงช Test ๐Ÿงช

Run:

$ cargo test

Manual Testing

body.json contains a simple request in the root of the project so once the API is running you can just run:

$ curl -H "Content-Type: application/json" --data @tests/body.json http://localhost:8080/api/v1/simulate

If you have jq installed, you can run this to see pretty traces:

$ curl -H "Content-Type: application/json" --data @tests/body.json http://localhost:8080/api/v1/simulate | jq -r ".formattedTrace"

๐Ÿงญ Roadmap ๐Ÿงญ

  • Support any RPC endpoint, not just Alchemy
  • Connect to local node via IPC
  • Connect to local reth DB
  • Support simulating a bundle of transactions against different blocks, applying state as the simulation progresses. Would help support paradigmxyz/reth#2018
  • Support more authentication methods

Contributing

See CONTRIBUTING.md.

Types

export type SimulationRequest = {
  chainId: number;
  from: string;
  to: string;
  data?: string;
  gasLimit: number;
  value: string;
  blockNumber?: number; // if not specified, latest used,
  formatTrace?: boolean;
};

export type SimulationResponse = {
  simulationId: string;
  gasUsed: number;
  blockNumber: number;
  success: boolean;
  trace: CallTrace[];
  logs?: Log[];
  exitReason?: Reason;
  bytes: string;
  formattedTrace?: string;
};

export type Log = {
  topics: string[];
  data: string;
  address: string;
};

export type CallTrace = {
  callType: CallType;
  from: string;
  to: string;
  value: string;
};

export enum CallType {
  CALL,
  STATICCALL,
  CALLCODE,
  DELEGATECALL,
  CREATE,
  CREATE2,
}

export enum Reason {
  //success codes
  Continue,
  Stop,
  Return,
  SelfDestruct,

  // revert code
  Revert, // revert opcode
  CallTooDeep,
  OutOfFund,

  // error codes
  OutOfGas,
  OpcodeNotFound,
  CallNotAllowedInsideStatic,
  InvalidOpcode,
  InvalidJump,
  InvalidMemoryRange,
  NotActivated,
  StackUnderflow,
  StackOverflow,
  OutOfOffset,
  FatalExternalError,
  GasMaxFeeGreaterThanPriorityFee,
  PrevrandaoNotSet,
  GasPriceLessThenBasefee,
  CallerGasLimitMoreThenBlock,
  /// EIP-3607 Reject transactions from senders with deployed code
  RejectCallerWithCode,
  LackOfFundForGasLimit,
  CreateCollision,
  OverflowPayment,
  PrecompileError,
  NonceOverflow,
  /// Create init code exceeds limit (runtime).
  CreateContractLimit,
  /// Error on created contract that begins with EF
  CreateContractWithEF,
}

๐Ÿ™ Thanks ๐Ÿ™

You might also like...
DeFiChain octopus is a codename research & development for DFIP 2111-B: VOC: Ethereum Virtual Machine (EVM) Support.

DeFiCh/octopus DeFiChain octopus is a codename research & development for DFIP 2111-B: VOC: Ethereum Virtual Machine (EVM) Support . Proposed as a DFI

ECS-friendly ldtk plugin for bevy, leveraging bevy_ecs_tilemap
ECS-friendly ldtk plugin for bevy, leveraging bevy_ecs_tilemap

bevy_ecs_ldtk An ECS-friendly ldtk plugin for bevy. Uses bevy_ecs_tilemap as a base. Not released yet, still in development. bevy_ecs_tilemap once sup

Tools to use Axon Server with rust, by leveraging Synapse.

Axon Rust This contains a Axon Synapse rust client, based on the open api generated code. For now, we didn't publish this crate, to forking this proje

Schemars is a high-performance Python serialization library, leveraging Rust and PyO3 for efficient handling of complex objects

Schemars Introduction Schemars is a Python package, written in Rust and leveraging PyO3, designed for efficient and flexible serialization of Python c

Substreams development kit for Ethereum chains, contains Firehose Block model and helpers as well as utilities for Ethereum ABI encoding/decoding.

Substreams Ethereum Substreams development kit for Ethereum chains, contains Rust Firehose Block model and helpers as well as utilities for Ethereum A

Ethereum (and Ethereum like) indexer using P2P message to fetch blocks and transactions

Ethereum P2P indexer This project is an indexer for Ethereum and Ethereum forks. It takes advantage of the ETH (Ethereum Wire Protocol) to fetch block

Find the ideal fuzz targets in a Rust codebase

Siderophile Siderophile finds the "most unsafe" functions in your Rust codebase, so you can fuzz them or refactor them out entirely. It checks the cal

An ultra-fast CLI app that fixes JSON files in large codebase or folders

minosse An ultra fast CLI app that fixes json files in large codebase or folders USAGE: minosse [OPTIONS] input-dir FLAGS: -h, --help Prints

Find the ideal fuzz targets in a Rust codebase

Siderophile Siderophile finds the "most unsafe" functions in your Rust codebase, so you can fuzz them or refactor them out entirely. It checks the cal

Codemod - Codemod is a tool/library to assist you with large-scale codebase refactors that can be partially automated but still require human oversight and occasional intervention

Codemod - Codemod is a tool/library to assist you with large-scale codebase refactors that can be partially automated but still require human oversight and occasional intervention. Codemod was developed at Facebook and released as open source.

Format codebase in documentation ๐Ÿฆค

Gelatyx Format codebase in documentation ๐Ÿฆค Features Format language code block inside documentation files Check mode. Ask Gelatyx is the documentatio

Local-first high performance codebase index engine designed for AI

CodeIndex CodeIndex is a local-first high performance codebase index engine designed for AI. It helps your LLM understand the structure and semantics

Sensorial System's Stable Diffusion codebase
Sensorial System's Stable Diffusion codebase

Stable Diffusion XL LoRA Trainer Welcome to the official codebase for the Sensorial System's Stable Diffusion projects. For now, this only hosts the c

Transparency for Mining Pool Transaction Selection

miningpool-observer Transparency for Mining Pool Transaction Selection The miningpool-observer project compares block templates produced by a Bitcoin

Zei is a library that provide tools to create and verify public transaction with confidential data.
Zei is a library that provide tools to create and verify public transaction with confidential data.

#Zei: Findora's Cryptographic Library Zei is a library that provide tools to create and verify public transaction with confidential data. Support: Bas

Open Internet Service to store transaction history for NFTs/Tokens on the Internet Computer
Open Internet Service to store transaction history for NFTs/Tokens on the Internet Computer

CAP - Certified Asset Provenance Transaction history & asset provenance for NFTโ€™s & Tokens on the Internet Computer CAP is an open internet service pr

This code generate coinjoin transaction whici has two inputs and two outputs

How to create coinjoin transaction This code generate coinjoin transaction whici has two inputs and two outputs. First, we create two trasactions. The

TSS of GG18 by WASM, for Confidential Transaction Generation and Signing

TSS WASM portable lightweight client application for threshold ECDSA (based on GG18), built on&for multi-party-ecdsa : Wasm HW friendly Dev yarn build

Uses the cardano mini-protocols to receive every block and transaction, and save them to a configurable destination

cardano-slurp Connects to one or more cardano-node's, streams all available transactions, and saves them to disk (or to S3) in raw cbor format. Usage

Owner
null
An ultra-fast CLI app that fixes JSON files in large codebase or folders

minosse An ultra fast CLI app that fixes json files in large codebase or folders USAGE: minosse [OPTIONS] <input-dir> FLAGS: -h, --help Prints

Antonino Bertulla 5 Oct 17, 2022
Codemod - Codemod is a tool/library to assist you with large-scale codebase refactors that can be partially automated but still require human oversight and occasional intervention

Codemod - Codemod is a tool/library to assist you with large-scale codebase refactors that can be partially automated but still require human oversight and occasional intervention. Codemod was developed at Facebook and released as open source.

Meta Archive 4k Dec 29, 2022
Format codebase in documentation ๐Ÿฆค

Gelatyx Format codebase in documentation ?? Features Format language code block inside documentation files Check mode. Ask Gelatyx is the documentatio

azzamsa 3 Oct 24, 2022
Local-first high performance codebase index engine designed for AI

CodeIndex CodeIndex is a local-first high performance codebase index engine designed for AI. It helps your LLM understand the structure and semantics

Jipiti AI 9 Aug 30, 2023
Sensorial System's Stable Diffusion codebase

Stable Diffusion XL LoRA Trainer Welcome to the official codebase for the Sensorial System's Stable Diffusion projects. For now, this only hosts the c

null 8 Mar 2, 2024
Uses the cardano mini-protocols to receive every block and transaction, and save them to a configurable destination

cardano-slurp Connects to one or more cardano-node's, streams all available transactions, and saves them to disk (or to S3) in raw cbor format. Usage

Pi Lanningham 16 Jan 31, 2023
Simulator for Analogue's CHIP32 VM on Analogue Pocket

Simulator for Analogue's CHIP32 VM This is a simulator for Analogue's CHIP32 virtual 32-bit CPU used as a data preprocessor for openFPGA. It allows yo

Adam Gastineau 6 Nov 14, 2022
A simulator for Street Fighter 6 battle data.

sf6_sim A simulator for Street Fighter 6 battle data. Very early in development. It can currently simulate boxes, cancel lists, and movement. Online v

null 4 Jun 18, 2023
A 2D Rust-Based Finite Element Simulator

Magnetite A 2D linear-elastic FEA program for isotropic materials, built in Rust. Overview Magnetite is a simple linear-elastic mechanical solver for

Kyle Tennison 3 Apr 9, 2024
Structopt derived ethers-rs types, useful for building Ethereum CLIs

ethers-structopt Provides ethers-compatible Structopt derives, useful for building Ethereum CLIs. Contributing Pull requests are welcome. For major ch

Georgios Konstantopoulos 6 Dec 27, 2022