KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

web3-decoder

★ 115 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Web3 Decoder

Web3 Decoder is a Burp Suite Extension that helps to analyze what is going on
with the operations involving smart contracts of the web3. This is mainly JSON-RPC calls to Ethereum Nodes,
and nodes of other compatible networks (like Polygon, Arbitrum, BSC...)

## Download & Install

Download the latest extension JAR — this link always serves the newest release:

**[⬇ web3-decoder.jar (latest)](https://github.com/nccgroup/web3-decoder/releases/latest/download/web3-decoder.jar)**

Older versions are on the [Releases page](https://github.com/nccgroup/web3-decoder/releases).

Then load it in Burp Suite:

1. Go to **Extensions → Installed → Add**.
2. Set *Extension type* to **Java** and select the downloaded `web3-decoder.jar`.
3. Click **Next** — the `Web3` tab and the `Web3 Request`/`Web3 Response` editor
   tabs appear once it loads.

> Requires a Burp release bundled with JRE 21 (current Burp Suite versions). The
> JAR is self-contained — all dependencies (web3j, etc.) are included.

### Building from source

```bash
./gradlew jar
```

The extension JAR is always written to a constant path — `web3-decoder/build/libs/web3-decoder.jar` —
regardless of version, so you can point Burp at it once and let it auto-reload on
rebuilds. Releasing is documented in [`docs/RELEASING.md`](docs/RELEASING.md).

## Screenshots

This is how our improved Web3 editor tabs look after successfully decoding your JSON-RPC requests and responses:

![Web3 decoded requests and responses](https://raw.githubusercontent.com/nccgroup/web3-decoder/main/docs/screenshots/web3_editor.png)

Below the redesigned Web3 Tab, with all the settings, detected ABIs, and more! (Thanks Claude Design!)

![Web3 Tab](https://raw.githubusercontent.com/nccgroup/web3-decoder/main/docs/screenshots/web3_tab.png)

## Documentation

Detailed documentation lives in the [`docs/`](docs/) folder:

- [Architecture](docs/ARCHITECTURE.md) — layers, components, and the key decode/encode flows (with diagrams).
- [Project Structure](docs/PROJECT_STRUCTURE.md) — directory layout and package-by-package responsibilities.
- [Tech Stack](docs/TECH_STACK.md) — dependencies, build/packaging, runtime, and CLI mode.
- [Features](docs/FEATURES.md) — full capability catalogue with implementation pointers.

## Block explorers API Keys

Most block explorers supported, like [etherscan.io](https://etherscan.io) require an API key to allow more than 1 request each 5 seconds.

The new interface allows you to manage the chains, block explorers and API keys

## Manually adding a contract's ABI

The extension caches the downloaded ABIs from the block explorers like etherscan. You can also add them directly from the Web3 tab, obtaining them automatically from the block explorer, or adding them manually.

## Implemented Features

- Burp integration
  - `Web3 Request` editor tab for JSON-RPC requests (hidden on traffic with no `eth_call` / `eth_sendRawTransaction`).
  - `Web3 Response` editor tab for matching JSON-RPC responses.
  - Dedicated `Web3` suite tab with chain/ABI/calldata tools.
  - Proxy history rows annotated with the decoded function signature in their note (decoded off-thread, persisted on the live history row).
- Decoded editor experience
  - Both editor tabs ship a structured tree view by default, with a JSON view a toggle away — the JSON remains the source of truth for re-encoding.
  - JSON view keeps syntax + semantic highlighting, line numbers, bracket matching, live validity, and a search bar.
- JSON-RPC request decoding
  - Decodes `eth_call` calldata into `function` + typed `args`.
  - Supports single-request and batch JSON-RPC payloads.
  - For batch payloads, each item is reported with status (`decoded`, `skipped`, `error`) and reason when skipped/failed.
- JSON-RPC response decoding
  - Decodes `result` for previously decoded `eth_call` requests.
  - Supports single and batch responses, matching entries by JSON-RPC `id` (or by index fallback).
- Re-encoding and edit workflow
  - You can edit decoded arguments in the request editor and write them back to encoded calldata.
  - Standalone calldata tool can decode and re-encode outside request history.
- ABI resolution and caching
  - ABI lookup priority: cached ABI → builtin → block explorer (Etherscan-compatible) → passively-detected pool → 4byte.
  - Downloaded ABIs are cached automatically for future decodes.
  - ABI source is tracked (`cache`, `builtin`, `etherscan`, `detected`, or `4byte`) in decoded output.
- Passive ABI detection (new)
  - A Burp `PassiveScanCheck` scans HTTP response bodies (typically minified dapp JS bundles) for Solidity ABIs
    and stores everything it finds in a project-scoped pool indexed by function selector.
  - Handles both strict JSON and the JS-object-literal form found in minified bundles, including the
    `!0` / `!1` boolean shortcuts emitted by Terser/esbuild/Svelte.
  - When the existing cache → builtin → etherscan chain misses, the decoder consults the detected pool before
    falling through to 4byte. Decoded output is tagged `decodeSource: "detected"`.
  - Works even when `eth_chainId` can't be determined: the detected pool and 4byte are chain-agnostic, so the
    decoder still attempts them rather than refusing outright.
  - Each new ABI raises an informational Burp issue ("Solidity contract ABI detected") with the full method
    list — every function/event/error with its canonical signature and 4-byte selector — and the URL where
    the ABI was found.
- 4byte fallback decoding
  - If ABI lookup fails, function selector lookup is performed against `api.4byte.sourcify.dev`.
  - Synthetic ABI definitions are generated from candidate signatures and used for decode/re-encode flows.
- Proxy-aware decoding
  - Detects implementation contracts for delegate proxy patterns and decodes against implementation ABI.
  - Implemented proxy detectors: `ERC1967` slot and legacy ZeppelinOS/OpenZeppelin slot.
- Multicall recursive decoding
  - Decodes nested calls for common Multicall variants:
    `aggregate`, `tryAggregate`, `aggregate3`, `aggregate3Value`, `blockAndAggregate`, `tryBlockAndAggregate`.
  - Recursively decodes nested calls with depth limiting and per-node status.
- Chain and explorer management UI
  - Add/edit/remove chain definitions (chain ID, name, explorer).
  - Per-chain explorer API key management.
  - Shared Etherscan-family API key support with per-chain override.
  - Loads default chains from `chains.json` and persists customizations in Burp preferences.
  - Includes migration of deprecated chain IDs to modern replacements (for persisted configs).
- Cached ABI management UI
  - Add cached ABI manually (paste JSON) or fetch from configured explorer.
  - Remove cached ABI entries.
  - Open cached ABIs in editor, validate JSON, and save updates.
- Detected ABI browser UI (new)
  - Side-by-side panel under the `Web3` tab listing every ABI the passive scanner has accumulated.
  - Each row shows a short fingerprint, function count, and the URL the ABI was first seen at.
  - Click a row to view the ABI JSON read-only in the ABI editor; remove unwanted entries from the pool.
- Calldata Decode / Re-encode panel
  - Decode calldata using chain ID + contract address context.
  - Optional RPC URL support for proxy-aware decoding in the standalone tool.
  - Displays nested multicall decode details when applicable.
- Decode of `eth_sendRawTransaction` JSON-RPC calls (and their inner functions)

## Chains Supported so far

The full, current list of bundled chains lives in
[`web3-decoder/src/main/resources/chains.json`](web3-decoder/src/main/resources/chains.json) —
the extension now ships the Etherscan v2 multichain set (Ethereum, Sepolia, BNB Smart
Chain, Polygon, Base, Arbitrum, Linea, Blast, Optimism, Avalanche, Gnosis, Scroll,
Taiko, Berachain, and many more, including their testnets). The interface also lets you
add your own chains at runtime — any chain whose block explorer exposes Etherscan-style
APIs will work. See [Features](docs/FEATURES.md#11-chain--explorer-management-ui) for
chain management details (including migration of deprecated chain IDs).

## How it works

`eth_chainId` JSON-RPC request to the node in use to detect which chain we are working on, and depending on
the chain, selects a block explorer API by searching in the `chains.json` file.

To decode function calls we need the ABI (Application Binary Interface) of the contract, which contains all
functions that can be called in the contract and their inputs and outputs. The extension resolves ABIs in
this order:

1. **Cached ABI** for the chain + contract address (Burp project-scoped persistence).
2. **Builtin ABIs** for well-known contracts (e.g. Multicall3).
3. **Block explorer** lookup (Etherscan-style API) for verified contracts.
4. **Detected ABI pool** — ABIs the passive scanner has lifted out of dapp frontend bundles, indexed by
   4-byte function selector. Chain-agnostic.
5. **4byte fallback** — selector → signature lookup against `api.4byte.sourcify.dev`, with a synthetic ABI
   built from any matching candidate.

If the chain ID can't be determined (e.g. the endpoint doesn't respond to `eth_chainId`), the chain-scoped
steps (1–3) are skipped and the decoder still tries the chain-agnostic steps (4 and 5).

## External Services & Data Sources

To decode traffic, the extension talks to a few external sources. These are optional and you can deactivate them from the Web3 tab. All outbound
requests are sent through Burp's own HTTP stack (`api.http().sendRequest`), so they
respect Burp's upstream proxy/TLS settings and appear in Burp's traffic.

| Service | Endpoint | Used for |
|---------|----------|----------|
| **JSON-RPC node** (the endpoint already in your traffic) | the proxied RPC URL | `eth_chainId` to detect the active chain, and `eth_getStorageAt` to read proxy implementation slots (ERC-1967 / legacy ZeppelinOS). |
| **Etherscan (v2 multichain)** | `https://api.etherscan.io/v2/api?chainid=…` | Fetching verified contract ABIs. Falls back to a chain's legacy explorer host (`/api`) when v2 doesn't support that chain. |
| **4byte signature database** | `https://api.4byte.sourcify.dev` | Resolving an unknown 4-byte function selector to candidate signatures when no ABI is available (a synthetic ABI is then built from the match). |

> **Privacy note:** ABI lookups send the **contract address** to the configured block
> explorer, and 4byte fallback sends the **function selector** to
> `api.4byte.sourcify.dev`. Downloaded ABIs are cached locally so repeat decodes don't
> re-query. Most explorers (e.g. [etherscan.io](https://etherscan.io)) need an API key
> for more than ~1 request / 5 seconds — manage keys from the `Web3` tab.
>
> The passive ABI detector reads HTTP response bodies that Burp already captured and runs
> entirely locally — no traffic is generated by detection itself.

web3-decoder

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README