代币列表与地址标签

这份列表是什么

每个网络两个文件。tokenlist.json 列出经过审核的代币，采用标准的 Uniswap Token Lists 格式，所以任何钱包、DEX 界面或聚合器都可以原样导入。tags.json 给知名合约一个可读的标签，即名称、类别和项目，这样浏览器就能在原本显示十六进制地址的地方显示「Pepper router」。

被收录的代币会在浏览器、Pepper、Toolkit、Names 和 Account 页面上显示已验证标记、它的 logo、名称和符号。被打上标签的合约在交易列表、地址页和搜索中都以它的标签显示。

没有任何东西会被自动收录。用 Pepper 的代币发行器发行的代币，不会因为存在就被加进来；只有当有人提了 pull request 并且它符合标准时，才会被加入。

它放在哪里

这份列表放在一个公开的 GitHub 仓库里，github.com/PickleChain/token-list，每个网络一个文件夹：

一个网络文件夹里面：

原始文件 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 界面里，把 tokenlist.json 的原始 URL 添加为自定义代币列表即可。

Pickle 应用如何使用它

在整个 Pickle 技术栈里，只有浏览器 API 会为这些文件去访问 GitHub。它大约每十分钟抓取一次这两个文件，把每个文件作为整体校验一遍，包括结构、链 ID、校验和、重复项，并把最后一份有效副本保存在内存和磁盘上。校验失败的文件会被整个拒绝，之前那份继续使用，所以一次坏提交永远不会让某个标签或 logo 变成空白。之后每个 Pickle 站点都从自己的来源读取浏览器的这份副本：

这些路由位于 https://explorer.picklechain.xyz 上，受浏览器的 CORS 允许名单保护：它们服务于 Pickle 站点。你自己的应用请读取上面的原始文件。

添加一个代币

先看一下标准：不符合标准的代币的 pull request 会被关闭。然后在你 fork 的仓库里：

1. 拿到校验和格式的地址。EIP-55 大小写混合，不是全小写。如果你的写错了，校验器会打印出正确的形式。
2. 添加 logo 到 testnet/logos/tokens/，文件名与该地址完全一致：testnet/logos/tokens/0x0000…dEaD.png（或 .svg）。它必须符合 logo 规则。
3. 追加一个条目到 testnet/tokenlist.json 的 tokens 中，如下面的示例所示。
4. 提升 tokenlist.json 的版本号：添加代币是一次 minor 升级，1.4.2 变成 1.5.0；并把 timestamp 设为当前时间，采用 ISO 8601 UTC 格式。
5. 运行检查：npm test。它只需要 Node 22 或更高版本，别无其他：校验器没有任何依赖，所以什么都不用安装。
6. 向 main 提一个 pull request。在描述里附上一个链接，指向项目自己的网站或官方账号上写明了该合约地址的帖子。

{
  "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.

Logo 规则

logos/ 下的每个文件都必须被列表或标签引用。没有被任何东西引用的 logo 会导致检查失败，所以删除条目时，请在同一个 pull request 里一并删除它的 logo。

添加一个地址标签

标签是给人们在交易中会遇到的合约用的：协议合约、路由器、工厂、池子、金库、游戏、跨链桥。个人钱包永远不会被打标签。项目必须已经在 Pickle Chain 上运行，并且地址必须能在项目自己的文档或部署文件中核实。

1. 添加一个条目到 testnet/tags.json 的 tags 中，以校验和格式的地址为键。
2. 可选地添加一个 logo 到 testnet/logos/tags/：格式规则与代币 logo 相同，文件名随意；然后把 logo 指向它的原始 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。

更新或移除一个条目

• 修改一个条目，比如名称、说明、网站、小数位：直接原地编辑，并提升 patch 版本号。和添加时一样，pull request 要由该代币的团队提交。
• 更换 logo：替换文件即可。在 PNG 和 SVG 之间切换会改变文件名，所以要同时更新 logoURI 并删除旧文件。
• 替换合约：添加新地址。对于标签，保留旧条目，并在它的名称后面加上 (previous)，这样旧交易依然清晰可读。
• 移除一个条目：删除它和它的 logo 文件，并做一次 major 版本升级。

维护者可以随时移除一个代币，比如在遭到攻击、卷款跑路、换到新合约，或元数据被误导性地修改之后。

版本

每个文件都有自己的 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 都会在 GitHub Actions 里运行 npm test 和版本检查，然后由一位维护者审核。满足以下全部条件时，代币才会被加入：

• 它部署在该文件夹对应的网络上，并且源码已验证或已公开。
• pull request 由该代币的团队提交或确认，并附上一个链接，指向项目自己的网站或官方账号上写明了该合约地址的帖子。
• 它的名称和符号没有模仿其他代币或项目。新的 PKL 或 WETH 会被拒绝。
• 它有真实的用途：在 Pepper 上有流动性、有持有者，或有一个在运行的产品，而不是几分钟前才发行的代币。
• 合约里没有团队未披露的隐藏增发、黑名单或手续费开关。

满足以下条件时，标签才会被加入：该地址是一个合约，项目已经在 Pickle Chain 上运行，并且地址能在项目自己的文档或部署文件中核实。

常见校验错误

npm test 会打印出每一个问题，而不只是第一个。大家最常遇到的错误及其修复方法：