Список токенов и метки адресов

Что такое список

Два файла на каждую сеть. tokenlist.json перечисляет проверенные токены в стандартном формате Uniswap Token Lists, так что любой кошелёк, интерфейс DEX или агрегатор может импортировать его как есть. tags.json даёт известным контрактам читаемую подпись - имя, категорию и проект, - чтобы обозреватель мог показать «Pepper router» там, где иначе стоял бы шестнадцатеричный адрес.

Токен из списка получает отметку проверки, свой логотип, имя и символ в обозревателе, на Pepper, в Toolkit, на Names и на странице Account. Контракт с меткой отображается под своей подписью в списках транзакций, на страницах адресов и в поиске.

Ничего не попадает в список автоматически. Токен, выпущенный через лаунчер токенов Pepper, не добавляется просто потому, что существует; он добавляется, когда кто-то открывает pull request и токен соответствует критериям.

Где он находится

Список находится в публичном репозитории GitHub, github.com/PickleChain/token-list, по одной папке на каждую сеть:

Внутри папки сети:

Raw-URL, всегда последний коммит в main:

https://raw.githubusercontent.com/PickleChain/token-list/main/testnet/tokenlist.json
https://raw.githubusercontent.com/PickleChain/token-list/main/testnet/tags.json

Для сайта загружайте файлы на сервере и отдавайте их со своего источника, а не ссылайтесь на raw.githubusercontent.com напрямую из браузеров посетителей: так их IP-адреса не уходят третьей стороне, вы не упираетесь в лимиты частоты GitHub и можете держать последнюю исправную копию, когда GitHub недоступен. В кошельке или интерфейсе DEX добавьте raw-URL файла tokenlist.json как пользовательский список токенов.

Как его используют приложения Pickle

API обозревателя - единственная часть стека Pickle, которая обращается к GitHub за этими файлами. Он загружает оба примерно каждые десять минут, проверяет каждый файл целиком - структуру, chain ID, контрольные суммы, дубликаты - и держит последнюю исправную копию в памяти и на диске. Файл, не прошедший проверку, отклоняется полностью, и в работе остаётся предыдущий, так что неудачный коммит никогда не сотрёт подпись или логотип. Каждый сайт Pickle затем читает копию обозревателя со своего собственного источника:

Маршруты находятся на https://explorer.picklechain.xyz, за списком разрешённых источников CORS обозревателя: они обслуживают сайты Pickle. Ваше собственное приложение читает raw-файлы, указанные выше.

Добавить токен

Сначала проверьте критерии: pull request для токена, который им не соответствует, закрывается. Затем в своём форке репозитория:

1. Получите адрес с контрольной суммой. Смешанный регистр EIP-55, а не все строчные. Если ваш адрес неверен, валидатор выведет ожидаемую форму.
2. Добавьте логотип в testnet/logos/tokens/, назвав его ровно по этому адресу: testnet/logos/tokens/0x0000…dEaD.png (или .svg). Он должен соответствовать правилам для логотипов.
3. Добавьте запись в конец tokens в testnet/tokenlist.json, как в примере ниже.
4. Поднимите версию tokenlist.json - добавление токена означает минорное повышение, 1.4.2 становится 1.5.0, - и установите timestamp на текущий момент в ISO 8601 UTC.
5. Запустите проверки командой npm test. Нужен Node 22 или новее и больше ничего: у валидатора нет зависимостей, так что устанавливать нечего.
6. Откройте pull request в main. В его описании дайте ссылку на публикацию на собственном сайте проекта или в его официальном аккаунте, где назван адрес контракта.

{
  "chainId": 78270,
  "address": "0x0000…dEaD",
  "name": "Example Token",
  "symbol": "EXM",
  "decimals": 18,
  "logoURI": "https://raw.githubusercontent.com/PickleChain/token-list/main/testnet/logos/tokens/0x0000…dEaD.png",
  "extensions": {
    "website": "https://your-project.example",
    "explorer": "https://explorer.picklechain.xyz/address/0x0000…dEaD"
  }
}

0x0000…dEaD обозначает ваш полный 42-символьный адрес с контрольной суммой; это заполнитель, а не токен.

Весь путь в командной строке:

# Fork and clone (or fork on the website and clone your fork):
gh repo fork PickleChain/token-list --clone
cd token-list
git checkout -b add-exm

# Logo, entry, version and timestamp, then:
npm test

git add testnet/tokenlist.json testnet/logos/tokens/
git commit -m "Add Example Token (EXM)"
git push origin add-exm
# ...and open the pull request on GitHub.

Правила для логотипов

На каждый файл в logos/ должен ссылаться список или метки. Логотип, на который ничто не указывает, не проходит проверки, поэтому удаляйте его в том же pull request, что и его запись.

Добавить метку адреса

Метки предназначены для контрактов, с которыми люди сталкиваются в транзакциях: контракты протокола, роутеры, фабрики, пулы, хранилища, игры, мосты. Личные кошельки не помечаются никогда. Проект должен работать в Pickle Chain, а адрес должен проверяться по собственной документации проекта или его файлам развёртывания.

1. Добавьте запись в tags в testnet/tags.json с адресом с контрольной суммой в качестве ключа.
2. При желании добавьте логотип в testnet/logos/tags/ - те же правила формата, что и для логотипа токена, любое имя файла - и укажите в logo его raw-URL. Несколько меток одного проекта могут делить один файл.
3. Поднимите версию tags.json и его timestamp, запустите npm test и откройте pull request.

"0x0000…dEaD": {
  "name": "Example vault",
  "category": "protocol",
  "project": "Example",
  "url": "https://your-project.example",
  "logo": "https://raw.githubusercontent.com/PickleChain/token-list/main/testnet/logos/tags/example.png",
  "note": "Holds deposits and pays out the weekly yield."
}

Категории, определённые на сегодня:

Если ни одна не подходит, предложите новую категорию в том же pull request: ключ в нижнем регистре длиной до 20 символов, с name и description.

Изменить или удалить запись

• Изменить запись - имя, примечание, сайт, десятичные знаки - можно, отредактировав её на месте и подняв патч-версию. Открывайте pull request от команды токена, как и при добавлении.
• Изменить логотип можно, заменив файл. Переход между PNG и SVG меняет его имя, поэтому обновите logoURI и удалите старый файл.
• Заменить контракт можно, добавив новый адрес. Для метки сохраните старую запись и добавьте к её имени суффикс (previous), чтобы старые транзакции по-прежнему читались понятно.
• Удалить запись можно, удалив её вместе с файлом логотипа и подняв мажорную версию.

Мейнтейнеры могут удалить токен в любой момент - после взлома, rug pull, перехода на новый контракт или вводящего в заблуждение изменения метаданных.

Версии

У каждого файла своя version, и повышение следует правилам Token Lists. CI проверяет его относительно базовой ветки pull request, а изменённая версия требует более нового timestamp.

npm test                                      # every list and logo, then the validator's own tests
node scripts/validate.mjs --base origin/main  # also the version bumps, as CI checks them

Что проверяет ревью

Каждый pull request запускает npm test и проверку версии в GitHub Actions, после чего его смотрит мейнтейнер. Токен добавляется, когда выполнены все условия:

• Он развёрнут в сети этой папки, а его исходный код верифицирован или опубликован.
• Pull request открыт или подтверждён командой токена, со ссылкой на публикацию на собственном сайте проекта или в его официальном аккаунте, где назван адрес контракта.
• Его имя и символ не подражают другому токену или проекту. Новый PKL или WETH будет отклонён.
• У него есть реальное применение: ликвидность на Pepper, держатели или работающий продукт, - а не токен, выпущенный несколько минут назад.
• В контракте нет скрытого минта, чёрного списка или переключателя комиссии, о которых команда не сообщила.

Метка добавляется, когда адрес является контрактом, проект работает в Pickle Chain, а адрес можно проверить по собственной документации проекта или его файлам развёртывания.

Частые ошибки валидации

npm test выводит все проблемы, а не только первую. Те, что встречаются чаще всего, и как их исправить: