Correctly Resolve Deposit Addresses
Ensure your app correctly resolves which address and chain a deposit to an ENS name should be sent to.
Category
ENS Resolution
Applies to
AppsApp support
51%
Ensure your app correctly resolves which address and chain a deposit to an ENS name should be sent to.
Category
ENS Resolution
Applies to
AppsApp support
51%
When an app needs its users to identify a particular address on a particular chain where an action should be taken (such as a transfer or deposit), ENS offers the possibility of a better user experience. Instead of forcing users to enter a long string of hexadecimal digits, with ENS, users can have the option of entering a simple name such as vitalik.eth. ENS can then be used to translate this input name into the relevant deposit address, such as0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045. This process of determining the deposit address for a name is an example of what is called "resolution".
This best practice checks that your app correctly resolves ENS names to the correct address and chain for different contexts.
The simplest way to get this right—and to continuously and automatically stay up to date with all ENS best practices even as ENS keeps evolving—is to use the ENS Omnigraph API (powered by ENSNode) which handles the implementation details of ENS resolution for you. The implementation recommendations below cover how your engineering team can adopt it, or other supported options.
Apps that fail to correctly implement ENS resolution fail their users and erode trust in important ways. Failure to integrate ENS at all damages the user experience of the app and exposes users to key risks such as address poisoning attacks.
If ENS resolution is integrated, but not according to all ENS best practices, then it can cause big issues. For example, deposits may silently be sent to the wrong address and be irrecoverably lost. Or only a subset of ENS names might be properly supported which damages the network effects and market distribution of ENS.
The baseline test for supporting ENS resolution of deposit addresses is to test with an onchain direct subname of .eth (such as vitalik.eth) where the name is input in fully normalized form and the context for resolving the deposit address is on the Ethereum Mainnet chain.
An app passes this test when it resolves the Ethereum Mainnet address ofvitalik.eth to 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045.
An app fails this test when it does not accept ENS names at all as input or fails to correctly resolve the Ethereum Mainnet address of vitalik.eth to anything other than the correct value (0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045).
This variation of the baseline test changes the input name to Ξthereum.eth.
This acceptance test verifies correct implementation of ENS name normalization and input validation rules. This name is valid for input as an ENS name. It is not ENS normalized but it is ENS normalizable.
An app passes this test when it correctly normalizes the input name from Ξthereum.eth to ξthereum.eth and then resolves the Ethereum Mainnet address of ξthereum.eth to 0x31C09F0616532F7a6f33d9ee4e1F45Ea529481af.
An app fails this test when it does not accept normalizable ENS names such as Ξthereum.eth as input or fails to correctly normalize this input to ξthereum.eth or fails to correctly resolve this input to anything other than the correct value (0x31C09F0616532F7a6f33d9ee4e1F45Ea529481af).
This variation of the baseline test changes the input name to jesse.base.eth.
This acceptance test verifies correct implementation of CCIP-read for a subname nested beneath .eth.
An app passes this test when it correctly resolves the Ethereum Mainnet address of jesse.base.eth to 0x2211d1D0020DAEA8039E46Cf1367962070d77DA9.
An app fails this test when it does not accept ENS names such as jesse.base.eth as input or fails to correctly resolve this input to anything other than the correct value (0x2211d1D0020DAEA8039E46Cf1367962070d77DA9).
This variation of the baseline test changes the input name to dperri.com.
This acceptance test verifies correct implementation of CCIP-read for DNS names that have not been imported onchain but are still valid ENS names.
An app passes this test when it correctly resolves the Ethereum Mainnet address of dperri.com to 0x0b08dA7068b73A579Bd5E8a8290ff8afd37bc32A.
An app fails this test when it does not accept ENS names such as dperri.com as input or fails to correctly resolve this input to anything other than the correct value (0x0b08dA7068b73A579Bd5E8a8290ff8afd37bc32A).
This variation of the baseline test makes two changes: (1) the input name changes to lightkeeper.eth and (2) the context of the resolution changes from Ethereum Mainnet to another EVM chain (the Base chain that's operated by Coinbase).
This acceptance test verifies correct implementation of resolving the address for a name in the context of different EVM chains.
An app passes this test when it correctly resolves the Base chain address of lightkeeper.eth to 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045.
An app fails this test when it fails to correctly resolve this input to anything other than the correct value (0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045).
This variation of the baseline test makes two changes: (1) the input name changes to gregskril.eth and (2) the context of the resolution changes from Ethereum Mainnet to the non-EVM chain Bitcoin.
This acceptance test verifies correct implementation of resolving the address for a name in the context of a non-EVM chain such as Bitcoin.
An app passes this test when it correctly resolves the Bitcoin address of gregskril.eth to 3NnpwUMGdGKuYaPDQagNXAgVXz9HdnJDNS.
An app fails this test when it does not accept ENS names such as gregskril.eth as input when sending to non-EVM chains such as Bitcoin or fails to correctly resolve this input to anything other than the correct value (3NnpwUMGdGKuYaPDQagNXAgVXz9HdnJDNS).
This variation of the baseline test makes two changes: (1) the input name changes to gregskril.eth and (2) the context of the resolution changes from Ethereum Mainnet to the non-EVM chain Solana.
This acceptance test verifies correct implementation of resolving the address for a name in the context of a non-EVM chain such as Solana.
An app passes this test when it correctly resolves the Solana address of gregskril.eth to 2JQANQn1kccapb7GT8XScf9qBy59uMo9vh9WwVQhwStJ.
An app fails this test when it does not accept ENS names such as gregskril.eth as input when sending to non-EVM chains such as Solana or fails to correctly resolve this input to anything other than the correct value (2JQANQn1kccapb7GT8XScf9qBy59uMo9vh9WwVQhwStJ).
This variation of the baseline test makes two changes: (1) the input name changes to zissou.eth and (2) the context of the resolution changes from Ethereum Mainnet to the EVM chain Base.
This acceptance test verifies correct implementation of resolving the address for a name on an EVM chain that is not formatted as a valid EVM address (not a 20-byte hex value), instead resolving to (invalid address).
An app passes this test so long as it gracefully handles the resolved address being an invalid EVM address. Here we define gracefully as not breaking the overall user experience.
An app fails this test if the resolution of an invalid EVM address is not handled gracefully and breaks the overall user experience.
Although the UI shows a resolved address, this fails because zissou.eth cannot be resolved on Base (because the address record saved on Base for this name is not a valid EVM address) and is silently falling back to the Ethereum Mainnet address, which risks irrecoverable loss of funds.
There are a few ways to make sure your app's ENS resolution follows all best practices.
1. Take full responsibility yourself.
One option is to take the full responsibility for implementing all of these details correctly yourself and continuously and rigorously testing your app for continued compliance.
2. Use the ENS Omnigraph API (recommended).
Another, more highly recommended option is to simply perform your ENS resolutions through the ENS Omnigraph API (powered by ENSNode).
Fetch your ENS data through the ENS Omnigraph API and everything just works. It's a single typed GraphQL API over both ENSv1 and ENSv2 for every chain and offchain names too. It also handles the indexed ENS data your app reads (e.g. the names an address owns, profiles, histories, etc.), with resolutions accelerated by Protocol Acceleration. Drop it in with enssdk (TypeScript) or enskit (React).
All ENS best practices on ENSAwards are open for public contribution.
All ENS best practices on ENSAwards are open for public contribution.
Founded in 2022, Namehash Labs is dedicated to developing open source infrastructure that helps the Ethereum Name Service (ENS) Protocol grow.