revert.wtf explorer

A Manifest V3 browser extension that explains reverted EVM transactions inline on block explorers, powered by the hosted revert.wtf API or a self-hosted compatible endpoint.

How It Works

Explorer tx page
  -> content script picks an adapter and extracts cheap evidence
  -> background worker tries Blockscout Pro with your key
  -> background worker replays via chain override or Chainlist default RPCs
  -> background worker calls the configured revert.wtf API
  -> successful tx explanations are cached by chain + hash
  -> inline panel renders explanation, evidence, and debug actions

The extension ships only @revertwtf/client. It does not bundle parser/catalog packages or the full catalog dataset. Raw decoding and catalog matching stay on the API side.

Blockscout Pro is the preferred enrichment path. Bring your own key and the background worker can fetch indexed transaction info and raw traces from api.blockscout.com before falling back to RPC replay. Explorers often do not expose custom-error bytes, so RPC is still useful as a last-mile fallback. The extension bundles Chainlist RPC defaults for Etherscan-family chains, and users can override any chain with their own endpoint.

Install For Development

npm install
npm run build

Then open chrome://extensions, enable Developer mode, choose "Load unpacked", and select this folder. npm run watch rebuilds on change.

Supported Explorers

Static content scripts run on:

• current Etherscan V2 deployments, including etherscan.io, basescan.org, arbiscan.io, gnosisscan.io, and the other Etherscan-family hosts listed in src/chain-defaults.js
• known Blockscout hosts plus *.blockscout.com

For self-hosted Blockscout instances, open a transaction page and click the extension action. The extension requests permission for that origin, injects the content script, and uses Blockscout Pro when the chain is known.

Configure

Open the extension options page:

• API mode: hosted https://revert.wtf or a custom compatible API base URL.
• API key: optional key for the configured API.
• Blockscout Pro API key: recommended, used before RPC replay.
• Etherscan V2 enrichment: optional fallback for weak DOM cases.
• Replay RPCs: Chainlist defaults are bundled; add a chain ID row only to override a chain, such as 8453 for Base.
• Replay strategy: auto, previous block, inclusion block, or latest.
• Debug bundles: raw revert bytes are truncated unless you opt into full bytes.

Saving settings requests host permissions for custom API and custom RPC origins. Default Chainlist RPC origins are listed in the manifest so replay can run without opening settings first. Non-local http:// endpoints are rejected; http://localhost and http://127.0.0.1 are allowed for local development.

Privacy

When enabled on a transaction page, the extension may send transaction hash, visible revert text, recovered revert bytes, and explorer hostname to the configured API. If you configure Blockscout Pro, the extension calls api.blockscout.com from the background worker. If RPC replay is enabled, the extension calls either your chain override or the bundled Chainlist default RPC from your browser. API keys and full RPC URLs are stored locally and are not included in copied debug bundles. See PRIVACY.md.

Project Layout

manifest.json          MV3 manifest
build.mjs              Rollup bundle entry
popup.html/.css        toolbar menu
options.html/.css      settings UI
src/
  background.js         client + replay orchestration
  cache.js              tx explanation cache helpers
  chain-defaults.js     generated Etherscan deployments + Chainlist RPC defaults
  config.js             chrome.storage-backed settings
  content.js            adapter -> background -> panel flow
  explorers.js          known explorer registry
  network.js            permission/origin helpers
  rpc.js                eth_call replay + diagnostics
  panel.js / panel.css  inline panel
  adapters/
    base.js             adapter contract + signal classifiers
    index.js            adapter registry
    etherscan.js        Etherscan-family DOM signal extraction
    blockscout.js       Blockscout page signal adapter
  blockscout-pro.js     Blockscout Pro transaction/trace enrichment
test/fixtures/          adapter/RPC fixtures
scripts/package-extension.mjs

Quality Gates

npm run lint
npm run typecheck
npm run test
npm run build
npm run check
npm run zip

npm run zip creates revertwtf-explorer-v0.1.0.zip containing only release files: manifest, build bundles, CSS/options, icons, README, privacy policy, and license.

Permissions

• storage: saves local settings.
• activeTab and scripting: enable the current explorer on click, especially self-hosted Blockscout instances.
• https://revert.wtf/*: default hosted API.
• https://api.blockscout.com/* and https://api.etherscan.io/*: optional enrichment APIs, enabled from settings.
• Chainlist default RPC origins: bundled so known chains can replay without manual RPC setup.
• Optional host permissions: requested only for custom API and custom RPC origins.

Panel Features

The panel includes:

• evidence/confidence/missing-context display
• copy debug bundle
• report bad explanation
• open same tx on Blockscout when a mapped chain is available
• retry replay
• open settings
• explain manually

Copied debug bundles are designed to be pasted into GitHub issues without leaking API keys or full RPC URLs. The settings page also includes a manual explain box so pasted revert bytes, RPC errors, wallet errors, and trace snippets exercise the same public API path.

License

MIT