|
| 1 | +--- |
| 2 | +title: Decoding Contracts |
| 3 | +description: Here's everything you need to know about Decoded contracts and how to submit them! |
| 4 | +--- |
| 5 | + |
| 6 | +Dune contains an extensive catalog of Decoded Contracts, brought into the platform through Wizard submissions! |
| 7 | + |
| 8 | +Instead of working with raw transaction, log, and trace data, contracts are decoded into human-readable tables for each event and function defined in the smart contract's ABI ([Application Binary Interface](https://www.alchemy.com/overviews/what-is-an-abi-of-a-smart-contract-examples-and-usage)). |
| 9 | + |
| 10 | +Learn more about how Decoding works and what Decoded tables are available [here](../../tables/decoded/). |
| 11 | + |
| 12 | +## Submitting a new contract for decoding |
| 13 | + |
| 14 | + |
| 15 | + |
| 16 | +Contracts can be submitted for decoding through: |
| 17 | + |
| 18 | +- [The New contract form](https://dune.com/contracts/new) |
| 19 | +- The [My Creations > Contracts Tab](https://dune.com/browse/contracts/authored) |
| 20 | +- Within the dataset explorer in the Query editor's sidebar: |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +The contract submission form, which consists of 2 steps: |
| 25 | + |
| 26 | +### 1. Blockchain and address |
| 27 | + |
| 28 | +We first ask for the contract's address and blockchain. Requesting this data first has two purposes: |
| 29 | + |
| 30 | +1. To enable us to review for potential duplicate contracts and pending submissions. |
| 31 | +2. To automate parts of the submission process where we can. |
| 32 | + |
| 33 | +The latter is usually accomplished by fetching potentially useful metadata from Dune and other third party sources where relevant. |
| 34 | + |
| 35 | +For instance, below here's an example of submitting the USDT contract (`0x94b008aA00579c1307B0EF2c499aD98a8ce58e58`) in Optimism: |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | +If we can find the contract through a third party source, we will show a green check mark next to the address field. |
| 40 | + |
| 41 | +This means we were able to fetch information such as the contract's name and ABI (Application Binary Interface). |
| 42 | + |
| 43 | +### 2. Contract details |
| 44 | + |
| 45 | +After pressing Next, we ask for other information about the contract that we need in order to decode it: |
| 46 | + |
| 47 | + |
| 48 | + |
| 49 | +If we found the contract through other third party sources, you will only have to fill in the project name. |
| 50 | + |
| 51 | +We have some naming conventions on that, partly due to our technical setup and also to make finding data more predictable. |
| 52 | + |
| 53 | +**Project Names Rules** |
| 54 | + |
| 55 | +- All lowercase |
| 56 | +- No spaces (underscore "_" if needed) |
| 57 | +- Added "_v2" or other version names at the end if applicable |
| 58 | + |
| 59 | +eg `augur`, `tornado_cash`, `uniswap_v2` |
| 60 | + |
| 61 | +Once you submit it, you are done! The contract will be stored in our queue, which we manually review for quality assurance purposes. |
| 62 | + |
| 63 | +!!! note |
| 64 | + |
| 65 | + Submission might take a few days to get processed, please be patient with us! 🙏 |
| 66 | + |
| 67 | +### Advanced options |
| 68 | + |
| 69 | +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. |
| 70 | + |
| 71 | +We have two strategies for detecting other contracts for decoding: |
| 72 | + |
| 73 | +1. **Bytecode match.** We use the bytecode of the contract address in the submission to find other matches in the whole chain history. |
| 74 | +2. **Factory instances.** We find all other contracts created by the same address as the one responsible for creating the submitted contract. |
| 75 | + |
| 76 | +In both cases, we assume that all the contracts found through either method correspond to the same blockchain, project name, contract name and ABI. |
| 77 | + |
| 78 | +If you want us to index more than one contract, toggle on Advanced options and select "Yes" to the first question, "Are there several instances of this contract?" |
| 79 | + |
| 80 | +Then, to the second question - "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: |
| 81 | + |
| 82 | + |
| 83 | + |
| 84 | +!!! warning |
| 85 | + |
| 86 | + Only use these options if you know what you're doing and are extremely familiar with the project's architecture and deployment hierarchy. Incorrectly applying these settings may lead to a rejected submission. |
| 87 | + |
| 88 | +## Tracking your submissions |
| 89 | + |
| 90 | +You can view your submissions and their processing status at any time by navigating to [My Creations > Contracts](https://dune.com/browse/contracts/authored): |
| 91 | + |
| 92 | + |
| 93 | + |
| 94 | +### Frequently Asked Questions |
| 95 | + |
| 96 | +#### How do I submit contract information manually? |
| 97 | + |
| 98 | +!!! note |
| 99 | + If the contract being manually submitted is a Proxy contract, we recommend you to move on to the next section. |
| 100 | + |
| 101 | +Although we try to fetch contract information such as the ABI, sometimes this information might not be available through our sources. |
| 102 | + |
| 103 | +In those instances, you will need to manually input the contract's name and its ABI. |
| 104 | + |
| 105 | +If the contract has been verified by the chain's block explorer, you should be able to find this information there. |
| 106 | + |
| 107 | +[Find a list of each chain's main block explorer here](../reference/wizard-tools/blockchain-explorers.md)! |
| 108 | + |
| 109 | +#### How do I submit a Proxy contract? |
| 110 | + |
| 111 | +In order to properly decode transactions towards contracts that fit the [Proxy pattern](https://blog.openzeppelin.com/proxy-patterns/), Dune needs to map the Proxy contract's address with the implementation contract's ABI. |
| 112 | + |
| 113 | +We avoid monitoring the implementation contract's address because its logic is accessed in transactions via the [`DelegateCall` function](https://medium.com/coinmonks/delegatecall-calling-another-contract-function-in-solidity-b579f804178c). |
| 114 | + |
| 115 | +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`. |
| 116 | + |
| 117 | +!!! warning |
| 118 | + When submitting Proxy-patterned contracts to Dune, you should input the Proxy contract's address and, if you have it, the Implementation contract's ABI.** |
| 119 | + |
| 120 | +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. |
| 121 | + |
| 122 | +If we can't find the Implementation contract's ABI, you'll need to find it using [the relevant chain's blockchain explorer](../reference/wizard-tools/blockchain-explorers.md) and input it manually. |
| 123 | + |
| 124 | + |
| 125 | +#### How do I re-submit a contract? |
| 126 | + |
| 127 | +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 `[blockchain].contracts` will override it for Decoding purposes. |
| 128 | + |
| 129 | +This has a couple potential dangerous side effects: |
| 130 | + |
| 131 | +- 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. |
| 132 | +- 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. |
| 133 | + |
| 134 | +If you attempt to submit a contract that already exists, we'll first present a warning note and ask you to confirm you want to proceed: |
| 135 | + |
| 136 | + |
| 137 | + |
| 138 | +Then, at the bottom of the Details page, we'll ask you to explain why you're resubmitting the contract so we can assess whether it's worth overriding the contract's data: |
| 139 | + |
| 140 | + |
| 141 | + |
| 142 | +If we believe the risk of accepting a re-submission is higher than the added value, we'll reject your resubmission. |
| 143 | + |
| 144 | +If you think we're wrong (we're only human!), feel free to reach out in our [#decoding Discord channel](https://discord.com/channels/757637422384283659/850326962152538122) and we'll discuss it further with you! |
| 145 | + |
| 146 | +#### How do I submit Diamond Proxy contracts? |
| 147 | + |
| 148 | +Similar to vanilla Proxy contracts, [EIP-2535](https://eips.ethereum.org/EIPS/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**. |
| 149 | + |
| 150 | +#### My submission got rejected, why? |
| 151 | + |
| 152 | +In the interest of data quality, we reject duplicative, incorrect or low quality submissions. To avoid rejection, be sure to submit accurate contract information! 🙏 |
| 153 | + |
| 154 | +#### For all other questions: |
| 155 | + |
| 156 | +Head over to the [#decoding Discord channel](https://discord.com/channels/757637422384283659/850326962152538122) and we'll be happy to help! |
0 commit comments