ERC-6734 L2 token list standard (L2 Token List)
Review · Names & metadata · created 2023-03-20
Defines a common token list (JSON) format that lets the same token be identified without confusion across multiple chains (layer 1, layer 2, sidechains). Lets you tell from the list alone which chain a token was issued on and what its original asset is.
Why it is needed
The Ethereum ecosystem includes not just mainnet (layer 1) but also multiple chains such as layer 2s and sidechains. When a token is moved to another chain via a bridge, a new representation of the token is created on that chain, but there is no agreed way to determine which one is the canonical token. Currently, layer 2s such as Arbitrum and Optimism each maintain their own token lists with different extension fields, and they judge canonicity based on the combination of token name and symbol. Existing lists also bundle information about the specific bridge a token can pass through, but since that bridge is not the only way to move the token, the token list and bridge information should be separated. In this state, it is difficult for systems to handle tokens on different chains consistently. This standard therefore proposes a common list format that can uniquely identify a token across chains and make its purpose clear.
In depth
Required top-level list fields [R1]
A conformant token list must include 7 data elements: type, tokenListId, name, createdAt, updatedAt, versions, and tokens. tokenListId is a resolvable URI in RFC 3986 format pointing to where the list is published, and versions is a version array containing major, minor, and patch integers. createdAt and updatedAt record when the list was created and updated. Including the remaining schema fields, such as logoURI and keywords, is also RECOMMENDED ([D1]). The schema sets additionalProperties to false, so undefined properties are not allowed.
Required token entry fields [R2]
Each entry in the tokens array must include at least chainId, chainURI, tokenId, tokenType, address, name, symbol, decimals, createdAt, and updatedAt. chainURI is a resolvable URI pointing to the genesis block of the chain the token was issued on, and tokenId is a URI such as the token deployment transaction or a DID that identifies the token and its issuer. tokenType is an array describing the nature of the token, such as ["fungible","transferable"]. Optional fields include genesisBlockHash (the genesis block hash), tokenIssuerId and tokenIssuerName (the issuer), standard (a URI describing the token standard), addressType, addressAlg (an address generation algorithm such as CREATE2), tokenDesc, and logoURI.
Disclosing the original chain with extensions
When a list entry points to a token on a chain other than the one it was originally issued on, extensions is used. When extensions is used, it must fill in three fields: rootChainId (the original chain number), rootChainURI (a URI to the original chain's genesis block), and rootAddress (the original token contract address). Unlike existing Arbitrum and Optimism lists, which put a specific bridge's address in an extension field, this standard separates standardization of bridges and route lists into a separate document and only records information about the token's origin.
URI and chainId rules [R3][R4]
All attributes specified as a URI in the schema description must follow RFC 3986 semantics ([R3]). chainId must be a value that satisfies the requirements of the EIP-155 standard, that is, a value that ensures transaction replay protection on that chain ([R4]). For replay protection to be guaranteed, chainId must be unique, but the method of guaranteeing uniqueness is outside the scope of this document. The source explains that both requirements can be verified with existing cryptographic libraries and public tools.
humanReadableTokenSymbol rule
The human readable token symbol field is optional ([O1]). However, if this field is used, it must be constructed by joining tokenSymbol and chainId with a hyphen, in that order ([CR2]>[O1]). In the source example, if tokenSymbol is ETH and chainId is 1, humanReadableTokenSymbol becomes ETH-1. The schema example also includes MATIC-137. This way, the chain on which the token was issued or moved to is also reflected in the symbol notation.
JSON-LD and DID based design
This schema can be used as a JSON-LD schema when paired with a JSON-LD context file, linking schema.org terms in each field's $comment to clarify the meaning and usage of terms. It is designed to integrate easily with self-sovereign identity frameworks such as W3C DID (Decentralized Identifiers) and W3C Verifiable Credentials, enabling interoperability when identifying entities such as token issuers across multiple chains. Implementers can use existing tooling built around JSON-LD, DID, and Verifiable Credentials as is.
Conformance levels and attestation
Implementation conformance is divided into three levels. Level 1 satisfies all MUST requirements, Level 2 satisfies MUST and SHOULD requirements, and Level 3 satisfies all requirements including MAY requirements with conditional MUST/SHOULD, and must demonstrate this with a test report. When claiming conformance, it is recommended to describe the test procedure performed for each requirement ([D2]), and to claim Level 2 or higher, describing the test procedure is mandatory for each requirement at that level ([R5]). A standardized set of test fixtures to verify all requirements has not yet been defined and is planned for release in the next version of the standard.
Proposal progress status
This document was written by the L2 working group of an EEA community project managed by OASIS, and was created on March 20, 2023. It is currently a proposal in Review status, so the content may still change. Standards defining the tokens themselves and standardization of bridge and route lists are outside the scope of this document; the bridge list will be addressed in a separate document.
Things to watch out for
- Potential links to malicious URIs: URIs contained in the list could link to dangerous resources such as malicious websites. Implementers must verify that the data used in official token lists is safe and accurate.
- Data privacy is the implementer's responsibility: The standard does not establish any country's laws or compliance requirements. It is the implementer's responsibility to comply with applicable data privacy laws.
- Due diligence required when choosing tools: The standard does not require the use of any specific application, tool, or library, so implementers must conduct sufficient review themselves when choosing one.
- String internationalization recommended: It is recommended to appropriately follow the W3C best practices guide regarding language and text direction metadata for strings used on the web.