Adding new contracts
Everything you should know about the submission process to successfully decode new contracts
Clicking there will pop up a new browser tab with the contract submission form, which consists of 2 steps:
We first ask for the contract's address and blockchain. Requesting this data first has two purposes: to anticipate potential duplicate contracts and pending submissions, and to automate parts of the submission process where we can. The latter is usually accomplished by fetching potentially useful metadata from Dune and other third party sources where relevant.
For instance, below we submit the USDT contract (
0x94b008aA00579c1307B0EF2c499aD98a8ce58e58) in Optimism:
If we can find the contract through a third party source, we will show a green check mark next to the address field. This means we were able to fetch information such as the contract's name and ABI.
Then, after pressing Next, you will be prompted for other information about the contract that we need in order to decode it:
If we found the contract through other third party sources, you will only have to fill in the project name. We have some naming conventions on that, partly due to our technical setup and also to make finding data more predictable.
Once you submit it, you are done! The contract will be stored in our queue, which we manually review for quality assurance purposes. Your submission might take a few days to get processed.
In some instances, Dune can automatically detect and index multiple contract addresses under the same submission. This is useful for examples such as AMM pools where there often exists one contract instance per pair.
We have two strategies for detecting other contracts for decoding:
- 1.Bytecode match. We use the bytecode of the contract address in the submission to find other matches in the whole chain history.
- 2.Factory instances. We find all other contracts created by the same address as the one responsible for creating the submitted contract.
In both cases, we assume that all the contracts found through either method correspond to the same blockchain, project name, contract name and ABI.
If you want us to index more than one contract, toggle on Advanced options and select "Yes" to the first question. Then, to the question of "Is it created by a factory contract?" select "No" to index all other contracts with the same bytecode or "Yes" to index all other contracts originating from the same creator.
Although we try to fetch contract information such as the ABI, sometimes this information might not be available through our sources.
In order to properly decode transactions towards 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 via usage of Delegatecall in transactions. This would cause us to miss out on any event logs in the implementation contract's logic, since these are actually fired by the caller (the Proxy in this case) when calling a function through Delegatecall.
When submitting proxy contracts to Dune, you should input the address of the Proxy contract. We then will attempt to fetch the proxy's contract name and the implementation address it's pointing towards. After, we will attempt to source the implementation contract's ABI.
Dune assumes each address in the blockchain can map to at most 1 contract. For this reason, submitting a contract with an address that already exists in
ethereum.contractswill override it for Decoding purposes. This has a couple potential dangerous side effects:
- If the project or contract name has changed, we will generate new tables for all of the contract's methods and events. In turn, previous tables will stop updating, data will be fragmented, and queries will stop working.
- If the ABI has changed in a way that modifies an existing table's parameters, queries that depend on such table might break or become inaccurate.
If you attempt to submit an already existent contract, make sure to include extra context as part of the submission so we can assess whether it's worth overriding the contract's data.
Sometimes, the risk of accepting a re-submission is higher than the perceived value by us, and my result in a rejection. If you disagree, feel free to reach out to us at #decoding in the Dune Discord and we'll see what we can do.
In the interest of data quality, we reject duplicative, incorrect or low quality submissions. To avoid that, make sure to submit accurate contract information.