search

shazow / whatsabi

Extract the ABI (and resolve proxies, and get other metadata) from Ethereum bytecode, even without source code.
https://shazow.github.io/whatsabi/
MIT License
1.06k stars 74 forks source link
bytecode ethereum evm web3

readme

WhatsABI

WhatsABI

Guess an ABI and detect proxies from an Ethereum bytecode, even if it's unverified.

WhatsABI is perfect for building procedural frontends, embedding in wallets, block explorers, or doing bytecode analysis.

Features

What can WhatsABI do?

WhatsABI is different from other EVM analysis tools in some important ways:

Usage

Generated docs: https://shazow.github.io/whatsabi/

Quick start:

import { ethers } from "ethers";
import { whatsabi } from "@shazow/whatsabi";

// Works with any provider (or client) library like Ethers.js, Viem, or Web3.js!
const provider = ethers.getDefaultProvider();
const address = "0x00000000006c3852cbEf3e08E8dF289169EdE581"; // Or your fav contract address

// Quick-start:

const result = await whatsabi.autoload(address, { provider });
console.log(result.abi);
// -> [ ... ]

Another quick example with Viem:

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { whatsabi } from "@shazow/whatsabi";

const client = createPublicClient({ chain: mainnet, transport: http() })
const result = await whatsabi.autoload(address, { provider: client });

Breaking it down, here's what autoload is doing on the inside:

const code = await provider.getCode(address); // Load the bytecode

// Get just the callable selectors
const selectors = whatsabi.selectorsFromBytecode(code);
console.log(selectors); // -> ["0x06fdde03", "0x46423aa7", "0x55944a42", ...]

// Get an ABI-like list of interfaces
const abi = whatsabi.abiFromBytecode(code);
console.log(abi);
// -> [
//  {"type": "event", "hash": "0x721c20121297512b72821b97f5326877ea8ecf4bb9948fea5bfcb6453074d37f"},
//  {"type": "function", "payable": true, "selector": "0x06fdde03", ...},
//  {"type": "function", "payable": true, "selector": "0x46423aa7", ...},
//   ...

// We also have a suite of database loaders for convenience
const signatureLookup = new whatsabi.loaders.OpenChainSignatureLookup();
console.log(await signatureLookup.loadFunctions("0x06fdde03"));
// -> ["name()"]);
console.log(await signatureLookup.loadFunctions("0x46423aa7"));
// -> ["getOrderStatus(bytes32)"]);

// We also have event loaders!
console.log(await signatureLookup.loadEvents("0x721c20121297512b72821b97f5326877ea8ecf4bb9948fea5bfcb6453074d37f"));
// -> ["CounterIncremented(uint256,address)"]

// There are more fancy loaders in whatsabi.loaders.*, take a look!

// Here's a multiloader with an Etherscan API key, it can be used with autoload below.
// Each source will be attempted until a result is found.
const loader = new whatsabi.loaders.MultiABILoader([
  new whatsabi.loaders.SourcifyABILoader(),
  new whatsabi.loaders.EtherscanABILoader({
    apiKey: "...", // Replace the value with your Etherscan API key
  }),
]);
const { abi, name, /* ... other metadata */ } = await loader.getContract(address));

See whatsabi.loaders for more examples of what our loaders can do, like loading verified contract source code and compiler settings.

All together with our do-all-the-things helper:

...

let result = await whatsabi.autoload(address, {
  provider: provider,

  // * Optional loaders:
  // abiLoader: whatsabi.loaders.defaultABILoader,
  // signatureLoader: whatsabi.loaders.defaultSignatureLookup,

  // There is a handy helper for adding the default loaders but with your own settings
  ... whatsabi.loaders.defaultsWithEnv({
    SOURCIFY_CHAIN_ID: 42161,
    ETHERSCAN_BASE_URL: "https://api.arbiscan.io/api",
    ETHERSCAN_API_KEY: "MYSECRETAPIKEY",
  }),

  // * Optional hooks:
  // onProgress: (phase: string) => { ... }
  // onError: (phase: string, context: any) => { ... }

  onProgress: (phase) => console.log("autoload progress", phase),
  onError: (phase, context) => console.log("autoload error", phase, context),

  // * Optional overrides:
  // addressResolver: (name: string) => Promise<string>

  // * Optional settings:
  // followProxies: false,
  // enableExperimentalMetadata: false,
});

console.log(result.abi);

// Detail will vary depending on whether `address` source code was available,
// or if bytecode-loaded selector signatures were available, or
// if WhatsABI had to guess everything from just bytecode.

// We can even detect and resolve proxies!
if (result.followProxies) {
    console.log("Proxies detected:", result.proxies);

    result = await result.followProxies();
    console.log(result.abi);
}

Or we can auto-follow resolved proxies, and expand parts of the result object:

const { abi, address } = await whatsabi.autoload(
    "0x4f8AD938eBA0CD19155a835f617317a6E788c868",
    {
        provider,
        followProxies: true,
    },
});

console.log("Resolved to:", address);
// -> "0x964f84048f0d9bb24b82413413299c0a1d61ea9f"

See Also

Projects powered by WhatsABI

Talks & Presentations

Some Cool People Said...

Omg WhatsABI by @shazow is so good that it can solve CTFs.
In one of my CTFs, students are supposed to find calldata that doesn’t revert
WhatsABI just spits out the solution automatically😂 I’m impressed!👏

🗣️ Nazar Ilamanov, creator of monobase.xyz

WhatsABI by @shazow takes contract bytecode, disassembled it into a set of EVM instructions, and then looks for the common Solidity's dispatch pattern.
Check out the source, it's actually very elegant!

🗣️ WINTΞR, creator of abi.w1nt3r.xyz

really cool stuff from @shazow
deduce a contract's ABI purely from bytecode

🗣️ t11s, from Paradigm

Caveats

Development

$ cat .env  # Write an .env file with your keys, or `cp .env.example .env`
export INFURA_API_KEY="..."
export ETHERSCAN_API_KEY="..."
$ nix develop  # Or use your system's package manager to install node/ts/etc
[dev] $ npm install
[dev] $ ONLINE=1 make test

Thanks

License

MIT