HEXKIT

A local-first EVM developer toolkit for decoding, simulating, debugging smart contract transactions, and managing DeFi yield.

Live app · How every PR is tested

Overview

HexKit is a browser-based web3 developer toolkit built for inspecting, simulating, and debugging EVM transactions, with an integrated DeFi yield management layer. All heavy compute -- REVM replay, instrumentation, and trace decoding -- runs locally, keeping your data private and your workflow fast.

The application pairs a React frontend with a local Rust-powered EDB (EVM Debugger) engine that provides full transaction replay, step-through debugging, and storage introspection without relying on third-party simulation services. The integrations layer connects to external DeFi protocols (starting with LI.FI) for cross-chain yield discovery, deposit execution, and portfolio management.

Tech Stack

Layer	Technologies
Frontend	React 19, TypeScript, Vite 5
Styling	Tailwind CSS v4, shadcn/ui
Web3	ethers v5, viem, wagmi, RainbowKit
Simulation	REVM (Rust), EDB engine, WebSocket bridge
Integrations	LI.FI SDK (Earn API, Composer), Gemini LLM
API Proxies	Vercel Serverless Functions
Testing	Vitest, Testing Library

Features

Smart Decoder

Paste raw calldata and HexKit resolves the selector against the OpenChain signature database and decodes the parameters. An args-only mode decodes ABI-encoded blobs with no selector. Supports custom ABI input for decoding private or unregistered functions; a local signature cache lets previously resolved selectors decode offline. (To decode an on-chain transaction by hash, use Transaction Replay.)

Signature Database

Look up function selectors (4-byte) and event topics by name or hex signature. Manage custom signatures and browse the local cache.

Transaction Builder

Two operating modes:

Live Interaction -- Connect a wallet via RainbowKit, then read and write contract functions on any EVM chain directly from the browser. Payable functions take a Value field, as decimal ETH or hex wei.
Simulation (EDB) -- Build transactions and simulate them through the local EDB engine. Get full REVM replay with execution traces, state changes, event logs, and gas analysis without spending gas or requiring a wallet.

Source Tools

Contract Explorer -- Browse verified contract source code fetched from Sourcify, Etherscan, and Blockscout.
Contract Diff -- Side-by-side runtime-bytecode comparison between two contracts on the same or different chains, with optional Solidity metadata stripping.
Storage Layout Viewer -- AST-based storage slot reconstruction with live value reading from on-chain state.

Simulation Results

A full simulation analysis page with six tabs:

Summary -- Gas usage, value transferred, and execution status.
Events -- Decoded event logs with token movement visualization.
State Changes -- Storage diff with named slots when source is available.
Execution Trace -- Step-through call tree with source mapping.
Contracts -- All contracts involved in the transaction with verification status.
Debug -- Step-through Solidity debugger with breakpoints, snapshots, and an expression evaluator.

Simulation History

Browse past simulations stored in IndexedDB. Re-open any previous result for review or further debugging.

Integrations

The /integrations route hosts protocol-specific modules that extend HexKit beyond debugging into active DeFi operations.

LI.FI Earn

A full yield management layer powered by the LI.FI Earn API:

Vault Browser -- Browse, search, and filter yield vaults across 20+ protocols and all supported EVM chains. Each vault shows live APY, TVL, underlying tokens, and protocol metadata.
My Positions -- View open earn positions for any connected wallet or arbitrary address. Shows per-position PnL and portfolio summary.
Deposit / Withdraw Flows -- Deposit into and withdraw from vaults directly through LI.FI's Composer API, which handles cross-chain swaps and bridging automatically.
Vault Simulator -- Forecast projected returns for any vault over a configurable time horizon before committing capital.

Yield Concierge (AI-powered)

An AI assistant that translates natural language yield goals into actionable vault recommendations:

Intent Parser -- Gemini LLM converts free-text prompts ("safest USDC vault above 5% on Arbitrum") into structured filters (token, chain, APY range, objective, protocol allow/deny lists).
My Assets Mode -- Say "best vaults for my assets" and the concierge fans out per-asset recommendations for every idle token in the connected wallet.
Consolidate Mode -- Say "best vault for my assets" (singular) and the concierge finds the top vault candidates to funnel all holdings into a single position via cross-chain swaps.
Idle Sweep -- Detects wallet tokens sitting idle (not earning yield) and suggests the best vault for each, with one-click deposit.
Execution Pipeline -- A sequential deposit queue that processes multiple deposits one after another, handling quoting, approval, execution, and cross-chain bridge status polling for each leg.
Model Fallback -- The LLM proxy tries gemini-3.1-pro-preview first and auto-falls back to gemini-2.5-flash on rate limits, keeping recommendations available without interruption.

Contract Resolution

HexKit resolves contract ABIs and source code through parallel multi-source lookup:

Sourcify (full match and partial match)
Etherscan (and compatible explorers)
Blockscout
WhatsABI decompilation fallback for unverified contracts

Additional capabilities:

Diamond proxy (EIP-2535) facet resolution with automatic loupe calls
Two-tier caching: L1 (in-memory LRU) and L2 (IndexedDB with 24-hour TTL)

Debug Sessions

Full Solidity step-through debugger powered by the local EDB engine:

Source-level breakpoints tied to Solidity source maps
Expression evaluator with a three-tier resolution chain: locals, storage-layout decode, and ABI getter fallback
Dual-layer snapshot system (opcode snapshots and hook snapshots)
Keep-alive sessions via the EDB bridge for long-running investigations

Testing with TestSprite

Nobody has to remember to run the tests. TestSprite runs them at three points:

When	What runs	Against	What happens on failure
Every pull request	20 browser tests	The PR's Vercel preview	The `TestSprite V3` check fails. It is required on `master`, so the PR cannot merge
Every merge to `master`	20 browser tests + 20 API tests	Production, https://hexkit.app	The run fails in the TestSprite portal
Every night, 12:00 AM PT	8 core browser flows (decode, replay, bad-hash message, explorer, signatures, LI.FI vaults)	Production	The run fails, and the result is emailed
Every night, 07:30 UTC	20 API tests, from GitHub Actions with the TestSprite CLI	Production	The workflow run fails. Its summary lists every test, and a JUnit report is attached

The PR and merge runs start from Vercel's own deployment events, through the TestSprite GitHub App. The API suite runs after merges, not on PRs. TestSprite's API tests carry their target URL in their own code, so on a PR they would test production rather than the preview, and their status would overwrite the browser suite's TestSprite V3 check. The nightly runs catch what no pull request changes: a public RPC or an upstream API changing under the app. The API suite's nightly results are public, in this repository's Actions tab.

Both suites were generated in the TestSprite portal, from a short product scope and an OpenAPI description, then tightened by hand. The browser tests assert exact values from one real mainnet USDC transfer, which lives in the production environment's variables.

Browser suite (20)

Area	Tests	What they check
Calldata decoding	2	Decoding from the home search and from the decoder shows `transfer(address,uint256)`, the recipient and the amount `2000000000`
Transaction replay	4	A mainnet transfer replays to Success with USDC −2,000 / +2,000; the result tabs open; it reopens from history; a malformed hash explains itself
Signature database	3	Selector → signature, event topic → signature, signature → selector
Contract explorer	2	Verified source for the USDC proxy, with compiler and proxy details
LI.FI Earn	3	Filtering vaults by chain and asset, vault details, positions for any address
Local storage	3	Storage inventory, simulation history surviving a reload, clearing history
Navigation	3	Source Tools and Integrations from home, Contract Explorer from the command palette

API suite (20)

Area	Tests	What they check
Simulator bridge	4	Health returns `status: ok` with its concurrency limits, with and without a same-origin request; PUT is refused with 405; CORS never grants a wildcard origin
Path guard	4	Encoded traversal, double-encoded traversal and illegal characters return 400 `invalid_path`; an unknown safe path returns 404
LI.FI Earn proxy	8	Chains, vaults (with chain filter and limit), protocols and positions return the expected shapes; a bad address returns 400; POST returns 405; CORS never grants a wildcard origin
Sourcify proxy	4	USDC's source on Ethereum is a runtime `match`; a short address and an unknown chain return 400; same-origin lookups work

Not covered: anything that needs a wallet signature (deposits, withdrawals, Live Interaction writes), the AI recommendation features, and the step debugger.

Keep branch names to 19 characters or fewer. Vercel shortens longer branch names in preview URLs with a hash, and the check then cannot find the preview.

What the suite caught on its first runs, fixed in #41:

Decode Calldata from search never decoded. It opened the 4-byte selector lookup with the whole calldata pasted in.
A malformed replay hash failed silently. Run Replay turned grey with no explanation.
Replays of transactions older than about 25 minutes failed on default settings. The default Ethereum RPC keeps no historical state, and the error wrongly said "Failed to connect to the RPC node". The default is now an archive-capable public RPC, and archive refusals show the historical-data message.

Later runs caught two more, both from public RPCs refusing requests under load:

Simulations failed when the default RPC rate-limited (#43). On the public default, a rate-limited simulation now retries on the next archive-capable public RPC.
The transaction lookup before a replay could hang for 30 seconds (#45). A rate-limit reply asking the app to retry later made it wait until its timeout fired. On the public default, a refused or stalled call now moves to the next public RPC at once.

Architecture

HexKit follows a local-first architecture. The frontend communicates with a local EDB simulator bridge over WebSocket, which in turn drives the Rust-based REVM engine.

Browser (React)  <-->  Simulator Bridge (:5789)  <-->  EDB Engine (Rust/REVM)

Visual architecture diagrams are available in the schematics/ folder:

Diagram	Description
`schematics/hexkit-app-architecture.excalidraw`	Frontend application layers, routes, and data flow
`schematics/edb-system-topology.excalidraw`	End-to-end system architecture (Frontend, Bridge, Rust Engine, REVM)
`schematics/edb-engine-internals.excalidraw`	EDB engine 8-step workflow and dual snapshot system

Getting Started

Prerequisites

Node.js 18+
npm
Rust toolchain (for building the EDB simulator)

Quick Start

The start script handles everything:

./start-dev.sh

It performs the following steps:

Checks for the edb-simulator binary (auto-builds via cargo build -p edb-simulator --release if missing)
Starts the EDB simulator bridge on port 5789
Starts the Vite dev server on port 5173

Manual Start

# Terminal 1: EDB bridge
npm run simulator:server

# Terminal 2: Frontend
npm run dev

Environment

The app works out of the box with public RPC endpoints. For better reliability, configure an Alchemy API key, Infura project ID, or a custom RPC URL through the RPC Settings modal (gear icon in the top bar).

For the LI.FI Earn integration and AI concierge, set the following in .env:

Variable	Purpose
`LIFI_API_KEY`	LI.FI API key for Earn and Composer endpoints
`GEMINI_API_KEY`	Google AI Studio API key for the yield concierge LLM
`GEMINI_MODEL`	Primary Gemini model (default: `gemini-3.1-pro-preview`)
`GEMINI_FALLBACK_MODEL`	Fallback on 429/503 (default: `gemini-2.5-flash`)
`PROXY_SECRET`	Shared secret for API proxy authentication (production)
`ALLOWED_ORIGINS`	Comma-separated allowed CORS origins (production)

Project Structure

src/
  components/
    simple-grid/             Transaction builder grid layout
    smart-decoder/           Calldata decoder module
    simulation-results/      Results page sub-modules
    explorer/                Source tools (explorer, diff, storage layout)
    execution-trace/         Trace viewer components
    debug/                   Debug window and panels
    integrations/
      IntegrationsHub.tsx    Integration router
      lifi-earn/
        LifiEarnPage.tsx     Main earn page (positions, vaults tabs)
        VaultList.tsx        Vault browser with filters
        VaultDrawer.tsx      Vault detail sheet
        DepositFlow.tsx      Deposit transaction flow
        WithdrawFlow.tsx     Withdraw transaction flow
        earnApi.ts           LI.FI Earn API client
        concierge/
          ConciergePanel.tsx       Yield concierge tabs (idle sweep + intent)
          IdleSweepPanel.tsx       Idle asset detection and recommendations
          VaultRecommendations.tsx  Recommendation card grid
          ExecutionQueue.tsx       Sequential deposit pipeline UI
          executionMachine.ts      Reducer-based execution state machine
          intent/
            IntentPanel.tsx        AI intent UI (prompt, chips, results)
            schema.ts              ParsedIntent zod schema
            hooks/
              useIntentParser.ts        LLM prompt → structured intent
              useVaultsByIntent.ts      Filter + rank vaults by intent
              useIntentRecommendation.ts  LLM-powered vault picks
    shared/                  Reusable components
    icons/                   Icon library
    ui/                      shadcn/ui primitives
  contexts/                  React contexts (state management)
  hooks/                     Custom hooks
  services/                  Service layer (bridge, history, vault)
  utils/
    resolver/                Contract resolution engine
    traceDecoder/            Trace decoding pipeline
    transaction-simulation/  Simulation logic
    solidity-layout/         Storage layout reconstruction
    fetchers/                API fetchers (Sourcify, Etherscan, Blockscout)
    cache/                   Caching utilities
  workers/                   Web Workers (trace decoder)
  types/                     TypeScript types
  styles/                    CSS modules
  config/                    App configuration
  lib/                       Shared libraries

api/
  llm-recommend.ts           Gemini LLM proxy with model fallback
  lifi-composer.ts           LI.FI Composer quote/execute proxy
  edb/                       EDB simulation API routes

edb/
  crates/engine/             Core debug engine
  crates/edb-simulator/      CLI simulator binary
  crates/rpc-proxy/          Intelligent RPC proxy

scripts/                     Dev scripts (bridge, perf tests)
schematics/                  Architecture documentation

Scripts

Script	Purpose
`npm run dev`	Start Vite dev server
`npm run build`	TypeScript check + production build
`npm run simulator:server`	Start EDB simulator bridge
`npm run test`	Run Vitest
`npm run qa:live:matrix`	Live QA test matrix
`npm run perf:debug-matrix`	Debug performance stress test

Documentation

Architecture docs live in schematics/:

Document	Purpose
`SYSTEM_SCHEMATIC.md`	High-level architecture and task-to-area index
`DATAFLOWS.md`	End-to-end data flow diagrams
`GRANULAR-COMPONENTS.md`	Component-level documentation
`LEGEND.md`	Doc routing guide

Giveth

https://giveth.io/project/hexkit

Name		Name	Last commit message	Last commit date
.codegraph		.codegraph
.github/workflows		.github/workflows
api		api
edb		edb
public		public
schematics		schematics
scripts		scripts
src		src
.codex		.codex
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
components.json		components.json
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

HEXKIT

Overview

Tech Stack

Features

Smart Decoder

Signature Database

Transaction Builder

Source Tools

Simulation Results

Simulation History

Integrations

LI.FI Earn

Yield Concierge (AI-powered)

Contract Resolution

Debug Sessions

Testing with TestSprite

Architecture

Getting Started

Prerequisites

Quick Start

Manual Start

Environment

Project Structure

Scripts

Documentation

Giveth

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

HEXKIT

Overview

Tech Stack

Features

Smart Decoder

Signature Database

Transaction Builder

Source Tools

Simulation Results

Simulation History

Integrations

LI.FI Earn

Yield Concierge (AI-powered)

Contract Resolution

Debug Sessions

Testing with TestSprite

Architecture

Getting Started

Prerequisites

Quick Start

Manual Start

Environment

Project Structure

Scripts

Documentation

Giveth

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages