Token Registration on Bitsy Wiki

Making the Icon

Mon, 01 Jan 0001 00:00:00 +0000

A token icon is displayed at 20 to 24 pixels in a wallet balance row, which is the size at which it does its actual work. Everything else — the 256-pixel version in the repository, the 512-pixel version on the project page — is a downscale target. Design for the 20-pixel render, then produce the seven files the registrars ask for from one vector source.

Constraints that come from the render size#

One mark, no wordmark. The symbol is already printed next to the icon in every interface that shows it. Lettering inside a 20-pixel square is four or five pixels tall and resolves to a smear.
Stroke weight at or above 6% of the canvas. A 256-pixel canvas wants strokes of 16 pixels or more; below that, the 20-pixel downscale drops them to under one pixel and the antialiaser turns them into grey haze.
Two colors, high contrast. Gradients average out at small sizes, so a gradient icon renders as its mean color and stops being distinguishable from every other icon whose mean is a similar blue.
Give the mark its own disc. Surfaces disagree about their background: Etherscan is light, most wallets default to dark, and a transparent icon that is pure black or pure white vanishes on one of them. A filled circle behind the mark makes the icon background-independent and also survives the circular cropping several wallets apply.
Keep the mark inside 88% of the canvas. Interfaces that crop to a circle cut the corners off a square icon.

The source file#

Author in SVG and rasterize from it. A hand-drawn 256-pixel bitmap cannot produce a clean 32-pixel version, but the reverse works every time.

On-Chain Metadata

Mon, 01 Jan 0001 00:00:00 +0000

Two mechanisms let a token carry its own icon without a company’s approval: a metadata document referenced from the contract, and a wallet method your interface can call to push the icon at the user directly. Neither needs a form, a fee, or a queue, and both work in the same block the contract is deployed in.

ERC-1046: a `tokenURI` on a fungible token#

ERC-1046 is Final, and adds one function to ERC-20:

Token Lists

Mon, 01 Jan 0001 00:00:00 +0000

A token list is a JSON document that maps chain identifier and contract address to a name, symbol, decimals count and logo URL. It is the only registration route where you are the publisher rather than the applicant: you write the file, you host it, and a user adds it to their interface by pasting a URL. Uniswap wrote the specification in 2020 and most swap interfaces and several wallets read the format.

Block Explorers

Mon, 01 Jan 0001 00:00:00 +0000

The explorer token page is the first result when anyone searches the contract address, and it is the cheapest registration to obtain: free, no liquidity requirement, no holder count, and turnaround measured in days. It is also the one with a hard prerequisite — the contract source must be verified before the form will open.

Step one: verify the source#

Verification publishes source that recompiles to the deployed bytecode. It proves nothing about who deployed the contract, but every later step depends on it, and an unverified token contract reads as a warning sign to anyone who looks.

Data Aggregators

Mon, 01 Jan 0001 00:00:00 +0000

CoinGecko and CoinMarketCap are two websites, and registering with them is worth more than the traffic they send, because they are the upstream source for a long tail of software that never asks you for anything. MetaMask’s token service, most portfolio trackers, tax tools, and the acceptance criteria of at least one major wallet registry all resolve token metadata through aggregator data. A logo submitted once here surfaces in a dozen places that have no submission form of their own.

Wallet Registries

Mon, 01 Jan 0001 00:00:00 +0000

Before token lists existed, wallets shipped their icons as a directory of files in a public repository, and adding a token meant opening a pull request. Two of those repositories still matter: trustwallet/assets, which is maintained and gatekept, and MetaMask’s contract-metadata, which is frozen. Both are worth understanding mainly to know when to stop trying.

`trustwallet/assets`#

The repository is a directory tree keyed by chain and address:

blockchains/
  ethereum/
    assets/
      0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984/
        logo.png
        info.json

The folder name is the EIP-55 checksummed address in mixed case. Lowercase is rejected by continuous integration before review, as is logo.PNG or Info.JSON — the checks are case-sensitive on both the extension and the filename.

Token Registration on Bitsy Wiki

Making the Icon

Constraints that come from the render size#

The source file#

On-Chain Metadata

ERC-1046: a tokenURI on a fungible token#

Token Lists

Block Explorers

Step one: verify the source#

Data Aggregators

Wallet Registries

trustwallet/assets#

ERC-1046: a `tokenURI` on a fungible token#

`trustwallet/assets`#