@quickswap-defi/token-list 2.0.0

package/README.md

@@ -0,0 +1,188 @@
+# @quickswap-defi/token-list
+
+[![npm version](https://img.shields.io/npm/v/@quickswap-defi/token-list.svg)](https://www.npmjs.com/package/@quickswap-defi/token-list)
+[![npm downloads](https://img.shields.io/npm/dm/@quickswap-defi/token-list.svg)](https://www.npmjs.com/package/@quickswap-defi/token-list)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
+[![Security](https://img.shields.io/badge/provenance-verified-brightgreen)](https://docs.npmjs.com/generating-provenance-statements)
+
+Official QuickSwap token list for multi-chain DeFi applications. Includes curated token metadata for Polygon, Base, zkEVM, and other supported networks.
+
+---
+
+## 🚨 Migration Notice
+
+**Former package name:** `quickswap-token-lists` (deprecated)  
+**New package name:** `@quickswap-defi/token-list`
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @quickswap-defi/token-list
+
+# pnpm
+pnpm add @quickswap-defi/token-list
+
+# yarn
+yarn add @quickswap-defi/token-list
+```
+
+## Usage
+
+```typescript
+import tokenList from '@quickswap-defi/token-list';
+
+// Access token list data
+console.log(tokenList.name);     // "Quickswap Default List"
+console.log(tokenList.version);  // { major: 2, minor: 0, patch: 0 }
+console.log(tokenList.tokens);   // Array of token metadata
+
+// Filter tokens by chain
+const polygonTokens = tokenList.tokens.filter(
+  token => token.chainId === 137
+);
+
+// Find specific token
+const usdc = tokenList.tokens.find(
+  token => token.symbol === 'USDC' && token.chainId === 137
+);
+```
+
+## Token List Schema
+
+The token list follows the [Uniswap Token List Standard](https://tokenlists.org/):
+
+```typescript
+interface TokenList {
+  name: string;
+  version: {
+    major: number;
+    minor: number;
+    patch: number;
+  };
+  tokens: Token[];
+  keywords?: string[];
+  tags?: Record<string, TagDefinition>;
+  logoURI?: string;
+}
+
+interface Token {
+  chainId: number;
+  address: string;
+  name: string;
+  symbol: string;
+  decimals: number;
+  logoURI?: string;
+  tags?: string[];
+}
+```
+
+## Supported Networks
+
+| Network | Chain ID |
+|---------|----------|
+| Polygon | 137 |
+| Ethereum | 1 |
+| Base | 8453 |
+| Polygon zkEVM | 1101 |
+| Manta | 169 |
+| IMX | 13371 |
+| X1 | 195 |
+| Dogechain | 2000 |
+| And more... | See `src/tokens/` |
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 18
+- npm >= 8
+
+### Setup
+
+```bash
+# Install dependencies
+npm ci
+
+# Run tests
+npm test
+
+# Build token list
+npm run build
+
+# Output: build/quickswap-default.tokenlist.json
+```
+
+### Adding a New Token
+
+**Token listing is NOT automatic.** We have strict requirements (TVL, Audit, Volume) to protect our users.
+
+**Process:**
+
+1. **Review Requirements & Request Listing:**
+   To understand the requirements and initiate a listing request, please use our [Token Listing Request Template](https://github.com/QuickSwap/quickswap-default-token-list/issues/new?assignees=&labels=token-listing&projects=&template=token-listing-request.md&title=%5BTOKEN+LISTING%5D+%3CToken+Symbol%3E+-+%3CNetwork%3E).
+
+#### Technical Steps (Only After BD Approval)
+
+1. **Edit network file** in `src/tokens/<network>.json`:
+
+   ```json
+   {
+     "name": "Example Token",
+     "address": "0x...",
+     "symbol": "EXT",
+     "decimals": 18,
+     "chainId": 137,
+     "logoURI": "https://assets.quickswap.exchange/tokens/ext.png"
+   }
+   ```
+
+2. **Run validation:**
+
+   ```bash
+   npm test
+   ```
+
+3. **Submit PR** with:
+   - Token details
+   - Logo in `assets/` folder (optimized WebP, max 15KB)
+
+**PRs without prior BD approval will be closed immediately.**
+
+## Security
+
+### NPM Provenance
+
+All published versions include [NPM Provenance](https://docs.npmjs.com/generating-provenance-statements) for supply chain security.
+
+**Verify authenticity:**
+
+```bash
+npm view @quickswap-defi/token-list@2.0.0 --json | jq '.provenance'
+```
+
+**Manual publish:**
+
+```bash
+# Bump version
+npm version patch  # or minor/major
+
+# Publish with provenance
+npm publish --access public --provenance
+```
+
+## License
+
+GPL-3.0-or-later - See [LICENSE](./LICENSE)
+
+## Links
+
+- **NPM Package:** https://www.npmjs.com/package/@quickswap-defi/token-list
+- **GitHub:** https://github.com/QuickSwap/quickswap-default-token-list
+- **QuickSwap:** https://quickswap.exchange
+- **Discord:** https://discord.com/invite/cSbHcjBSWM
+- **Twitter:** https://twitter.com/QuickswapDEX
+
+**Maintained by:** [QuickSwap Team](https://quickswap.exchange)