Lista de tokens e tags de endereço

O que é a lista

Dois arquivos por rede. tokenlist.json lista os tokens revisados, no formato padrão Uniswap Token Lists, para que qualquer carteira, interface de DEX ou agregador possa importá-lo do jeito que está. tags.json dá a contratos conhecidos um rótulo legível - um nome, uma categoria e um projeto - para que um explorador possa mostrar "Pepper router" onde, de outro modo, mostraria um endereço hexadecimal.

Um token listado ganha a marca de verificado, o seu logo, o seu nome e o seu símbolo no explorador, no Pepper, no Toolkit, no Names e na página Account. Um contrato com tag aparece pelo seu rótulo nas listas de transações, nas páginas de endereço e na busca.

Nada é listado automaticamente. Um token lançado com o lançador de tokens do Pepper não é adicionado só por existir; ele é adicionado quando alguém abre um pull request e ele atende aos critérios.

Onde ela fica

A lista fica num repositório público no GitHub, github.com/PickleChain/token-list, com uma pasta por rede:

Dentro de uma pasta de rede:

As URLs raw, sempre no último commit de main:

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

Num site, busque os arquivos no servidor e sirva-os a partir da sua própria origem em vez de fazer hot-linking de raw.githubusercontent.com a partir do navegador dos visitantes: isso mantém os endereços IP deles longe de um terceiro, evita os limites de taxa do GitHub e permite guardar a última cópia boa quando o GitHub estiver inacessível. Numa carteira ou numa interface de DEX, adicione a URL raw de tokenlist.json como lista de tokens personalizada.

Como as aplicações Pickle a usam

A API do explorador é a única parte da pilha Pickle que fala com o GitHub para buscar esses arquivos. Ela busca os dois mais ou menos a cada dez minutos, valida cada arquivo por inteiro - formato, chain ID, checksums, duplicatas - e guarda a última cópia boa em memória e em disco. Um arquivo que falha é rejeitado por inteiro e o anterior continua em serviço, então um commit ruim nunca apaga um rótulo ou um logo. Cada site Pickle lê então a cópia do explorador a partir da sua própria origem:

As rotas ficam em https://explorer.picklechain.xyz, atrás da allowlist de CORS do explorador: elas servem os sites Pickle. A sua própria aplicação lê os arquivos raw acima.

Adicionar um token

Confira os critérios primeiro: um pull request para um token que não os atende é fechado. Depois, no seu fork do repositório:

1. Obtenha o endereço com checksum. Maiúsculas e minúsculas do EIP-55, não tudo em minúsculas. Se o seu estiver errado, o validador imprime a forma esperada.
2. Adicione o logo em testnet/logos/tokens/, com exatamente o nome desse endereço: testnet/logos/tokens/0x0000…dEaD.png (ou .svg). Ele precisa seguir as regras para logos.
3. Acrescente uma entrada a tokens em testnet/tokenlist.json, como no exemplo abaixo.
4. Suba a versão de tokenlist.json - adicionar um token é um bump minor, 1.4.2 vira 1.5.0 - e defina timestamp como agora, em ISO 8601 UTC.
5. Rode as verificações com npm test. Precisa do Node 22 ou mais recente e de nada mais: o validador não tem dependências, então não há nada para instalar.
6. Abra um pull request contra main. Na descrição, inclua o link de uma publicação do site próprio do projeto ou da sua conta oficial que cite o endereço do contrato.

{
  "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 representa o seu endereço completo com checksum, de 42 caracteres; é um marcador, não um token.

O ciclo completo na linha de comando:

# 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.

Regras para logos

Todo arquivo em logos/ precisa ser referenciado pela lista ou pelas tags. Um logo para o qual nada aponta reprova nas verificações, então remova-o no mesmo pull request que a sua entrada.

Adicionar uma tag de endereço

As tags são para contratos que as pessoas encontram nas transações: contratos de protocolo, routers, factories, pools, vaults, jogos, bridges. Carteiras pessoais nunca recebem tag. O projeto precisa estar no ar na Pickle Chain, e o endereço precisa ser verificável na documentação ou nos arquivos de implantação do próprio projeto.

1. Adicione uma entrada a tags em testnet/tags.json, indexada pelo endereço com checksum.
2. Opcionalmente, adicione um logo em testnet/logos/tags/ - mesmas regras de formato que um logo de token, qualquer nome de arquivo - e aponte logo para a sua URL raw. Várias tags de um mesmo projeto podem compartilhar um só arquivo.
3. Suba a versão de tags.json e o seu timestamp, rode npm test e abra o 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."
}

As categorias definidas hoje:

Se nenhuma servir, proponha uma nova categoria no mesmo pull request: uma chave em minúsculas de até 20 caracteres, com um name e uma description.

Atualizar ou remover uma entrada

• Altere uma entrada - um nome, uma nota, um site, as decimais - editando-a no lugar e subindo a versão patch. Abra o pull request a partir da equipe do token, como numa adição.
• Troque um logo substituindo o arquivo. Passar de PNG para SVG, ou o contrário, muda o nome dele, então atualize logoURI e apague o arquivo antigo.
• Substitua um contrato adicionando o novo endereço. Para uma tag, mantenha a entrada antiga e acrescente ao nome dela o sufixo (previous), para que as transações antigas continuem claras.
• Remova uma entrada apagando-a junto com o seu arquivo de logo, com um bump major da versão.

Os mantenedores podem remover um token a qualquer momento - depois de um exploit, de um rug pull, da troca por um novo contrato ou de uma alteração enganosa dos metadados.

Versões

Cada arquivo tem a sua própria version, e o bump segue as regras das Token Lists. O CI o impõe em relação ao branch de base do pull request, e uma versão alterada exige um timestamp mais recente.

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

O que a revisão verifica

Todo pull request executa npm test e a verificação de versão no GitHub Actions, e depois um mantenedor o revisa. Um token é adicionado quando tudo isto vale:

• Ele está implantado na rede daquela pasta, e o seu código-fonte está verificado ou publicado.
• O pull request é aberto ou confirmado pela equipe do token, com o link de uma publicação no site próprio do projeto ou na sua conta oficial que cite o endereço do contrato.
• O nome e o símbolo não imitam outro token ou projeto. Um novo PKL ou WETH é recusado.
• Ele tem uso real: liquidez no Pepper, detentores ou um produto no ar - não um token lançado há poucos minutos.
• O contrato não tem mint oculto, blacklist ou chave de taxa que a equipe não tenha divulgado.

Uma tag é adicionada quando o endereço é um contrato, o projeto está no ar na Pickle Chain e o endereço pode ser verificado na documentação ou nos arquivos de implantação do próprio projeto.

Erros de validação comuns

npm test imprime todos os problemas, não só o primeiro. Os que as pessoas mais encontram, e a correção: