Architecture

System overview

How ArbiSim Guard is built — four layers from the user's agent down to the forked blockchain. Each layer has a clear responsibility and a hard boundary.

High-level architecturehld.png

Low-level detaillld.png

Client

HTTPS / MCP stdio

Where the user or their AI agent sends transaction plans to be checked.

Next.js dashboard (Vercel)Agent frameworks (Vibekit, Eliza, LangGraph)Claude Desktop / Cursor via MCP

Edge (Cloudflare Worker)

HTTP → Queue

The first line of defense. Validates the API key, checks rate limits, and forwards valid requests to the application layer. Runs globally with sub-10ms overhead.

Hono routerAPI key validationRate limit enforcement (KV store)Request queuing

Application (Node.js Gateway)

Postgres queue

The coordination layer. Accepts simulation requests, writes them to the queue, and returns results when the worker completes.

REST API server (Express + TypeScript)MCP server (stdio or Streamable HTTP)Job queue managementResult polling

Data / Worker (Python)

JSON-RPC (Anvil)

The actual simulation happens here. A persistent Anvil process forks the chain, executes the transaction, and the analytical engine parses the result into a structured safety report.

Simulation engine (Anvil fork management)EVM state snapshottingAnalytical brain (gas, slippage, MEV detection)Chainlink oracle integration

Key design decisions

Persistent Anvil processes

Instead of spawning a new fork for every simulation, ArbiSim keeps a live Anvil process per chain. Each simulation takes a snapshot, runs, then reverts to the snapshot. This reduces latency from ~4 seconds to under 100ms.

Cloudflare Workers at the edge

API key validation and rate limiting happen at the edge before any request reaches the origin. This means abuse and invalid requests never consume application resources.

Neon Postgres as the queue

Using SELECT FOR UPDATE SKIP LOCKED as a work queue removes the need for a separate message broker (Redis, SQS). Keeps the stack small and deployable on free tiers.

Separate Python worker

The simulation engine runs in Python (web3.py + subprocess Anvil). Python was chosen for its mature EVM tooling ecosystem. The Gateway (Node.js) communicates with it via the shared database.

External dependencies

Foundry AnvilLocal EVM fork engine

Neon PostgresJob queue + API key store

MongoDB AtlasTelemetry (append-only)

Cloudflare KVRate limit mirror

ChainlinkAVAX/ETH price oracles

VercelFrontend hosting

← Frameworks Request lifecycle →