ERC-7831 Multichain address notation (Multi-Chain Addressing)
Draft · Accounts & wallets · created 2024-08-30
A text address notation that appends a human-readable chain name after the account address to specify which chain the funds should be sent to.
Why it is needed
As the Ethereum ecosystem becomes increasingly fragmented across multiple L2s, a single 20-byte address alone cannot indicate which chain a transaction should occur on. Sending funds to the wrong chain risks locking the funds by sending them to an address that cannot receive them. Since EIP-155, the mapping between chain identifiers and chain names has been managed through centralized off-chain lists, which do not scale well as the number of L2s grows and also carry a centralization problem of having to trust the list's maintainer. This standard uses ENS to map chain names to identifiers, allowing chain names to be resolved without a centralized list while retaining the flexibility to change the root chain.
What to implement
function chainId() external view returns (uint64);: Returns the EIP-155 chain identifier of the target chain this bridge connects to.function coinType() external view returns (uint256);: Returns the coin type value used for ERC-2304 style address resolution.function acceptsName(bytes32 keccak) external view returns (bool);: Returns whether this bridge supports the given namehash (chain name).
In depth
Syntax structure
An address takes the form local-part : chain-part [ : root-part ], with colon-separated components arranged left to right from the most specific (the account) to the most general (the root chain). The entire address may optionally be wrapped in parentheses to remove parsing ambiguity. The root-part is optional; the other two parts are required.
Two formats for local-part
The local-part is either a hex-address or an ens-like name. A hex-address is a hexadecimal string of 1 to 40 digits without a 0x prefix, following ERC-55 checksum casing rules; leading zeros may be omitted, and implementations must also support addresses longer or shorter than 20 bytes. An ens-like name must contain at least one dot to distinguish it from a hex string, and a trailing dot is removed before resolution.
chain-part
The chain-part identifies the target chain and must be a valid ENS name as defined by ERC-137.
Root-part and the root chain
The root-part is the EIP-155 chainid written in decimal; it must be omitted if the root chain's chainid is 1, and must be included otherwise. This value determines which chain's deployed ENS is used to resolve the local-part and chain-part. For example, example.eth:optimism resolves against mainnet ENS, while example.eth:optimism:10 resolves against the ENS deployed on the Optimism chain.
Target chain resolution and bridge verification
The agent appends .tbd.eth to the chain-part value and looks up the resulting ENS name via ERC-137's addr on the root chain's ENS to obtain the bridge contract address. It then queries the ChainMetadata interface identifier via ERC-165's supportsInterface; if this returns false, resolution fails. It also calls the bridge's acceptsName with the same namehash; if this returns false, resolution likewise fails.
Local address resolution
If the local-part is hexadecimal, its checksum is verified and the value itself is used as the native address on the target chain. If it is an ens-like name, the trailing dot is removed and the value returned by the bridge's coinType() is used as the coin type to look up ERC-2304's addr on the root chain's ENS.
Checksum algorithm
The casing of the hexadecimal local-part is determined by a variant of the ERC-55 algorithm. The original ERC-55 assumes a 20-byte (40-digit) address, but this standard wraps the nibble_index using the modulo of the hash length to support local-parts of arbitrary length.
Proposal status
This document is currently in Draft status, and key details such as the target chain ENS subdomain name (.tbd.eth) and the ERC-165 interface identifier value for ChainMetadata are marked TODO and not yet finalized. This proposal may change or be discontinued.
Things to watch out for
- Unicode typosquatting: An attacker could register ENS names that look similar to ethereum, such as etherium or ehtereum, to deceive users. ENS libraries filter out many Unicode homoglyphs, but agents must still remain aware of this risk.