Decoding Contracts
Instead of working with the logs and traces in their raw states, on Dune we decode smart contract activity into nice human-readable tables.
Dune’s extensive catalog of decoded smart contracts are driven by our Wizards. Our decoding process empowers our community to submit the data and build the tables that they’d like to query on Dune!
But what does decoding mean? Blockchain transaction data starts as bytecode, a low level programming language that can be read by machines. Using the ABI (Application Binary Interface) that is specific to each contract, we translate that bytecode into query-able data tables.
A. The Lifecycle of Decoding
Step 1: Submission
Our decoding process begins with our contract submission page.
To successfully submit a contract, you will need four pieces of information:
- Blockchain: Blockchain the contract is deployed on
- Contract Address: The address of the contract you want to decode
- Project Name: The name of the project that the contract originates from (e.g. Tether, Uniswap, Bancor)
- Contract Name: The name of the smart contract as given by the project (ex. USDT, Pair, LiquidityFactory)
- ABI: Unique to each smart contract. Further details can be found here. Note that for contracts that are verified by a chain’s explorer we will attempt to auto-fetch the ABI. Otherwise the ABI will need to be entered manually.
In most cases, the contract name will be pulled directly from a blockchain scanner. We recommend using the name provided. If the name is not automatically provided, please follow our naming conventions to assure the contract is properly assimilated into Dune’s database.
When do you need Several Instances Options?
Enable bytecode matching
Contract “instances” are contracts on the same chain with the same bytecode (and therefore the same ABI) for the same project. If you check this box, Dune can decode all instances of this project on the given blockchain with the same bytecode and ABI, consolidating them into the same tables under one namespace.project directory without multiple submissions.
To check for other instances of the contract, go to a blockchain explorer and look for “Similar Match Source Code” under the Contract tab. Here is an example:
Decoded via dynamic contract detection
Contracts decoded this way are referred to as dynamically decoded by Dune. These are contracts that are decoded automatically because users checked the box “Are there several instances of this contract?” when submitting the contract. Note that Dune only considers a contract a dynamic instance if the bytecode matches 100%. This is done by querying the <chain>_creation_traces table and matching the code field. If the bytecode does not match 100%, we will not decode that instance.
For example, this contract is nearly identical to this other contract in terms of bytecode, but Dune currently does not dynamically decode the first contract because we currently require a 100% bytecode match.
Decode other contracts created by the same factory
A factory contract is a smart contract that creates other smart contracts. If there are multiple instances of a contract, it might be due to a factory contract. If you check this box, Dune can decode all contracts created by the same factory that use the same ABI, consolidating them into the same tables under one namespace.project directory (e.g., Pair contract from Uniswap V2).
When you submit a contract as a factory contract, Dune verifies it by checking if the deployer (from address) is a contract and not an EOA. This is done by querying the <chain>_creation_traces table. If the from address is a contract, Dune will gather all address fields created by it for decoding.
To check if a contract is created by a factory, use a blockchain explorer to see if the “From” address in a Contract Creation transaction is a contract or an EOA. For example, this is a factory-created contract by Uniswap V3 factory.
Decoded via the factory pattern
Contracts decoded this way are referred to as factory decoded by Dune. These contracts are automatically decoded because users checked “Is it created by a factory contract?” when submitting. Dune detects this by querying the <chain>_creation_traces table and fetching all address fields created by the same from.
Dynamic vs Factory Decoded
Dynamic decoding anchors on the bytecode being the same, while factory decoding also requires the contract to be deployed by another contract (not an EOA) with the same deployer address.
Dynamically Decoded Contracts share the same bytecode but may have different deployers.
For example, this contract can be decoded as dynamic because it has the same bytecode as this contract. Both will appear under the same decoded tables in the SmartTokens for Bancor directory but have different deployers (from address).
Factory Decoded Contracts are deployed by a factory contract and share the same deployer address.
For example, contracts created by the Uniswap V3 Factory, such as this one and this one, are factory decoded because they share the same bytecode and deployer. These contracts will appear under the same decoded tables in the Pair for Uniswap V3 directory.
Other Special Contracts
Other special smart contracts can be decoded as well, following these conventions:
Proxy contract
Submit using the proxy address but with the ABI of the implementation.
You can identify a proxy contract by looking for the “Read as Proxy” tab on a blockchain explorer. This tab will also show the implementation contract. Here is an example.
To decode:
- Use the address of the proxy contract.
- Fetch the ABI of the implementation contract.
Diamond proxy contracts
Submit all the facets using just the same name for the project and contract and upload all the relevant ABIs. This can be done with one ABI representing all facets or separate ABIs for each facet.
Where can I find this information?
Contract addresses can usually be found in a project’s docs. Once you have the contract address, you can use a blockchain explorer to get the rest of the information. Most blockchain explorers have everything you need!
Resubmissions
Sometimes you need to resubmit a contract because the name is originally submitted wrong, or you need to update the ABI. Follow the steps as guided. But if you are resubmitting for other reason not listed in the dropdown, provide as much detail as possible to avoid the resubmission being rejected.
Step 2: Decoding
Once the contract has been approved for decoding, you will receive a notification in your email. While the table itself may be visible after approval, it may be empty. No reason to worry! Note that it takes around 24 hours from the time the contract has been approved to be fully decoded and incorporated into the Dune database.
At any point you can check the status of your submitted contract under “Contracts” in your settings.
Step 3: Finding Your Decoded Contract
One quick tip to find and begin querying your decoded table is to use Dune’s Explorer. When beginning a new query, the Explorer is located to the left side of the Query Editor. From there, follow simple steps:
- Drop the contract address of your decoded contract in the search bar
- Pull up the specific function or event you are looking for
- use the >> button to immediately populate that table in your Query Editor.
Then it’s all ready for you to query. Let the data flow!
B. Frequently Asked Questions
How do I figure out if my contract has been decoded?
How do I figure out if my contract has been decoded?
There are two main ways to find out if your contract has been decoded.
First: Account Settings
Information on submitted contracts can be found in your account settings under “Contracts”. The status of the contract will reflect one of the following:
- Pending
- Approved/Rejected*
Note that once a contract has been approved, it takes around 24 hours for the data to be fully decoded and populated into our database.
*If the contract is rejected, hover your mouse over the status to see the reason for the rejection.
Second: Our Contract Decoding Dashboard
Built by our decoding team, this dashboard gives you information on the status of any submitted contract. Input the contract address in the box at the top of the dashboard and if the contract has been decoded, the contract information will populate the box along with where it is located in the Dune database.
I see data on Dune but it doesn't match or is missing what I expected to see
I see data on Dune but it doesn't match or is missing what I expected to see
Unfortunately, Dune only has access to contract data in circumstances that the contract performed an event that left a trace. Our recommendation is to check out the {blockchain}.traces table to see what information is available for a particular contract.
Alternatively, some contracts are upgradeable (ie., the smart contract code can be modified). In this case we may not have all of the ABIs. ABIs can be checked in the ABI column of the {blockchain}.contracts tables. A contract can always be resubmitted with missing ABIs so we can update our data.
How do I submit contract information manually?
How do I submit contract information manually?
Although we try to fetch contract information such as the ABI, sometimes this information might not be available through our sources.
In those instances, you will need to manually input the contract’s name and its ABI.
If the contract has been verified by the chain’s block explorer, you should be able to find this information there.
How do I submit a proxy contract?
How do I submit a proxy contract?
In order to properly decode transactions for contracts that fit the Proxy pattern, Dune needs to map the Proxy contract’s address with the implementation contract’s ABI.
We avoid monitoring the implementation contract’s address because its logic is accessed in transactions via the DelegateCall function.
If we did monitor the implementation contract’s address directly, we would miss out on any event logs in its logic since these are actually fired by the caller (the Proxy in this case) when calling a function through DelegateCall.
When you submit the Proxy contract’s address, we’ll attempt to fetch the proxy’s contract name and the implementation address it’s pointing towards to source the Implementation contract’s ABI.
If we can’t find the Implementation contract’s ABI, you’ll need to find it using the relevant chain’s blockchain explorer and input it manually.
How do I submit Diamond Proxy contracts?
How do I submit Diamond Proxy contracts?
Similar to vanilla Proxy contracts, EIP-2535 contracts can be supported by passing in the address of the Diamond Proxy as well as a single ABI representing the totality of all the facets interfaces.
My submission got rejected, why?
My submission got rejected, why?
The most common reason that your submission got rejected is because it has already been decoded! You can make use of this dashboard to check whether the contract have been decoded.
Enter the contract that you wish to decode and hit enter to run:
Viewing results:
If you see results after running the query, that means the contract is already decoded! You’ll be able to find the decoded tables under ‘Decoded Projects’ in the data explorer.
In the interest of data quality, we reject duplicative, incorrect or low quality submissions. To avoid rejection, be sure to submit accurate contract information! Submissions can be rejected for a number of reasons, including not following the naming conventions, not providing clear data at submission, etc. The particular reason for a contract submission being rejected can be found in account settings under “Contracts” by hovering the mouse over the “Rejected” status.
Why am I missing historical data for my contract?
Why am I missing historical data for my contract?
It may take up to six hours from the time of contract approval for the contract to be fully decoded along with its historical data. If you still can’t see the data after this period, please reach out to us through our #decoding Discord channel.
I'm waiting for my data to fully decode. What can I do in the meantime?
I'm waiting for my data to fully decode. What can I do in the meantime?
Need some data urgently but the contract have yet to be fully decoded? You can refer to these queries that utilizes the logs table to get the events:
Additional Questions?
Head over to the #decoding Discord channel and we’ll be happy to help!