Etherscan: Everyone's Favorite Blockchain Explorer
04 Apr 2024If you’ve been around the Ethereum ecosystem for some time, you’ve already used Etherscan before. Etherscan has many useful features, some more hidden than others, so I will start from the beginning. Skip any sections that are old news to you.
Which Chain?
There are blockchain explorers for Ethereum testnets, like rinkeby and goerli, as well as many other blockchains. This article only focuses on the mainnet Etherscan Etherscan website, but most of this information should translate to other block explorers.
Setup
There is no mandatory installation or setup for Etherscan, but it is helpful to create a free account if you will be using the API. Having an account allows you to send more requests to the website before getting rate limited.
More Information
If you have specified Etherscan questions, search the developer docs or the knowledge base. This article will give a broad overview focusing on security use cases.
EoA Address Lookup
First let’s search for an externally owned account (EOA) address, which is an address owned by some user, as opposed to a contract. You can search by ENS name or using the actual address. Here’s what the result of searching for “vitalik.eth” looks like.
Because “vitalik.eth” is an ENS domain, our search tells us what the resolved address of this ENS domain is. If we click on this address, we will see the transactions made by “vitalik.eth”.
The two main sections of address information are:
- The information tabs at the bottom that list different types of information. The default tab selected is “Transactions”, but there are six other tabs visible: Internal Txns, Erc20 Token Txns, Erc721 Token Txns, Erc1155 Token Txns, Analytics, and Comments.
- The Overview section lists the tokens that an address holds. The “Balance” in the screenshot below only includes the value of the Ether the account holds. If you click on the “Token” dropdown menu, a list of ERC tokens held by the account is shown. A cleaner view of the tokens is available by clicking the “View expanded ERC-20 token holding” button to the right of the dropdown menu.
Because most security usage of Etherscan involves investigating contracts, searching for an EoA for security purposes is a less common activity.
Contract Address Lookup
You can search for a contract using either the contract address or a descriptor for the contract. To see the results of searching by descriptor, type “WETH” into the search bar but DO NOT submit the search. Instead, after typing “WETH” you will see a dropdown menu of tokens appear below the search bar. You can click the WETH result from the dropdown to get to the WETH contract. As a sidenote, you can even search for queries besides ERC token names, such as the phrase “Compound Governance”.
We can see the information available for this contract looks different than the EoA result from earlier. There is no “Balance” or “Tokens” list, but in its place is the “Price”, “Fully Diluted Market Cap”, “Max Total Supply”, “Holders”, and “Transfers”. And further down, we can see different tabs to view different information.
Let’s click on the “Contract” tab and examine the WETH contract more closely.
Contract Function Interaction
The “Contract” tab is where most of the security work in Etherscan happens, because that’s where you will find the contract code. Under the “Contract” tab, click the “Expand All” link on the right. The list you will see is a list of contracts in the function.
If the function does not take input parameters and is a view function, meaning it only reads the blockchain state and does not modify the state (read-only), then the result will automaticaly be shown. For example, the “totalSupply” function outputs the total supply of WETH, and if you refresh the page a few times, you can see the value changing. Other functions, like the “name” and “decimals” functions, have outputs that are hard-coded to the contract and will not change (this is based on extra knowledge of the ERC20 contract code, so Etherscan doesn’t provide this information). If a function is called with input parameters, you can provide those input parameters and click the “Query” button to query the result from the blockchain. To test out this feature, enter the address “0xd8da6bf26964af9d7eed9e03e53415d37aa96045” (the same vitalik.eth resolved address we used earlier) in the input field for the “balanceOf” function and click the “Query” button. The result in this case is in units of wei, because the decimals value was 18. If we divide this value by 10^18, we get the result 0.05 WETH. We can double check our work by searching for the “0xd8da6bf26964af9d7eed9e03e53415d37aa96045” address, clicking on the dropdown menu of Tokens in the upper left, and observing that this address holds 0.05 WETH. You can even connect your Metamask wallet to Etherscan to interact with contract functions directly, but this approach is not often used for security because custom scripts and contracts are more often the tool of choice.
Contract Code
Often the reputable contracts that you will look at in Etherscan have verified source code. Let’s pretend we want to examine the deployed code for MakerDAO, because we’re either doing some fun research or heard they offer a large bug bounty. We can search the MakerDAO developer documentation and GitHub repository to see if they maintain a public list of their actively deployed contracts, and like any major protocol should, they do have such a list. You can pick any contract address, but for this example I will use the Changelog contract at 0xda0ab1e0017debcd72be8599041a2aa3ba7e740f (which is actually named Chainlog in the contract source code). Make sure you have “Ethereum mainnet” selected on this page, because we are using the Ethereum mainnet Etherscan website.
When we search for this address in Etherscan and navigate to the “Contract” tab, we see that the “Contract” tab has a green checkmark and contains source code. This is because the contract developers uploaded their contract source code and Etherscan verified that the compiled source code matches the bytecode that is stored on the Ethereum blockchain. The source code is visible in Etherscan.
There are some options to the top right of the “Contract Source Code” that can sometimes be useful:
- The “Outline” dropdown menu makes it easy to navigate to specific functions in the code
- The “More Options” dropdown menu allows you to
- Find similar contracts with the “Similar” button (with mixed results in my experience)
- Visualize the contract function calls with the “Sol2Uml” button (see screenshot below)
- Diff the contract with another contract with the “Compare” button
Verified source code might be the most used Etherscan feature for security purposes. Scrolling through code on Etherscan is how you look for bugs on mainnet, because the code in the GitHub repository for projects can often be different than what is currently deployed. Most large projects should have verified their source code on Etherscan, because it improves transparency and trust in the project. If the developers did not upload their source code to Etherscan, you can still try decompiling the bytecode using one of the many options for Ethereum decompilers, but this process can get messy and is normally only necessary when analyzing contracts used in hacks.
When contract source code is verified on Etherscan, the contract must be “flattened”. This means that the import statements are removed and the source code for the contracts that were imported and stored in the same file. You will encounter contract code on Etherscan that is very long because of this, and sometimes you need to scroll to the very bottom of the source code, past all of the imported code, to find the custom contract code that you are seeking.
If you feel more at home looking at code in VS Code that in the Contract tab of Etherscan’s website, try using this DethCode viewer. By replacing modifying the Etherscan URL from etherscan.io to etherscan.deth.net, you can view the same contract code in a browser-based VS Code. If you look at code a lot, it’s a nice tool. Try out the interface at https://etherscan.deth.net/.
Contract Events and Analytics
While the “Contract” tab with the source code is where the most time is spent when analyzing security bugs, the “Events” and “Analytics” tabs can sometimes provide additional data. In the “Events” tab for the MakerDAO Changelog contract, we can see the logs for past emit calls. The UpdateVersion emit is in the setVersion() function, and because it takes a string as an input parameter type, we can use Etherscan to decode the value as text. Similarly, the UpdateAddress emit is found in the setAddress() function and take a bytes32 string and address as input parameters, so we can decode these values accordingly.
The MakerDAO Changelog Contract does not hold any value, so the “Analytics” tab does not show anything exciting. If we return to the WETH contract, the “Analytics” tab shows us a lot of data about the token over time.
A more interesting Analytics view is found in the Ronin Bridge contract, which suffered a large hack in early 2022. The screenshot below zooms in on the ETH transfers to and from this contract during the month of the hack, March 2022. Want to guess what day the hack occurred on?
Transaction Lookup
Like searching for addresses and contracts, searching for a transaction is also possible. Let’s continue with the Ronin hack, where transaction 0xc28fad5e8d5e0ce6a2eaf67b6687be5d58113e16be590824d6cfa1a94467d0b7 transferred the hacked Ether. Scroll down in the “Overview” tab, select “Click to see More”, and then click the “Decode Input Data” button to view the input data for this transaction. This information provides insight into the input data that the Ronin hacker used to withdraw the ETH from the bridge contract.
The “Logs” and “State” tabs can give more insight into what functions were called and what state variables were changed.
However, Etherscan isn’t necessarily the best tool to tell us everything about what is happening in this transaction. Most security power users prefer the ethtx.info site for this purpose. It provides a more granular view of the function call sequence in this transaction, a view that Etherscan doesn’t currently have. Viewing the same transaction on ethtx, we can see the five different validator addresses that were compromised in MainchainValidator.isValidator() => True calls. The requirement for a 5 out of 8 majority to perform this attack is visible in the MainchainValidator.checkThreshold() => True call. This information cannot (yet?) easily be found in Etherscan to the best of my knowledge.
Block Lookup
You can investigate individual Ethereum blocks in Etherscan too. I have not used this feature much, but it should be useful for MEV researchers. The easiest way to view a block is to click on one of the most recent block numbers on the Etherscan homepage. From there, you can view basic data about the block (timestamp, block reward, uncles, etc.), but clicking on the transactions within the block is where most of the useful information is. From there, you can manually examine the transactions that interest you.
Etherscan API
Finally, one of the most useful features of Etherscan is its API. To get an API key, you need a free account, and you will be able to create an API key from the account dashboard. Some frameworks and command line tools require the Etherscan API key for full functionality. For example, the command line tool seth requires the Etherscan API key saved to the ETHERSCAN_API_KEY environment variable, while some projects or frameworks will require a variable such as ETHERSCAN_TOKEN to be set in the project’s .env file. You can use the API to query accounts, contracts, transactions, and all the same types of data that can be accessed on the website. Unless you are building a new tool, in which case you should read the Etherscan API documentation thoroughly, the most common way the API key is used is by configuring it in whichever tool needs the API key to work properly.
More Features
There are even more features of Etherscan, including charts and statistics of recent blockchain activity, top ERC20/721/1155 tokens, a list of recent block uncles, and more. I haven’t seen these used at all for security purposes, so consult the Etherscan documentation or just click around the website to learn more about these features.