​

Dune Contract Decoding Best Practices Guide

​

Introduction

​

Before You Begin

• Start with the basics: Review Andrew’s Decoding 101 video
• Reference documentation @ Dune Docs | Decoding Contracts
• Leverage AI assistance: Use the “Ask AI” feature throughout Dune documentation for quick help

​

Quick Reference: Submission Checklist

• Identify the contract type (single, created by a factory, proxy)
• Locate the correct ABI (implementation, not proxy)
  • For more information, check this Documentation by OpenZeppelin
• If submitting for multiple chains use a multichain explorer like Blockscout to determine which chains a contract has been deployed on (Please note: if an address exists on another chain that doesn’t mean that it is a contract on that chain, so make sure to validate this by ensuring that the address is a contract on that specific chain)
• Check for identical bytecode across addresses
• Document any special patterns or versions

​

Quick Decision Tree

​

Contract Decoding Scenarios

​

Single Smart Contract on Single Chain

• Submit the contract’s ABI with the specific contract address and chain
• Straightforward process with no special considerations

• Contract: 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e (Ethereum only)
• Action: Submit ENS Registry ABI for this specific address on Ethereum

​

Single Contract on Multiple Chains

• Submit the same ABI once
• Specify all chains where it’s deployed
• Use the same submission if addresses match across chains

• Contract: 0x66A71Dcef29A0fFBDBE3c6a460a3B5BC225Cd675 (multiple chains)
• Action: Submit as “Submit as multiple chains” with same ABI for all chains with this address and select the chains

​

Factory-Deployed Contracts (Single Chain)

• Submit the ABI for the created contracts, NOT the factory ABI
• Mark as factory-deployed in submission
• Include sample addresses of created contracts

• Factory: 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f
• Sample Pair: 0xB4e16d0168e52d35CaCD2c6185b44281Ec28C9Dc (USDC/ETH)
• Action: Submit UniswapV2Pair contract & ABI (not factory ABI)
• Tip: If an ABI isn’t verified for certain addresses, the ABI will be the same across chains in the same project (ie., UniswapV2Pair ABI is going to be the same on all EVM chains regardless of the address)

​

Factory-Deployed Contracts (Multiple Chains)

• Submit the created contract’s ABI once
• Select all chains where factories exist
• Check the “Decode other contracts deployed by the same factory” checkbox
• The submission will detect factory-created instances on each selected chain

• Ethereum Factory: 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f
• Polygon Factory: 0x5757371414417b8C6CAad45bAeF941aBc7d3Ab32
• Arbitrum Factory: 0xf1D7CC64Fb4452F05c498126312eBE29f30Fbcf9
• Action: Submit UniswapV2Pair ABI once, select all three chains, enable factory flag

​

Contracts with Identical Bytecode (Single Chain)

• Submit one ABI that covers all instances
• Check the “Enable bytecode matching” checkbox
• Note the shared bytecode pattern

• cUSDC: 0x39AA39c021dfbaE8faC545936693aC917d5E7563
• cETH: 0x4Ddc2D193948926D02f9B1fE9e1daa0718270ED5
• Action: One cToken ABI submission covers all

​

Contracts with Identical Bytecode (Across Multiple Chains)

• Submit one ABI specifying all chains and addresses
• Check the “Enable bytecode matching” checkbox

• Address: 0xd9Db270c1B5E3Bd161E8c8503c55cEABeE709552 (multiple chains)
• Action: One Safe ABI submission for all chains

​

Proxy Contract Patterns

​

Basic Proxy Rules

• Submit the proxy address
• Decode using the implementation’s functions
• The implementation contains the actual business logic
• To check if your contract is a proxy, you can visit a block explorer like etherscan.io and click into the “Contract” section. If you see “Read as Proxy” and “Write as Proxy” as the image below then select the ABI of the implementation contract.
• For more resources:
  • https://info.etherscan.com/what-is-proxy-contract/
  • https://etherscan.io/proxyContractChecker

​

Proxy Contract (Single Chain)

• Proxy: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
• Action: Use implementation ABI, submit proxy address

​

Proxy Contract (Multiple Chains)

• Use implementation ABI
• Specify all proxy addresses across chains
• Include implementation addresses in notes

​

Advanced Patterns

​

Upgradeable Proxies

​

Transparent Upgradeable Proxy

• Use the Proxy Contract Address: Submit using the proxy contract’s address (not the implementation contract address)
• Use the Implementation Contract’s ABI: You must provide the ABI of the implementation contract (not the proxy contract’s ABI)
• Submit Initial implementation then it is best to:
  • Resubmit each implementation version as “upgrade the ABI of a contract” with the new implementation ABI each time.
• Use the same name for all implementations (e.g., just “uniswap_v3” for all versions)
  • The system will handle merging and version tracking automatically
• Track upgrade events if needed

• Proxy: 0xEe6A57eC80ea46401049E92587E52f5Ec1c24785
• Implementation V1: 0x0882477e7895bdc5cea7cb1552ed914ab157fe56

​

Beacon Proxy

• Contract Address: Use the Beacon proxy contract address (the actual proxy that users interact with)
• Submit beacon’s implementation ABI: Use the implementation contract’s ABI (not the beacon or proxy ABI)
• For additional beacon proxies with the same implementation:
  • Use the same project name and contract name
  • Check “Are there several instances of this contract?” if they have identical bytecode
  • This will consolidate them into the same decoded tables
• All proxies decode using same ABI
• Note the beacon pattern in comments

​

Diamond Proxy (EIP-2535)

• Option A: Submit each facet’s ABI separately as upgrades
  • Submit the first facet ABI as a new contract
  • Submit additional facet ABIs as “upgrades” to the same contract
  • Use the same project name and contract name for all submissions
  • Dune will merge the ABIs in the background
• Option B: Create one combined ABI with all facet functions
  • Merge all facet ABIs into a single file before submission
  • Submit once as a new contract

• Each facet typically has its own purpose (e.g., deposits, payments, lending)
• Even though facets have distinct names, submit all under the same contract name
• Query by event/function name to distinguish between facets
• Facets can be updated independently - submit new versions as upgrades
• Contact Dune support via Slack (For Enterprise Customers), Telegram (Paid Customers), Discord, or email support@dune.com if you have questions about the submission process

​

Factory Variations

​

Multi-Type Factories

• Submit separate contracts individually, in this case do NOT check “is created by factory”
• Submit separate ABIs for each contract type
• TLDR; you will need to submit each contract individually
• Clear naming convention for each type
• Document the factory’s capabilities
• Reach out to Dune Support if you have any questions

​

Minimal Proxy (EIP-1167)

• Address: Use minimal proxy contract address
• ABI: Submit implementation (master/template) contract ABI
• For EIP-1167 minimal proxies that have multiple clones deployed from the same factory:
  • Check the “Are there several instances of this contract?” box during submission
  • Dune only considers a contract a dynamic instance if the bytecode matches 100%
• Note the clone pattern

• Master: 0xd9Db270c1B5E3Bd161E8c8503c55cEABeE709552
• All clones use master’s ABI

​

Version Management

​

Multiple ABI Versions

• Submit each version separately
  • First submission, submit normally, then each submission afterwards would need to be a resubmission with the upgraded ABI
• Document version differences

​

Gradual Cross-Chain Rollouts

• Start with latest/most complete ABI
• Add chains as they deploy
• Note any chain-specific differences

​

Edge Cases & Special Situations

​

Self-Destructed and Redeployed Contracts

• Resubmit new ABI with updated deployment info
• Clearly note the redeployment
• Include destruction/redeployment dates

​

Factory-Deployed Proxies

• The address to use would be the address of one of the created proxies
• Submit the proxy’s implementation ABI
• Note both factory and proxy patterns
• Clear documentation is crucial

​

Common Mistakes to Avoid

1. Submitting Factory ABIs: Always submit the created contract’s ABI, not the factory’s
2. Using Proxy ABIs: Always use implementation ABIs for proxy contracts
3. Missing Chains: Use tools like Blockscout to find all deployments
4. Poor Naming: Use descriptive names that include version/type info
5. Incomplete Documentation: Always note special patterns or deployment methods

​

Best Practices Summary

1. Start Simple: Begin with one chain, expand gradually
2. Focus on Logic: Always decode using the contract with actual business logic
3. Document Everything: Use submission comments for complex patterns
4. Version Clearly: Use descriptive naming for different versions/types
5. Verify Thoroughly: Double-check addresses and bytecode matches
6. Think User-First: Make contract interactions readable regardless of complexity

​

Troubleshooting Tips

• Can’t find all deployments? Start with what you have—you can add more chains later
• Unsure about bytecode? Use Etherscan’s “Similar Contracts” feature
• Complex proxy pattern? Focus on the final implementation that executes
• Factory creating variants? Submit separate ABIs for each variant type

​

Additional

​

Check Your Work

​

Check Contract Submissions for Decoding

​

Check if Contract is decoded on the specific blockchain

select *
from {blockchain}.contracts
where address = 0x...

​

Verify the table exists and has data

/* Verify the table exists and has data */
SELECT
    COUNT(*) AS total_rows,
    MIN(evt_block_time) AS first_event,
    MAX(evt_block_time) AS latest_event
FROM eigenlayer_ethereum.DelegationManager_evt_OperatorSharesIncreased
-- replace above line with {your_project_ethereum.yourcontract_evt_yourevent};

​

Check all columns are properly decoded

-- Check all columns are properly decoded
DESCRIBE eigenlayer_ethereum.DelegationManager_evt_OperatorSharesIncreased;
-- replace above line with {your_project_ethereum.yourcontract_evt_yourevent};

-- Or get column info
-- Ethereum
SELECT 'ethereum' as chain, column_name, data_type
FROM information_schema.columns
WHERE table_name = 'factory_evt_poolcreated'
AND table_schema = 'uniswap_v3_ethereum'
UNION ALL
-- Add other chains as needed
SELECT 'worldchain' as chain, column_name, data_type
FROM information_schema.columns
WHERE table_name = 'uniswapv3factory_evt_poolcreated'
AND table_schema = 'uniswap_worldchain';

​

Expected Tables and Event Types

• Search the contract in the data explorer to view both the tables and events related to the contract

​

When NOT to Decode

• Pure libraries (no deployable bytecode)
• Contracts with only view functions
• Simple forwarder/relay contracts
• Contracts that only emit standard ERC20/721 events
• Test/deprecated contracts with no usage
• Contracts with no transactions are not needed to decode

• Governance contracts (usually low activity)
• Admin/owner contracts (minimal events)
• Price oracle contracts (mostly reads)

​

Remember

• One ABI can decode thousands of contracts
• Namespaces can’t be merged or moved
• 100% bytecode match is strict
• Factory pattern and bytecode finds future contracts too
• Plan namespace structure before submitting