ERC-7828 interoperable name (chain-qualified address notation) (Interoperable Names)
Review · Names & metadata · created 2024-11-27
A notation in the form address@chain that lets a human read which chain an address belongs to. Looking up the chain name via ENS (Ethereum Name Service) makes notations like alice.eth@ethereum possible.
Why it is needed
The Ethereum ecosystem is heading toward hundreds, and eventually thousands, of layer 2 (L2) chains that use the same address format as mainnet. An address alone does not reveal which chain it belongs to, creating the risk of sending funds to an unreachable address on the wrong chain. The earlier standard ERC-7930 defined a binary format for holding an address on a specific chain, but it is suited to low-level uses such as contracts and carries no meaning for humans. In addition, the mapping between chain names and identifiers has been managed since EIP-155 through centralized off-chain lists, which cannot keep up with the growing number of chains, depend on a trusted central administrator, and cannot support non-Ethereum-family chains. This standard solves the problem by defining a human-readable chain-qualified address format together with an on-chain registry that lets chain operators register their own chain information directly.
What to implement
data(bytes32 node, string key) -> bytes: The ENSIP-24 arbitrary data resolution interface. Calling it with the interoperable-address key against a label node such as ethereum.on.eth returns that chain's ERC-7930 interoperable address.text(bytes32 node, string key) -> string: The ENSIP-5 text record interface. Calling it against the reverse.on.eth node with a key of chain-label: followed by the interoperable address returns that chain's canonical label.
In depth
Basic structure of the name
An interoperable name takes the form <address>@<chain>#<checksum>. <address> holds either the target address (raw address) defined by ERC-7930 or an ENS name such as wallet.ensdao.eth. <chain> holds either a chain identifier string defined by CAIP-350, such as eip155:1, or a human-readable label registered as a subdomain of on.eth (ethereum, base, etc.). <checksum> is optional and consists of 8 uppercase hexadecimal characters. The same address can be written as either 0xFe89...44b7@eip155:1#80B12379 or 0xFe89...44b7@ethereum#80B12379, and a Bitcoin mainnet address can likewise be written as @bip122:0000...1e93 or @bitcoin.
Checksum calculation rule
The checksum is computed by applying the Keccak-256 hash to the concatenation of the ChainType, ChainReferenceLength, ChainReference, AddressLength, and Address fields of the canonical ERC-7930 interoperable address, then taking the first 4 bytes and writing them as 8 hexadecimal characters (RFC 4648 Base16). The Version field must not be included in the hash input, so that the same name remains valid even as the binary format's version increments. When using a raw target address, the checksum is optional but RECOMMENDED, since it helps reduce homoglyph and spoofing attacks. Conversely, it SHOULD NOT be attached to ENS names, since an ENS name can resolve to a different address over time depending on resolver behavior, which could make an old checksum no longer match. Clients may display the checksum with or without it included, and may accept input in either form.
Resolving the chain label: the on.eth namespace
If <chain> contains no colon (:), it is resolved as a label under the on.eth ENS namespace. The resolver for on.eth must implement ENSIP-24 (arbitrary data resolution) and must return the ERC-7930 interoperable address of the corresponding chain for the interoperable-address key. For example, querying the interoperable-address record of ethereum.on.eth must return 0x00010000010100, representing Ethereum mainnet. A resolver may set up aliases where multiple labels, such as op.on.eth and optimism.on.eth, point to the same data, but there must be a single canonical representation of that data.
Reverse lookup: reverse.on.eth
A reverse lookup that finds the label from a binary chain identifier is also defined. The on.eth resolver must implement ENSIP-5 (text records) and support text records for the reverse.on.eth namespace whose key is chain-label: followed by the ERC-7930 interoperable address. For example, querying chain-label:0x00010000010100 must return ethereum. Even when multiple labels such as op and optimism point to 0x00010000010a00, the reverse lookup always returns the single canonical label, optimism. Since the resolver is set on the second-level domain on.eth, ENSIP-10 (wildcard resolution) must also be taken into account.
Address resolution and normalization
If <address> contains a dot (.), it is treated as an ENS name. Because ENS is integrated with DNS, traditional domain names can be used just like .eth names. An ENS name must be resolved according to the ENS resolution specifications, taking into account the target chain indicated by <chain>; the relevant specifications are ENSIP-9 (multichain address resolution), ENSIP-10 (wildcard resolution), and ENSIP-11 (resolution of addresses for EVM-compatible chains). A raw target address, or an address that has already been resolved via ENS, is serialized according to the CAIP-350 profile rules for that chain. This ensures that multiple valid textual representations, such as differences in letter case, converge to a single canonical binary form, keeping checksum computation and data integrity consistent. Implementations must preserve mutual convertibility between the interoperable name and the ERC-7930 binary format.
Why ENS and an onchain registry
ENS is an already-established blockchain identity primitive that resolves human-readable names into chain-specific addresses, and it is familiar to both users and implementers. For flexibility and backward compatibility, a raw target address is also allowed to be used directly in the <address> slot. Moving the mapping between chain names and identifiers to an onchain registry lets chain operators own their own chain data directly, reducing the limitations of existing offchain centralized lists, which could not keep up with the growing number of chains, depended on a central administrator, and failed to support non-EVM chains.
Proposal status
This proposal is still at the Review stage. Since it is not yet a finalized standard, details such as the format or resolution rules may change going forward. This standard also presupposes ERC-7930 and EIP-155, and since it has no version scheme of its own and follows ERC-7930's versioning rules, implementers must keep the ERC-7930 version they use up to date.
Things to watch out for
- Name normalization and spoofing: Implementers must take into account the ENS name normalization specifications defined in ENSIP-1 and ENSIP-15 to prevent homoglyph attacks, which substitute similar-looking characters, and spoofing attacks.
- Address poisoning: When a raw target address is used in <address>, users must remain cautious of address poisoning attacks, which plant similar-looking addresses in transaction history.
- Risk of resolver changes: ENS resolution depends on the resolver contract set for each name. A resolver can change over time, and a wildcard resolver (ENSIP-10) can return dynamic data.