토큰 목록과 주소 태그

목록이란 무엇인가

네트워크마다 파일 두 개입니다. tokenlist.json은 리뷰를 거친 토큰을 표준 Uniswap Token Lists 형식으로 나열하므로, 어떤 지갑, DEX 인터페이스, 애그리게이터든 그대로 가져올 수 있습니다. tags.json은 잘 알려진 컨트랙트에 읽을 수 있는 레이블 - 이름, 카테고리, 프로젝트 - 을 붙여, 익스플로러가 16진수 주소를 보여 줄 자리에 "Pepper 라우터"를 보여 줄 수 있게 합니다.

목록에 오른 토큰은 익스플로러, 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 주소가 제3자에게 가지 않고, GitHub의 요청 한도에 걸리지 않으며, GitHub에 닿을 수 없을 때도 마지막으로 정상이었던 사본을 유지할 수 있습니다. 지갑이나 DEX 인터페이스에서는 tokenlist.json의 raw URL을 사용자 지정 토큰 목록으로 추가하십시오.

Pickle 앱들이 쓰는 방식

Pickle 스택에서 이 파일들을 위해 GitHub와 통신하는 것은 익스플로러 API뿐입니다. 약 10분마다 두 파일을 가져와 각 파일을 통째로 검증하고 - 형태, 체인 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. 항목을 추가합니다. 아래 예시처럼 testnet/tokenlist.json의 tokens 끝에 덧붙입니다.
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. 항목을 추가합니다. testnet/tags.json의 tags에 체크섬 주소를 키로 해서 넣습니다.
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을 붙이면 됩니다.

항목 수정 또는 삭제

• 항목 수정 - 이름, 노트, 웹사이트, decimals - 은 그 자리에서 편집하고 패치 버전을 올립니다. 추가할 때와 마찬가지로 pull request는 토큰 팀이 여십시오.
• 로고 교체는 파일을 바꿔 넣으면 됩니다. PNG와 SVG 사이를 바꾸면 파일 이름이 달라지므로, logoURI를 갱신하고 이전 파일을 삭제하십시오.
• 컨트랙트 교체는 새 주소를 추가합니다. 태그라면 이전 항목을 남겨 두고 그 이름 뒤에 (previous)를 붙여, 과거 트랜잭션도 여전히 알아보기 쉽게 하십시오.
• 항목 삭제는 항목과 그 로고 파일을 지우고 메이저 버전을 올립니다.

메인테이너는 언제든 토큰을 삭제할 수 있습니다 - 익스플로잇, 러그 풀, 새 컨트랙트로의 전환, 오해를 부르는 메타데이터 변경이 있은 뒤라면.

버전

각 파일은 자기 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는 첫 번째 문제만이 아니라 모든 문제를 출력합니다. 가장 자주 만나는 것들과 그 해결 방법입니다.