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

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

Original ERC · ← ERCs