Foundry Tx Simulator

Local transaction simulation and visualization tooling. The backend runs either a Foundry test harness or cast-kyber run and returns execution trace, fund-flow, and balance-analysis data; the frontend provides the local UI.

Quick Start

Install Go:

brew install go

Install Node/Yarn with Volta:

curl https://get.volta.sh | bash
volta install node yarn

Install the pinned Kyber Foundry fork:

scripts/install-foundry-kyber.sh

The installer downloads the thepluck/foundry release nightly-04bdb43d9435cecec89abc17b3dcb618086c0d99, verifies the release checksum, and installs forge-kyber, cast-kyber, anvil-kyber, and chisel-kyber into ~/.foundry/bin by default. Make sure that directory is on your PATH, then check:

forge-kyber --version

Create local config files from examples:

cp .env.example .env
cp config.example.yml config.yml

Fill in RPC URLs in .env, then start both servers:

./dev.sh

Local Run

Run the backend and frontend together:

./dev.sh

After a run finishes, the UI shows its request ID. Paste that ID into the Request ID field later, or open a URL with ?requestId=<id>, to reload the saved request and previous output from the backend record database.

Set local ports in config.yml; ./dev.sh reads that file and points the frontend at the configured backend address.

Run the backend directly:

cd backend
go run ./cmd/server

Run the frontend directly:

cd frontend
yarn install
yarn dev

When run directly, the local frontend defaults to http://127.0.0.1:8080 for the backend API.

Configuration

App settings are read from YAML config. config.yml is the local config, and config.example.yml is the template for new configs. ./dev.sh uses config.yml by default; direct backend runs from backend/ find ../config.yml automatically.

listen_addr: "127.0.0.1:8080"
frontend_port: 5173
work_dir: "backend/.runs"
default_project_root: "backend/.runs/default-project"
forge_bin: "forge-kyber"
cast_bin: "cast-kyber"
anvil_bin: "anvil-kyber"
anvil_port_start: 18545
rpc_urls:
  mainnet: "${MAINNET_RPC_URL}"

Set TXSIM_CONFIG only when you want to use a different YAML file:

cd backend
TXSIM_CONFIG=/path/to/config.yml go run ./cmd/server

The backend loads .env from the repo root and backend/.env. YAML config fields only use environment values when the YAML explicitly references them with ${...}. For example, MAINNET_RPC_URL is applied because config.yml uses ${MAINNET_RPC_URL} under rpc_urls; a plain MAINNET_RPC_URL environment variable does not override a literal YAML URL.

Use .env.example as the template for .env. Put secrets and machine-specific values in .env:

MAINNET_RPC_URL=https://mainnet.example
BASE_RPC_URL=https://base.example
ARBITRUM_RPC_URL=https://arbitrum.example
ETHERSCAN_API_KEY=...
COINGECKO_API_KEY=...

Then reference them from YAML:

etherscan_api_key: "${ETHERSCAN_API_KEY}"
rpc_urls:
  mainnet: "${MAINNET_RPC_URL}"

Use YAML fields such as listen_addr, frontend_port, work_dir, default_project_root, max_concurrent_runs, anvil_port_start, rpc_urls, explorer_urls, and etherscan_api_key for backend and ./dev.sh settings. Runtime-only environment variables such as COINGECKO_API_KEY are still read directly by the code that needs them. TXSIM_API_URL is still available when running the frontend directly and the browser should call a specific backend URL.

Keep local forge_bin set to forge-kyber, cast_bin set to cast-kyber, and anvil_bin set to anvil-kyber. Set request field decodeInternal to true when you want the runner to add --decode-internal; the default is false.

For local deployment without Docker:

(cd backend && go run ./cmd/server)
(cd frontend && TXSIM_API_URL=http://127.0.0.1:8080 yarn dev)

Local deployment stores saved simulation records in backend/.runs/records.sqlite, recently used Foundry project paths in backend/.runs/projects.json, and the default Foundry project in backend/.runs/default-project by default.

Docker Run

Docker is optional and does not replace local deployment.

docker compose up --build

Then open:

• Frontend: http://127.0.0.1:5173
• Backend: http://127.0.0.1:8080
• Swagger UI: http://127.0.0.1:8080/docs

Docker stores recently used Foundry project paths in the backend-runs volume at /data/runs/projects.json, so project suggestions survive container rebuilds. The default Foundry project lives in the separate default-project volume at /data/default-project. The backend image installs the pinned Kyber Foundry release and runs as linux/amd64, matching the release's published Linux archive.

Override Docker host ports through .env or shell variables:

TXSIM_BACKEND_PORT=18080 TXSIM_FRONTEND_PORT=15173 docker compose up --build

The frontend container uses TXSIM_BACKEND_PORT to generate its browser runtime config, so the default API URL follows the published backend port. Set TXSIM_API_URL if the browser should call a different backend URL.

Inside Docker, Add Source writes Solidity files into the default project's src/ folder. The backend initializes that project with forge init on first use. The native folder picker is only available when the backend runs locally on macOS.

Release

Create and push a version tag from master to run the release workflow:

git checkout master
git pull --ff-only origin master
git tag v0.1.0
git push origin v0.1.0

The workflow checks the existing CI status on the tagged merge commit before publishing release artifacts. It uploads backend server archives for Linux and macOS, a frontend dist archive, and SHA256SUMS.

Use the manual Release workflow dispatch only when re-running release creation for an existing v* tag after deleting the existing GitHub release for that tag.

Foundry Contracts

The local simulation test harness and its Foundry project live in contracts/.

Build

$ cd contracts
$ forge-kyber build

Test

$ cd contracts
$ forge-kyber test

Format

$ cd contracts
$ forge-kyber fmt

You can also run from the repo root by passing --root contracts:

$ forge-kyber build --root contracts
$ forge-kyber test --root contracts