This package includes a JSON schema for address lists, and TypeScript utilities for working with address lists. It is inspired by and forked from Uniswap’s Token Lists and uses some features from the Chainlist project.
Address Lists are groups of Ethereum addresses that are shareable across apps, wallets, and networks. For example, address books, lists of bad actors, snapshots of token/NFT holders, Sybil tested users, verified smart contracts, or any other grouping.
Anyone can create, validate, or maintain an address list, as long as they follow the specification.
Specifically an instance of an address list is a JSON blob that contains a list of address metadata for use in wallets and dapp user interfaces. Token list JSON must validate against the JSON schema in order to be used. Addresses on address lists, and address lists themselves, are tagged so that users can easily find them.
The JSON schema ID is /src/addresslist.schema.json
This package does not include code for address list validation. You can easily do this by including a library such as ajv to perform the validation against the JSON schema. The schema is exported from the package for ease of use.
import Ajv from 'ajv';
import { schema } from '@uniswap/token-lists'
const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);
const response = await fetch('https://bridge.arbitrum.io/token-list-42161.json')
const listData = await response.json()
const valid = validate(listData)
if (!valid) {
// oh no!
}The best way to manually author token lists is to use an editor that supports JSON schema validation. Most popular code editors do, such as IntelliJ or VSCode. Other editors can be found here.
The schema is registered in the SchemaStore, and any file that matches
the pattern *.tokenlist.json should
automatically utilize
the JSON schema for the supported text editors.
In order for your token list to be able to be used, it must pass all JSON schema validation.
If you want to automate token listing, e.g. by pulling from a smart contract, or other sources, you can use this npm package to take advantage of the JSON schema for validation and the TypeScript types. Otherwise, you are simply working with JSON. All the usual tools apply, e.g.:
import { TokenList, schema } from '@uniswap/token-lists'
// generate your token list however you like.
const myList: TokenList = generateMyTokenList();
// use a tool like `ajv` to validate your generated token list
validateMyTokenList(myList, schema);
// print the resulting JSON to stdout
process.stdout.write(JSON.stringify(myList));Lists include a version field, which follows semantic versioning.
List versions must follow the rules:
- Increment major version when tokens are removed
- Increment minor version when tokens are added
- Increment patch version when tokens already on the list have minor details changed (name, symbol, logo URL, decimals)
Changing a token address or chain ID is considered both a remove and an add, and should be a major version update.
Note that list versioning is used to improve the user experience, but not for security, i.e. list versions are not meant to provide protection against malicious updates to a token list; i.e. the list semver is used as a lossy compression of the diff of list updates. List updates may still be diffed in the client dApp.
Once you have authored the list, you can make it available at any URI. Prefer pinning your list to IPFS (e.g. via pinata.cloud) and referencing the list by an ENS name that resolves to the contenthash.
If hosted on HTTPS, make sure the endpoint is configured to send an access-control-allow-origin header to avoid CORS errors.
An ENS name can be assigned to an IPFS hash via the contenthash text record. This is the preferred way of referencing your list.
You can find a simple example of a token list in test/schema/example.tokenlist.json.
A snapshot of the Uniswap default list encoded as a token list is found in test/schema/bigexample.tokenlist.json.