Web3 Decoder

Web3 Decoder 是一个 Burp Suite 扩展，可帮助分析涉及 web3 智能合约的操作具体发生了什么。这主要是对以太坊节点以及其他兼容网络（如 Polygon、Arbitrum、BSC…）节点的 JSON-RPC 调用。

下载与安装

下载最新的扩展 JAR — 此链接始终提供最新版本：

⬇ web3-decoder.jar（最新版本）

旧版本可在发布页面获取。

然后在 Burp Suite 中加载：

1. 转到 扩展 → 已安装 → 添加。
2. 将 扩展类型 设置为 Java，然后选择下载的 web3-decoder.jar。
3. 单击 下一步 — 加载完成后即会出现 Web3 选项卡以及 Web3 Request/Web3 Response 编辑器选项卡。

需要捆绑了 JRE 21 的 Burp 版本（当前的 Burp Suite 版本）。该 JAR 是自包含的 — 所有依赖项（web3j 等）均已包含在内。

从源码构建

./gradlew jar

扩展 JAR 始终写入固定路径 — web3-decoder/build/libs/web3-decoder.jar — 与版本无关，因此您可以一次性指定 Burp 指向它，并在重建时让其自动重新加载。发布流程记录在 docs/RELEASING.md 中。

截图

这是我们改进后的 Web3 编辑器选项卡在成功解码您的 JSON-RPC 请求和响应后的样子：

下方是重新设计的 Web3 选项卡，包含所有设置、检测到的 ABI 等！（感谢 Claude Design！）

文档

详细文档位于 docs/ 文件夹中：

• 架构 — 层次结构、组件以及关键解码/编码流程（含图表）。
• 项目结构 — 目录布局和各包职责。
• 技术栈 — 依赖项、构建/打包、运行时和 CLI 模式。
• 功能 — 完整能力目录及实现指引。

区块浏览器 API 密钥

大多数受支持的区块浏览器（如 etherscan.io）需要 API 密钥，才能每 5 秒发送超过 1 个请求。

新界面允许您管理链、区块浏览器和 API 密钥。

手动添加合约的 ABI

该扩展会缓存从 etherscan 等区块浏览器下载的 ABI。您也可以直接从 Web3 选项卡添加它们，可以从区块浏览器自动获取，也可以手动添加。

已实现的功能

• Burp 集成
  • 用于 JSON-RPC 请求的 Web3 Request 编辑器选项卡（在没有 eth_call / eth_sendRawTransaction 的流量上隐藏）。
  • 用于匹配 JSON-RPC 响应的 Web3 Response 编辑器选项卡。
  • 专用的 Web3 套件选项卡，提供链/ABI/calldata 工具。
  • 代理历史记录行会在其备注中标注解码后的函数签名（在后台线程解码，并持久化到实时历史记录行）。
• 解码后的编辑器体验
  • 两个编辑器选项卡默认都提供结构化树视图，只需一次切换即可进入 JSON 视图 — JSON 仍是重新编码的权威来源。
  • JSON 视图保留语法和语义高亮、行号、括号匹配、实时有效性以及搜索栏。
• JSON-RPC 请求解码
  • 将 eth_call calldata 解码为 function + 类型化的 args。
  • 支持单请求和批量 JSON-RPC 负载。
  • 对于批量负载，每个条目都会报告状态（decoded、skipped、error），并在跳过/失败时给出原因。
• JSON-RPC 响应解码
  • 为先前已解码的 eth_call 请求解码 result。
  • 支持单个和批量响应，通过 JSON-RPC id（或按索引回退）匹配条目。
• 重新编码和编辑工作流
  • 您可以在请求编辑器中编辑已解码的参数，并将其写回编码后的 calldata。
  • 独立的 calldata 工具可以在请求历史之外进行解码和重新编码。
• ABI 解析与缓存
  • ABI 查找优先级：缓存 ABI → 内置 → 区块浏览器（兼容 Etherscan）→ 被动检测池 → 4byte。
  • 下载的 ABI 会自动缓存，供将来解码使用。
  • 解码输出中会跟踪 ABI 来源（cache、builtin、etherscan、detected 或 4byte）。
• 被动 ABI 检测（新增）
  • 一个 Burp PassiveScanCheck 会扫描 HTTP 响应体（通常是压缩后的 dapp JS 包）以查找 Solidity ABI，并将找到的所有内容存储在以函数选择器为索引的项目级池中。
  • 同时处理严格的 JSON 和压缩包中常见的 JS 对象字面量形式，包括 Terser/esbuild/Svelte 生成的 !0 / !1 布尔简写。
  • 当现有的缓存 → 内置 → etherscan 链路未命中时，解码器会在回退到 4byte 之前查询检测到的池。解码输出会标记为 decodeSource: "detected"。
  • 即使无法确定 eth_chainId 也能工作：检测到的池和 4byte 与链无关，因此解码器仍会尝试它们，而不是直接拒绝。
  • 每个新 ABI 都会产生一条信息性 Burp 问题（“检测到 Solidity 合约 ABI”），其中包含完整的方法列表 — 每个函数/事件/错误及其规范签名和 4 字节选择器 — 以及发现该 ABI 的 URL。
• 4byte 回退解码
  • 如果 ABI 查找失败，则针对 api.4byte.sourcify.dev 执行函数选择器查找。
  • 根据候选签名生成合成 ABI 定义，并用于解码/重新编码流程。
• 代理感知解码
  • 检测委托代理模式的实现合约，并针对实现 ABI 进行解码。
  • 已实现的代理检测器：ERC1967 槽位和旧版 ZeppelinOS/OpenZeppelin 槽位。
• Multicall 递归解码
  • 解码常见 Multicall 变体的嵌套调用：aggregate、tryAggregate、aggregate3、aggregate3Value、blockAndAggregate、tryBlockAndAggregate。
  • 递归解码嵌套调用，具有深度限制和每节点状态。
• 链和区块浏览器管理界面
  • 添加/编辑/删除链定义（链 ID、名称、区块浏览器）。
  • 每链区块浏览器 API 密钥管理。
  • 支持共享的 Etherscan 系列 API 密钥，并可按链覆盖。
  • 从 chains.json 加载默认链，并将自定义设置持久化到 Burp 偏好设置中。
  • 包括将已弃用的链 ID 迁移到现代替代链（针对持久化配置）。
• 缓存 ABI 管理界面
  • 手动添加缓存 ABI（粘贴 JSON）或从已配置的区块浏览器获取。
  • 移除缓存 ABI 条目。
  • 在编辑器中打开缓存 ABI、验证 JSON 并保存更新。
• 已检测 ABI 浏览界面（新增）
  • Web3 选项卡下的并排面板，列出被动扫描器累积的每个 ABI。
  • 每一行显示简短指纹、函数数量以及首次发现该 ABI 的 URL。
  • 单击某行可在 ABI 编辑器中以只读方式查看 ABI JSON；从池中移除不需要的条目。
• Calldata 解码/重新编码面板
  • 使用链 ID + 合约地址上下文解码 calldata。
  • 在独立工具中为代理感知解码提供可选 RPC URL 支持。
  • 在适用时显示嵌套 multicall 解码详情。
• 解码 eth_sendRawTransaction JSON-RPC 调用（及其内部函数）

目前支持的链

当前捆绑的完整链列表位于 web3-decoder/src/main/resources/chains.json — 该扩展现在内置了 Etherscan v2 多链集合（Ethereum、Sepolia、BNB Smart Chain、Polygon、Base、Arbitrum、Linea、Blast、Optimism、Avalanche、Gnosis、Scroll、Taiko、Berachain 等，包括它们的测试网）。该界面还允许您在运行时添加自己的链 — 任何其区块浏览器提供 Etherscan 风格 API 的链都可以使用。有关链管理详情（包括已弃用链 ID 的迁移），请参阅功能。

工作原理

向当前使用的节点发送 eth_chainId JSON-RPC 请求，以检测我们在哪条链上工作，并根据链的不同，通过搜索 chains.json 文件来选择区块浏览器 API。

要解码函数调用，我们需要合约的 ABI（应用程序二进制接口），它包含合约中所有可调用的函数及其输入和输出。该扩展按以下顺序解析 ABI：

1. 针对链 + 合约地址的缓存 ABI（Burp 项目级持久化）。
2. 针对知名合约（例如 Multicall3）的内置 ABI。
3. 针对已验证合约的区块浏览器查找（Etherscan 风格 API）。
4. 已检测 ABI 池 — 被动扫描器从 dapp 前端包中提取的 ABI，按 4 字节函数选择器索引。与链无关。
5. 4byte 回退 — 针对 api.4byte.sourcify.dev 的选择器 → 签名查找，并根据任何匹配的候选签名构建合成 ABI。

如果无法确定链 ID（例如端点不响应 eth_chainId），则会跳过链级步骤（1–3），解码器仍会尝试与链无关的步骤（4 和 5）。

外部服务与数据源

为了解码流量，该扩展会与一些外部源通信。这些是可选的，您可以在 Web3 选项卡中停用它们。所有出站请求都通过 Burp 自身的 HTTP 栈（api.http().sendRequest）发送，因此它们遵循 Burp 的上游代理/TLS 设置，并出现在 Burp 的流量中。

服务	端点	用途
JSON-RPC 节点（您的流量中已有的端点）	被代理的 RPC URL	用于 eth_chainId 检测活动链，以及 eth_getStorageAt 读取代理实现槽位（ERC-1967 / 旧版 ZeppelinOS）。
Etherscan（v2 多链）	https://api.etherscan.io/v2/api?chainid=…	获取已验证合约的 ABI。当 v2 不支持该链时，回退到该链的旧版区块浏览器主机（/api）。
4byte 签名数据库	https://api.4byte.sourcify.dev	在没有可用 ABI 时，将未知的 4 字节函数选择器解析为候选签名（随后根据匹配结果构建合成 ABI）。

隐私说明： ABI 查找会将合约地址发送到已配置的区块浏览器，4byte 回退会将函数选择器发送到 api.4byte.sourcify.dev。下载的 ABI 会缓存在本地，因此重复解码不会重新查询。大多数区块浏览器（例如 etherscan.io）需要 API 密钥，才能每 5 秒发送超过约 1 个请求 — 可从 Web3 选项卡管理密钥。

被动 ABI 检测器读取 Burp 已捕获的 HTTP 响应体，并且完全在本地运行 — 检测本身不会产生任何流量。