--- eip: 7828 title: Interoperable Names description: Defines a human readable chain-specific address format that allows for chain discovery using ENS. author: Sam Kaufman (@SampkaML), Marco Stronati (@paracetamolo), Yuliya Alexiev (@yuliyaalexiev), Jeff Lau (@jefflau), Sam Wilson (@samwilsn), Vitalik Buterin (@vbuterin), Teddy (@0xteddybear), Joxes (@Joxess), Racu (@0xRacoon), Skeletor Spaceman (@0xskeletor-spaceman), TiTi (@0xtiti), Gori (@0xGorilla), Ardy (@0xArdy), Onizuka (@onizuka-wl), Lumi (@oxlumi), Moebius (@0xmoebius), Thomas Clowes (@clowestab), Prem Makeig (@nxt3d), Mono (@0xMonoAx), Orca (@0xrcinus) discussions-to: https://ethereum-magicians.org/t/erc-7828-chain-specific-addresses-using-ens/21930 status: Draft type: Standards Track category: ERC created: 2024-11-27 requires: 155, 7930 --- ## Abstract This proposal defines an Interoperable Name, a chain-specific address format with the structure `
@#`. The `
` can be an address, or an ENS name. The `` can be a [CAIP-350] chain identifier, or it can be a human-readable label. This specification defines how such labels can be resolved to chain-specific metadata, via the Ethereum Name Service (ENS). The optional `` allows clients to verify the integrity of the Interoperable Name. The result is chain-specific addresses such as: - `0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7@eip155:1#80B12379` - `alice.eth@eip155:1` - `alice.eth@ethereum` ## Motivation The current Ethereum address landscape is evolving toward an ecosystem with hundreds, and eventually thousands, of L2s that share the same address format as Ethereum mainnet. This means an address by itself is insufficient to determine which chain it is associated with. This ambiguity can result in funds being sent to an unreachable address on the wrong chain. [ERC-7930] introduced a binary format for representing a _target address_ on a specific blockchain. While this binary data is well suited for low-level usage (e.g. in smart contracts), its meaning is semantically opaque to human users. The core motivation for introducing the _Interoperable Name_ standard is to provide maximally readable, _chain-specific addresses_ for user-facing interactions. A foundational text representation (e.g. `0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7@eip155:1`) enables a significantly more readable _chain-specific address_ format. An expanded form that leverages the name resolution capabilities of the Ethereum Name Service (ENS) further improves readability, allowing addresses to be expressed in a maximally human-friendly form (e.g. `wallet.ensdao.eth@ethereum`). An on-chain registry provides a canonical source of truth for mapping human-readable chain labels to the metadata associated with each chain. Today, chains are identified using a variety of specifications (e.g. [CAIP-2] and [EIP-155] for EVM-compatible networks), whose formats are not necessarily semantically clear to human users. By introducing an on-chain registry, applications can refer to a chain using a readable identifier such as `base`, rather than an opaque identifier like `eip155:8453` or `8453`. Historically, the mapping from chain names to identifiers has, since [EIP-155], been maintained off-chain using a centralized list. This approach has several shortcomings: - It does not scale with the growing number of blockchains - It relies on a trusted centralized maintainer - It does not support non-EVM chains This specification defines an architecture that enables chain operators to take ownership of their chain-specific data, thereby reducing reliance on a single centralized entity and ensuring data integrity. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. ### Terminology This section builds upon the Terminology defined in [ERC-7930]. **Interoperable Name** : A human-readable _chain-specific address_ format meant to be used by humans for user-facing interactions. e.g. `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045@eip155:1#4CA88C9C` ### Interoperable Name Definition The format of an _Interoperable Name_ is `
@#` where the components match the following regular expressions: #### Syntax ```bnf ::=
"@" [ "#" ]
::= [.-:_%a-zA-Z0-9]* ::= [.-:_a-zA-Z0-9]* ::= [0-9A-F]{8} ``` These components have the following meanings: - `
` can either be: - A _target address_ as defined in [ERC-7930]. - An Ethereum Name Service (ENS) name. e.g., `wallet.ensdao.eth` - `` can either be: - The string representation of a specific blockchain as defined in [CAIP-350]. For example `eip155:1` for Ethereum Mainnet, or `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d` for Solana Mainnet. - A human-readable label identifier for a specific chain, defined and registered as a subdomain of the `on.eth` ENS name. An on-chain resolver contract maps these labels to their corresponding canonical [ERC-7930] chain identifiers, and exposes additional chain metadata. - `` is defined as the first 4 bytes (8 characters) of the Keccak-256 hash, represented as a hexadecimal string (Base16, as specified in [RFC 4648]). The hash is computed over the concatenation of the following binary fields from the canonical [ERC-7930] Interoperable Address: - `ChainType` - `ChainReferenceLength` - `ChainReference` - `AddressLength` - `Address` **Note:** The Version field MUST NOT be included in the hashed data. #### Checksums The checksum provides an optional integrity verification mechanism for Interoperable Names that include a raw target address. - The checksum is OPTIONAL but RECOMMENDED when the
component represents a target address, as it helps mitigate homoglyph and spoofing attacks for chain-specific addresses. - A checksum SHOULD NOT be included when the
component is an ENS name - Clients MAY include or omit the checksum when displaying or sharing an _Interoperable Name_. - Clients MAY accept _Interoperable Name_ inputs with or without a checksum. - When a checksum is provided for a target address, clients MAY validate it by deriving the underlying _Interoperable Address_ and recalculating the checksum. UI/UX developers are encouraged to determine the most appropriate way to warn users when a checksum does not match, when resolution fails, or any other scenario they deem necessary to ensure user safety and clarity. #### Versioning This specification does not define its own versioning mechanism. Implementers SHOULD ensure they are up to date with the version of [ERC-7930] they are using. Refer to the versioning section of [ERC-7930] for detailed rules. Implementations MUST maintain convertibility between _Interoperable Names_ and the corresponding [ERC-7930] _Interoperable Address_ binary format. ### _Target Address_ Examples #### Ethereum Mainnet The address `0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7` on Ethereum Mainnet could be represented as either of the following: ``` 0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7@eip155:1#80B12379 0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7@ethereum#80B12379 ``` **Note:** In the second example `ethereum` is the chain label for Ethereum Mainnet in the on-chain ENS resolver set for the `on.eth` namespace (see below). #### Non-EVM chains The address `bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk` on Bitcoin Mainnet could be represented as: ``` bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk@bip122:000000000019d6689c085ae165831e93#597D21A1 bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk@bitcoin#597D21A1 ``` **Note:** In the second example `bitcoin` is the chain label for Bitcoin Mainnet in the on-chain ENS resolver set for the `on.eth` namespace (see below). ### ENS `
` Examples ENS resolves addresses on a chain-specific basis, as outlined in ENSIP-9 and ENSIP-11. **Note:** When the `
` component is an ENS name, a checksum SHOULD NOT be included (see Checksums above). The examples in this section therefore omit the optional `#` suffix. #### Ethereum Mainnet Assuming that `wallet.ensdao.eth` resolves to `0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7` **for Ethereum Mainnet** either of the following could be used to represent the same _target address_: ``` wallet.ensdao.eth@eip155:1 wallet.ensdao.eth@ethereum ``` #### Non-EVM chains Assuming that `wallet.ensdao.eth` resolves to `bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk` **for Bitcoin Mainnet** either of the following could be used to represent the same _target address_: ``` wallet.ensdao.eth@bip122:000000000019d6689c085ae165831e93 wallet.ensdao.eth@bitcoin ``` ### Resolving the `` component If the `` component of an _Interoperable Name_ does not contain a colon (`:`) it is interpreted as being a label under the `on.eth` ENS namespace. The resolver for `on.eth` MUST implement ENSIP-24 - Arbitrary Data Resolution, and allow for the resolution of the [ERC-7930] _Interoperable Address_ for the specified chain label using the key, `interoperable-address`. For example if you resolve the `interoperable-address` data record for `ethereum.on.eth` the _Interoperable Address_ `0x00010000010100` SHOULD be returned. The on-chain resolver for `on.eth` MAY implement aliasing so that multiple chain labels, such as `op.on.eth` and `optimism.on.eth`, resolve to the same underlying data. To ensure consistency and integrity, there must be a single canonical representation of this data. A pseudocode implementation of this resolution is as follows: ```js /** * Pseudocode to resolve the Interoperable Address associated with 'ethereum.on.eth' * Using ENSIP-24 and the data key 'interoperable-address' */ // 1. Inputs const domain = "ethereum.on.eth"; const key = "interoperable-address"; // 2. Derive the Node (Namehash) const node = namehash(domain); // 3. Locate the Resolver for the node const registry = getContract(ENS_REGISTRY_ADDRESS); const resolverAddress = registry.resolver(node); // 4. Instantiate the Resolver const resolver = getContract(resolverAddress); // 5. Resolve the Interoperable Address // ENSIP-24 Interface: data(bytes32 node, string key) -> bytes const rawData = resolver.data(node, key); ``` The resolver for `on.eth` MUST implement ENSIP-5 - Text Records, and allow for the resolution of text records for the `reverse.on.eth` namespace of the form `chain-label:` followed by the [ERC-7930] _Interoperable Address_ you are trying to discern the label for. For example, the _Interoperable Address_ representing Ethereum Mainnet is `0x00010000010100`. Resolution of the text record `chain-label:0x00010000010100` for the `reverse.on.eth` namespace SHOULD return `ethereum`. While multiple labels - such as `op.on.eth` and `optimism.on.eth` — may resolve to the _Interoperable Address_ `0x00010000010a00`, the reverse resolution process will always return the canonical label: `optimism`. A pseudocode implementation of this resolution is as follows: ```js /** * Pseudocode to resolve a chain label from an ERC-7930 Interoperable Address * Using ENSIP-5, the namespace reverse.on.eth, and the text record key chain-label:0x00010000010a00 */ // 1. Inputs const interoperableAddress = "0x00010000010a00"; const namespace = "reverse.on.eth"; // 2. Construct the specific Text Record Key // Format: "chain-label:" + [ERC-7930 Address] const textKey = "chain-label:" + interoperableAddress; // 3. Derive the Node (Namehash) for the reverse namespace const node = namehash(namespace); // 4. Locate the Resolver for 'reverse.on.eth' // As the resolver will be set on the second level domain `on.eth` consideration should be given to ENSIP-10 const registry = getContract(ENS_REGISTRY_ADDRESS); const resolverAddress = registry.resolver(node); // 5. Instantiate the Resolver const resolver = getContract(resolverAddress); // 6. Query the Text Record (ENSIP-5) // Signature: text(bytes32 node, string key) -> string const chainLabel = resolver.text(node, textKey); ``` Additional implementation details about the resolver contract implementation can be discerned by referencing the ENS documentation, and viewing the verified source code of the contract set as the resolver for `on.eth`. ### Resolving the `
` component If the `
` component contains a period (`.`), it is assumed to be an ENS name. Because ENS fully integrates with the Domain Name System (DNS), any traditional domain name can function as an ENS name, as can any name using the blockchain-native `.eth` extension. If an ENS address is used within the `
` component, it MUST be resolved subject to the ENS resolution specifications, giving consideration to the target chain specified in the `` component. The specifications of note are ENSIP-9: Multichain address resolution, ENSIP-10: Wildcard resolution, and ENSIP-11: EVM compatible Chain Address Resolution. These specifications outline how one resolves an ENS name to discern the address **for a specific chain**. Consideration MUST be given to both current and future ENSIPs pertaining to address resolution. If a _target address_ has been used for the `
` component (or once the ENS name has been resolved to a _target address_) it should be serialized subject to the rules defined in the relevant [CAIP-350] profile for the given ``. This ensures that different valid text representations (e.g., case variations in an address) resolve to a single, canonical binary form, which is essential for consistent checksum calculation and data integrity. ## Rationale - The Ethereum Name Service (ENS) is a well-established blockchain identity primitive that enables the registration of human-readable names (e.g. example.eth, wallet.ensdao.eth) which resolve to addresses on a chain-specific basis. ENS is widely used, familiar to users, and well understood by implementers. - For flexibility and backwards compatibility, this specification allows a raw target address to be used in the `
` component, accommodating users and applications that prefer traditional address representations. - In this specification, checksums are defined as OPTIONAL. While they provide meaningful integrity guarantees for raw, chain-specific target addresses, their applicability to ENS-based names is limited. ENS names may resolve to different addresses over time depending on resolver behavior, which means that a previously generated checksum may no longer validate even when resolution is correct. In addition, when using ENS, users already delegate name normalization, resolution, and validation to ENS-specific mechanisms, so applying checksums in these cases provides limited additional security while increasing complexity and ambiguity for implementers. As a result, checksums are primarily intended to protect the integrity of raw, chain-specific addresses, while remaining optional and flexible for user-facing applications. - The [ERC-7930] Version field is excluded from checksum calculation to allow the same Interoperable Name to remain valid across version upgrades of the binary format. ## Security Considerations - Implementers MUST give consideration to the name normalization specifications of the Ethereum Name Service so as to avoid homoglyph or spoofing attacks. These are outlined in ENSIP-1 and ENSIP-15. - Users should stay vigilant of address poisoning attacks when using a raw _target address_ in the `
` component. - ENS resolution depends on resolver contracts set for each name. Resolvers may change over time, and wildcard resolvers (ENSIP-10) may return dynamic data. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md). [BIP 44]: https://github.com/bitcoin/bips/blob/1d371a58978fd2f313c9d162762de04d3b697bf5/bip-0044.mediawiki [EIP-155]: ./eip-155.md [ERC-7930]: ./eip-7930.md [CAIP-2]: https://github.com/ChainAgnostic/CAIPs/blob/36ef9ee906da090366cb679634a0850e91785db6/CAIPs/caip-2.md [CAIP-350]: https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md [RFC 4648]: https://www.rfc-editor.org/rfc/rfc4648 [ENSIP-1]: https://docs.ens.domains/ensip/1/ [ENSIP-5]: https://docs.ens.domains/ensip/5/ [ENSIP-9]: https://docs.ens.domains/ensip/9/ [ENSIP-10]: https://docs.ens.domains/ensip/10/ [ENSIP-11]: https://docs.ens.domains/ensip/11/ [ENSIP-15]: https://docs.ens.domains/ensip/15/ [ENSIP-24]: https://docs.ens.domains/ensip/24/